1STRFTIME(3P)               POSIX Programmer's Manual              STRFTIME(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       strftime - convert date and time to a string
13

SYNOPSIS

15       #include <time.h>
16
17       size_t strftime(char *restrict s, size_t maxsize,
18              const char *restrict format, const struct tm *restrict timeptr);
19
20

DESCRIPTION

22       The strftime() function shall place bytes into the array pointed to  by
23       s  as  controlled  by  the string pointed to by format. The format is a
24       character string, beginning and ending in its initial shift  state,  if
25       any.  The  format string consists of zero or more conversion specifica‐
26       tions and ordinary characters.  A conversion specification consists  of
27       a  '%' character, possibly followed by an E or O modifier, and a termi‐
28       nating conversion specifier character that  determines  the  conversion
29       specification's behavior. All ordinary characters (including the termi‐
30       nating null byte) are copied unchanged into the array. If copying takes
31       place  between objects that overlap, the behavior is undefined. No more
32       than maxsize bytes are placed into the array. Each conversion specifier
33       is  replaced  by  appropriate  characters as described in the following
34       list. The appropriate characters are determined using the LC_TIME cate‐
35       gory of the current locale and by the values of zero or more members of
36       the broken-down time structure pointed to by timeptr, as  specified  in
37       brackets in the description. If any of the specified values are outside
38       the normal range, the characters stored are unspecified.
39
40       Local timezone information is used as though strftime() called tzset().
41
42       The following conversion specifications are supported:
43
44       %a     Replaced by the locale's abbreviated weekday name. [ tm_wday]
45
46       %A     Replaced by the locale's full weekday name. [ tm_wday]
47
48       %b     Replaced by the locale's abbreviated month name. [ tm_mon]
49
50       %B     Replaced by the locale's full month name. [ tm_mon]
51
52       %c     Replaced by the locale's appropriate date and  time  representa‐
53              tion.  (See the Base Definitions volume of IEEE Std 1003.1-2001,
54              <time.h>.)
55
56       %C     Replaced by the year divided by 100 and truncated to an integer,
57              as a decimal number [00,99]. [ tm_year]
58
59       %d     Replaced  by the day of the month as a decimal number [01,31]. [
60              tm_mday]
61
62       %D     Equivalent to %m / %d / %y . [ tm_mon, tm_mday, tm_year]
63
64       %e     Replaced by the day of the month as a decimal number  [1,31];  a
65              single digit is preceded by a space. [ tm_mday]
66
67       %F     Equivalent to %Y - %m - %d (the ISO 8601:2000 standard date for‐
68              mat). [ tm_year, tm_mon, tm_mday]
69
70       %g     Replaced by the last 2 digits of the week-based year (see below)
71              as a decimal number [00,99]. [ tm_year, tm_wday, tm_yday]
72
73       %G     Replaced  by the week-based year (see below) as a decimal number
74              (for example, 1977). [ tm_year, tm_wday, tm_yday]
75
76       %h     Equivalent to %b . [ tm_mon]
77
78       %H     Replaced by  the  hour  (24-hour  clock)  as  a  decimal  number
79              [00,23].  [ tm_hour]
80
81       %I     Replaced  by  the  hour  (12-hour  clock)  as  a  decimal number
82              [01,12].  [ tm_hour]
83
84       %j     Replaced by the day of the year as a decimal number [001,366]. [
85              tm_yday]
86
87       %m     Replaced by the month as a decimal number [01,12]. [ tm_mon]
88
89       %M     Replaced by the minute as a decimal number [00,59]. [ tm_min]
90
91       %n     Replaced by a <newline>.
92
93       %p     Replaced  by  the  locale's  equivalent of either a.m. or p.m. [
94              tm_hour]
95
96       %r     Replaced by the time in a.m. and p.m. notation;   in  the  POSIX
97              locale this shall be equivalent to %I : %M : %S %p .  [ tm_hour,
98              tm_min, tm_sec]
99
100       %R     Replaced by the time in  24-hour  notation  (  %H  :  %M  ).   [
101              tm_hour, tm_min]
102
103       %S     Replaced by the second as a decimal number [00,60]. [ tm_sec]
104
105       %t     Replaced by a <tab>.
106
107       %T     Replaced  by  the  time  (  %H  :  %M : %S ). [ tm_hour, tm_min,
108              tm_sec]
109
110       %u     Replaced by the weekday as a decimal number [1,7], with 1 repre‐
111              senting Monday. [ tm_wday]
112
113       %U     Replaced  by  the  week  number  of the year as a decimal number
114              [00,53].  The first Sunday of January is the first day  of  week
115              1;  days  in  the new year before this are in week 0. [ tm_year,
116              tm_wday, tm_yday]
117
118       %V     Replaced by the week number of the year (Monday as the first day
119              of the week) as a decimal number [01,53]. If the week containing
120              1 January has four or more days in the new year, then it is con‐
121              sidered  week  1. Otherwise, it is the last week of the previous
122              year, and the next week is week 1.  Both  January  4th  and  the
123              first  Thursday  of  January  are  always  in week 1. [ tm_year,
124              tm_wday, tm_yday]
125
126       %w     Replaced by the weekday as a decimal number [0,6], with 0 repre‐
127              senting Sunday. [ tm_wday]
128
129       %W     Replaced  by  the  week  number  of the year as a decimal number
130              [00,53].  The first Monday of January is the first day  of  week
131              1;  days  in  the new year before this are in week 0. [ tm_year,
132              tm_wday, tm_yday]
133
134       %x     Replaced by the locale's appropriate date  representation.  (See
135              the Base Definitions volume of IEEE Std 1003.1-2001, <time.h>.)
136
137       %X     Replaced  by  the locale's appropriate time representation. (See
138              the Base Definitions volume of IEEE Std 1003.1-2001, <time.h>.)
139
140       %y     Replaced by the last two digits of the year as a decimal  number
141              [00,99].  [ tm_year]
142
143       %Y     Replaced  by the year as a decimal number (for example, 1997). [
144              tm_year]
145
146       %z     Replaced by the offset from UTC in  the  ISO 8601:2000  standard
147              format ( +hhmm or -hhmm ), or by no characters if no timezone is
148              determinable. For example, "-0430"  means  4  hours  30  minutes
149              behind UTC (west of Greenwich).   If tm_isdst is zero, the stan‐
150              dard time offset is used. If tm_isdst is greater than zero,  the
151              daylight  savings  time offset is used. If tm_isdst is negative,
152              no characters are returned.  [ tm_isdst]
153
154       %Z     Replaced by the timezone name or abbreviation, or by no bytes if
155              no timezone information exists. [ tm_isdst]
156
157       %%     Replaced by % .
158
159
160       If  a conversion specification does not correspond to any of the above,
161       the behavior is undefined.
162
163       If a struct tm broken-down time structure is created by localtime()  or
164       localtime_r(),  or  modified by mktime(), and the value of TZ is subse‐
165       quently modified, the results of the %Z and  %z  strftime()  conversion
166       specifiers are undefined, when strftime() is called with such a broken-
167       down time structure.
168
169       If a struct tm broken-down time structure is  created  or  modified  by
170       gmtime()  or gmtime_r(), it is unspecified whether the result of the %Z
171       and %z conversion specifiers shall refer to UTC or  the  current  local
172       timezone, when strftime() is called with such a broken-down time struc‐
173       ture.
174
175   Modified Conversion Specifiers
176       Some conversion specifiers can be modified by the E or O modifier char‐
177       acters  to  indicate that an alternative format or specification should
178       be used rather than the one normally used by the unmodified  conversion
179       specifier.  If  the  alternative format or specification does not exist
180       for the current locale (see ERA  in  the  Base  Definitions  volume  of
181       IEEE Std 1003.1-2001, Section 7.3.5, LC_TIME), the behavior shall be as
182       if the unmodified conversion specification were used.
183
184       %Ec    Replaced by the locale's alternative appropriate date  and  time
185              representation.
186
187       %EC    Replaced  by  the name of the base year (period) in the locale's
188              alternative representation.
189
190       %Ex    Replaced by the locale's alternative date representation.
191
192       %EX    Replaced by the locale's alternative time representation.
193
194       %Ey    Replaced by the offset from %EC  (year  only)  in  the  locale's
195              alternative representation.
196
197       %EY    Replaced by the full alternative year representation.
198
199       %Od    Replaced by the day of the month, using the locale's alternative
200              numeric symbols, filled as needed with leading zeros if there is
201              any alternative symbol for zero; otherwise, with leading spaces.
202
203       %Oe    Replaced by the day of the month, using the locale's alternative
204              numeric symbols, filled as needed with leading spaces.
205
206       %OH    Replaced by the hour (24-hour clock) using the locale's alterna‐
207              tive numeric symbols.
208
209       %OI    Replaced by the hour (12-hour clock) using the locale's alterna‐
210              tive numeric symbols.
211
212       %Om    Replaced by the month using  the  locale's  alternative  numeric
213              symbols.
214
215       %OM    Replaced  by  the minutes using the locale's alternative numeric
216              symbols.
217
218       %OS    Replaced by the seconds using the locale's  alternative  numeric
219              symbols.
220
221       %Ou    Replaced  by the weekday as a number in the locale's alternative
222              representation (Monday=1).
223
224       %OU    Replaced by the week number of the year (Sunday as the first day
225              of  the  week,  rules  corresponding  to %U ) using the locale's
226              alternative numeric symbols.
227
228       %OV    Replaced by the week number of the year (Monday as the first day
229              of  the  week,  rules  corresponding  to %V ) using the locale's
230              alternative numeric symbols.
231
232       %Ow    Replaced by the number  of  the  weekday  (Sunday=0)  using  the
233              locale's alternative numeric symbols.
234
235       %OW    Replaced by the week number of the year (Monday as the first day
236              of the week) using the locale's alternative numeric symbols.
237
238       %Oy    Replaced by the year (offset from %C ) using the locale's alter‐
239              native numeric symbols.
240
241
242       %g,  %G,  and  %V  give  values according to the ISO 8601:2000 standard
243       week-based year. In this system, weeks begin on a Monday and week 1  of
244       the  year is the week that includes January 4th, which is also the week
245       that includes the first Thursday of the year, and  is  also  the  first
246       week  that contains at least four days in the year. If the first Monday
247       of January is the 2nd, 3rd, or 4th, the preceding days are part of  the
248       last  week  of the preceding year; thus, for Saturday 2nd January 1999,
249       %G is replaced by 1998 and %V is replaced by  53.   If  December  29th,
250       30th, or 31st is a Monday, it and any following days are part of week 1
251       of the following year. Thus, for Tuesday  30th  December  1997,  %G  is
252       replaced by 1998 and %V is replaced by 01.
253
254       If  a  conversion  specifier  is  not one of the above, the behavior is
255       undefined.
256

