1STRFTIME(3)                Linux Programmer's Manual               STRFTIME(3)
2
3
4

NAME

6       strftime - format date and time
7

SYNOPSIS

9       #include <time.h>
10
11       size_t strftime(char *restrict s, size_t max,
12                       const char *restrict format,
13                       const struct tm *restrict tm);
14

DESCRIPTION

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

RETURN VALUE

214       Provided that the result string, including the terminating  null  byte,
215       does  not exceed max bytes, strftime() returns the number of bytes (ex‐
216       cluding the terminating null byte) placed  in  the  array  s.   If  the
217       length of the result string (including the terminating null byte) would
218       exceed max bytes, then strftime() returns 0, and the  contents  of  the
219       array are undefined.
220
221       Note  that  the  return value 0 does not necessarily indicate an error.
222       For example, in many locales %p yields an empty string.  An empty  for‐
223       mat string will likewise yield an empty string.
224

ENVIRONMENT

226       The environment variables TZ and LC_TIME are used.
227

ATTRIBUTES

229       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
230       tributes(7).
231
232       ┌─────────────────────────────────┬───────────────┬────────────────────┐
233Interface                        Attribute     Value              
234       ├─────────────────────────────────┼───────────────┼────────────────────┤
235strftime()                       │ Thread safety │ MT-Safe env locale │
236       └─────────────────────────────────┴───────────────┴────────────────────┘
237

CONFORMING TO

239       SVr4, C89, C99.  There are strict inclusions between the set of conver‐
240       sions given in ANSI C (unmarked), those given in the Single UNIX Speci‐
241       fication (marked SU), those given in Olson's timezone  package  (marked
242       TZ),  and those given in glibc (marked GNU), except that %+ is not sup‐
243       ported in glibc2.  On the other hand glibc2  has  several  more  exten‐
244       sions.   POSIX.1 only refers to ANSI C; POSIX.2 describes under date(1)
245       several extensions that could apply to strftime() as well.  The %F con‐
246       version is in C99 and POSIX.1-2001.
247
248       In  SUSv2,  the  %S specifier allowed a range of 00 to 61, to allow for
249       the theoretical possibility of a minute that  included  a  double  leap
250       second (there never has been such a minute).
251

NOTES

253   ISO 8601 week dates
254       %G, %g, and %V yield values calculated from the week-based year defined
255       by the ISO 8601 standard.  In this system, weeks start on a Monday, and
256       are  numbered from 01, for the first week, up to 52 or 53, for the last
257       week.  Week 1 is the first week where four or more days fall within the
258       new year (or, synonymously, week 01 is: the first week of the year that
259       contains a Thursday; or, the week that has  4  January  in  it).   When
260       three  or  fewer  days  of the first calendar week of the new year fall
261       within that year, then the ISO 8601 week-based system counts those days
262       as part of week 52 or 53 of the preceding year.  For example, 1 January
263       2010 is a Friday, meaning that just three days of  that  calendar  week
264       fall  in  2010.   Thus,  the ISO 8601 week-based system considers these
265       days to be part of week 53 (%V) of the  year  2009  (%G);  week  01  of
266       ISO 8601  year  2010  starts on Monday, 4 January 2010.  Similarly, the
267       first two days of January 2011 are considered to be part of week 52  of
268       the year 2010.
269
270   Glibc notes
271       Glibc  provides  some extensions for conversion specifications.  (These
272       extensions are not specified in POSIX.1-2001, but a few  other  systems
273       provide  similar  features.)  Between the '%' character and the conver‐
274       sion specifier character, an optional flag and field width may be spec‐
275       ified.  (These precede the E or O modifiers, if present.)
276
277       The following flag characters are permitted:
278
279       _      (underscore) Pad a numeric result string with spaces.
280
281       -      (dash) Do not pad a numeric result string.
282
283       0      Pad  a  numeric  result string with zeros even if the conversion
284              specifier character uses space-padding by default.
285
286       ^      Convert alphabetic characters in result string to uppercase.
287
288       #      Swap the case of the result string.  (This flag works only  with
289              certain conversion specifier characters, and of these, it is on‐
290              ly really useful with %Z.)
291
292       An optional decimal width specifier may follow  the  (possibly  absent)
293       flag.   If  the  natural  size of the field is smaller than this width,
294       then the result string is padded (on the left) to the specified width.
295

BUGS

297       If the output string would exceed max bytes, errno is  not  set.   This
298       makes it impossible to distinguish this error case from cases where the
299       format  string  legitimately  produces  a  zero-length  output  string.
300       POSIX.1-2001 does not specify any errno settings for strftime().
301
302       Some  buggy  versions  of gcc(1) complain about the use of %c: warning:
303       `%c' yields only last 2 digits of year in some locales.  Of course pro‐
304       grammers  are  encouraged to use %c, as it gives the preferred date and
305       time representation.  One meets all kinds of  strange  obfuscations  to
306       circumvent  this  gcc(1)  problem.  A relatively clean one is to add an
307       intermediate function
308
309           size_t
310           my_strftime(char *s, size_t max, const char *fmt,
311                       const struct tm *tm)
312           {
313               return strftime(s, max, fmt, tm);
314           }
315
316       Nowadays, gcc(1) provides the -Wno-format-y2k  option  to  prevent  the
317       warning, so that the above workaround is no longer required.
318

EXAMPLES

320       RFC 2822-compliant date format (with an English locale for %a and %b)
321
322           "%a, %d %b %Y %T %z"
323
324       RFC 822-compliant date format (with an English locale for %a and %b)
325
326           "%a, %d %b %y %T %z"
327
328   Example program
329       The program below can be used to experiment with strftime().
330
331       Some examples of the result string produced by the glibc implementation
332       of strftime() are as follows:
333
334           $ ./a.out '%m'
335           Result string is "11"
336           $ ./a.out '%5m'
337           Result string is "00011"
338           $ ./a.out '%_5m'
339           Result string is "   11"
340
341   Program source
342
343       #include <time.h>
344       #include <stdio.h>
345       #include <stdlib.h>
346
347       int
348       main(int argc, char *argv[])
349       {
350           char outstr[200];
351           time_t t;
352           struct tm *tmp;
353
354           t = time(NULL);
355           tmp = localtime(&t);
356           if (tmp == NULL) {
357               perror("localtime");
358               exit(EXIT_FAILURE);
359           }
360
361           if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
362               fprintf(stderr, "strftime returned 0");
363               exit(EXIT_FAILURE);
364           }
365
366           printf("Result string is \"%s\"\n", outstr);
367           exit(EXIT_SUCCESS);
368       }
369

SEE ALSO

371       date(1), time(2), ctime(3), nl_langinfo(3),  setlocale(3),  sprintf(3),
372       strptime(3)
373

COLOPHON

375       This  page  is  part of release 5.12 of the Linux man-pages project.  A
376       description of the project, information about reporting bugs,  and  the
377       latest     version     of     this    page,    can    be    found    at
378       https://www.kernel.org/doc/man-pages/.
379
380
381
382GNU                               2021-03-22                       STRFTIME(3)
Impressum