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.)
33
34       %A     The full name of the day of the week according  to  the  current
35              locale.  (Calculated from tm_wday.)
36
37       %b     The  abbreviated  month  name  according  to the current locale.
38              (Calculated from tm_mon.)
39
40       %B     The full month name according to the  current  locale.   (Calcu‐
41              lated from tm_mon.)
42
43       %c     The  preferred  date  and  time  representation  for the current
44              locale.
45
46       %C     The century number (year/100) as a 2-digit integer. (SU) (Calcu‐
47              lated from tm_year.)
48
49       %d     The  day  of  the  month  as  a decimal number (range 01 to 31).
50              (Calculated from tm_mday.)
51
52       %D     Equivalent to %m/%d/%y.  (Yecch—for Americans  only.   Americans
53              should  note  that in other countries %d/%m/%y is rather common.
54              This means that in international context this format is  ambigu‐
55              ous and should not be used.) (SU)
56
57       %e     Like %d, the day of the month as a decimal number, but a leading
58              zero is replaced by a space. (SU) (Calculated from tm_mday.)
59
60       %E     Modifier: use alternative format, see below. (SU)
61
62       %F     Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)
63
64       %G     The ISO 8601 week-based year (see NOTES) with century as a deci‐
65              mal number.  The 4-digit year corresponding to the ISO week num‐
66              ber (see %V).  This has the same format and value as %Y,  except
67              that  if  the  ISO  week  number belongs to the previous or next
68              year, that year is used instead. (TZ) (Calculated from  tm_year,
69              tm_yday, and tm_wday.)
70
71       %g     Like  %G,  but  without  century,  that  is, with a 2-digit year
72              (00–99). (TZ) (Calculated from tm_year, tm_yday, and tm_wday.)
73
74       %h     Equivalent to %b.  (SU)
75
76       %H     The hour as a decimal number using a 24-hour clock (range 00  to
77              23).  (Calculated from tm_hour.)
78
79       %I     The  hour as a decimal number using a 12-hour clock (range 01 to
80              12).  (Calculated from tm_hour.)
81
82       %j     The day of the year as a decimal  number  (range  001  to  366).
83              (Calculated from tm_yday.)
84
85       %k     The  hour  (24-hour  clock) as a decimal number (range 0 to 23);
86              single digits are preceded by a blank.  (See also %H.)   (Calcu‐
87              lated from tm_hour.)  (TZ)
88
89       %l     The  hour  (12-hour  clock) as a decimal number (range 1 to 12);
90              single digits are preceded by a blank.  (See also %I.)   (Calcu‐
91              lated from tm_hour.)  (TZ)
92
93       %m     The  month  as  a  decimal number (range 01 to 12).  (Calculated
94              from tm_mon.)
95
96       %M     The minute as a decimal number (range 00  to  59).   (Calculated
97              from tm_min.)
98
99       %n     A newline character. (SU)
100
101       %O     Modifier: use alternative format, see below. (SU)
102
103       %p     Either  "AM"  or  "PM" according to the given time value, or the
104              corresponding strings for the current locale.  Noon  is  treated
105              as "PM" and midnight as "AM".  (Calculated from tm_hour.)
106
107       %P     Like %p but in lowercase: "am" or "pm" or a corresponding string
108              for the current locale.  (Calculated from tm_hour.)  (GNU)
109
110       %r     The time in a.m. or p.m. notation.  In the POSIX locale this  is
111              equivalent to %I:%M:%S %p.  (SU)
112
113       %R     The  time  in  24-hour  notation  (%H:%M).   (SU)  For a version
114              including the seconds, see %T below.
115
116       %s     The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000
117              (UTC). (TZ) (Calculated from mktime(tm).)
118
119       %S     The  second as a decimal number (range 00 to 60).  (The range is
120              up to 60 to allow for  occasional  leap  seconds.)   (Calculated
121              from tm_sec.)
122
123       %t     A tab character. (SU)
124
125       %T     The time in 24-hour notation (%H:%M:%S).  (SU)
126
127       %u     The  day of the week as a decimal, range 1 to 7, Monday being 1.
128              See also %w.  (Calculated from tm_wday.)  (SU)
129
130       %U     The week number of the current year as a decimal  number,  range
131              00  to  53,  starting  with the first Sunday as the first day of
132              week 01.  See also %V and  %W.   (Calculated  from  tm_yday  and
133              tm_wday.)
134
135       %V     The  ISO 8601  week  number (see NOTES) of the current year as a
136              decimal number, range 01 to 53, where week 1 is the  first  week
137              that  has  at least 4 days in the new year.  See also %U and %W.
138              (Calculated from tm_year, tm_yday, and tm_wday.)  (SU)
139
140       %w     The day of the week as a decimal, range 0 to 6, Sunday being  0.
141              See also %u.  (Calculated from tm_wday.)
142
143       %W     The  week  number of the current year as a decimal number, range
144              00 to 53, starting with the first Monday as  the  first  day  of
145              week 01.  (Calculated from tm_yday and tm_wday.)
146
147       %x     The preferred date representation for the current locale without
148              the time.
149
150       %X     The preferred time representation for the current locale without
151              the date.
152
153       %y     The year as a decimal number without a century (range 00 to 99).
154              (Calculated from tm_year)
155
156       %Y     The year as a decimal number including the century.  (Calculated
157              from tm_year)
158
159       %z     The  +hhmm  or  -hhmm  numeric  timezone  (that is, the hour and
160              minute offset from UTC). (SU)
161
162       %Z     The timezone name or abbreviation.
163
164       %+     The date and time in date(1)  format.  (TZ)  (Not  supported  in
165              glibc2.)
166
167       %%     A literal '%' character.
168
169       Some conversion specifications can be modified by preceding the conver‐
170       sion specifier character by the E or O modifier  to  indicate  that  an
171       alternative format should be used.  If the alternative format or speci‐
172       fication does not exist for the current locale, the behavior will be as
173       if  the  unmodified conversion specification were used. (SU) The Single
174       UNIX Specification mentions %Ec, %EC, %Ex, %EX,  %Ey,  %EY,  %Od,  %Oe,
175       %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect
176       of the O modifier is to use alternative  numeric  symbols  (say,  roman
177       numerals),  and  that  of  the  E modifier is to use a locale-dependent
178       alternative representation.
179

