1strftime(3)                Library Functions Manual                strftime(3)
2
3
4

NAME

6       strftime - format date and time
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <time.h>
13
14       size_t strftime(char s[restrict .max], size_t max,
15                       const char *restrict format,
16                       const struct tm *restrict tm);
17
18       size_t strftime_l(char s[restrict .max], size_t max,
19                       const char *restrict format,
20                       const struct tm *restrict tm,
21                       locale_t locale);
22

DESCRIPTION

24       The  strftime()  function  formats the broken-down time tm according to
25       the format specification format and places the result in the  character
26       array  s  of size max.  The broken-down time structure tm is defined in
27       <time.h>.  See also ctime(3).
28
29       The format specification is a null-terminated string  and  may  contain
30       special  character  sequences called conversion specifications, each of
31       which is introduced by a '%' character and  terminated  by  some  other
32       character known as a conversion specifier character.  All other charac‐
33       ter sequences are ordinary character sequences.
34
35       The characters of ordinary  character  sequences  (including  the  null
36       byte) are copied verbatim from format to s.  However, the characters of
37       conversion specifications are replaced as shown in the list below.   In
38       this list, the field(s) employed from the tm structure are also shown.
39
40       %a     The  abbreviated  name  of  the day of the week according to the
41              current locale.  (Calculated from tm_wday.)  (The specific names
42              used  in  the current locale can be obtained by calling nl_lang‐
43              info(3) with ABDAY_{17} as an argument.)
44
45       %A     The full name of the day of the week according  to  the  current
46              locale.  (Calculated from tm_wday.)  (The specific names used in
47              the current locale can be  obtained  by  calling  nl_langinfo(3)
48              with DAY_{17} as an argument.)
49
50       %b     The  abbreviated  month  name  according  to the current locale.
51              (Calculated from tm_mon.)  (The specific names used in the  cur‐
52              rent  locale  can be obtained by calling nl_langinfo(3) with AB‐
53              MON_{112} as an argument.)
54
55       %B     The full month name according to the  current  locale.   (Calcu‐
56              lated from tm_mon.)  (The specific names used in the current lo‐
57              cale can be obtained by calling nl_langinfo(3)  with  MON_{112}
58              as an argument.)
59
60       %c     The  preferred  date and time representation for the current lo‐
61              cale.  (The specific format used in the current  locale  can  be
62              obtained  by  calling nl_langinfo(3) with D_T_FMT as an argument
63              for the %c conversion specification, and  with  ERA_D_T_FMT  for
64              the %Ec conversion specification.)  (In the POSIX locale this is
65              equivalent to %a %b %e %H:%M:%S %Y.)
66
67       %C     The century number (year/100) as a 2-digit  integer.  (SU)  (The
68              %EC  conversion  specification  corresponds  to  the name of the
69              era.)  (Calculated from tm_year.)
70
71       %d     The day of the month as a  decimal  number  (range  01  to  31).
72              (Calculated from tm_mday.)
73
74       %D     Equivalent  to  %m/%d/%y.  (Yecch—for Americans only.  Americans
75              should note that in other countries %d/%m/%y is  rather  common.
76              This  means that in international context this format is ambigu‐
77              ous and should not be used.) (SU)
78
79       %e     Like %d, the day of the month as a decimal number, but a leading
80              zero is replaced by a space. (SU) (Calculated from tm_mday.)
81
82       %E     Modifier: use alternative ("era-based") format, see below. (SU)
83
84       %F     Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)
85
86       %G     The ISO 8601 week-based year (see NOTES) with century as a deci‐
87              mal number.  The 4-digit year corresponding to the ISO week num‐
88              ber  (see %V).  This has the same format and value as %Y, except
89              that if the ISO week number belongs  to  the  previous  or  next
90              year,  that year is used instead. (TZ) (Calculated from tm_year,
91              tm_yday, and tm_wday.)
92
93       %g     Like %G, but without century,  that  is,  with  a  2-digit  year
94              (00–99). (TZ) (Calculated from tm_year, tm_yday, and tm_wday.)
95
96       %h     Equivalent to %b.  (SU)
97
98       %H     The  hour as a decimal number using a 24-hour clock (range 00 to
99              23).  (Calculated from tm_hour.)
100
101       %I     The hour as a decimal number using a 12-hour clock (range 01  to
102              12).  (Calculated from tm_hour.)
103
104       %j     The  day  of  the  year  as a decimal number (range 001 to 366).
105              (Calculated from tm_yday.)
106
107       %k     The hour (24-hour clock) as a decimal number (range  0  to  23);
108              single  digits are preceded by a blank.  (See also %H.)  (Calcu‐
109              lated from tm_hour.)  (TZ)
110
111       %l     The hour (12-hour clock) as a decimal number (range  1  to  12);
112              single  digits are preceded by a blank.  (See also %I.)  (Calcu‐
113              lated from tm_hour.)  (TZ)
114
115       %m     The month as a decimal number (range  01  to  12).   (Calculated
116              from tm_mon.)
117
118       %M     The  minute  as  a decimal number (range 00 to 59).  (Calculated
119              from tm_min.)
120
121       %n     A newline character. (SU)
122
123       %O     Modifier: use alternative numeric symbols, see below. (SU)
124
125       %p     Either "AM" or "PM" according to the given time  value,  or  the
126              corresponding  strings  for the current locale.  Noon is treated
127              as "PM" and midnight as "AM".  (Calculated from tm_hour.)   (The
128              specific  string  representations  used for "AM" and "PM" in the
129              current locale can be obtained by  calling  nl_langinfo(3)  with
130              AM_STR and PM_STR, respectively.)
131
132       %P     Like %p but in lowercase: "am" or "pm" or a corresponding string
133              for the current locale.  (Calculated from tm_hour.)  (GNU)
134
135       %r     The time in a.m. or p.m. notation.  (SU)  (The  specific  format
136              used  in  the current locale can be obtained by calling nl_lang‐
137              info(3) with T_FMT_AMPM as an argument.)  (In the  POSIX  locale
138              this is equivalent to %I:%M:%S %p.)
139
140       %R     The  time  in  24-hour notation (%H:%M).  (SU) For a version in‐
141              cluding the seconds, see %T below.
142
143       %s     The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000
144              (UTC). (TZ) (Calculated from mktime(tm).)
145
146       %S     The  second as a decimal number (range 00 to 60).  (The range is
147              up to 60 to allow for  occasional  leap  seconds.)   (Calculated
148              from tm_sec.)
149
150       %t     A tab character. (SU)
151
152       %T     The time in 24-hour notation (%H:%M:%S).  (SU)
153
154       %u     The  day of the week as a decimal, range 1 to 7, Monday being 1.
155              See also %w.  (Calculated from tm_wday.)  (SU)
156
157       %U     The week number of the current year as a decimal  number,  range
158              00  to  53,  starting  with the first Sunday as the first day of
159              week 01.  See also %V and  %W.   (Calculated  from  tm_yday  and
160              tm_wday.)
161
162       %V     The  ISO 8601  week  number (see NOTES) of the current year as a
163              decimal number, range 01 to 53, where week 1 is the  first  week
164              that  has  at least 4 days in the new year.  See also %U and %W.
165              (Calculated from tm_year, tm_yday, and tm_wday.)  (SU)
166
167       %w     The day of the week as a decimal, range 0 to 6, Sunday being  0.
168              See also %u.  (Calculated from tm_wday.)
169
170       %W     The  week  number of the current year as a decimal number, range
171              00 to 53, starting with the first Monday as  the  first  day  of
172              week 01.  (Calculated from tm_yday and tm_wday.)
173
174       %x     The preferred date representation for the current locale without
175              the time.  (The specific format used in the current  locale  can
176              be  obtained by calling nl_langinfo(3) with D_FMT as an argument
177              for the %x conversion specification, and with ERA_D_FMT for  the
178              %Ex  conversion  specification.)   (In  the POSIX locale this is
179              equivalent to %m/%d/%y.)
180
181       %X     The preferred time representation for the current locale without
182              the  date.   (The specific format used in the current locale can
183              be obtained by calling nl_langinfo(3) with T_FMT as an  argument
184              for  the %X conversion specification, and with ERA_T_FMT for the
185              %EX conversion specification.)  (In the  POSIX  locale  this  is
186              equivalent to %H:%M:%S.)
187
188       %y     The year as a decimal number without a century (range 00 to 99).
189              (The %Ey conversion specification corresponds to the year  since
190              the  beginning of the era denoted by the %EC conversion specifi‐
191              cation.)  (Calculated from tm_year)
192
193       %Y     The year as a decimal number including the  century.   (The  %EY
194              conversion  specification  corresponds  to  the full alternative
195              year representation.)  (Calculated from tm_year)
196
197       %z     The +hhmm or -hhmm numeric  timezone  (that  is,  the  hour  and
198              minute offset from UTC). (SU)
199
200       %Z     The timezone name or abbreviation.
201
202       %+     The  date  and  time  in  date(1) format. (TZ) (Not supported in
203              glibc2.)
204
205       %%     A literal '%' character.
206
207       Some conversion specifications can be modified by preceding the conver‐
208       sion specifier character by the E or O modifier to indicate that an al‐
209       ternative format should be used.  If the alternative format or specifi‐
210       cation  does  not exist for the current locale, the behavior will be as
211       if the unmodified conversion specification were used. (SU)  The  Single
212       UNIX  Specification  mentions  %Ec,  %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe,
213       %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect
214       of the O modifier is to use alternative numeric symbols (say, roman nu‐
215       merals), and that of the E modifier is to use a locale-dependent alter‐
216       native  representation.   The  rules governing date representation with
217       the E modifier can be obtained by supplying ERA as  an  argument  to  a
218       nl_langinfo(3).   One example of such alternative forms is the Japanese
219       era calendar scheme in the ja_JP glibc locale.
220
221       strftime_l() is equivalent to strftime(), except it uses the  specified
222       locale  instead  of  the current locale.  The behaviour is undefined if
223       locale is invalid or LC_GLOBAL_LOCALE.
224

