1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
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.
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.
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" References consulted:
26 .\" Linux libc source code
27 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
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.
37 .TH STRFTIME 3 2019-03-06 "GNU" "Linux Programmer's Manual"
39 strftime \- format date and time
44 .BI "size_t strftime(char *" s ", size_t " max ", const char *" format ,
45 .BI " const struct tm *" tm );
50 function formats the broken-down time
52 according to the format specification
55 result in the character array
59 The broken-down time structure
65 .\" FIXME . POSIX says: Local timezone information is used as though
66 .\" strftime() called tzset(). But this doesn't appear to be the case
68 The format specification is a null-terminated string and may contain
69 special character sequences called
70 .IR "conversion specifications",
71 each of which is introduced by a \(aq%\(aq character and terminated by
72 some other character known as a
73 .IR "conversion specifier character".
74 All other character sequences are
75 .IR "ordinary character sequences".
77 The characters of ordinary character sequences (including the null byte)
78 are copied verbatim from
82 However, the characters
83 of conversion specifications are replaced as shown in the list below.
84 In this list, the field(s) employed from the
86 structure are also shown.
89 The abbreviated name of the day of the week according to the current locale.
94 The full name of the day of the week according to the current locale.
99 The abbreviated month name according to the current locale.
104 The full month name according to the current locale.
109 The preferred date and time representation for the current locale.
112 The century number (year/100) as a 2-digit integer. (SU)
117 The day of the month as a decimal number (range 01 to 31).
124 (Yecch\(emfor Americans only.
125 Americans should note that in other countries
128 This means that in international context this format is
129 ambiguous and should not be used.) (SU)
134 the day of the month as a decimal number, but a leading
135 zero is replaced by a space. (SU)
140 Modifier: use alternative format, see below. (SU)
145 (the ISO\ 8601 date format). (C99)
148 The ISO\ 8601 week-based year (see NOTES) with century as a decimal number.
149 The 4-digit year corresponding to the ISO week number (see
151 This has the same format and value as
153 except that if the ISO week number belongs to the previous or next year,
154 that year is used instead. (TZ)
164 but without century, that is, with a 2-digit year (00\(en99). (TZ)
177 The hour as a decimal number using a 24-hour clock (range 00 to 23).
182 The hour as a decimal number using a 12-hour clock (range 01 to 12).
187 The day of the year as a decimal number (range 001 to 366).
192 The hour (24-hour clock) as a decimal number (range 0 to 23);
193 single digits are preceded by a blank.
201 The hour (12-hour clock) as a decimal number (range 1 to 12);
202 single digits are preceded by a blank.
210 The month as a decimal number (range 01 to 12).
215 The minute as a decimal number (range 00 to 59).
220 A newline character. (SU)
223 Modifier: use alternative format, see below. (SU)
226 Either "AM" or "PM" according to the given time value, or the
227 corresponding strings for the current locale.
228 Noon is treated as "PM" and midnight as "AM".
235 but in lowercase: "am" or "pm" or a corresponding
236 string for the current locale.
242 The time in a.m. or p.m. notation.
243 In the POSIX locale this is equivalent to
248 The time in 24-hour notation
251 For a version including the seconds, see
256 The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)
261 The second as a decimal number (range 00 to 60).
262 (The range is up to 60 to allow for occasional leap seconds.)
267 A tab character. (SU)
270 The time in 24-hour notation
275 The day of the week as a decimal, range 1 to 7, Monday being 1.
283 The week number of the current year as a decimal number,
284 range 00 to 53, starting with the first Sunday as the first day
296 The ISO\ 8601 week number (see NOTES) of the current year as a decimal number,
297 range 01 to 53, where week 1 is the first week that has at least
298 4 days in the new year.
311 The day of the week as a decimal, range 0 to 6, Sunday being 0.
318 The week number of the current year as a decimal number,
319 range 00 to 53, starting with the first Monday as the first day of week 01.
326 The preferred date representation for the current locale without the time.
329 The preferred time representation for the current locale without the date.
332 The year as a decimal number without a century (range 00 to 99).
337 The year as a decimal number including the century.
346 numeric timezone (that is, the hour and minute offset from UTC). (SU)
349 The timezone name or abbreviation.
352 .\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
357 (Not supported in glibc2.)
360 A literal \(aq%\(aq character.
362 Some conversion specifications can be modified by preceding the
363 conversion specifier character by the
368 to indicate that an alternative format should be used.
369 If the alternative format or specification does not exist for
370 the current locale, the behavior will be as if the unmodified
371 conversion specification were used. (SU)
372 The Single UNIX Specification mentions
392 where the effect of the
395 alternative numeric symbols (say, roman numerals), and that of the
396 E modifier is to use a locale-dependent alternative representation.
398 Provided that the result string,
399 including the terminating null byte, does not exceed
403 returns the number of bytes (excluding the terminating null byte)
406 If the length of the result string (including the terminating null byte)
411 returns 0, and the contents of the array are undefined.
412 .\" (This behavior applies since at least libc 4.4.4;
413 .\" very old versions of libc, such as libc 4.4.1,
416 .\" if the array was too small.)
418 Note that the return value 0 does not necessarily indicate an error.
419 For example, in many locales
421 yields an empty string.
424 string will likewise yield an empty string.
426 The environment variables
432 For an explanation of the terms used in this section, see
438 Interface Attribute Value
441 T} Thread safety MT-Safe env locale
445 .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
446 .\" in the standards changed across versions. Investigate and
448 There are strict inclusions between the set of conversions
449 given in ANSI C (unmarked), those given in the Single UNIX Specification
450 (marked SU), those given in Olson's timezone package (marked TZ),
451 and those given in glibc (marked GNU), except that
453 is not supported in glibc2.
454 On the other hand glibc2 has several more extensions.
455 POSIX.1 only refers to ANSI C; POSIX.2 describes under
457 several extensions that could apply to
462 conversion is in C99 and POSIX.1-2001.
466 specifier allowed a range of 00 to 61,
467 to allow for the theoretical possibility of a minute that
468 included a double leap second
469 (there never has been such a minute).
471 .SS ISO 8601 week dates
476 yield values calculated from the week-based year defined by the
478 In this system, weeks start on a Monday, and are numbered from 01,
479 for the first week, up to 52 or 53, for the last week.
480 Week 1 is the first week where four or more days fall within the
481 new year (or, synonymously, week 01 is:
482 the first week of the year that contains a Thursday;
483 or, the week that has 4 January in it).
484 When three of fewer days of the first calendar week of the new year fall
486 then the ISO 8601 week-based system counts those days as part of week 53
487 of the preceding year.
488 For example, 1 January 2010 is a Friday,
489 meaning that just three days of that calendar week fall in 2010.
490 Thus, the ISO\ 8601 week-based system considers these days to be part of
495 week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010.
497 Glibc provides some extensions for conversion specifications.
498 (These extensions are not specified in POSIX.1-2001, but a few other
499 systems provide similar features.)
500 .\" HP-UX and Tru64 also have features like this.
501 Between the \(aq%\(aq character and the conversion specifier character,
511 modifiers, if present.)
513 The following flag characters are permitted:
517 Pad a numeric result string with spaces.
521 Do not pad a numeric result string.
524 Pad a numeric result string with zeros even if the conversion
525 specifier character uses space-padding by default.
528 Convert alphabetic characters in result string to uppercase.
531 Swap the case of the result string.
532 (This flag works only with certain conversion specifier characters,
533 and of these, it is only really useful with
536 An optional decimal width specifier may follow the (possibly absent) flag.
537 If the natural size of the field is smaller than this width,
538 then the result string is padded (on the left) to the specified width.
540 If the output string would exceed
547 This makes it impossible to distinguish this error case from cases where the
549 string legitimately produces a zero-length output string.
558 Some buggy versions of
560 complain about the use of
562 .IR "warning: `%c' yields only last 2 digits of year in some locales" .
563 Of course programmers are encouraged to use
565 it gives the preferred date and time representation.
566 One meets all kinds of strange obfuscations
570 A relatively clean one is to add an
571 intermediate function
576 my_strftime(char *s, size_t max, const char *fmt,
579 return strftime(s, max, fmt, tm);
587 .IR \-Wno\-format\-y2k
588 option to prevent the warning,
589 so that the above workaround is no longer required.
591 .BR "RFC\ 2822-compliant date format"
592 (with an English locale for %a and %b)
595 "%a,\ %d\ %b\ %Y\ %T\ %z"
597 .BR "RFC\ 822-compliant date format"
598 (with an English locale for %a and %b)
601 "%a,\ %d\ %b\ %y\ %T\ %z"
603 The program below can be used to experiment with
606 Some examples of the result string produced by the glibc implementation of
612 .RB "$" " ./a.out \(aq%m\(aq"
613 Result string is "11"
614 .RB "$" " ./a.out \(aq%5m\(aq"
615 Result string is "00011"
616 .RB "$" " ./a.out \(aq%_5m\(aq"
617 Result string is " 11"
628 main(int argc, char *argv[])
641 if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
642 fprintf(stderr, "strftime returned 0");
646 printf("Result string is \e"%s\e"\en", outstr);