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