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