Debian Codegraph @

upstream/debian-trixie/man3/strftime.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 .\" GNU texinfo documentation on glibc date/time functions.
11 .\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith ([email protected])
12 .\" Applied fix by Wolfgang Franke, aeb, 961011
13 .\" Corrected return value, aeb, 970307
14 .\" Added Single UNIX Spec conversions and %z, aeb/esr, 990329.
15 .\" 2005-11-22 mtk, added glibc Notes covering optional 'flag' and
16 .\" 'width' components of conversion specifications.
17 .\"
18 .TH strftime 3 2024-06-15 "Linux man-pages 6.9.1"
19 .SH NAME
20 strftime \- format date and time
21 .SH LIBRARY
22 Standard C library
23 .RI ( libc ", " \-lc )
24 .SH SYNOPSIS
25 .nf
26 .B #include <time.h>
27 .P
28 .BI "size_t strftime(char " s "[restrict ." max "], size_t " max ,
29 .BI " const char *restrict " format ,
30 .BI " const struct tm *restrict " tm );
31 .P
32 .BI "size_t strftime_l(char " s "[restrict ." max "], size_t " max ,
33 .BI " const char *restrict " format ,
34 .BI " const struct tm *restrict " tm ,
35 .BI " locale_t " locale );
36 .fi
37 .SH DESCRIPTION
38 The
39 .BR strftime ()
40 function formats the broken-down time
41 .I tm
42 according to the format specification
43 .I format
44 and places the
45 result in the character array
46 .I s
47 of size
48 .IR max .
49 The broken-down time structure
50 .I tm
51 is defined in
52 .IR <time.h> .
53 See also
54 .BR ctime (3).
55 .\" FIXME . POSIX says: Local timezone information is used as though
56 .\" strftime() called tzset(). But this doesn't appear to be the case
57 .P
58 The format specification is a null-terminated string and may contain
59 special character sequences called
60 .IR "conversion specifications",
61 each of which is introduced by a \[aq]%\[aq] character and terminated by
62 some other character known as a
63 .IR "conversion specifier character".
64 All other character sequences are
65 .IR "ordinary character sequences".
66 .P
67 The characters of ordinary character sequences (including the null byte)
68 are copied verbatim from
69 .I format
70 to
71 .IR s .
72 However, the characters
73 of conversion specifications are replaced as shown in the list below.
74 In this list, the field(s) employed from the
75 .I tm
76 structure are also shown.
77 .TP
78 .B %a
79 The abbreviated name of the day of the week according to the current locale.
80 (Calculated from
81 .IR tm_wday .)
82 (The specific names used in the current locale can be obtained by calling
83 .BR nl_langinfo (3)
84 with
85 .BR ABDAY_ { 1 \[en] 7 }
86 as an argument.)
87 .TP
88 .B %A
89 The full name of the day of the week according to the current locale.
90 (Calculated from
91 .IR tm_wday .)
92 (The specific names used in the current locale can be obtained by calling
93 .BR nl_langinfo (3)
94 with
95 .BR DAY_ { 1 \[en] 7 }
96 as an argument.)
97 .TP
98 .B %b
99 The abbreviated month name according to the current locale.
100 (Calculated from
101 .IR tm_mon .)
102 (The specific names used in the current locale can be obtained by calling
103 .BR nl_langinfo (3)
104 with
105 .BR ABMON_ { 1 \[en] 12 }
106 as an argument.)
107 .TP
108 .B %B
109 The full month name according to the current locale.
110 (Calculated from
111 .IR tm_mon .)
112 (The specific names used in the current locale can be obtained by calling
113 .BR nl_langinfo (3)
114 with
115 .BR MON_ { 1 \[en] 12 }
116 as an argument.)
117 .TP
118 .B %c
119 The preferred date and time representation for the current locale.
120 (The specific format used in the current locale can be obtained by calling
121 .BR nl_langinfo (3)
122 with
123 .B D_T_FMT
124 as an argument for the
125 .B %c
126 conversion specification, and with
127 .B ERA_D_T_FMT
128 for the
129 .B %Ec
130 conversion specification.)
131 (In the POSIX locale this is equivalent to
132 .BR "%a %b %e %H:%M:%S %Y" .)
133 .TP
134 .B %C
135 The century number (year/100) as a 2-digit integer. (SU)
136 (The
137 .B %EC
138 conversion specification corresponds to the name of the era.)
139 (Calculated from
140 .IR tm_year .)
141 .TP
142 .B %d
143 The day of the month as a decimal number (range 01 to 31).
144 (Calculated from
145 .IR tm_mday .)
146 .TP
147 .B %D
148 Equivalent to
149 .BR %m/%d/%y .
150 (Yecch\[em]for Americans only.
151 Americans should note that in other countries
152 .B %d/%m/%y
153 is rather common.
154 This means that in international context this format is
155 ambiguous and should not be used.) (SU)
156 .TP
157 .B %e
158 Like
159 .BR %d ,
160 the day of the month as a decimal number, but a leading
161 zero is replaced by a space. (SU)
162 (Calculated from
163 .IR tm_mday .)
164 .TP
165 .B %E
166 Modifier: use alternative ("era-based") format, see below. (SU)
167 .TP
168 .B %F
169 Equivalent to
170 .B %Y\-%m\-%d
171 (the ISO\~8601 date format). (C99)
172 .TP
173 .B %G
174 The ISO\~8601 week-based year (see NOTES) with century as a decimal number.
175 The 4-digit year corresponding to the ISO week number (see
176 .BR %V ).
177 This has the same format and value as
178 .BR %Y ,
179 except that if the ISO week number belongs to the previous or next year,
180 that year is used instead. (TZ)
181 (Calculated from
182 .IR tm_year ,
183 .IR tm_yday ,
184 and
185 .IR tm_wday .)
186 .TP
187 .B %g
188 Like
189 .BR %G ,
190 but without century, that is, with a 2-digit year (00\[en]99). (TZ)
191 (Calculated from
192 .IR tm_year ,
193 .IR tm_yday ,
194 and
195 .IR tm_wday .)
196 .TP
197 .B %h
198 Equivalent to
199 .BR %b .
200 (SU)
201 .TP
202 .B %H
203 The hour as a decimal number using a 24-hour clock (range 00 to 23).
204 (Calculated from
205 .IR tm_hour .)
206 .TP
207 .B %I
208 The hour as a decimal number using a 12-hour clock (range 01 to 12).
209 (Calculated from
210 .IR tm_hour .)
211 .TP
212 .B %j
213 The day of the year as a decimal number (range 001 to 366).
214 (Calculated from
215 .IR tm_yday .)
216 .TP
217 .B %k
218 The hour (24-hour clock) as a decimal number (range 0 to 23);
219 single digits are preceded by a blank.
220 (See also
221 .BR %H .)
222 (Calculated from
223 .IR tm_hour .)
224 (TZ)
225 .TP
226 .B %l
227 The hour (12-hour clock) as a decimal number (range 1 to 12);
228 single digits are preceded by a blank.
229 (See also
230 .BR %I .)
231 (Calculated from
232 .IR tm_hour .)
233 (TZ)
234 .TP
235 .B %m
236 The month as a decimal number (range 01 to 12).
237 (Calculated from
238 .IR tm_mon .)
239 .TP
240 .B %M
241 The minute as a decimal number (range 00 to 59).
242 (Calculated from
243 .IR tm_min .)
244 .TP
245 .B %n
246 A newline character. (SU)
247 .TP
248 .B %O
249 Modifier: use alternative numeric symbols, see below. (SU)
250 .TP
251 .B %p
252 Either "AM" or "PM" according to the given time value, or the
253 corresponding strings for the current locale.
254 Noon is treated as "PM" and midnight as "AM".
255 (Calculated from
256 .IR tm_hour .)
257 (The specific string representations used for "AM" and "PM"
258 in the current locale can be obtained by calling
259 .BR nl_langinfo (3)
260 with
261 .BR AM_STR " and " PM_STR ,
262 respectively.)
263 .TP
264 .B %P
265 Like
266 .B %p
267 but in lowercase: "am" or "pm" or a corresponding
268 string for the current locale.
269 (Calculated from
270 .IR tm_hour .)
271 (GNU)
272 .TP
273 .B %r
274 The time in a.m. or p.m. notation.
275 (SU)
276 (The specific format used in the current locale can be obtained by calling
277 .BR nl_langinfo (3)
278 with
279 .B T_FMT_AMPM
280 as an argument.)
281 (In the POSIX locale this is equivalent to
282 .BR "%I:%M:%S %p" .)
283 .TP
284 .B %R
285 The time in 24-hour notation
286 .RB ( %H:%M ).
287 (SU)
288 For a version including the seconds, see
289 .B %T
290 below.
291 .TP
292 .B %s
293 The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)
294 (Calculated from
295 .IR mktime(tm) .)
296 .TP
297 .B %S
298 The second as a decimal number (range 00 to 60).
299 (The range is up to 60 to allow for occasional leap seconds.)
300 (Calculated from
301 .IR tm_sec .)
302 .TP
303 .B %t
304 A tab character. (SU)
305 .TP
306 .B %T
307 The time in 24-hour notation
308 .RB ( %H:%M:%S ).
309 (SU)
310 .TP
311 .B %u
312 The day of the week as a decimal, range 1 to 7, Monday being 1.
313 See also
314 .BR %w .
315 (Calculated from
316 .IR tm_wday .)
317 (SU)
318 .TP
319 .B %U
320 The week number of the current year as a decimal number,
321 range 00 to 53, starting with the first Sunday as the first day
322 of week 01.
323 See also
324 .B %V
325 and
326 .BR %W .
327 (Calculated from
328 .I tm_yday
329 and
330 .IR tm_wday .)
331 .TP
332 .B %V
333 The ISO\~8601 week number (see NOTES) of the current year as a decimal number,
334 range 01 to 53, where week 1 is the first week that has at least
335 4 days in the new year.
336 See also
337 .B %U
338 and
339 .BR %W .
340 (Calculated from
341 .IR tm_year ,
342 .IR tm_yday ,
343 and
344 .IR tm_wday .)
345 (SU)
346 .TP
347 .B %w
348 The day of the week as a decimal, range 0 to 6, Sunday being 0.
349 See also
350 .BR %u .
351 (Calculated from
352 .IR tm_wday .)
353 .TP
354 .B %W
355 The week number of the current year as a decimal number,
356 range 00 to 53, starting with the first Monday as the first day of week 01.
357 (Calculated from
358 .I tm_yday
359 and
360 .IR tm_wday .)
361 .TP
362 .B %x
363 The preferred date representation for the current locale without the time.
364 (The specific format used in the current locale can be obtained by calling
365 .BR nl_langinfo (3)
366 with
367 .B D_FMT
368 as an argument for the
369 .B %x
370 conversion specification, and with
371 .B ERA_D_FMT
372 for the
373 .B %Ex
374 conversion specification.)
375 (In the POSIX locale this is equivalent to
376 .BR %m/%d/%y .)
377 .TP
378 .B %X
379 The preferred time representation for the current locale without the date.
380 (The specific format used in the current locale can be obtained by calling
381 .BR nl_langinfo (3)
382 with
383 .B T_FMT
384 as an argument for the
385 .B %X
386 conversion specification, and with
387 .B ERA_T_FMT
388 for the
389 .B %EX
390 conversion specification.)
391 (In the POSIX locale this is equivalent to
392 .BR %H:%M:%S .)
393 .TP
394 .B %y
395 The year as a decimal number without a century (range 00 to 99).
396 (The
397 .B %Ey
398 conversion specification corresponds to the year since the beginning of the era
399 denoted by the
400 .B %EC
401 conversion specification.)
402 (Calculated from
403 .IR tm_year )
404 .TP
405 .B %Y
406 The year as a decimal number including the century.
407 (The
408 .B %EY
409 conversion specification corresponds to
410 the full alternative year representation.)
411 (Calculated from
412 .IR tm_year )
413 .TP
414 .B %z
415 The
416 .I +hhmm
417 or
418 .I \-hhmm
419 numeric timezone (that is, the hour and minute offset from UTC). (SU)
420 .TP
421 .B %Z
422 The timezone name or abbreviation.
423 .TP
424 .B %+
425 .\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
426 .\" their man pages)
427 The date and time in
428 .BR date (1)
429 format. (TZ)
430 (Not supported in glibc2.)
431 .TP
432 .B %%
433 A literal \[aq]%\[aq] character.
434 .P
435 Some conversion specifications can be modified by preceding the
436 conversion specifier character by the
437 .B E
438 or
439 .B O
440 .I modifier
441 to indicate that an alternative format should be used.
442 If the alternative format or specification does not exist for
443 the current locale, the behavior will be as if the unmodified
444 conversion specification were used. (SU)
445 The Single UNIX Specification mentions
446 .BR %Ec ,
447 .BR %EC ,
448 .BR %Ex ,
449 .BR %EX ,
450 .BR %Ey ,
451 .BR %EY ,
452 .BR %Od ,
453 .BR %Oe ,
454 .BR %OH ,
455 .BR %OI ,
456 .BR %Om ,
457 .BR %OM ,
458 .BR %OS ,
459 .BR %Ou ,
460 .BR %OU ,
461 .BR %OV ,
462 .BR %Ow ,
463 .BR %OW ,
464 .BR %Oy ,
465 where the effect of the
466 .B O
467 modifier is to use
468 alternative numeric symbols (say, roman numerals), and that of the
469 .B E
470 modifier is to use a locale-dependent alternative representation.
471 The rules governing date representation with the
472 .B E
473 modifier can be obtained by supplying
474 .B ERA
475 as an argument to a
476 .BR nl_langinfo (3).
477 One example of such alternative forms is the Japanese era calendar scheme in the
478 .B ja_JP
479 glibc locale.
480 .P
481 .BR strftime_l ()
482 is equivalent to
483 .BR strftime (),
484 except it uses the specified
485 .I locale
486 instead of the current locale.
487 The behaviour is undefined if
488 .I locale
489 is invalid or
490 .BR LC_GLOBAL_LOCALE .
491 .SH RETURN VALUE
492 Provided that the result string,
493 including the terminating null byte, does not exceed
494 .I max
495 bytes,
496 .BR strftime ()
497 returns the number of bytes (excluding the terminating null byte)
498 placed in the array
499 .IR s .
500 If the length of the result string (including the terminating null byte)
501 would exceed
502 .I max
503 bytes, then
504 .BR strftime ()
505 returns 0, and the contents of the array are undefined.
506 .\" (This behavior applies since at least libc 4.4.4;
507 .\" very old versions of libc, such as libc 4.4.1,
508 .\" would return
509 .\" .I max
510 .\" if the array was too small.)
511 .P
512 Note that the return value 0 does not necessarily indicate an error.
513 For example, in many locales
514 .B %p
515 yields an empty string.
516 An empty
517 .I format
518 string will likewise yield an empty string.
519 .SH ENVIRONMENT
520 The environment variables
521 .B TZ
522 and
523 .B LC_TIME
524 are used.
525 .SH ATTRIBUTES
526 For an explanation of the terms used in this section, see
527 .BR attributes (7).
528 .TS
529 allbox;
530 lbx lb lb
531 l l l.
532 Interface Attribute Value
533 T{
534 .na
535 .nh
536 .BR strftime (),
537 .BR strftime_l ()
538 T} Thread safety MT-Safe env locale
539 .TE
540 .SH STANDARDS
541 .TP
542 .BR strftime ()
543 C11, POSIX.1-2008.
544 .TP
545 .BR strftime_l ()
546 POSIX.1-2008.
547 .SH HISTORY
548 .TP
549 .BR strftime ()
550 SVr4, C89.
551 .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
552 .\" in the standards changed across versions. Investigate and
553 .\" write up.
554 .TP
555 .BR strftime_l ()
556 POSIX.1-2008.
557 .P
558 There are strict inclusions between the set of conversions
559 given in ANSI C (unmarked), those given in the Single UNIX Specification
560 (marked SU), those given in Olson's timezone package (marked TZ),
561 and those given in glibc (marked GNU), except that
562 .B %+
563 is not supported in glibc2.
564 On the other hand glibc2 has several more extensions.
565 POSIX.1 only refers to ANSI C; POSIX.2 describes under
566 .BR date (1)
567 several extensions that could apply to
568 .BR strftime ()
569 as well.
570 The
571 .B %F
572 conversion is in C99 and POSIX.1-2001.
573 .P
574 In SUSv2, the
575 .B %S
576 specifier allowed a range of 00 to 61,
577 to allow for the theoretical possibility of a minute that
578 included a double leap second
579 (there never has been such a minute).
580 .SH NOTES
581 .SS ISO\~8601 week dates
582 .BR %G ,
583 .BR %g ,
584 and
585 .B %V
586 yield values calculated from the week-based year defined by the
587 ISO\~8601 standard.
588 In this system, weeks start on a Monday, and are numbered from 01,
589 for the first week, up to 52 or 53, for the last week.
590 Week 1 is the first week where four or more days fall within the
591 new year (or, synonymously, week 01 is:
592 the first week of the year that contains a Thursday;
593 or, the week that has 4 January in it).
594 When three or fewer days of the first calendar week of the new year fall
595 within that year,
596 then the ISO\~8601 week-based system counts those days as part of week 52
597 or 53 of the preceding year.
598 For example, 1 January 2010 is a Friday,
599 meaning that just three days of that calendar week fall in 2010.
600 Thus, the ISO\~8601 week-based system considers these days to be part of
601 week 53
602 .RB ( %V )
603 of the year 2009
604 .RB ( %G );
605 week 01 of ISO\~8601 year 2010 starts on Monday, 4 January 2010.
606 Similarly, the first two days of January 2011 are considered to be part
607 of week 52 of the year 2010.
608 .SS glibc notes
609 glibc provides some extensions for conversion specifications.
610 (These extensions are not specified in POSIX.1-2001, but a few other
611 systems provide similar features.)
612 .\" HP-UX and Tru64 also have features like this.
613 Between the \[aq]%\[aq] character and the conversion specifier character,
614 an optional
615 .I flag
616 and field
617 .I width
618 may be specified.
619 (These precede the
620 .B E
621 or
622 .B O
623 modifiers, if present.)
624 .P
625 The following flag characters are permitted:
626 .TP
627 .B _
628 (underscore)
629 Pad a numeric result string with spaces.
630 .TP
631 .B \-
632 (dash)
633 Do not pad a numeric result string.
634 .TP
635 .B 0
636 Pad a numeric result string with zeros even if the conversion
637 specifier character uses space-padding by default.
638 .TP
639 .B \[ha]
640 Convert alphabetic characters in result string to uppercase.
641 .TP
642 .B #
643 Swap the case of the result string.
644 (This flag works only with certain conversion specifier characters,
645 and of these, it is only really useful with
646 .BR %Z .)
647 .P
648 An optional decimal width specifier may follow the (possibly absent) flag.
649 If the natural size of the field is smaller than this width,
650 then the result string is padded (on the left) to the specified width.
651 .SH BUGS
652 If the output string would exceed
653 .I max
654 bytes,
655 .I errno
656 is
657 .I not
658 set.
659 This makes it impossible to distinguish this error case from cases where the
660 .I format
661 string legitimately produces a zero-length output string.
662 POSIX.1-2001
663 does
664 .I not
665 specify any
666 .I errno
667 settings for
668 .BR strftime ().
669 .P
670 Some buggy versions of
671 .BR gcc (1)
672 complain about the use of
673 .BR %c :
674 .IR "warning: \`%c\[aq] yields only last 2 digits of year in some locales" .
675 Of course programmers are encouraged to use
676 .BR %c ,
677 as it gives the preferred date and time representation.
678 One meets all kinds of strange obfuscations
679 to circumvent this
680 .BR gcc (1)
681 problem.
682 A relatively clean one is to add an
683 intermediate function
684 .P
685 .in +4n
686 .EX
687 size_t
688 my_strftime(char *s, size_t max, const char *fmt,
689 const struct tm *tm)
690 {
691 return strftime(s, max, fmt, tm);
692 }
693 .EE
694 .in
695 .P
696 Nowadays,
697 .BR gcc (1)
698 provides the
699 .I \-Wno\-format\-y2k
700 option to prevent the warning,
701 so that the above workaround is no longer required.
702 .SH EXAMPLES
703 .B RFC\~2822-compliant date format
704 (with an English locale for %a and %b)
705 .P
706 .in +4n
707 .EX
708 "%a,\ %d\ %b\ %Y\ %T\ %z"
709 .EE
710 .in
711 .P
712 .B RFC\~822-compliant date format
713 (with an English locale for %a and %b)
714 .P
715 .in +4n
716 .EX
717 "%a,\ %d\ %b\ %y\ %T\ %z"
718 .EE
719 .in
720 .SS Example program
721 The program below can be used to experiment with
722 .BR strftime ().
723 .P
724 Some examples of the result string produced by the glibc implementation of
725 .BR strftime ()
726 are as follows:
727 .P
728 .in +4n
729 .EX
730 .RB "$" " ./a.out \[aq]%m\[aq]"
731 Result string is "11"
732 .RB "$" " ./a.out \[aq]%5m\[aq]"
733 Result string is "00011"
734 .RB "$" " ./a.out \[aq]%_5m\[aq]"
735 Result string is " 11"
736 .EE
737 .in
738 .SS Program source
739 \&
740 .\" SRC BEGIN (strftime.c)
741 .EX
742 #include <stdio.h>
743 #include <stdlib.h>
744 #include <time.h>
745 \&
746 int
747 main(int argc, char *argv[])
748 {
749 char outstr[200];
750 time_t t;
751 struct tm *tmp;
752 \&
753 t = time(NULL);
754 tmp = localtime(&t);
755 if (tmp == NULL) {
756 perror("localtime");
757 exit(EXIT_FAILURE);
758 }
759 \&
760 if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
761 fprintf(stderr, "strftime returned 0");
762 exit(EXIT_FAILURE);
763 }
764 \&
765 printf("Result string is \[rs]"%s\[rs]"\[rs]n", outstr);
766 exit(EXIT_SUCCESS);
767 }
768 .EE
769 .\" SRC END
770 .SH SEE ALSO
771 .BR date (1),
772 .BR time (2),
773 .BR ctime (3),
774 .BR nl_langinfo (3),
775 .BR setlocale (3),
776 .BR sprintf (3),
777 .BR strptime (3)