]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" References consulted: | |
26 | .\" Linux libc source code | |
27 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
28 | .\" 386BSD man pages | |
29 | .\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu) | |
30 | .\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de) | |
31 | .\" Modified 2001-11-13, aeb | |
32 | .\" Modified 2001-12-13, joey, aeb | |
3e53c142 | 33 | .\" Modified 2004-11-16, mtk |
fea681da | 34 | .\" |
35deeb87 | 35 | .TH CTIME 3 2016-12-12 "" "Linux Programmer's Manual" |
fea681da MK |
36 | .SH NAME |
37 | asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, | |
38 | localtime_r \- transform date and time to broken-down time or ASCII | |
39 | .SH SYNOPSIS | |
40 | .nf | |
41 | .B #include <time.h> | |
68e4db0a | 42 | .PP |
fea681da MK |
43 | .BI "char *asctime(const struct tm *" tm ); |
44 | .br | |
45 | .BI "char *asctime_r(const struct tm *" tm ", char *" buf ); | |
68e4db0a | 46 | .PP |
fea681da MK |
47 | .BI "char *ctime(const time_t *" timep ); |
48 | .br | |
49 | .BI "char *ctime_r(const time_t *" timep ", char *" buf ); | |
68e4db0a | 50 | .PP |
fea681da MK |
51 | .BI "struct tm *gmtime(const time_t *" timep ); |
52 | .br | |
53 | .BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result ); | |
68e4db0a | 54 | .PP |
fea681da MK |
55 | .BI "struct tm *localtime(const time_t *" timep ); |
56 | .br | |
57 | .BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result ); | |
68e4db0a | 58 | .PP |
fea681da MK |
59 | .BI "time_t mktime(struct tm *" tm ); |
60 | .fi | |
68e4db0a | 61 | .PP |
cc4615cc MK |
62 | .in -4n |
63 | Feature Test Macro Requirements for glibc (see | |
64 | .BR feature_test_macros (7)): | |
65 | .in | |
4bc22b3c | 66 | .ad l |
68e4db0a | 67 | .PP |
cc4615cc MK |
68 | .BR asctime_r (), |
69 | .BR ctime_r (), | |
70 | .BR gmtime_r (), | |
71 | .BR localtime_r (): | |
4bc22b3c | 72 | .RS |
d59161f9 MK |
73 | _POSIX_C_SOURCE |
74 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE | |
4bc22b3c MK |
75 | .RE |
76 | .ad | |
fea681da | 77 | .SH DESCRIPTION |
60a90ecd MK |
78 | The |
79 | .BR ctime (), | |
80 | .BR gmtime () | |
81 | and | |
82 | .BR localtime () | |
83 | functions all take | |
213d2580 | 84 | an argument of data type \fItime_t\fP, which represents calendar time. |
fea681da | 85 | When interpreted as an absolute time value, it represents the number of |
f49c451a | 86 | seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). |
fea681da | 87 | .PP |
60a90ecd MK |
88 | The |
89 | .BR asctime () | |
90 | and | |
91 | .BR mktime () | |
92 | functions both take an argument | |
213d2580 | 93 | representing broken-down time, which is a representation |
1c2816e2 | 94 | separated into year, month, day, and so on. |
fea681da MK |
95 | .PP |
96 | Broken-down time is stored | |
213d2580 | 97 | in the structure \fItm\fP, which is defined in \fI<time.h>\fP as follows: |
ba39b288 | 98 | .PP |
bd191423 | 99 | .in +4n |
ba39b288 | 100 | .EX |
fea681da | 101 | struct tm { |
213d2580 MK |
102 | int tm_sec; /* Seconds (0-60) */ |
103 | int tm_min; /* Minutes (0-59) */ | |
104 | int tm_hour; /* Hours (0-23) */ | |
105 | int tm_mday; /* Day of the month (1-31) */ | |
106 | int tm_mon; /* Month (0-11) */ | |
107 | int tm_year; /* Year - 1900 */ | |
108 | int tm_wday; /* Day of the week (0-6, Sunday = 0) */ | |
109 | int tm_yday; /* Day in the year (0-365, 1 Jan = 0) */ | |
110 | int tm_isdst; /* Daylight saving time */ | |
fea681da | 111 | }; |
ba39b288 | 112 | .EE |
bd191423 | 113 | .in |
fea681da MK |
114 | .PP |
115 | The members of the \fItm\fP structure are: | |
8fe528b3 | 116 | .TP 10 |
fea681da | 117 | .I tm_sec |
c13182ef | 118 | The number of seconds after the minute, normally in the range 0 to 59, |
7f4f9585 | 119 | but can be up to 60 to allow for leap seconds. |
fea681da MK |
120 | .TP |
121 | .I tm_min | |
c13182ef | 122 | The number of minutes after the hour, in the range 0 to 59. |
fea681da MK |
123 | .TP |
124 | .I tm_hour | |
125 | The number of hours past midnight, in the range 0 to 23. | |
126 | .TP | |
127 | .I tm_mday | |
128 | The day of the month, in the range 1 to 31. | |
129 | .TP | |
130 | .I tm_mon | |
131 | The number of months since January, in the range 0 to 11. | |
132 | .TP | |
133 | .I tm_year | |
134 | The number of years since 1900. | |
135 | .TP | |
136 | .I tm_wday | |
137 | The number of days since Sunday, in the range 0 to 6. | |
138 | .TP | |
139 | .I tm_yday | |
140 | The number of days since January 1, in the range 0 to 365. | |
141 | .TP | |
142 | .I tm_isdst | |
143 | A flag that indicates whether daylight saving time is in effect at the | |
c13182ef MK |
144 | time described. |
145 | The value is positive if daylight saving time is in | |
fea681da MK |
146 | effect, zero if it is not, and negative if the information is not |
147 | available. | |
148 | .PP | |
149 | The call | |
150 | .BI ctime( t ) | |
151 | is equivalent to | |
152 | .BI asctime(localtime( t )) \fR. | |
0e8fe3b4 MK |
153 | It converts the calendar time \fIt\fP into a |
154 | null-terminated string of the form | |
ba39b288 MK |
155 | .PP |
156 | .in +4n | |
157 | .EX | |
fea681da MK |
158 | .RS |
159 | "Wed Jun 30 21:49:08 1993\\n" | |
ba39b288 MK |
160 | .EE |
161 | ,in | |
162 | .PP | |
84c517a4 MK |
163 | The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed", |
164 | "Thu", "Fri", and "Sat". | |
165 | The abbreviations for the months are "Jan", | |
166 | "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and | |
167 | "Dec". | |
c13182ef | 168 | The return value points to a statically allocated string which |
fea681da | 169 | might be overwritten by subsequent calls to any of the date and time |
c13182ef | 170 | functions. |
546f67f3 MK |
171 | The function also sets the external |
172 | variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see | |
fea681da | 173 | .BR tzset (3)) |
5b0dc1ba | 174 | with information about the current timezone. |
da27f178 | 175 | The reentrant version |
60a90ecd MK |
176 | .BR ctime_r () |
177 | does the same, but stores the | |
ef38dda0 MK |
178 | string in a user-supplied buffer |
179 | which should have room for at least 26 bytes. | |
c13182ef | 180 | It need not |
546f67f3 | 181 | set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. |
fea681da | 182 | .PP |
60a90ecd MK |
183 | The |
184 | .BR gmtime () | |
185 | function converts the calendar time \fItimep\fP to | |
fea681da | 186 | broken-down time representation, expressed in Coordinated Universal Time |
c13182ef MK |
187 | (UTC). |
188 | It may return NULL when the year does not fit into an integer. | |
fea681da MK |
189 | The return value points to a statically allocated struct which might be |
190 | overwritten by subsequent calls to any of the date and time functions. | |
60a90ecd MK |
191 | The |
192 | .BR gmtime_r () | |
193 | function does the same, but stores the data in a | |
fea681da MK |
194 | user-supplied struct. |
195 | .PP | |
60a90ecd MK |
196 | The |
197 | .BR localtime () | |
198 | function converts the calendar time \fItimep\fP to | |
5f14486c MK |
199 | broken-down time representation, |
200 | expressed relative to the user's specified timezone. | |
c13182ef | 201 | The function acts as if it called |
fea681da | 202 | .BR tzset (3) |
c13182ef | 203 | and sets the external variables \fItzname\fP with |
5b0dc1ba | 204 | information about the current timezone, \fItimezone\fP with the difference |
fea681da | 205 | between Coordinated Universal Time (UTC) and local standard time in |
c7094399 | 206 | seconds, and \fIdaylight\fP to a nonzero value if daylight savings |
fea681da MK |
207 | time rules apply during some part of the year. |
208 | The return value points to a statically allocated struct which might be | |
209 | overwritten by subsequent calls to any of the date and time functions. | |
60a90ecd MK |
210 | The |
211 | .BR localtime_r () | |
212 | function does the same, but stores the data in a | |
c13182ef | 213 | user-supplied struct. |
546f67f3 | 214 | It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. |
fea681da | 215 | .PP |
60a90ecd MK |
216 | The |
217 | .BR asctime () | |
218 | function converts the broken-down time value | |
0e8fe3b4 | 219 | \fItm\fP into a null-terminated string with the same format as |
60a90ecd | 220 | .BR ctime (). |
c13182ef | 221 | The return value points to a statically allocated string which might be |
fea681da | 222 | overwritten by subsequent calls to any of the date and time functions. |
60a90ecd MK |
223 | The |
224 | .BR asctime_r () | |
225 | function does the same, but stores the string in | |
ef38dda0 | 226 | a user-supplied buffer which should have room for at least 26 bytes. |
fea681da | 227 | .PP |
60a90ecd MK |
228 | The |
229 | .BR mktime () | |
230 | function converts a broken-down time structure, expressed | |
c13182ef MK |
231 | as local time, to calendar time representation. |
232 | The function ignores | |
9ef659a9 MK |
233 | the values supplied by the caller in the |
234 | .I tm_wday | |
235 | and | |
236 | .I tm_yday | |
237 | fields. | |
f9db4400 MK |
238 | The value specified in the |
239 | .I tm_isdst | |
240 | field informs | |
241 | .BR mktime () | |
242 | whether or not daylight saving time (DST) | |
243 | is in effect for the time supplied in the | |
244 | .I tm | |
245 | structure: | |
246 | a positive value means DST is in effect; | |
247 | zero means that DST is not in effect; | |
248 | and a negative value means that | |
9ef659a9 | 249 | .BR mktime () |
f9db4400 MK |
250 | should (use timezone information and system databases to) |
251 | attempt to determine whether DST is in effect at the specified time. | |
847e0d88 | 252 | .PP |
f9db4400 MK |
253 | The |
254 | .BR mktime () | |
255 | function modifies the fields of the | |
9ef659a9 MK |
256 | .IR tm |
257 | structure as follows: | |
258 | .I tm_wday | |
259 | and | |
260 | .I tm_yday | |
261 | are set to values determined from the contents of the other fields; | |
262 | if structure members are outside their valid interval, they will be | |
f9db4400 MK |
263 | normalized (so that, for example, 40 October is changed into 9 November); |
264 | .I tm_isdst | |
265 | is set (regardless of its initial value) | |
266 | to a positive value or to 0, respectively, | |
acddbaea | 267 | to indicate whether DST is or is not in effect at the specified time. |
60a90ecd MK |
268 | Calling |
269 | .BR mktime () | |
270 | also sets the external variable \fItzname\fP with | |
5b0dc1ba | 271 | information about the current timezone. |
847e0d88 | 272 | .PP |
c13182ef | 273 | If the specified broken-down |
be9634cf | 274 | time cannot be represented as calendar time (seconds since the Epoch), |
60a90ecd | 275 | .BR mktime () |
ab3206e7 | 276 | returns |
009df872 | 277 | .I (time_t)\ \-1 |
7d2cb9d5 | 278 | and does not alter the |
f9db4400 | 279 | members of the broken-down time structure. |
47297adb | 280 | .SH RETURN VALUE |
f5633e8d MK |
281 | On success, |
282 | .BR gmtime () | |
283 | and | |
284 | .BR localtime () | |
285 | return a pointer to a | |
286 | .IR "struct\ tm" . | |
847e0d88 | 287 | .PP |
f5633e8d MK |
288 | On success, |
289 | .BR gmtime_r () | |
290 | and | |
291 | .BR localtime_r () | |
292 | return the address of the structure pointed to by | |
293 | .IR result . | |
847e0d88 | 294 | .PP |
f5633e8d MK |
295 | On success, |
296 | .BR asctime () | |
297 | and | |
298 | .BR ctime () | |
299 | return a pointer to a string. | |
847e0d88 | 300 | .PP |
f5633e8d MK |
301 | On success, |
302 | .BR asctime_r () | |
303 | and | |
304 | .BR ctime_r () | |
305 | return a pointer to the string pointed to by | |
306 | .IR buf . | |
847e0d88 | 307 | .PP |
f5633e8d MK |
308 | On success, |
309 | .BR mktime () | |
d957e9a4 MK |
310 | returns the calendar time (seconds since the Epoch), |
311 | expressed as a value of type | |
f5633e8d | 312 | .IR time_t . |
847e0d88 | 313 | .PP |
f5633e8d MK |
314 | On error, |
315 | .BR mktime () | |
316 | returns the value | |
317 | .IR "(time_t)\ -1" . | |
318 | The remaining functions return NULL on error. | |
319 | On error, | |
320 | .I errno | |
321 | is set to indicate the cause of the error. | |
d957e9a4 MK |
322 | .SH ERRORS |
323 | .TP | |
324 | .B EOVERFLOW | |
1b9d5819 | 325 | The result cannot be represented. |
c8b68136 ZL |
326 | .SH ATTRIBUTES |
327 | For an explanation of the terms used in this section, see | |
328 | .BR attributes (7). | |
74714ea8 | 329 | .ad l |
c8b68136 ZL |
330 | .TS |
331 | allbox; | |
332 | lbw14 lb lbw31 | |
333 | l l l. | |
334 | Interface Attribute Value | |
335 | T{ | |
336 | .BR asctime () | |
337 | T} Thread safety MT-Unsafe race:asctime locale | |
338 | T{ | |
339 | .BR asctime_r () | |
340 | T} Thread safety MT-Safe locale | |
341 | T{ | |
342 | .BR ctime () | |
343 | T} Thread safety T{ | |
344 | MT-Unsafe race:tmbuf | |
345 | .br | |
346 | race:asctime env locale | |
347 | T} | |
348 | T{ | |
349 | .BR ctime_r (), | |
350 | .BR gmtime_r (), | |
351 | .BR localtime_r (), | |
352 | .BR mktime () | |
353 | T} Thread safety MT-Safe env locale | |
354 | T{ | |
355 | .BR gmtime (), | |
356 | .BR localtime () | |
357 | T} Thread safety MT-Unsafe race:tmbuf env locale | |
358 | .TE | |
74714ea8 | 359 | .ad |
47297adb | 360 | .SH CONFORMING TO |
2b2581ee MK |
361 | POSIX.1-2001. |
362 | C89 and C99 specify | |
363 | .BR asctime (), | |
364 | .BR ctime (), | |
365 | .BR gmtime (), | |
366 | .BR localtime (), | |
367 | and | |
44a2c328 | 368 | .BR mktime (). |
ca5711a5 MK |
369 | POSIX.1-2008 marks |
370 | .BR asctime (), | |
371 | .BR asctime_r (), | |
372 | .BR ctime (), | |
373 | and | |
374 | .BR ctime_r () | |
9e36b352 MK |
375 | as obsolete, |
376 | recommending the use of | |
377 | .BR strftime (3) | |
378 | instead. | |
fea681da MK |
379 | .SH NOTES |
380 | The four functions | |
63aa9df0 MK |
381 | .BR asctime (), |
382 | .BR ctime (), | |
383 | .BR gmtime () | |
fea681da | 384 | and |
63aa9df0 | 385 | .BR localtime () |
fea681da | 386 | return a pointer to static data and hence are not thread-safe. |
800a076a | 387 | The thread-safe versions, |
63aa9df0 MK |
388 | .BR asctime_r (), |
389 | .BR ctime_r (), | |
390 | .BR gmtime_r () | |
fea681da | 391 | and |
800a076a MK |
392 | .BR localtime_r (), |
393 | are specified by SUSv2. | |
847e0d88 | 394 | .PP |
8167059b MK |
395 | POSIX.1-2001 says: |
396 | "The | |
397 | .BR asctime (), | |
398 | .BR ctime (), | |
399 | .BR gmtime (), | |
400 | and | |
401 | .BR localtime () | |
402 | functions shall return values in one of two static objects: | |
403 | a broken-down time structure and an array of type | |
404 | .IR char . | |
405 | Execution of any of the functions may overwrite the information returned | |
406 | in either of these objects by any of the other functions." | |
407 | This can occur in the glibc implementation. | |
fea681da | 408 | .LP |
8167059b | 409 | In many implementations, including glibc, a 0 in |
3e53c142 MK |
410 | .I tm_mday |
411 | is interpreted as meaning the last day of the preceding month. | |
412 | .LP | |
0c2ec4f1 | 413 | The glibc version of \fIstruct tm\fP has additional fields |
ba39b288 MK |
414 | .PP |
415 | .in +4n | |
416 | .EX | |
fea681da | 417 | const char *tm_zone; /* Timezone abbreviation */ |
ba39b288 MK |
418 | .EE |
419 | .in | |
420 | .PP | |
db4e96b7 MK |
421 | defined when |
422 | .B _BSD_SOURCE | |
423 | was set before including | |
fea681da MK |
424 | .IR <time.h> . |
425 | This is a BSD extension, present in 4.3BSD-Reno. | |
847e0d88 | 426 | .PP |
7b16ff49 MK |
427 | According to POSIX.1-2004, |
428 | .BR localtime () | |
429 | is required to behave as though | |
0b80cf56 | 430 | .BR tzset (3) |
7b16ff49 MK |
431 | was called, while |
432 | .BR localtime_r () | |
433 | does not have this requirement. | |
434 | .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/ | |
68fc27f7 | 435 | For portable code, |
0b80cf56 | 436 | .BR tzset (3) |
7b16ff49 MK |
437 | should be called before |
438 | .BR localtime_r (). | |
47297adb | 439 | .SH SEE ALSO |
fea681da MK |
440 | .BR date (1), |
441 | .BR gettimeofday (2), | |
442 | .BR time (2), | |
443 | .BR utime (2), | |
444 | .BR clock (3), | |
445 | .BR difftime (3), | |
fea681da MK |
446 | .BR strftime (3), |
447 | .BR strptime (3), | |
7877f012 | 448 | .BR timegm (3), |
eafd5ce1 MK |
449 | .BR tzset (3), |
450 | .BR time (7) |