RETURN VALUE

226       Provided that the result string, including the terminating  null  byte,
227       does  not exceed max bytes, strftime() returns the number of bytes (ex‐
228       cluding the terminating null byte) placed  in  the  array  s.   If  the
229       length of the result string (including the terminating null byte) would
230       exceed max bytes, then strftime() returns 0, and the  contents  of  the
231       array are undefined.
232
233       Note  that  the  return value 0 does not necessarily indicate an error.
234       For example, in many locales %p yields an empty string.  An empty  for‐
235       mat string will likewise yield an empty string.
236

ENVIRONMENT

238       The environment variables TZ and LC_TIME are used.
239

ATTRIBUTES

241       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
242       tributes(7).
243
244       ┌─────────────────────────────────┬───────────────┬────────────────────┐
245Interface                        Attribute     Value              
246       ├─────────────────────────────────┼───────────────┼────────────────────┤
247strftime(), strftime_l()         │ Thread safety │ MT-Safe env locale │
248       └─────────────────────────────────┴───────────────┴────────────────────┘
249

STANDARDS

251       strftime()
252              C11, POSIX.1-2008.
253
254       strftime_l()
255              POSIX.1-2008.
256

HISTORY

258       strftime()
259              SVr4, C89.
260
261       strftime_l()
262              POSIX.1-2008.
263
264       There are strict inclusions between the set of conversions given in AN‐
265       SI  C  (unmarked), those given in the Single UNIX Specification (marked
266       SU), those given in Olson's timezone package  (marked  TZ),  and  those
267       given in glibc (marked GNU), except that %+ is not supported in glibc2.
268       On the other hand glibc2 has several  more  extensions.   POSIX.1  only
269       refers  to  ANSI  C; POSIX.2 describes under date(1) several extensions
270       that could apply to strftime() as well.  The %F conversion  is  in  C99
271       and POSIX.1-2001.
272
273       In  SUSv2,  the  %S specifier allowed a range of 00 to 61, to allow for
274       the theoretical possibility of a minute that  included  a  double  leap
275       second (there never has been such a minute).
276