RETURN VALUE

181       Provided that the result string, including the terminating  null  byte,
182       does  not  exceed  max  bytes,  strftime()  returns the number of bytes
183       (excluding the terminating null byte) placed in the array  s.   If  the
184       length of the result string (including the terminating null byte) would
185       exceed max bytes, then strftime() returns 0, and the  contents  of  the
186       array are undefined.
187
188       Note  that  the  return value 0 does not necessarily indicate an error.
189       For example, in many locales %p yields an empty string.  An empty  for‐
190       mat string will likewise yield an empty string.
191

ENVIRONMENT

193       The environment variables TZ and LC_TIME are used.
194

ATTRIBUTES

196       For   an   explanation   of   the  terms  used  in  this  section,  see
197       attributes(7).
198
199       ┌───────────┬───────────────┬────────────────────┐
200Interface  Attribute     Value              
201       ├───────────┼───────────────┼────────────────────┤
202strftime() │ Thread safety │ MT-Safe env locale │
203       └───────────┴───────────────┴────────────────────┘

CONFORMING TO

205       SVr4, C89, C99.  There are strict inclusions between the set of conver‐
206       sions given in ANSI C (unmarked), those given in the Single UNIX Speci‐
207       fication (marked SU), those given in Olson's timezone  package  (marked
208       TZ),  and those given in glibc (marked GNU), except that %+ is not sup‐
209       ported in glibc2.  On the other hand glibc2  has  several  more  exten‐
210       sions.   POSIX.1 only refers to ANSI C; POSIX.2 describes under date(1)
211       several extensions that could apply to strftime() as well.  The %F con‐
212       version is in C99 and POSIX.1-2001.
213
214       In  SUSv2,  the  %S specifier allowed a range of 00 to 61, to allow for
215       the theoretical possibility of a minute that  included  a  double  leap
216       second (there never has been such a minute).
217

NOTES