RETURN VALUE

258       If the total number of resulting bytes including the  terminating  null
259       byte  is  not  more than maxsize, strftime() shall return the number of
260       bytes placed into the array pointed to by s, not including  the  termi‐
261       nating  null  byte.  Otherwise, 0 shall be returned and the contents of
262       the array are unspecified.
263

ERRORS

265       No errors are defined.
266
267       The following sections are informative.
268

EXAMPLES

270   Getting a Localized Date String
271       The following example first sets the locale to the user's default.  The
272       locale  information  will  be  used in the nl_langinfo() and strftime()
273       functions. The nl_langinfo() function returns the localized date string
274       which specifies how the date is laid out. The strftime() function takes
275       this information and, using the tm structure  for  values,  places  the
276       date and time information into datestring.
277
278
279              #include <time.h>
280              #include <locale.h>
281              #include <langinfo.h>
282              ...
283              struct tm *tm;
284              char datestring[256];
285              ...
286              setlocale (LC_ALL, "");
287              ...
288              strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm);
289              ...
290

APPLICATION USAGE

292       The  range of values for %S is [00,60] rather than [00,59] to allow for
293       the occasional leap second.
294
295       Some of the conversion specifications are duplicates  of  others.  They
296       are  included  for  compatibility  with  nl_cxtime() and nl_ascxtime(),
297       which were published in Issue 2.
298
299       Applications should use %Y (4-digit years) in preference to %y (2-digit
300       years).
301
302       In  the C locale, the E and O modifiers are ignored and the replacement
303       strings for the following specifiers are:
304
305       %a     The first three characters of %A .
306
307       %A     One of Sunday, Monday, ..., Saturday.
308
309       %b     The first three characters of %B .
310
311       %B     One of January, February, ..., December.
312
313       %c     Equivalent to %a %b %e %T %Y .
314
315       %p     One of AM or PM.
316
317       %r     Equivalent to %I : %M : %S %p .
318
319       %x     Equivalent to %m / %d / %y .
320
321       %X     Equivalent to %T .
322
323       %Z     Implementation-defined.
324
325

RATIONALE

327       None.
328

FUTURE DIRECTIONS

330       None.
331

SEE ALSO

333       asctime(), clock(), ctime(), difftime(),  getdate(),  gmtime(),  local‐
334       time(),  mktime(),  strptime(),  time(), tzset(), utime(), Base Defini‐
335       tions volume of IEEE Std 1003.1-2001, Section 7.3.5, LC_TIME, <time.h>
336
338       Portions of this text are reprinted and reproduced in  electronic  form
339       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
340       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
341       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
342       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
343       event of any discrepancy between this version and the original IEEE and
344       The Open Group Standard, the original IEEE and The Open Group  Standard
345       is  the  referee document. The original Standard can be obtained online
346       at http://www.opengroup.org/unix/online.html .
347
348
349
350IEEE/The Open Group                  2003                         STRFTIME(3P)
Impressum