NOTES

278   ISO 8601 week dates
279       %G, %g, and %V yield values calculated from the week-based year defined
280       by the ISO 8601 standard.  In this system, weeks start on a Monday, and
281       are  numbered from 01, for the first week, up to 52 or 53, for the last
282       week.  Week 1 is the first week where four or more days fall within the
283       new year (or, synonymously, week 01 is: the first week of the year that
284       contains a Thursday; or, the week that has  4  January  in  it).   When
285       three  or  fewer  days  of the first calendar week of the new year fall
286       within that year, then the ISO 8601 week-based system counts those days
287       as part of week 52 or 53 of the preceding year.  For example, 1 January
288       2010 is a Friday, meaning that just three days of  that  calendar  week
289       fall  in  2010.   Thus,  the ISO 8601 week-based system considers these
290       days to be part of week 53 (%V) of the  year  2009  (%G);  week  01  of
291       ISO 8601  year  2010  starts on Monday, 4 January 2010.  Similarly, the
292       first two days of January 2011 are considered to be part of week 52  of
293       the year 2010.
294
295   glibc notes
296       glibc  provides  some extensions for conversion specifications.  (These
297       extensions are not specified in POSIX.1-2001, but a few  other  systems
298       provide  similar  features.)  Between the '%' character and the conver‐
299       sion specifier character, an optional flag and field width may be spec‐
300       ified.  (These precede the E or O modifiers, if present.)
301
302       The following flag characters are permitted:
303
304       _      (underscore) Pad a numeric result string with spaces.
305
306       -      (dash) Do not pad a numeric result string.
307
308       0      Pad  a  numeric  result string with zeros even if the conversion
309              specifier character uses space-padding by default.
310
311       ^      Convert alphabetic characters in result string to uppercase.
312
313       #      Swap the case of the result string.  (This flag works only  with
314              certain conversion specifier characters, and of these, it is on‐
315              ly really useful with %Z.)
316
317       An optional decimal width specifier may follow  the  (possibly  absent)
318       flag.   If  the  natural  size of the field is smaller than this width,
319       then the result string is padded (on the left) to the specified width.
320

