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 2005-11-23 "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 );
46 The \fBstrftime\fP() function formats the broken-down time \fItm\fP
47 according to the format specification \fIformat\fP and places the
48 result in the character array \fIs\fP of size \fImax\fP.
50 Ordinary characters placed in the format string are copied to \fIs\fP
52 .I "Conversion specifications"
53 are introduced by a `%'
54 character, and terminated by a
55 .IR "conversion specifier character" ,
56 and are replaced in \fIs\fP as follows:
59 The abbreviated weekday name according to the current locale.
62 The full weekday name according to the current locale.
65 The abbreviated month name according to the current locale.
68 The full month name according to the current locale.
71 The preferred date and time representation for the current locale.
74 The century number (year/100) as a 2-digit integer. (SU)
77 The day of the month as a decimal number (range 01 to 31).
80 Equivalent to %m/%d/%y. (Yecch \(em for Americans only.
81 Americans should note that in other countries %d/%m/%y is rather
82 common. This means that in international context this format is
83 ambiguous and should not be used.) (SU)
86 Like %d, the day of the month as a decimal number, but a leading
87 zero is replaced by a space. (SU)
90 Modifier: use alternative format, see below. (SU)
93 Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)
96 The ISO 8601 year with century as a decimal number.
97 The 4-digit year corresponding to the ISO week number (see %V).
98 This has the same format and value as %y, except that if the
99 ISO week number belongs to the previous or next year,
100 that year is used instead. (TZ)
103 Like %G, but without century, i.e., with a 2-digit year (00-99). (TZ)
106 Equivalent to %b. (SU)
109 The hour as a decimal number using a 24-hour clock (range 00 to 23).
112 The hour as a decimal number using a 12-hour clock (range 01 to 12).
115 The day of the year as a decimal number (range 001 to 366).
118 The hour (24-hour clock) as a decimal number (range 0 to 23);
119 single digits are preceded by a blank. (See also %H.) (TZ)
122 The hour (12-hour clock) as a decimal number (range 1 to 12);
123 single digits are preceded by a blank. (See also %I.) (TZ)
126 The month as a decimal number (range 01 to 12).
129 The minute as a decimal number (range 00 to 59).
132 A newline character. (SU)
135 Modifier: use alternative format, see below. (SU)
138 Either `AM' or `PM' according to the given time value, or the
139 corresponding strings for the current locale.
140 Noon is treated as `pm' and midnight as `am'.
143 Like %p but in lowercase: `am' or `pm' or a corresponding
144 string for the current locale. (GNU)
147 The time in a.m. or p.m. notation.
148 In the POSIX locale this is equivalent to `%I:%M:%S %p'. (SU)
151 The time in 24-hour notation (%H:%M). (SU)
152 For a version including the seconds, see %T below.
155 The number of seconds since the Epoch, i.e., since 1970-01-01
159 The second as a decimal number (range 00 to 60).
160 (The range is up to 60 to allow for occasional leap seconds.)
163 A tab character. (SU)
166 The time in 24-hour notation (%H:%M:%S). (SU)
169 The day of the week as a decimal, range 1 to 7, Monday being 1.
173 The week number of the current year as a decimal number,
174 range 00 to 53, starting with the first Sunday as the first day
175 of week 01. See also %V and %W.
178 The ISO 8601:1988 week number of the current year as a decimal number,
179 range 01 to 53, where week 1 is the first week that has at least
180 4 days in the current year, and with Monday as the first day of
181 the week. See also %U and %W. (SU)
184 The day of the week as a decimal, range 0 to 6, Sunday being 0.
188 The week number of the current year as a decimal number,
189 range 00 to 53, starting with the first Monday as the first day of week 01.
192 The preferred date representation for the current locale without the time.
195 The preferred time representation for the current locale without the date.
198 The year as a decimal number without a century (range 00 to 99).
201 The year as a decimal number including the century.
204 The time-zone as hour offset from GMT.
205 Required to emit RFC\ 822-conformant dates
206 (using "%a, %d %b %Y %H:%M:%S %z"). (GNU)
209 The time zone or name or abbreviation.
212 .\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
217 (Not supported in glibc2.)
220 A literal `%' character.
222 Some conversion specifications can be modified by preceding the
223 conversion specifier character by the E or O
225 to indicate that an alternative format should be used.
226 If the alternative format or specification does not exist for
227 the current locale, the behaviour will be as if the unmodified
228 conversion specification were used. (SU)
229 The Single Unix Specification mentions %Ec, %EC, %Ex, %EX,
230 %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV,
231 %Ow, %OW, %Oy, where the effect of the O modifier is to use
232 alternative numeric symbols (say, roman numerals), and that of the
233 E modifier is to use a locale-dependent alternative representation.
235 The broken-down time structure \fItm\fP is defined in \fI<time.h>\fP.
239 The \fBstrftime\fP() function returns the number of characters placed
240 in the array \fIs\fP, not including the terminating null byte,
241 provided the string, including the terminating null byte, fits.
242 Otherwise, it returns 0, and the contents of the array is undefined.
243 (Thus at least since libc 4.4.4; very old versions of libc,
244 such as libc 4.4.1, would return \fImax\fP if the array was too small.)
246 Note that the return value 0 does not necessarily indicate an error;
247 for example, in many locales %p yields an empty string.
249 The environment variables TZ and LC_TIME are used.
252 There are strict inclusions between the set of conversions
253 given in ANSI C (unmarked), those given in the Single Unix Specification
254 (marked SU), those given in Olson's timezone package (marked TZ),
255 and those given in glibc (marked GNU), except that %+ is not supported
256 in glibc2. On the other hand glibc2 has several more extensions.
257 POSIX.1 only refers to ANSI C; POSIX.2 describes under
259 several extensions that could apply to
262 The %F conversion is in C99 and POSIX.1-2001.
264 In SUSv2, the %S specified allowed a range of 00 to 61,
265 to allow for the theoretical possibility of a minute that
266 included a double leap second
267 (there never has been such a minute).
269 Glibc provides some extensions for conversion specifications.
270 (These extensions are not specified in POSIX.1-2001, but a few other
271 systems provide similar features.)
272 .\" HP-UX and Tru64 also have features like this.
273 Between the % character and the conversion specifier character,
279 (These precede the E or O modifiers, if present.)
281 The following flag characters are permitted:
285 Pad a numeric result string with spaces.
289 Do not pad a numeric result string.
292 Pad a numeric result string with zeros even if the conversion
293 specifier character uses space-padding by default.
296 Convert alphabetic characters in result string to upper case.
299 Swap the case of the result string.
300 (This flag only works with certain conversion specifier characters,
301 and of these, it is only really useful with %Z).
303 An optional decimal width specifier may follow the (possibly absent) flag.
304 If the natural size of the field is smaller than this width,
305 then the result string is padded (on the left) to the specified width.
307 Some buggy versions of gcc complain about the use of %c:
308 .IR "warning: `%c' yields only last 2 digits of year in some locales" .
309 Of course programmers are encouraged to use %c, it gives the preferred
310 date and time representation. One meets all kinds of strange obfuscations
311 to circumvent this gcc problem. A relatively clean one is to add an
312 intermediate function
317 my_strftime(char *s, size_t max, const char *fmt,
320 return strftime(s, max, fmt, tm);
325 The program below can be used to experiment with
334 main(int argc, char *argv[])
347 if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
348 fprintf(stderr, "strftime returned 0");
352 printf("Result string is \\"%s\\"\\n", outstr);
357 Some examples of the result string produced by the glibc implementation of
363 Result string is "11"
365 Result string is "00011"
367 Result string is " 11"