]>
Commit | Line | Data |
---|---|---|
5b2abdfb A |
1 | .\" Copyright (c) 1989, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" Arthur Olson. | |
6 | .\" Redistribution and use in source and binary forms, with or without | |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
9 | .\" 1. Redistributions of source code must retain the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer. | |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer in the | |
13 | .\" documentation and/or other materials provided with the distribution. | |
5b2abdfb A |
14 | .\" 4. Neither the name of the University nor the names of its contributors |
15 | .\" may be used to endorse or promote products derived from this software | |
16 | .\" without specific prior written permission. | |
17 | .\" | |
18 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
19 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
20 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
21 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
22 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
23 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
24 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
25 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
26 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
27 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
28 | .\" SUCH DAMAGE. | |
29 | .\" | |
30 | .\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93 | |
1f2f436a | 31 | .\" $FreeBSD: src/lib/libc/stdtime/ctime.3,v 1.24 2007/01/09 00:28:11 imp Exp $ |
5b2abdfb A |
32 | .\" |
33 | .Dd January 2, 1999 | |
34 | .Dt CTIME 3 | |
35 | .Os | |
36 | .Sh NAME | |
37 | .Nm asctime , | |
38 | .Nm asctime_r , | |
39 | .Nm ctime , | |
40 | .Nm ctime_r , | |
41 | .Nm difftime , | |
42 | .Nm gmtime , | |
43 | .Nm gmtime_r , | |
44 | .Nm localtime , | |
45 | .Nm localtime_r , | |
46 | .Nm mktime , | |
47 | .Nm timegm | |
48 | .Nd transform binary date and time values | |
49 | .Sh LIBRARY | |
50 | .Lb libc | |
51 | .Sh SYNOPSIS | |
52 | .In time.h | |
53 | .Vt extern char *tzname[2] ; | |
54 | .Ft char * | |
ad3c9f2a A |
55 | .Fn asctime "const struct tm *timeptr" |
56 | .Ft char * | |
57 | .Fn asctime_r "const struct tm *restrict timeptr" "char *restrict buf" | |
58 | .Ft char * | |
5b2abdfb | 59 | .Fn ctime "const time_t *clock" |
ad3c9f2a A |
60 | .Ft char * |
61 | .Fn ctime_r "const time_t *clock" "char *buf" | |
5b2abdfb A |
62 | .Ft double |
63 | .Fn difftime "time_t time1" "time_t time0" | |
ad3c9f2a A |
64 | .Ft struct tm * |
65 | .Fn gmtime "const time_t *clock" | |
66 | .Ft struct tm * | |
67 | .Fn gmtime_r "const time_t *clock" "struct tm *result" | |
5b2abdfb A |
68 | .Ft struct tm * |
69 | .Fn localtime "const time_t *clock" | |
70 | .Ft struct tm * | |
ad3c9f2a | 71 | .Fn localtime_r "const time_t *clock" "struct tm *result" |
5b2abdfb | 72 | .Ft time_t |
ad3c9f2a | 73 | .Fn mktime "struct tm *timeptr" |
5b2abdfb | 74 | .Ft time_t |
ad3c9f2a | 75 | .Fn timegm "struct tm *timeptr" |
5b2abdfb A |
76 | .Sh DESCRIPTION |
77 | The functions | |
78 | .Fn ctime , | |
ad3c9f2a | 79 | .Fn gmtime , |
5b2abdfb A |
80 | and |
81 | .Fn localtime | |
82 | all take as an argument a time value representing the time in seconds since | |
83 | the Epoch (00:00:00 | |
84 | .Tn UTC , | |
85 | January 1, 1970; see | |
86 | .Xr time 3 ) . | |
6465356a A |
87 | When encountering an error, these functions return |
88 | .Dv NULL | |
89 | and set | |
90 | .Dv errno | |
91 | to an appropriate value. | |
5b2abdfb A |
92 | .Pp |
93 | The function | |
94 | .Fn localtime | |
95 | converts the time value pointed at by | |
ad3c9f2a A |
96 | .Fa clock . |
97 | It returns a pointer to a | |
5b2abdfb | 98 | .Dq Fa struct tm |
ad3c9f2a | 99 | (described below), which contains |
5b2abdfb A |
100 | the broken-out time information for the value after adjusting for the current |
101 | time zone (and any other factors such as Daylight Saving Time). | |
102 | Time zone adjustments are performed as specified by the | |
103 | .Ev TZ | |
104 | environment variable (see | |
105 | .Xr tzset 3 ) . | |
106 | The function | |
107 | .Fn localtime | |
108 | uses | |
109 | .Xr tzset 3 | |
ad3c9f2a | 110 | to initialize time conversion information, if |
5b2abdfb A |
111 | .Xr tzset 3 |
112 | has not already been called by the process. | |
113 | .Pp | |
114 | After filling in the tm structure, | |
115 | .Fn localtime | |
116 | sets the | |
117 | .Fa tm_isdst Ns 'th | |
118 | element of | |
119 | .Fa tzname | |
120 | to a pointer to an | |
121 | .Tn ASCII | |
ad3c9f2a | 122 | string containing the time zone abbreviation to be |
5b2abdfb A |
123 | used with |
124 | .Fn localtime Ns 's | |
125 | return value. | |
126 | .Pp | |
127 | The function | |
128 | .Fn gmtime | |
ad3c9f2a A |
129 | also converts the time value, but makes no time zone adjustment. |
130 | It returns a pointer to a tm structure (described below). | |
5b2abdfb A |
131 | .Pp |
132 | The | |
133 | .Fn ctime | |
134 | function | |
ad3c9f2a A |
135 | adjusts the time value for the current time zone, in the same manner as |
136 | .Fn localtime . | |
137 | It returns a pointer to a 26-character string of the form: | |
5b2abdfb A |
138 | .Bd -literal -offset indent |
139 | Thu Nov 24 18:22:48 1986\en\e0 | |
140 | .Ed | |
141 | .Pp | |
ad3c9f2a | 142 | All of the fields have constant width. |
5b2abdfb | 143 | .Pp |
9385eb3d | 144 | The |
5b2abdfb | 145 | .Fn ctime_r |
9385eb3d | 146 | function |
5b2abdfb | 147 | provides the same functionality as |
ad3c9f2a A |
148 | .Fn ctime , |
149 | except that the caller must provide the output buffer | |
5b2abdfb | 150 | .Fa buf |
ad3c9f2a | 151 | (which must be at least 26 characters long) to store the result. |
9385eb3d | 152 | The |
5b2abdfb A |
153 | .Fn localtime_r |
154 | and | |
155 | .Fn gmtime_r | |
9385eb3d | 156 | functions |
5b2abdfb A |
157 | provide the same functionality as |
158 | .Fn localtime | |
159 | and | |
ad3c9f2a | 160 | .Fn gmtime , |
5b2abdfb A |
161 | respectively, except the caller must provide the output buffer |
162 | .Fa result . | |
163 | .Pp | |
164 | The | |
165 | .Fn asctime | |
166 | function | |
ad3c9f2a | 167 | converts the broken-out time in the structure |
5b2abdfb | 168 | .Fa tm |
ad3c9f2a A |
169 | (pointed at by |
170 | .Fa *timeptr ) | |
5b2abdfb A |
171 | to the form |
172 | shown in the example above. | |
173 | .Pp | |
9385eb3d | 174 | The |
5b2abdfb | 175 | .Fn asctime_r |
9385eb3d | 176 | function |
5b2abdfb | 177 | provides the same functionality as |
ad3c9f2a A |
178 | .Fn asctime , |
179 | except that the caller provides the output buffer | |
5b2abdfb | 180 | .Fa buf |
ad3c9f2a | 181 | (which must be at least 26 characters long) to store the result. |
5b2abdfb A |
182 | .Pp |
183 | The functions | |
184 | .Fn mktime | |
185 | and | |
186 | .Fn timegm | |
ad3c9f2a A |
187 | convert the broken-out time |
188 | (in the structure pointed to by | |
189 | .Fa *timeptr ) | |
190 | into a time value with the same encoding as that of the | |
5b2abdfb A |
191 | values returned by the |
192 | .Xr time 3 | |
193 | function (that is, seconds from the Epoch, | |
194 | .Tn UTC ) . | |
9385eb3d | 195 | The |
5b2abdfb | 196 | .Fn mktime |
9385eb3d | 197 | function |
5b2abdfb A |
198 | interprets the input structure according to the current timezone setting |
199 | (see | |
200 | .Xr tzset 3 ) . | |
9385eb3d | 201 | The |
5b2abdfb | 202 | .Fn timegm |
ad3c9f2a A |
203 | function interprets the input structure |
204 | as representing Universal Coordinated Time | |
5b2abdfb A |
205 | .Pq Tn UTC . |
206 | .Pp | |
207 | The original values of the | |
208 | .Fa tm_wday | |
209 | and | |
210 | .Fa tm_yday | |
ad3c9f2a A |
211 | components of the structure are ignored. The original values of the |
212 | other components are not restricted to their normal ranges and will be | |
213 | normalized, if need be. | |
5b2abdfb A |
214 | For example, |
215 | October 40 is changed into November 9, | |
216 | a | |
217 | .Fa tm_hour | |
218 | of \-1 means 1 hour before midnight, | |
219 | .Fa tm_mday | |
220 | of 0 means the day preceding the current month, and | |
221 | .Fa tm_mon | |
222 | of \-2 means 2 months before January of | |
223 | .Fa tm_year . | |
224 | (A positive or zero value for | |
225 | .Fa tm_isdst | |
226 | causes | |
227 | .Fn mktime | |
228 | to presume initially that summer time (for example, Daylight Saving Time) | |
ad3c9f2a | 229 | is or is not (respectively) in effect for the specified time. |
5b2abdfb A |
230 | A negative value for |
231 | .Fa tm_isdst | |
232 | causes the | |
233 | .Fn mktime | |
234 | function to attempt to divine whether summer time is in effect for the | |
235 | specified time. | |
236 | The | |
237 | .Fa tm_isdst | |
238 | and | |
239 | .Fa tm_gmtoff | |
240 | members are forced to zero by | |
241 | .Fn timegm . ) | |
242 | .Pp | |
243 | On successful completion, the values of the | |
244 | .Fa tm_wday | |
245 | and | |
246 | .Fa tm_yday | |
247 | components of the structure are set appropriately, and the other components | |
248 | are set to represent the specified calendar time, but with their values | |
249 | forced to their normal ranges; the final value of | |
250 | .Fa tm_mday | |
251 | is not set until | |
252 | .Fa tm_mon | |
253 | and | |
254 | .Fa tm_year | |
255 | are determined. | |
9385eb3d A |
256 | The |
257 | .Fn mktime | |
258 | function | |
5b2abdfb A |
259 | returns the specified calendar time; if the calendar time cannot be |
260 | represented, it returns \-1; | |
261 | .Pp | |
262 | The | |
263 | .Fn difftime | |
264 | function | |
265 | returns the difference between two calendar times, | |
266 | .Pf ( Fa time1 | |
267 | - | |
268 | .Fa time0 ) , | |
269 | expressed in seconds. | |
270 | .Pp | |
ad3c9f2a A |
271 | External declarations, as well as the tm structure definition, |
272 | are contained in the | |
3d9156a7 | 273 | .In time.h |
5b2abdfb A |
274 | include file. |
275 | The tm structure includes at least the following fields: | |
276 | .Bd -literal -offset indent | |
277 | int tm_sec; /\(** seconds (0 - 60) \(**/ | |
278 | int tm_min; /\(** minutes (0 - 59) \(**/ | |
279 | int tm_hour; /\(** hours (0 - 23) \(**/ | |
280 | int tm_mday; /\(** day of month (1 - 31) \(**/ | |
281 | int tm_mon; /\(** month of year (0 - 11) \(**/ | |
282 | int tm_year; /\(** year \- 1900 \(**/ | |
283 | int tm_wday; /\(** day of week (Sunday = 0) \(**/ | |
284 | int tm_yday; /\(** day of year (0 - 365) \(**/ | |
285 | int tm_isdst; /\(** is summer time in effect? \(**/ | |
286 | char \(**tm_zone; /\(** abbreviation of timezone name \(**/ | |
287 | long tm_gmtoff; /\(** offset from UTC in seconds \(**/ | |
288 | .Ed | |
289 | .Pp | |
290 | The | |
291 | field | |
292 | .Fa tm_isdst | |
ad3c9f2a | 293 | is non-zero if summer (i.e., Daylight Saving) time is in effect. |
5b2abdfb A |
294 | .Pp |
295 | The field | |
296 | .Fa tm_gmtoff | |
297 | is the offset (in seconds) of the time represented from | |
298 | .Tn UTC , | |
299 | with positive | |
ad3c9f2a | 300 | values indicating locations east of the Prime Meridian. |
5b2abdfb A |
301 | .Sh SEE ALSO |
302 | .Xr date 1 , | |
303 | .Xr gettimeofday 2 , | |
304 | .Xr getenv 3 , | |
305 | .Xr time 3 , | |
306 | .Xr tzset 3 , | |
307 | .Xr tzfile 5 | |
308 | .Sh STANDARDS | |
309 | The | |
310 | .Fn asctime , | |
311 | .Fn ctime , | |
312 | .Fn difftime , | |
313 | .Fn gmtime , | |
314 | .Fn localtime , | |
315 | and | |
316 | .Fn mktime | |
317 | functions conform to | |
318 | .St -isoC , | |
319 | and conform to | |
320 | .St -p1003.1-96 | |
321 | provided the selected local timezone does not contain a leap-second table | |
322 | (see | |
323 | .Xr zic 8 ) . | |
324 | .Pp | |
325 | The | |
326 | .Fn asctime_r , | |
327 | .Fn ctime_r , | |
328 | .Fn gmtime_r , | |
329 | and | |
330 | .Fn localtime_r | |
331 | functions are expected to conform to | |
332 | .St -p1003.1-96 | |
333 | (again provided the selected local timezone does not contain a leap-second | |
334 | table). | |
335 | .Pp | |
336 | The | |
337 | .Fn timegm | |
338 | function is not specified by any standard; its function cannot be | |
339 | completely emulated using the standard functions described above. | |
340 | .Sh HISTORY | |
341 | This manual page is derived from | |
342 | the time package contributed to Berkeley by | |
343 | .An Arthur Olson | |
344 | and which appeared in | |
345 | .Bx 4.3 . | |
346 | .Sh BUGS | |
347 | Except for | |
348 | .Fn difftime , | |
349 | .Fn mktime , | |
350 | and the | |
351 | .Fn \&_r | |
352 | variants of the other functions, | |
353 | these functions leaves their result in an internal static object and return | |
354 | a pointer to that object. | |
355 | Subsequent calls to these | |
356 | function will modify the same object. | |
357 | .Pp | |
358 | The C Standard provides no mechanism for a program to modify its current | |
359 | local timezone setting, and the | |
360 | .Tn POSIX Ns No \&-standard | |
3d9156a7 A |
361 | method is not reentrant. |
362 | (However, thread-safe implementations are provided | |
5b2abdfb A |
363 | in the |
364 | .Tn POSIX | |
365 | threaded environment.) | |
366 | .Pp | |
367 | The | |
9385eb3d A |
368 | .Va tm_zone |
369 | field of a returned | |
370 | .Vt tm | |
371 | structure points to a static array of characters, | |
5b2abdfb A |
372 | which will also be overwritten by any subsequent calls (as well as by |
373 | subsequent calls to | |
374 | .Xr tzset 3 | |
375 | and | |
376 | .Xr tzsetwall 3 ) . | |
377 | .Pp | |
378 | Use of the external variable | |
379 | .Fa tzname | |
380 | is discouraged; the | |
381 | .Fa tm_zone | |
382 | entry in the tm structure is preferred. |