BUGS

322       If the output string would exceed max bytes, errno is  not  set.   This
323       makes it impossible to distinguish this error case from cases where the
324       format  string  legitimately  produces  a  zero-length  output  string.
325       POSIX.1-2001 does not specify any errno settings for strftime().
326
327       Some  buggy  versions  of gcc(1) complain about the use of %c: warning:
328       `%c' yields only last 2 digits of year in some locales.  Of course pro‐
329       grammers  are  encouraged to use %c, as it gives the preferred date and
330       time representation.  One meets all kinds of  strange  obfuscations  to
331       circumvent  this  gcc(1)  problem.  A relatively clean one is to add an
332       intermediate function
333
334           size_t
335           my_strftime(char *s, size_t max, const char *fmt,
336                       const struct tm *tm)
337           {
338               return strftime(s, max, fmt, tm);
339           }
340
341       Nowadays, gcc(1) provides the -Wno-format-y2k  option  to  prevent  the
342       warning, so that the above workaround is no longer required.
343

EXAMPLES

345       RFC 2822-compliant date format (with an English locale for %a and %b)
346
347           "%a, %d %b %Y %T %z"
348
349       RFC 822-compliant date format (with an English locale for %a and %b)
350
351           "%a, %d %b %y %T %z"
352
353   Example program
354       The program below can be used to experiment with strftime().
355
356       Some examples of the result string produced by the glibc implementation
357       of strftime() are as follows:
358
359           $ ./a.out '%m'
360           Result string is "11"
361           $ ./a.out '%5m'
362           Result string is "00011"
363           $ ./a.out '%_5m'
364           Result string is "   11"
365
366   Program source
367
368       #include <stdio.h>
369       #include <stdlib.h>
370       #include <time.h>
371
372       int
373       main(int argc, char *argv[])
374       {
375           char outstr[200];
376           time_t t;
377           struct tm *tmp;
378
379           t = time(NULL);
380           tmp = localtime(&t);
381           if (tmp == NULL) {
382               perror("localtime");
383               exit(EXIT_FAILURE);
384           }
385
386           if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
387               fprintf(stderr, "strftime returned 0");
388               exit(EXIT_FAILURE);
389           }
390
391           printf("Result string is \"%s\"\n", outstr);
392           exit(EXIT_SUCCESS);
393       }
394

SEE ALSO

396       date(1), time(2), ctime(3), nl_langinfo(3),  setlocale(3),  sprintf(3),
397       strptime(3)
398
399
400
401Linux man-pages 6.04              2023-03-30                       strftime(3)
Impressum