1STRFTIME(3) Linux Programmer's Manual STRFTIME(3)
2
6 strftime - format date and time
7
9 #include <time.h>
10 size_t strftime(char *s, size_t max, const char *format,
12 const struct tm *tm);
13
15 The strftime() function formats the broken-down time tm according to
16 the format specification format and places the result in the character
17 array s of size max. The broken-down time structure tm is defined in
18 <time.h>. See also ctime(3).
19 The format specification is a null-terminated string and may contain
21 special character sequences called conversion specifications, each of
22 which is introduced by a '%' character and terminated by some other
23 character known as a conversion specifier character. All other charac‐
24 ter sequences are ordinary character sequences.
25 The characters of ordinary character sequences (including the null
27 byte) are copied verbatim from format to s. However, the characters of
28 conversion specifications are replaced as shown in the list below. In
29 this list, the field(s) employed from the tm structure are also shown.
30 %a The abbreviated name of the day of the week according to the
32 current locale. (Calculated from tm_wday.) (The specific names
33 used in the current locale can be obtained by calling nl_lang‐
34 info(3) with ABDAY_{1–7} as an argument.)
35 %A The full name of the day of the week according to the current
37 locale. (Calculated from tm_wday.) (The specific names used in
38 the current locale can be obtained by calling nl_langinfo(3)
39 with DAY_{1–7} as an argument.)
40 %b The abbreviated month name according to the current locale.
42 (Calculated from tm_mon.) (The specific names used in the cur‐
43 rent locale can be obtained by calling nl_langinfo(3) with AB‐
44 MON_{1–12} as an argument.)
45 %B The full month name according to the current locale. (Calcu‐
47 lated from tm_mon.) (The specific names used in the current lo‐
48 cale can be obtained by calling nl_langinfo(3) with MON_{1–12}
49 as an argument.)
50 %c The preferred date and time representation for the current lo‐
52 cale. (The specific format used in the current locale can be
53 obtained by calling nl_langinfo(3) with D_T_FMT as an argument
54 for the %c conversion specification, and with ERA_D_T_FMT for
55 the %Ec conversion specification.) (In the POSIX locale this is
56 equivalent to %a %b %e %H:%M:%S %Y.)
57 %C The century number (year/100) as a 2-digit integer. (SU) (The
59 %EC conversion specification corresponds to the name of the
60 era.) (Calculated from tm_year.)
61 %d The day of the month as a decimal number (range 01 to 31).
63 (Calculated from tm_mday.)
64 %D Equivalent to %m/%d/%y. (Yecch—for Americans only. Americans
66 should note that in other countries %d/%m/%y is rather common.
67 This means that in international context this format is ambigu‐
68 ous and should not be used.) (SU)
69 %e Like %d, the day of the month as a decimal number, but a leading
71 zero is replaced by a space. (SU) (Calculated from tm_mday.)
72 %E Modifier: use alternative ("era-based") format, see below. (SU)
74 %F Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)
76 %G The ISO 8601 week-based year (see NOTES) with century as a deci‐
78 mal number. The 4-digit year corresponding to the ISO week num‐
79 ber (see %V). This has the same format and value as %Y, except
80 that if the ISO week number belongs to the previous or next
81 year, that year is used instead. (TZ) (Calculated from tm_year,
82 tm_yday, and tm_wday.)
83 %g Like %G, but without century, that is, with a 2-digit year
85 (00–99). (TZ) (Calculated from tm_year, tm_yday, and tm_wday.)
86 %h Equivalent to %b. (SU)
88 %H The hour as a decimal number using a 24-hour clock (range 00 to
90 23). (Calculated from tm_hour.)
91 %I The hour as a decimal number using a 12-hour clock (range 01 to
93 12). (Calculated from tm_hour.)
94 %j The day of the year as a decimal number (range 001 to 366).
96 (Calculated from tm_yday.)
97 %k The hour (24-hour clock) as a decimal number (range 0 to 23);
99 single digits are preceded by a blank. (See also %H.) (Calcu‐
100 lated from tm_hour.) (TZ)
101 %l The hour (12-hour clock) as a decimal number (range 1 to 12);
103 single digits are preceded by a blank. (See also %I.) (Calcu‐
104 lated from tm_hour.) (TZ)
105 %m The month as a decimal number (range 01 to 12). (Calculated
107 from tm_mon.)
108 %M The minute as a decimal number (range 00 to 59). (Calculated
110 from tm_min.)
111 %n A newline character. (SU)
113 %O Modifier: use alternative numeric symbols, see below. (SU)
115 %p Either "AM" or "PM" according to the given time value, or the
117 corresponding strings for the current locale. Noon is treated
118 as "PM" and midnight as "AM". (Calculated from tm_hour.) (The
119 specific string representations used for "AM" and "PM" in the
120 current locale can be obtained by calling nl_langinfo(3) with
121 AM_STR and PM_STR, respectively.)
122 %P Like %p but in lowercase: "am" or "pm" or a corresponding string
124 for the current locale. (Calculated from tm_hour.) (GNU)
125 %r The time in a.m. or p.m. notation. (SU) (The specific format
127 used in the current locale can be obtained by calling nl_lang‐
128 info(3) with T_FMT_AMPM as an argument.) (In the POSIX locale
129 this is equivalent to %I:%M:%S %p.)
130 %R The time in 24-hour notation (%H:%M). (SU) For a version in‐
132 cluding the seconds, see %T below.
133 %s The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000
135 (UTC). (TZ) (Calculated from mktime(tm).)
136 %S The second as a decimal number (range 00 to 60). (The range is
138 up to 60 to allow for occasional leap seconds.) (Calculated
139 from tm_sec.)
140 %t A tab character. (SU)
142 %T The time in 24-hour notation (%H:%M:%S). (SU)
144 %u The day of the week as a decimal, range 1 to 7, Monday being 1.
146 See also %w. (Calculated from tm_wday.) (SU)
147 %U The week number of the current year as a decimal number, range
149 00 to 53, starting with the first Sunday as the first day of
150 week 01. See also %V and %W. (Calculated from tm_yday and
151 tm_wday.)
152 %V The ISO 8601 week number (see NOTES) of the current year as a
154 decimal number, range 01 to 53, where week 1 is the first week
155 that has at least 4 days in the new year. See also %U and %W.
156 (Calculated from tm_year, tm_yday, and tm_wday.) (SU)
157 %w The day of the week as a decimal, range 0 to 6, Sunday being 0.
159 See also %u. (Calculated from tm_wday.)
160 %W The week number of the current year as a decimal number, range
162 00 to 53, starting with the first Monday as the first day of
163 week 01. (Calculated from tm_yday and tm_wday.)
164 %x The preferred date representation for the current locale without
166 the time. (The specific format used in the current locale can
167 be obtained by calling nl_langinfo(3) with D_FMT as an argument
168 for the %x conversion specification, and with ERA_D_FMT for the
169 %Ex conversion specification.) (In the POSIX locale this is
170 equivalent to %m/%d/%y.)
171 %X The preferred time representation for the current locale without
173 the date. (The specific format used in the current locale can
174 be obtained by calling nl_langinfo(3) with T_FMT as an argument
175 for the %X conversion specification, and with ERA_T_FMT for the
176 %EX conversion specification.) (In the POSIX locale this is
177 equivalent to %H:%M:%S.)
178 %y The year as a decimal number without a century (range 00 to 99).
180 (The %Ey conversion specification corresponds to the year since
181 the beginning of the era denoted by the %EC conversion specifi‐
182 cation.) (Calculated from tm_year)
183 %Y The year as a decimal number including the century. (The %EY
185 conversion specification corresponds to the full alternative
186 year representation.) (Calculated from tm_year)
187 %z The +hhmm or -hhmm numeric timezone (that is, the hour and
189 minute offset from UTC). (SU)
190 %Z The timezone name or abbreviation.
192 %+ The date and time in date(1) format. (TZ) (Not supported in
194 glibc2.)
195 %% A literal '%' character.
197 Some conversion specifications can be modified by preceding the conver‐
199 sion specifier character by the E or O modifier to indicate that an al‐
200 ternative format should be used. If the alternative format or specifi‐
201 cation does not exist for the current locale, the behavior will be as
202 if the unmodified conversion specification were used. (SU) The Single
203 UNIX Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe,
204 %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect
205 of the O modifier is to use alternative numeric symbols (say, roman nu‐
206 merals), and that of the E modifier is to use a locale-dependent alter‐
207 native representation. The rules governing date representation with
208 the E modifier can be obtained by supplying ERA as an argument to a
209 nl_langinfo(3). One example of such alternative forms is the Japanese
210 era calendar scheme in the ja_JP glibc locale.
211
213 Provided that the result string, including the terminating null byte,
214 does not exceed max bytes, strftime() returns the number of bytes (ex‐
215 cluding the terminating null byte) placed in the array s. If the
216 length of the result string (including the terminating null byte) would
217 exceed max bytes, then strftime() returns 0, and the contents of the
218 array are undefined.
219 Note that the return value 0 does not necessarily indicate an error.
221 For example, in many locales %p yields an empty string. An empty for‐
222 mat string will likewise yield an empty string.
223
225 The environment variables TZ and LC_TIME are used.
226
228 For an explanation of the terms used in this section, see at‐
229 tributes(7).
230 ┌───────────┬───────────────┬────────────────────┐
232 │Interface │ Attribute │ Value │
233 ├───────────┼───────────────┼────────────────────┤
234 │strftime() │ Thread safety │ MT-Safe env locale │
235 └───────────┴───────────────┴────────────────────┘
237 SVr4, C89, C99. There are strict inclusions between the set of conver‐
238 sions given in ANSI C (unmarked), those given in the Single UNIX Speci‐
239 fication (marked SU), those given in Olson's timezone package (marked
240 TZ), and those given in glibc (marked GNU), except that %+ is not sup‐
241 ported in glibc2. On the other hand glibc2 has several more exten‐
242 sions. POSIX.1 only refers to ANSI C; POSIX.2 describes under date(1)
243 several extensions that could apply to strftime() as well. The %F con‐
244 version is in C99 and POSIX.1-2001.
245 In SUSv2, the %S specifier allowed a range of 00 to 61, to allow for
247 the theoretical possibility of a minute that included a double leap
248 second (there never has been such a minute).
249
251 ISO 8601 week dates
252 %G, %g, and %V yield values calculated from the week-based year defined
253 by the ISO 8601 standard. In this system, weeks start on a Monday, and
254 are numbered from 01, for the first week, up to 52 or 53, for the last
255 week. Week 1 is the first week where four or more days fall within the
256 new year (or, synonymously, week 01 is: the first week of the year that
257 contains a Thursday; or, the week that has 4 January in it). When
258 three or fewer days of the first calendar week of the new year fall
259 within that year, then the ISO 8601 week-based system counts those days
260 as part of week 52 or 53 of the preceding year. For example, 1 January
261 2010 is a Friday, meaning that just three days of that calendar week
262 fall in 2010. Thus, the ISO 8601 week-based system considers these
263 days to be part of week 53 (%V) of the year 2009 (%G); week 01 of
264 ISO 8601 year 2010 starts on Monday, 4 January 2010. Similarly, the
265 first two days of January 2011 are considered to be part of week 52 of
266 the year 2010.
267 Glibc notes
269 Glibc provides some extensions for conversion specifications. (These
270 extensions are not specified in POSIX.1-2001, but a few other systems
271 provide similar features.) Between the '%' character and the conver‐
272 sion specifier character, an optional flag and field width may be spec‐
273 ified. (These precede the E or O modifiers, if present.)
274 The following flag characters are permitted:
276 _ (underscore) Pad a numeric result string with spaces.
278 - (dash) Do not pad a numeric result string.
280 0 Pad a numeric result string with zeros even if the conversion
282 specifier character uses space-padding by default.
283 ^ Convert alphabetic characters in result string to uppercase.
285 # Swap the case of the result string. (This flag works only with
287 certain conversion specifier characters, and of these, it is
288 only really useful with %Z.)
289 An optional decimal width specifier may follow the (possibly absent)
291 flag. If the natural size of the field is smaller than this width,
292 then the result string is padded (on the left) to the specified width.
293
295 If the output string would exceed max bytes, errno is not set. This
296 makes it impossible to distinguish this error case from cases where the
297 format string legitimately produces a zero-length output string.
298 POSIX.1-2001 does not specify any errno settings for strftime().
299 Some buggy versions of gcc(1) complain about the use of %c: warning:
301 `%c' yields only last 2 digits of year in some locales. Of course pro‐
302 grammers are encouraged to use %c, as it gives the preferred date and
303 time representation. One meets all kinds of strange obfuscations to
304 circumvent this gcc(1) problem. A relatively clean one is to add an
305 intermediate function
306 size_t
308 my_strftime(char *s, size_t max, const char *fmt,
309 const struct tm *tm)
310 {
311 return strftime(s, max, fmt, tm);
312 }
313 Nowadays, gcc(1) provides the -Wno-format-y2k option to prevent the
315 warning, so that the above workaround is no longer required.
316
318 RFC 2822-compliant date format (with an English locale for %a and %b)
319 "%a, %d %b %Y %T %z"
321 RFC 822-compliant date format (with an English locale for %a and %b)
323 "%a, %d %b %y %T %z"
325 Example program
327 The program below can be used to experiment with strftime().
328 Some examples of the result string produced by the glibc implementation
330 of strftime() are as follows:
331 $ ./a.out '%m'
333 Result string is "11"
334 $ ./a.out '%5m'
335 Result string is "00011"
336 $ ./a.out '%_5m'
337 Result string is " 11"
338 Program source
340 #include <time.h>
342 #include <stdio.h>
343 #include <stdlib.h>
344 int
346 main(int argc, char *argv[])
347 {
348 char outstr[200];
349 time_t t;
350 struct tm *tmp;
351 t = time(NULL);
353 tmp = localtime(&t);
354 if (tmp == NULL) {
355 perror("localtime");
356 exit(EXIT_FAILURE);
357 }
358 if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
360 fprintf(stderr, "strftime returned 0");
361 exit(EXIT_FAILURE);
362 }
363 printf("Result string is \"%s\"\n", outstr);
365 exit(EXIT_SUCCESS);
366 }
367
369 date(1), time(2), ctime(3), nl_langinfo(3), setlocale(3), sprintf(3),
370 strptime(3)
371
373 This page is part of release 5.10 of the Linux man-pages project. A
374 description of the project, information about reporting bugs, and the
375 latest version of this page, can be found at
376 https://www.kernel.org/doc/man-pages/.
377GNU 2020-08-13 STRFTIME(3)