Debian Codegraph @

upstream/debian-unstable/man3/ctime.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH ctime 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
10 localtime_r \- transform date and time to broken-down time or ASCII
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <time.h>
17 .P
18 .BI "char *asctime(const struct tm *" tm );
19 .BI "char *asctime_r(const struct tm *restrict " tm ,
20 .BI " char " buf "[restrict 26]);"
21 .P
22 .BI "char *ctime(const time_t *" timep );
23 .BI "char *ctime_r(const time_t *restrict " timep ,
24 .BI " char " buf "[restrict 26]);"
25 .P
26 .BI "struct tm *gmtime(const time_t *" timep );
27 .BI "struct tm *gmtime_r(const time_t *restrict " timep ,
28 .BI " struct tm *restrict " result );
29 .P
30 .BI "struct tm *localtime(const time_t *" timep );
31 .BI "struct tm *localtime_r(const time_t *restrict " timep ,
32 .BI " struct tm *restrict " result );
33 .P
34 .BI "time_t mktime(struct tm *" tm );
35 .fi
36 .P
37 .RS -4
38 Feature Test Macro Requirements for glibc (see
39 .BR feature_test_macros (7)):
40 .RE
41 .P
42 .BR asctime_r (),
43 .BR ctime_r (),
44 .BR gmtime_r (),
45 .BR localtime_r ():
46 .nf
47 _POSIX_C_SOURCE
48 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
49 .fi
50 .SH DESCRIPTION
51 The
52 .BR ctime (),
53 .BR gmtime (),
54 and
55 .BR localtime ()
56 functions all take
57 an argument of data type
58 .IR time_t ,
59 which represents calendar time.
60 When interpreted as an absolute time value, it represents the number of
61 seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
62 .P
63 The
64 .BR asctime ()
65 and
66 .BR mktime ()
67 functions both take an argument
68 representing broken-down time, which is a representation
69 separated into year, month, day, and so on.
70 .P
71 Broken-down time is stored in the structure
72 .IR tm ,
73 described in
74 .BR tm (3type).
75 .P
76 The call
77 .BI ctime( t )
78 is equivalent to
79 .IR asctime(localtime(t)) .
80 It converts the calendar time
81 .I t
82 into a
83 null-terminated string of the form
84 .P
85 .in +4n
86 .EX
87 "Wed Jun 30 21:49:08 1993\[rs]n"
88 .EE
89 .in
90 .P
91 The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed",
92 "Thu", "Fri", and "Sat".
93 The abbreviations for the months are "Jan",
94 "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and
95 "Dec".
96 The return value points to a statically allocated string which
97 might be overwritten by subsequent calls to any of the date and time
98 functions.
99 The function also sets the external variables
100 .IR tzname ,
101 .IR timezone ,
102 and
103 .I daylight
104 as if it called
105 .BR tzset (3).
106 The reentrant version
107 .BR ctime_r ()
108 does the same, but stores the
109 string in a user-supplied buffer
110 which should have room for at least 26 bytes.
111 It need not set
112 .IR tzname ,
113 .IR timezone ,
114 and
115 .IR daylight .
116 .P
117 The
118 .BR gmtime ()
119 function converts the calendar time
120 .I timep
121 to broken-down time representation,
122 expressed in Coordinated Universal Time (UTC).
123 It may return NULL when the year does not fit into an integer.
124 The return value points to a statically allocated struct which might be
125 overwritten by subsequent calls to any of the date and time functions.
126 The
127 .BR gmtime_r ()
128 function does the same, but stores the data in a
129 user-supplied struct.
130 .P
131 The
132 .BR localtime ()
133 function converts the calendar time
134 .I timep
135 to broken-down time representation,
136 expressed relative to the user's specified timezone.
137 The function also sets the external variables
138 .IR tzname ,
139 .IR timezone ,
140 and
141 .I daylight
142 as if it called
143 .BR tzset (3).
144 The return value points to a statically allocated struct which might be
145 overwritten by subsequent calls to any of the date and time functions.
146 The
147 .BR localtime_r ()
148 function does the same, but stores the data in a
149 user-supplied struct.
150 It need not set
151 .IR tzname ,
152 .IR timezone ,
153 and
154 .IR daylight .
155 .P
156 The
157 .BR asctime ()
158 function converts the broken-down time value
159 .I tm
160 into a null-terminated string with the same format as
161 .BR ctime ().
162 The return value points to a statically allocated string which might be
163 overwritten by subsequent calls to any of the date and time functions.
164 The
165 .BR asctime_r ()
166 function does the same, but stores the string in
167 a user-supplied buffer which should have room for at least 26 bytes.
168 .P
169 The
170 .BR mktime ()
171 function converts a broken-down time structure, expressed
172 as local time, to calendar time representation.
173 The function ignores
174 the values supplied by the caller in the
175 .I tm_wday
176 and
177 .I tm_yday
178 fields.
179 The value specified in the
180 .I tm_isdst
181 field informs
182 .BR mktime ()
183 whether or not daylight saving time (DST)
184 is in effect for the time supplied in the
185 .I tm
186 structure:
187 a positive value means DST is in effect;
188 zero means that DST is not in effect;
189 and a negative value means that
190 .BR mktime ()
191 should (use timezone information and system databases to)
192 attempt to determine whether DST is in effect at the specified time.
193 See
194 .BR timegm (3)
195 for a UTC equivalent of this function.
196 .P
197 The
198 .BR mktime ()
199 function modifies the fields of the
200 .I tm
201 structure as follows:
202 .I tm_wday
203 and
204 .I tm_yday
205 are set to values determined from the contents of the other fields;
206 if structure members are outside their valid interval, they will be
207 normalized (so that, for example, 40 October is changed into 9 November);
208 .I tm_isdst
209 is set (regardless of its initial value)
210 to a positive value or to 0, respectively,
211 to indicate whether DST is or is not in effect at the specified time.
212 The function also sets the external variables
213 .IR tzname ,
214 .IR timezone ,
215 and
216 .I daylight
217 as if it called
218 .BR tzset (3).
219 .P
220 If the specified broken-down
221 time cannot be represented as calendar time (seconds since the Epoch),
222 .BR mktime ()
223 returns
224 .I (time_t)\ \-1
225 and does not alter the
226 members of the broken-down time structure.
227 .SH RETURN VALUE
228 On success,
229 .BR gmtime ()
230 and
231 .BR localtime ()
232 return a pointer to a
233 .IR "struct\ tm" .
234 .P
235 On success,
236 .BR gmtime_r ()
237 and
238 .BR localtime_r ()
239 return the address of the structure pointed to by
240 .IR result .
241 .P
242 On success,
243 .BR asctime ()
244 and
245 .BR ctime ()
246 return a pointer to a string.
247 .P
248 On success,
249 .BR asctime_r ()
250 and
251 .BR ctime_r ()
252 return a pointer to the string pointed to by
253 .IR buf .
254 .P
255 On success,
256 .BR mktime ()
257 returns the calendar time (seconds since the Epoch),
258 expressed as a value of type
259 .IR time_t .
260 .P
261 On error,
262 .BR mktime ()
263 returns the value
264 .IR "(time_t)\ \-1" ,
265 and leaves the
266 .I tm->tm_wday
267 member unmodified.
268 The remaining functions return NULL on error.
269 On error,
270 .I errno
271 is set to indicate the error.
272 .SH ERRORS
273 .TP
274 .B EOVERFLOW
275 The result cannot be represented.
276 .SH ATTRIBUTES
277 For an explanation of the terms used in this section, see
278 .BR attributes (7).
279 .TS
280 allbox;
281 lb lb lbx
282 l l l.
283 Interface Attribute Value
284 T{
285 .na
286 .nh
287 .BR asctime ()
288 T} Thread safety T{
289 .na
290 .nh
291 MT-Unsafe race:asctime locale
292 T}
293 T{
294 .na
295 .nh
296 .BR asctime_r ()
297 T} Thread safety T{
298 .na
299 .nh
300 MT-Safe locale
301 T}
302 T{
303 .na
304 .nh
305 .BR ctime ()
306 T} Thread safety T{
307 .na
308 .nh
309 MT-Unsafe race:tmbuf
310 race:asctime env locale
311 T}
312 T{
313 .na
314 .nh
315 .BR ctime_r (),
316 .BR gmtime_r (),
317 .BR localtime_r (),
318 .BR mktime ()
319 T} Thread safety T{
320 .na
321 .nh
322 MT-Safe env locale
323 T}
324 T{
325 .na
326 .nh
327 .BR gmtime (),
328 .BR localtime ()
329 T} Thread safety T{
330 .na
331 .nh
332 MT-Unsafe race:tmbuf env locale
333 T}
334 .TE
335 .SH VERSIONS
336 POSIX doesn't specify the parameters of
337 .BR ctime_r ()
338 to be
339 .IR restrict ;
340 that is specific to glibc.
341 .P
342 In many implementations, including glibc, a 0 in
343 .I tm_mday
344 is interpreted as meaning the last day of the preceding month.
345 .P
346 According to POSIX.1,
347 .BR localtime ()
348 is required to behave as though
349 .BR tzset (3)
350 was called, while
351 .BR localtime_r ()
352 does not have this requirement.
353 .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/
354 For portable code,
355 .BR tzset (3)
356 should be called before
357 .BR localtime_r ().
358 .SH STANDARDS
359 .TP
360 .BR asctime ()
361 .TQ
362 .BR ctime ()
363 .TQ
364 .BR gmtime ()
365 .TQ
366 .BR localtime ()
367 .TQ
368 .BR mktime ()
369 C23, POSIX.1-2024.
370 .TP
371 .BR gmtime_r ()
372 .TQ
373 .BR localtime_r ()
374 POSIX.1-2024.
375 .TP
376 .BR asctime_r ()
377 .TQ
378 .BR ctime_r ()
379 None.
380 .SH HISTORY
381 .TP
382 .BR gmtime ()
383 .TQ
384 .BR localtime ()
385 .TQ
386 .BR mktime ()
387 C89, POSIX.1-1988.
388 .TP
389 .BR asctime ()
390 .TQ
391 .BR ctime ()
392 C89, POSIX.1-1988.
393 Marked obsolescent in C23 and in POSIX.1-2008 (recommending
394 .BR strftime (3)).
395 .TP
396 .BR gmtime_r ()
397 .TQ
398 .BR localtime_r ()
399 POSIX.1-1996.
400 .TP
401 .BR asctime_r ()
402 .TQ
403 .BR ctime_r ()
404 POSIX.1-1996.
405 Marked obsolescent in POSIX.1-2008.
406 Removed in POSIX.1-2024 (recommending
407 .BR strftime (3)).
408 .SH CAVEATS
409 .SS Thread safety
410 The four functions
411 .BR asctime (),
412 .BR ctime (),
413 .BR gmtime (),
414 and
415 .BR localtime ()
416 return a pointer to static data and hence are not thread-safe.
417 The thread-safe versions,
418 .BR asctime_r (),
419 .BR ctime_r (),
420 .BR gmtime_r (),
421 and
422 .BR localtime_r (),
423 are specified by SUSv2.
424 .P
425 POSIX.1 says:
426 "The
427 .BR asctime (),
428 .BR ctime (),
429 .BR gmtime (),
430 and
431 .BR localtime ()
432 functions shall return values in one of two static objects:
433 a broken-down time structure and an array of type
434 .IR char .
435 Execution of any of the functions that return a pointer to one of these
436 object types may overwrite the information in any object of the same type
437 pointed to by the value returned from any previous call to any of them."
438 This can occur in the glibc implementation.
439 .SS mktime()
440 .I (time_t) \-1
441 can represent a valid time
442 (one second before the Epoch).
443 To determine whether
444 .BR mktime ()
445 failed,
446 one must use the
447 .I tm->tm_wday
448 field.
449 See the example program in EXAMPLES.
450 .P
451 The handling of a non-negative
452 .I tm_isdst
453 in
454 .BR mktime ()
455 is poorly specified,
456 and passing a value that is incorrect for the time specified
457 yields unspecified results.
458 Since
459 .BR mktime ()
460 is one of the few functions that knows when DST is in effect,
461 providing a correct value may be difficult.
462 One workaround for this is to call
463 .BR mktime ()
464 twice,
465 once with
466 .I tm_isdst
467 set to zero,
468 and once with
469 .I tm_isdst
470 set to a positive value,
471 and discarding the results from the call that changes it.
472 If neither call changes
473 .I tm_isdst
474 then the time specified probably happens during a fall-back period
475 where DST begins or ends,
476 and both results are valid
477 but represent two different times.
478 If both calls change it, that could indicate a fall-forward transition,
479 or some other reason why the time specified does not exist.
480 .P
481 The specification of time zones and daylight saving time
482 are up to regional governments, change often,
483 and may include discontinuities beyond
484 .IR mktime 's
485 ability to document a result.
486 For example, a change in the timezone definition
487 may cause a clock time to be repeated or skipped
488 without a corresponding DST change.
489 .SH EXAMPLES
490 The program below defines a wrapper that
491 allows detecting invalid and ambiguous times,
492 with
493 .B EINVAL
494 and
495 .BR ENOTUNIQ ,
496 respectively.
497 .P
498 The following shell session shows sample runs of the program:
499 .P
500 .in +4n
501 .EX
502 .RB $\~ "TZ=UTC ./a.out 1969 12 31 23 59 59 0" ;
503 \-1
504 $
505 .RB $\~ "export TZ=Europe/Madrid" ;
506 $
507 .RB $\~ "./a.out 2147483647 2147483647 00 00 00 00 \-1" ;
508 a.out: mktime: Value too large for defined data type
509 $
510 .RB $\~ "./a.out 2024 08 23 00 17 53 \-1" ;
511 1724365073
512 .RB $\~ "./a.out 2024 08 23 00 17 53 0" ;
513 a.out: my_mktime: Invalid argument
514 1724368673
515 .RB $\~ "./a.out 2024 08 23 00 17 53 1" ;
516 1724365073
517 $
518 .RB $\~ "./a.out 2024 02 23 00 17 53 \-1" ;
519 1708643873
520 .RB $\~ "./a.out 2024 02 23 00 17 53 0" ;
521 1708643873
522 .RB $\~ "./a.out 2024 02 23 00 17 53 1" ;
523 a.out: my_mktime: Invalid argument
524 1708640273
525 $
526 .RB $\~ "./a.out 2023 03 26 02 17 53 \-1" ;
527 a.out: my_mktime: Invalid argument
528 1679793473
529 $
530 .RB $\~ "./a.out 2023 10 29 02 17 53 \-1" ;
531 a.out: my_mktime: Name not unique on network
532 1698542273
533 .RB $\~ "./a.out 2023 10 29 02 17 53 0" ;
534 1698542273
535 .RB $\~ "./a.out 2023 10 29 02 17 53 1" ;
536 1698538673
537 $
538 .RB $\~ "./a.out 2023 02 29 12 00 00 \-1" ;
539 a.out: my_mktime: Invalid argument
540 1677668400
541 .EE
542 .SS Program source: mktime.c
543 \&
544 .\" SRC BEGIN (mktime.c)
545 .EX
546 #include <err.h>
547 #include <errno.h>
548 #include <stdint.h>
549 #include <stdio.h>
550 #include <stdlib.h>
551 #include <string.h>
552 #include <time.h>
553 \&
554 #define is_signed(T) ((T) \-1 < 1)
555 \&
556 static time_t my_mktime(struct tm *tp);
557 \&
558 int
559 main(int argc, char *argv[])
560 {
561 char **p;
562 time_t t;
563 struct tm tm;
564 \&
565 if (argc != 8) {
566 fprintf(stderr, "Usage: %s yyyy mm dd HH MM SS isdst\[rs]n", argv[0]);
567 exit(EXIT_FAILURE);
568 }
569 \&
570 p = &argv[1];
571 tm.tm_year = atoi(*p++) \- 1900;
572 tm.tm_mon = atoi(*p++) \- 1;
573 tm.tm_mday = atoi(*p++);
574 tm.tm_hour = atoi(*p++);
575 tm.tm_min = atoi(*p++);
576 tm.tm_sec = atoi(*p++);
577 tm.tm_isdst = atoi(*p++);
578 \&
579 errno = 0;
580 tm.tm_wday = \-1;
581 t = my_mktime(&tm);
582 if (tm.tm_wday == \-1)
583 err(EXIT_FAILURE, "mktime");
584 if (errno == EINVAL || errno == ENOTUNIQ)
585 warn("my_mktime");
586 \&
587 if (is_signed(time_t))
588 printf("%jd\[rs]n", (intmax_t) t);
589 else
590 printf("%ju\[rs]n", (uintmax_t) t);
591 \&
592 exit(EXIT_SUCCESS);
593 }
594 \&
595 static time_t
596 my_mktime(struct tm *tp)
597 {
598 int e, isdst;
599 time_t t;
600 struct tm tm;
601 unsigned char wday[sizeof(tp\->tm_wday)];
602 \&
603 e = errno;
604 \&
605 tm = *tp;
606 isdst = tp\->tm_isdst;
607 \&
608 memcpy(wday, &tp\->tm_wday, sizeof(wday));
609 tp\->tm_wday = \-1;
610 t = mktime(tp);
611 if (tp\->tm_wday == \-1) {
612 memcpy(&tp\->tm_wday, wday, sizeof(wday));
613 return \-1;
614 }
615 \&
616 if (isdst == \-1)
617 tm.tm_isdst = tp\->tm_isdst;
618 \&
619 if ( tm.tm_sec != tp\->tm_sec
620 || tm.tm_min != tp\->tm_min
621 || tm.tm_hour != tp\->tm_hour
622 || tm.tm_mday != tp\->tm_mday
623 || tm.tm_mon != tp\->tm_mon
624 || tm.tm_year != tp\->tm_year
625 || tm.tm_isdst != tp\->tm_isdst)
626 {
627 errno = EINVAL;
628 return t;
629 }
630 \&
631 if (isdst != \-1)
632 goto out;
633 \&
634 tm = *tp;
635 tm.tm_isdst = !tm.tm_isdst;
636 \&
637 tm.tm_wday = \-1;
638 mktime(&tm);
639 if (tm.tm_wday == \-1)
640 goto out;
641 \&
642 if (tm.tm_isdst != tp\->tm_isdst) {
643 errno = ENOTUNIQ;
644 return t;
645 }
646 out:
647 errno = e;
648 return t;
649 }
650 .EE
651 .\" SRC END
652 .SH SEE ALSO
653 .BR date (1),
654 .BR gettimeofday (2),
655 .BR time (2),
656 .BR utime (2),
657 .BR clock (3),
658 .BR difftime (3),
659 .BR strftime (3),
660 .BR strptime (3),
661 .BR timegm (3),
662 .BR tzset (3),
663 .BR time (7)