1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
3 .\" Permission is granted to make and distribute verbatim copies of this
4 .\" manual provided the copyright notice and this permission notice are
5 .\" preserved on all copies.
7 .\" Permission is granted to copy and distribute modified versions of this
8 .\" manual under the conditions for verbatim copying, provided that the
9 .\" entire resulting derived work is distributed under the terms of a
10 .\" permission notice identical to this one.
12 .\" Since the Linux kernel and libraries are constantly changing, this
13 .\" manual page may be incorrect or out-of-date. The author(s) assume no
14 .\" responsibility for errors or omissions, or for damages resulting from
15 .\" the use of the information contained herein. The author(s) may not
16 .\" have taken the same level of care in the production of this manual,
17 .\" which is licensed free of charge, as they might when working
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" References consulted:
24 .\" Linux libc source code
25 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
27 .\" GNU texinfo documentation on glibc date/time functions.
28 .\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu)
29 .\" Applied fix by Wolfgang Franke, aeb, 961011
30 .\" Corrected return value, aeb, 970307
31 .\" Added Single Unix Spec conversions and %z, aeb/esr, 990329.
32 .\" 2005-11-22 mtk, added Glibc Notes covering optional 'flag' and
33 .\" 'width' components of conversion specifications.
35 .TH STRFTIME 3 2008-10-29 "GNU" "Linux Programmer's Manual"
37 strftime \- format date and time
42 .BI "size_t strftime(char *" s ", size_t " max ", const char *" format ,
43 .BI " const struct tm *" tm );
48 function formats the broken-down time \fItm\fP
49 according to the format specification \fIformat\fP and places the
50 result in the character array \fIs\fP of size \fImax\fP.
51 .\" FIXME POSIX says: Local timezone information is used as though
52 .\" strftime() called tzset(). But this doesn't appear to be the case
54 Ordinary characters placed in the format string are copied to \fIs\fP
56 .I "Conversion specifications"
57 are introduced by a \(aq%\(aq
58 character, and terminated by a
59 .IR "conversion specifier character" ,
60 and are replaced in \fIs\fP as follows:
63 The abbreviated weekday name according to the current locale.
66 The full weekday name according to the current locale.
69 The abbreviated month name according to the current locale.
72 The full month name according to the current locale.
75 The preferred date and time representation for the current locale.
78 The century number (year/100) as a 2-digit integer. (SU)
81 The day of the month as a decimal number (range 01 to 31).
86 (Yecch \(em for Americans only.
87 Americans should note that in other countries
90 This means that in international context this format is
91 ambiguous and should not be used.) (SU)
96 the day of the month as a decimal number, but a leading
97 zero is replaced by a space. (SU)
100 Modifier: use alternative format, see below. (SU)
105 (the ISO 8601 date format). (C99)
108 The ISO 8601 year with century as a decimal number.
109 The 4-digit year corresponding to the ISO week number (see
111 This has the same format and value as
114 ISO week number belongs to the previous or next year,
115 that year is used instead. (TZ)
120 but without century, that is, with a 2-digit year (00-99). (TZ)
128 The hour as a decimal number using a 24-hour clock (range 00 to 23).
131 The hour as a decimal number using a 12-hour clock (range 01 to 12).
134 The day of the year as a decimal number (range 001 to 366).
137 The hour (24-hour clock) as a decimal number (range 0 to 23);
138 single digits are preceded by a blank.
144 The hour (12-hour clock) as a decimal number (range 1 to 12);
145 single digits are preceded by a blank.
151 The month as a decimal number (range 01 to 12).
154 The minute as a decimal number (range 00 to 59).
157 A newline character. (SU)
160 Modifier: use alternative format, see below. (SU)
163 Either "AM" or "PM" according to the given time value, or the
164 corresponding strings for the current locale.
165 Noon is treated as "PM" and midnight as "AM".
170 but in lowercase: "am" or "pm" or a corresponding
171 string for the current locale. (GNU)
174 The time in a.m. or p.m. notation.
175 In the POSIX locale this is equivalent to
180 The time in 24-hour notation (\fB%H:%M\fP). (SU)
181 For a version including the seconds, see
186 The number of seconds since the Epoch, that is, since 1970-01-01
190 The second as a decimal number (range 00 to 60).
191 (The range is up to 60 to allow for occasional leap seconds.)
194 A tab character. (SU)
197 The time in 24-hour notation (\fB%H:%M:%S\fP). (SU)
200 The day of the week as a decimal, range 1 to 7, Monday being 1.
206 The week number of the current year as a decimal number,
207 range 00 to 53, starting with the first Sunday as the first day
215 The ISO 8601:1988 week number of the current year as a decimal number,
216 range 01 to 53, where week 1 is the first week that has at least
217 4 days in the current year, and with Monday as the first day of
226 The day of the week as a decimal, range 0 to 6, Sunday being 0.
231 The week number of the current year as a decimal number,
232 range 00 to 53, starting with the first Monday as the first day of week 01.
235 The preferred date representation for the current locale without the time.
238 The preferred time representation for the current locale without the date.
241 The year as a decimal number without a century (range 00 to 99).
244 The year as a decimal number including the century.
247 The time-zone as hour offset from GMT.
248 Required to emit RFC\ 822-conformant dates
249 (using "%a,\ %d\ %b\ %Y\ %H:%M:%S\ %z"). (GNU)
252 The timezone or name or abbreviation.
255 .\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
260 (Not supported in glibc2.)
263 A literal \(aq%\(aq character.
265 Some conversion specifications can be modified by preceding the
266 conversion specifier character by the
271 to indicate that an alternative format should be used.
272 If the alternative format or specification does not exist for
273 the current locale, the behavior will be as if the unmodified
274 conversion specification were used. (SU)
275 The Single Unix Specification mentions
295 where the effect of the
298 alternative numeric symbols (say, roman numerals), and that of the
299 E modifier is to use a locale-dependent alternative representation.
301 The broken-down time structure \fItm\fP is defined in \fI<time.h>\fP.
307 function returns the number of characters placed
308 in the array \fIs\fP, not including the terminating null byte,
309 provided the string, including the terminating null byte, fits.
310 Otherwise, it returns 0, and the contents of the array is undefined.
311 (This behavior applies since at least libc 4.4.4;
312 very old versions of libc, such as libc 4.4.1,
313 would return \fImax\fP if the array was too small.)
315 Note that the return value 0 does not necessarily indicate an error;
316 for example, in many locales
318 yields an empty string.
320 The environment variables
327 There are strict inclusions between the set of conversions
328 given in ANSI C (unmarked), those given in the Single Unix Specification
329 (marked SU), those given in Olson's timezone package (marked TZ),
330 and those given in glibc (marked GNU), except that
332 is not supported in glibc2.
333 On the other hand glibc2 has several more extensions.
334 POSIX.1 only refers to ANSI C; POSIX.2 describes under
336 several extensions that could apply to
341 conversion is in C99 and POSIX.1-2001.
345 specifier allowed a range of 00 to 61,
346 to allow for the theoretical possibility of a minute that
347 included a double leap second
348 (there never has been such a minute).
351 Glibc provides some extensions for conversion specifications.
352 (These extensions are not specified in POSIX.1-2001, but a few other
353 systems provide similar features.)
354 .\" HP-UX and Tru64 also have features like this.
355 Between the \(aq%\(aq character and the conversion specifier character,
365 modifiers, if present.)
367 The following flag characters are permitted:
371 Pad a numeric result string with spaces.
375 Do not pad a numeric result string.
378 Pad a numeric result string with zeros even if the conversion
379 specifier character uses space-padding by default.
382 Convert alphabetic characters in result string to upper case.
385 Swap the case of the result string.
386 (This flag only works with certain conversion specifier characters,
387 and of these, it is only really useful with
390 An optional decimal width specifier may follow the (possibly absent) flag.
391 If the natural size of the field is smaller than this width,
392 then the result string is padded (on the left) to the specified width.
394 Some buggy versions of
396 complain about the use of
398 .IR "warning: `%c' yields only last 2 digits of year in some locales" .
399 Of course programmers are encouraged to use
401 it gives the preferred date and time representation.
402 One meets all kinds of strange obfuscations
406 A relatively clean one is to add an
407 intermediate function
412 my_strftime(char *s, size_t max, const char *fmt,
415 return strftime(s, max, fmt, tm);
422 provides the \fI\-Wno\-format\-y2k\fP option to prevent the warning,
423 so that the above workaround is no longer required.
425 The program below can be used to experiment with
428 Some examples of the result string produced by the glibc implementation of
434 .RB "$" " ./a.out \(aq%m\(aq"
435 Result string is "11"
436 .RB "$" " ./a.out \(aq%5m\(aq"
437 Result string is "00011"
438 .RB "$" " ./a.out \(aq%_5m\(aq"
439 Result string is " 11"
450 main(int argc, char *argv[])
463 if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
464 fprintf(stderr, "strftime returned 0");
468 printf("Result string is \\"%s\\"\\n", outstr);