219   ISO 8601 week dates
220       %G, %g, and %V yield values calculated from the week-based year defined
221       by the ISO 8601 standard.  In this system, weeks start on a Monday, and
222       are  numbered from 01, for the first week, up to 52 or 53, for the last
223       week.  Week 1 is the first week where four or more days fall within the
224       new year (or, synonymously, week 01 is: the first week of the year that
225       contains a Thursday; or, the week that has  4  January  in  it).   When
226       three  of  fewer  days  of the first calendar week of the new year fall
227       within that year, then the ISO 8601 week-based system counts those days
228       as  part of week 53 of the preceding year.  For example, 1 January 2010
229       is a Friday, meaning that just three days of that calendar week fall in
230       2010.   Thus, the ISO 8601 week-based system considers these days to be
231       part of week 53 (%V) of the year 2009 (%G); week 01  of  ISO 8601  year
232       2010 starts on Monday, 4 January 2010.
233
234   Glibc notes
235       Glibc  provides  some extensions for conversion specifications.  (These
236       extensions are not specified in POSIX.1-2001, but a few  other  systems
237       provide  similar  features.)  Between the '%' character and the conver‐
238       sion specifier character, an optional flag and field width may be spec‐
239       ified.  (These precede the E or O modifiers, if present.)
240
241       The following flag characters are permitted:
242
243       _      (underscore) Pad a numeric result string with spaces.
244
245       -      (dash) Do not pad a numeric result string.
246
247       0      Pad  a  numeric  result string with zeros even if the conversion
248              specifier character uses space-padding by default.
249
250       ^      Convert alphabetic characters in result string to uppercase.
251
252       #      Swap the case of the result string.  (This flag works only  with
253              certain  conversion  specifier  characters,  and of these, it is
254              only really useful with %Z.)
255
256       An optional decimal width specifier may follow  the  (possibly  absent)
257       flag.   If  the  natural  size of the field is smaller than this width,
258       then the result string is padded (on the left) to the specified width.
259

BUGS

261       If the output string would exceed max bytes, errno is  not  set.   This
262       makes it impossible to distinguish this error case from cases where the
263       format  string  legitimately  produces  a  zero-length  output  string.
264       POSIX.1-2001 does not specify any errno settings for strftime().
265
266       Some  buggy  versions  of gcc(1) complain about the use of %c: warning:
267       `%c' yields only last 2 digits of year in some locales.  Of course pro‐
268       grammers are encouraged to use %c, it gives the preferred date and time
269       representation.  One meets all kinds of strange obfuscations to circum‐
270       vent this gcc(1) problem.  A relatively clean one is to add an interme‐
271       diate function
272
273           size_t
274           my_strftime(char *s, size_t max, const char *fmt,
275                       const struct tm *tm)
276           {
277               return strftime(s, max, fmt, tm);
278           }
279
280       Nowadays, gcc(1) provides the -Wno-format-y2k  option  to  prevent  the
281       warning, so that the above workaround is no longer required.
282

EXAMPLE

284       RFC 2822-compliant date format (with an English locale for %a and %b)
285
286         "%a, %d %b %Y %T %z"
287
288       RFC 822-compliant date format (with an English locale for %a and %b)
289
290         "%a, %d %b %y %T %z"
291
292   Example program
293       The program below can be used to experiment with strftime().
294
295       Some examples of the result string produced by the glibc implementation
296       of strftime() are as follows:
297
298           $ ./a.out '%m'
299           Result string is "11"
300           $ ./a.out '%5m'
301           Result string is "00011"
302           $ ./a.out '%_5m'
303           Result string is "   11"
304
305   Program source
306
307       #include <time.h>
308       #include <stdio.h>
309       #include <stdlib.h>
310
311       int
312       main(int argc, char *argv[])
313       {
314           char outstr[200];
315           time_t t;
316           struct tm *tmp;
317
318           t = time(NULL);
319           tmp = localtime(&t);
320           if (tmp == NULL) {
321               perror("localtime");
322               exit(EXIT_FAILURE);
323           }
324
325           if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
326               fprintf(stderr, "strftime returned 0");
327               exit(EXIT_FAILURE);
328           }
329
330           printf("Result string is \"%s\"\n", outstr);
331           exit(EXIT_SUCCESS);
332       }
333

SEE ALSO

335       date(1), time(2), ctime(3), setlocale(3), sprintf(3), strptime(3)
336

COLOPHON

338       This page is part of release 4.16 of the Linux  man-pages  project.   A
339       description  of  the project, information about reporting bugs, and the
340       latest    version    of    this    page,    can     be     found     at
341       https://www.kernel.org/doc/man-pages/.
342
343
344
345GNU                               2017-09-15                       STRFTIME(3)
Impressum