Debian Codegraph @

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