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 *s, size_t max, const char *format,
12                       const struct tm *tm);
13

DESCRIPTION

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
20       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
26       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
31       %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_{17} as an argument.)
35
36       %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_{17} as an argument.)
40
41       %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_{112} as an argument.)
45
46       %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_{112}
49              as an argument.)
50
51       %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
58       %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
62       %d     The day of the month as a  decimal  number  (range  01  to  31).
63              (Calculated from tm_mday.)
64
65       %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
70       %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
73       %E     Modifier: use alternative ("era-based") format, see below. (SU)
74
75       %F     Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)
76
77       %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
84       %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
87       %h     Equivalent to %b.  (SU)
88
89       %H     The  hour as a decimal number using a 24-hour clock (range 00 to
90              23).  (Calculated from tm_hour.)
91
92       %I     The hour as a decimal number using a 12-hour clock (range 01  to
93              12).  (Calculated from tm_hour.)
94
95       %j     The  day  of  the  year  as a decimal number (range 001 to 366).
96              (Calculated from tm_yday.)
97
98       %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
102       %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
106       %m     The month as a decimal number (range  01  to  12).   (Calculated
107              from tm_mon.)
108
109       %M     The  minute  as  a decimal number (range 00 to 59).  (Calculated
110              from tm_min.)
111
112       %n     A newline character. (SU)
113
114       %O     Modifier: use alternative numeric symbols, see below. (SU)
115
116       %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
123       %P     Like %p but in lowercase: "am" or "pm" or a corresponding string
124              for the current locale.  (Calculated from tm_hour.)  (GNU)
125
126       %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
131       %R     The  time  in  24-hour notation (%H:%M).  (SU) For a version in‐
132              cluding the seconds, see %T below.
133
134       %s     The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000
135              (UTC). (TZ) (Calculated from mktime(tm).)
136
137       %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
141       %t     A tab character. (SU)
142
143       %T     The time in 24-hour notation (%H:%M:%S).  (SU)
144
145       %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
148       %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
153       %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
158       %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
161       %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
165       %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
172       %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
179       %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
184       %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
188       %z     The +hhmm or -hhmm numeric  timezone  (that  is,  the  hour  and
189              minute offset from UTC). (SU)
190
191       %Z     The timezone name or abbreviation.
192
193       %+     The  date  and  time  in  date(1) format. (TZ) (Not supported in
194              glibc2.)
195
196       %%     A literal '%' character.
197
198       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

RETURN VALUE

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
220       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

ENVIRONMENT

225       The environment variables TZ and LC_TIME are used.
226

ATTRIBUTES

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

CONFORMING TO

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
246       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

NOTES

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
268   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
275       The following flag characters are permitted:
276
277       _      (underscore) Pad a numeric result string with spaces.
278
279       -      (dash) Do not pad a numeric result string.
280
281       0      Pad  a  numeric  result string with zeros even if the conversion
282              specifier character uses space-padding by default.
283
284       ^      Convert alphabetic characters in result string to uppercase.
285
286       #      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
290       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

BUGS

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
300       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
307           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
314       Nowadays, gcc(1) provides the -Wno-format-y2k  option  to  prevent  the
315       warning, so that the above workaround is no longer required.
316

EXAMPLES

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

SEE ALSO

369       date(1), time(2), ctime(3), nl_langinfo(3),  setlocale(3),  sprintf(3),
370       strptime(3)
371

COLOPHON

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/.
377
378
379
380GNU                               2020-08-13                       STRFTIME(3)
Impressum