Debian Codegraph @

upstream/fedora-44/man3/ctime.3

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