1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
1 |
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved |
2
by Francesco Paolo Lovergine
* Alligned to linux main manpages edition. |
2 |
.TH "STRFTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" |
1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
3 |
.\" strftime |
4 |
.SH NAME |
|
5 |
strftime \- convert date and time to a string
|
|
6 |
.SH SYNOPSIS |
|
7 |
.LP
|
|
8 |
\fB#include <time.h>
|
|
9 |
.br
|
|
10 |
.sp
|
|
11 |
size_t strftime(char *restrict\fP \fIs\fP\fB, size_t\fP \fImaxsize\fP\fB, |
|
12 |
.br
|
|
13 |
\ \ \ \ \ \ const char *restrict\fP \fIformat\fP\fB, const struct |
|
14 |
tm *restrict\fP
|
|
15 |
\fItimeptr\fP\fB); |
|
16 |
.br
|
|
17 |
\fP
|
|
18 |
.SH DESCRIPTION |
|
19 |
.LP
|
|
20 |
The \fIstrftime\fP() function shall place bytes into the array pointed |
|
21 |
to by \fIs\fP as controlled by the string pointed to by |
|
22 |
\fIformat\fP. The format is a character string, beginning and ending |
|
23 |
in its initial shift state, if any. The \fIformat\fP string |
|
24 |
consists of zero or more conversion specifications and ordinary characters. |
|
25 |
A conversion specification consists of a \fB'%'\fP |
|
26 |
character, possibly followed by an \fBE\fP or \fBO\fP modifier, and |
|
27 |
a terminating conversion specifier character that |
|
28 |
determines the conversion specification's behavior. All ordinary characters |
|
29 |
(including the terminating null byte) are copied |
|
30 |
unchanged into the array. If copying takes place between objects that |
|
31 |
overlap, the behavior is undefined. No more than |
|
32 |
\fImaxsize\fP bytes are placed into the array. Each conversion specifier |
|
33 |
is replaced by appropriate characters as described in the |
|
34 |
following list. The appropriate characters are determined using the |
|
35 |
\fILC_TIME\fP category of the current locale and by the values |
|
36 |
of zero or more members of the broken-down time structure pointed |
|
37 |
to by \fItimeptr\fP, as specified in brackets in the |
|
38 |
description. If any of the specified values are outside the normal |
|
39 |
range, the characters stored are unspecified. |
|
40 |
.LP
|
|
41 |
Local timezone information is used as though \fIstrftime\fP() called |
|
42 |
\fItzset\fP(). |
|
43 |
.LP
|
|
44 |
The following conversion specifications are supported: |
|
45 |
.TP 7 |
|
46 |
\fB%a\fP |
|
47 |
Replaced by the locale's abbreviated weekday name. [ \fItm_wday\fP] |
|
48 |
.TP 7 |
|
49 |
\fB%A\fP |
|
50 |
Replaced by the locale's full weekday name. [ \fItm_wday\fP] |
|
51 |
.TP 7 |
|
52 |
\fB%b\fP |
|
53 |
Replaced by the locale's abbreviated month name. [ \fItm_mon\fP] |
|
54 |
.TP 7 |
|
55 |
\fB%B\fP |
|
56 |
Replaced by the locale's full month name. [ \fItm_mon\fP] |
|
57 |
.TP 7 |
|
58 |
\fB%c\fP |
|
59 |
Replaced by the locale's appropriate date and time representation. |
|
60 |
(See the Base Definitions volume of |
|
61 |
IEEE\ Std\ 1003.1-2001, \fI<time.h>\fP.) |
|
62 |
.TP 7 |
|
63 |
\fB%C\fP |
|
64 |
Replaced by the year divided by 100 and truncated to an integer, as |
|
65 |
a decimal number [00,99]. [ \fItm_year\fP] |
|
66 |
.TP 7 |
|
67 |
\fB%d\fP |
|
68 |
Replaced by the day of the month as a decimal number [01,31]. [ \fItm_mday\fP] |
|
69 |
.TP 7 |
|
70 |
\fB%D\fP |
|
71 |
Equivalent to \fB%m\fP / \fB%d\fP / \fB%y\fP . [ \fItm_mon\fP, \fItm_mday\fP, |
|
72 |
\fItm_year\fP] |
|
73 |
.TP 7 |
|
74 |
\fB%e\fP |
|
75 |
Replaced by the day of the month as a decimal number [1,31]; a single |
|
76 |
digit is preceded by a space. [ \fItm_mday\fP] |
|
77 |
.TP 7 |
|
78 |
\fB%F\fP |
|
79 |
Equivalent to \fB%Y\fP - \fB%m\fP - \fB%d\fP (the ISO\ 8601:2000 standard |
|
80 |
date format). [ \fItm_year\fP, |
|
81 |
\fItm_mon\fP, \fItm_mday\fP] |
|
82 |
.TP 7 |
|
83 |
\fB%g\fP |
|
84 |
Replaced by the last 2 digits of the week-based year (see below) as |
|
85 |
a decimal number [00,99]. [ \fItm_year\fP, \fItm_wday\fP, |
|
86 |
\fItm_yday\fP] |
|
87 |
.TP 7 |
|
88 |
\fB%G\fP |
|
89 |
Replaced by the week-based year (see below) as a decimal number (for |
|
90 |
example, 1977). [ \fItm_year\fP, \fItm_wday\fP, |
|
91 |
\fItm_yday\fP] |
|
92 |
.TP 7 |
|
93 |
\fB%h\fP |
|
94 |
Equivalent to \fB%b\fP . [ \fItm_mon\fP] |
|
95 |
.TP 7 |
|
96 |
\fB%H\fP |
|
97 |
Replaced by the hour (24-hour clock) as a decimal number [00,23]. |
|
98 |
[ \fItm_hour\fP] |
|
99 |
.TP 7 |
|
100 |
\fB%I\fP |
|
101 |
Replaced by the hour (12-hour clock) as a decimal number [01,12]. |
|
102 |
[ \fItm_hour\fP] |
|
103 |
.TP 7 |
|
104 |
\fB%j\fP |
|
105 |
Replaced by the day of the year as a decimal number [001,366]. [ \fItm_yday\fP] |
|
106 |
.TP 7 |
|
107 |
\fB%m\fP |
|
108 |
Replaced by the month as a decimal number [01,12]. [ \fItm_mon\fP] |
|
109 |
.TP 7 |
|
110 |
\fB%M\fP |
|
111 |
Replaced by the minute as a decimal number [00,59]. [ \fItm_min\fP] |
|
112 |
.TP 7 |
|
113 |
\fB%n\fP |
|
114 |
Replaced by a <newline>. |
|
115 |
.TP 7 |
|
116 |
\fB%p\fP |
|
117 |
Replaced by the locale's equivalent of either a.m. or p.m. [ \fItm_hour\fP] |
|
118 |
.TP 7 |
|
119 |
\fB%r\fP |
|
120 |
Replaced by the time in a.m. and p.m. notation; \ in the POSIX locale
|
|
121 |
this shall be equivalent to \fB%I\fP : |
|
122 |
\fB%M\fP : \fB%S\fP \fB%p\fP . [ \fItm_hour\fP, |
|
123 |
\fItm_min\fP, \fItm_sec\fP] |
|
124 |
.TP 7 |
|
125 |
\fB%R\fP |
|
126 |
Replaced by the time in 24-hour notation ( \fB%H\fP : \fB%M\fP ). |
|
127 |
[ \fItm_hour\fP, \fItm_min\fP] |
|
128 |
.TP 7 |
|
129 |
\fB%S\fP |
|
130 |
Replaced by the second as a decimal number [00,60]. [ \fItm_sec\fP] |
|
131 |
.TP 7 |
|
132 |
\fB%t\fP |
|
133 |
Replaced by a <tab>. |
|
134 |
.TP 7 |
|
135 |
\fB%T\fP |
|
136 |
Replaced by the time ( \fB%H\fP : \fB%M\fP : \fB%S\fP ). [ \fItm_hour\fP, |
|
137 |
\fItm_min\fP, \fItm_sec\fP] |
|
138 |
.TP 7 |
|
139 |
\fB%u\fP |
|
140 |
Replaced by the weekday as a decimal number [1,7], with 1 representing |
|
141 |
Monday. [ \fItm_wday\fP] |
|
142 |
.TP 7 |
|
143 |
\fB%U\fP |
|
144 |
Replaced by the week number of the year as a decimal number [00,53]. |
|
145 |
The first Sunday of January is the first day of week 1; |
|
146 |
days in the new year before this are in week 0. [ \fItm_year\fP, \fItm_wday\fP, |
|
147 |
\fItm_yday\fP] |
|
148 |
.TP 7 |
|
149 |
\fB%V\fP |
|
150 |
Replaced by the week number of the year (Monday as the first day of |
|
151 |
the week) as a decimal number [01,53]. If the week |
|
152 |
containing 1 January has four or more days in the new year, then it |
|
153 |
is considered week 1. Otherwise, it is the last week of the |
|
154 |
previous year, and the next week is week 1. Both January 4th and the |
|
155 |
first Thursday of January are always in week 1. [ |
|
156 |
\fItm_year\fP, \fItm_wday\fP, \fItm_yday\fP] |
|
157 |
.TP 7 |
|
158 |
\fB%w\fP |
|
159 |
Replaced by the weekday as a decimal number [0,6], with 0 representing |
|
160 |
Sunday. [ \fItm_wday\fP] |
|
161 |
.TP 7 |
|
162 |
\fB%W\fP |
|
163 |
Replaced by the week number of the year as a decimal number [00,53]. |
|
164 |
The first Monday of January is the first day of week 1; |
|
165 |
days in the new year before this are in week 0. [ \fItm_year\fP, \fItm_wday\fP, |
|
166 |
\fItm_yday\fP] |
|
167 |
.TP 7 |
|
168 |
\fB%x\fP |
|
169 |
Replaced by the locale's appropriate date representation. (See the |
|
170 |
Base Definitions volume of IEEE\ Std\ 1003.1-2001, |
|
171 |
\fI<time.h>\fP.) |
|
172 |
.TP 7 |
|
173 |
\fB%X\fP |
|
174 |
Replaced by the locale's appropriate time representation. (See the |
|
175 |
Base Definitions volume of IEEE\ Std\ 1003.1-2001, |
|
176 |
\fI<time.h>\fP.) |
|
177 |
.TP 7 |
|
178 |
\fB%y\fP |
|
179 |
Replaced by the last two digits of the year as a decimal number [00,99]. |
|
180 |
[ \fItm_year\fP] |
|
181 |
.TP 7 |
|
182 |
\fB%Y\fP |
|
183 |
Replaced by the year as a decimal number (for example, 1997). [ \fItm_year\fP] |
|
184 |
.TP 7 |
|
185 |
\fB%z\fP |
|
186 |
Replaced by the offset from UTC in the ISO\ 8601:2000 standard format
|
|
187 |
( \fB+hhmm\fP or \fB-hhmm\fP ), or by no |
|
188 |
characters if no timezone is determinable. For example, \fB"-0430"\fP |
|
189 |
means 4 hours 30 minutes behind UTC (west of Greenwich). |
|
190 |
\ If \fItm_isdst\fP is zero, the standard time offset is used. If |
|
191 |
\fItm_isdst\fP is greater than zero, the daylight savings |
|
192 |
time offset is used. If \fItm_isdst\fP is negative, no characters |
|
193 |
are returned. [ \fItm_isdst\fP] |
|
194 |
.TP 7 |
|
195 |
\fB%Z\fP |
|
196 |
Replaced by the timezone name or abbreviation, or by no bytes if no |
|
197 |
timezone information exists. [ \fItm_isdst\fP] |
|
198 |
.TP 7 |
|
199 |
\fB%%\fP |
|
200 |
Replaced by \fB%\fP . |
|
201 |
.sp
|
|
202 |
.LP
|
|
203 |
If a conversion specification does not correspond to any of the above, |
|
204 |
the behavior is undefined. |
|
205 |
.LP
|
|
206 |
If |
|
207 |
a \fBstruct tm\fP broken-down time structure is created by \fIlocaltime\fP() |
|
208 |
or \fIlocaltime_r\fP(), or modified by \fImktime\fP(), and the value |
|
209 |
of \fITZ\fP is subsequently modified, the results of the \fB%Z\fP |
|
210 |
and \fB%z\fP \fIstrftime\fP() conversion specifiers are undefined, |
|
211 |
when \fIstrftime\fP() is called with such a broken-down |
|
212 |
time structure. |
|
213 |
.LP
|
|
214 |
If a \fBstruct tm\fP broken-down time structure is created or modified |
|
215 |
by \fIgmtime\fP() or \fIgmtime_r\fP(), it is unspecified |
|
216 |
whether the result of the \fB%Z\fP and \fB%z\fP conversion specifiers |
|
217 |
shall refer to UTC or the current local timezone, when |
|
218 |
\fIstrftime\fP() is called with such a broken-down time structure. |
|
219 |
.SS Modified Conversion Specifiers |
|
220 |
.LP
|
|
221 |
Some conversion specifiers can be modified by the \fBE\fP or \fBO\fP |
|
222 |
modifier characters to indicate that an alternative |
|
223 |
format or specification should be used rather than the one normally |
|
224 |
used by the unmodified conversion specifier. If the alternative |
|
225 |
format or specification does not exist for the current locale (see |
|
226 |
ERA in the Base Definitions volume of |
|
227 |
IEEE\ Std\ 1003.1-2001, Section 7.3.5, LC_TIME), the behavior shall |
|
228 |
be as if the unmodified conversion specification were used. |
|
229 |
.TP 7 |
|
230 |
\fB%Ec\fP |
|
231 |
Replaced by the locale's alternative appropriate date and time representation. |
|
232 |
.TP 7 |
|
233 |
\fB%EC\fP |
|
234 |
Replaced by the name of the base year (period) in the locale's alternative |
|
235 |
representation. |
|
236 |
.TP 7 |
|
237 |
\fB%Ex\fP |
|
238 |
Replaced by the locale's alternative date representation. |
|
239 |
.TP 7 |
|
240 |
\fB%EX\fP |
|
241 |
Replaced by the locale's alternative time representation. |
|
242 |
.TP 7 |
|
243 |
\fB%Ey\fP |
|
244 |
Replaced by the offset from \fB%EC\fP (year only) in the locale's |
|
245 |
alternative representation. |
|
246 |
.TP 7 |
|
247 |
\fB%EY\fP |
|
248 |
Replaced by the full alternative year representation. |
|
249 |
.TP 7 |
|
250 |
\fB%Od\fP |
|
251 |
Replaced by the day of the month, using the locale's alternative numeric |
|
252 |
symbols, filled as needed with leading zeros if there |
|
253 |
is any alternative symbol for zero; otherwise, with leading spaces. |
|
254 |
.TP 7 |
|
255 |
\fB%Oe\fP |
|
256 |
Replaced by the day of the month, using the locale's alternative numeric |
|
257 |
symbols, filled as needed with leading spaces. |
|
258 |
.TP 7 |
|
259 |
\fB%OH\fP |
|
260 |
Replaced by the hour (24-hour clock) using the locale's alternative |
|
261 |
numeric symbols. |
|
262 |
.TP 7 |
|
263 |
\fB%OI\fP |
|
264 |
Replaced by the hour (12-hour clock) using the locale's alternative |
|
265 |
numeric symbols. |
|
266 |
.TP 7 |
|
267 |
\fB%Om\fP |
|
268 |
Replaced by the month using the locale's alternative numeric symbols. |
|
269 |
.TP 7 |
|
270 |
\fB%OM\fP |
|
271 |
Replaced by the minutes using the locale's alternative numeric symbols. |
|
272 |
.TP 7 |
|
273 |
\fB%OS\fP |
|
274 |
Replaced by the seconds using the locale's alternative numeric symbols. |
|
275 |
.TP 7 |
|
276 |
\fB%Ou\fP |
|
277 |
Replaced by the weekday as a number in the locale's alternative representation |
|
278 |
(Monday=1). |
|
279 |
.TP 7 |
|
280 |
\fB%OU\fP |
|
281 |
Replaced by the week number of the year (Sunday as the first day of |
|
282 |
the week, rules corresponding to \fB%U\fP ) using the |
|
283 |
locale's alternative numeric symbols. |
|
284 |
.TP 7 |
|
285 |
\fB%OV\fP |
|
286 |
Replaced by the week number of the year (Monday as the first day of |
|
287 |
the week, rules corresponding to \fB%V\fP ) using the |
|
288 |
locale's alternative numeric symbols. |
|
289 |
.TP 7 |
|
290 |
\fB%Ow\fP |
|
291 |
Replaced by the number of the weekday (Sunday=0) using the locale's |
|
292 |
alternative numeric symbols. |
|
293 |
.TP 7 |
|
294 |
\fB%OW\fP |
|
295 |
Replaced by the week number of the year (Monday as the first day of |
|
296 |
the week) using the locale's alternative numeric |
|
297 |
symbols. |
|
298 |
.TP 7 |
|
299 |
\fB%Oy\fP |
|
300 |
Replaced by the year (offset from \fB%C\fP ) using the locale's alternative |
|
301 |
numeric symbols. |
|
302 |
.sp
|
|
303 |
.LP
|
|
304 |
\fB%g\fP , \fB%G\fP , and \fB%V\fP give values according to the ISO\ 8601:2000 |
|
305 |
standard week-based year. In this |
|
306 |
system, weeks begin on a Monday and week 1 of the year is the week |
|
307 |
that includes January 4th, which is also the week that includes |
|
308 |
the first Thursday of the year, and is also the first week that contains |
|
309 |
at least four days in the year. If the first Monday of |
|
310 |
January is the 2nd, 3rd, or 4th, the preceding days are part of the |
|
311 |
last week of the preceding year; thus, for Saturday 2nd January |
|
312 |
1999, \fB%G\fP is replaced by 1998 and \fB%V\fP is replaced by 53. |
|
313 |
If December 29th, 30th, or 31st is a Monday, it and any |
|
314 |
following days are part of week 1 of the following year. Thus, for |
|
315 |
Tuesday 30th December 1997, \fB%G\fP is replaced by 1998 and |
|
316 |
\fB%V\fP is replaced by 01. |
|
317 |
.LP
|
|
318 |
If a conversion specifier is not one of the above, the behavior is |
|
319 |
undefined. |
|
320 |
.SH RETURN VALUE |
|
321 |
.LP
|
|
322 |
If the total number of resulting bytes including the terminating null |
|
323 |
byte is not more than \fImaxsize\fP, \fIstrftime\fP() |
|
324 |
shall return the number of bytes placed into the array pointed to |
|
325 |
by \fIs\fP, not including the terminating null byte. Otherwise, |
|
326 |
0 shall be returned and the contents of the array are unspecified. |
|
327 |
.SH ERRORS |
|
328 |
.LP
|
|
329 |
No errors are defined. |
|
330 |
.LP
|
|
331 |
\fIThe following sections are informative.\fP |
|
332 |
.SH EXAMPLES |
|
333 |
.SS Getting a Localized Date String |
|
334 |
.LP
|
|
335 |
The following example first sets the locale to the user's default. |
|
336 |
The locale information will be used in the \fInl_langinfo\fP() and |
|
337 |
\fIstrftime\fP() functions. The \fInl_langinfo\fP() function returns |
|
338 |
the localized date string which specifies how the date is |
|
339 |
laid out. The \fIstrftime\fP() function takes this information and, |
|
340 |
using the \fBtm\fP structure for values, places the date and |
|
341 |
time information into \fIdatestring\fP. |
|
342 |
.sp
|
|
343 |
.RS
|
|
344 |
.nf
|
|
345 |
||
346 |
\fB#include <time.h>
|
|
347 |
#include <locale.h> |
|
348 |
#include <langinfo.h> |
|
349 |
\&...
|
|
350 |
struct tm *tm; |
|
351 |
char datestring[256]; |
|
352 |
\&...
|
|
353 |
setlocale (LC_ALL, ""); |
|
354 |
\&...
|
|
355 |
strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); |
|
356 |
\&...
|
|
357 |
\fP
|
|
358 |
.fi
|
|
359 |
.RE
|
|
360 |
.SH APPLICATION USAGE |
|
361 |
.LP
|
|
362 |
The range of values for \fB%S\fP is [00,60] rather than [00,59] to |
|
363 |
allow for the occasional leap second. |
|
364 |
.LP
|
|
365 |
Some of the conversion specifications are duplicates of others. They |
|
366 |
are included for compatibility with \fInl_cxtime\fP() and |
|
367 |
\fInl_ascxtime\fP(), which were published in Issue 2. |
|
368 |
.LP
|
|
369 |
Applications should use \fB%Y\fP (4-digit years) in preference to |
|
370 |
\fB%y\fP (2-digit years). |
|
371 |
.LP
|
|
372 |
In the C locale, the \fBE\fP and \fBO\fP modifiers are ignored and |
|
373 |
the replacement strings for the following specifiers |
|
374 |
are: |
|
375 |
.TP 7 |
|
376 |
\fB%a\fP |
|
377 |
The first three characters of \fB%A\fP . |
|
378 |
.TP 7 |
|
379 |
\fB%A\fP |
|
380 |
One of Sunday, Monday, ..., Saturday. |
|
381 |
.TP 7 |
|
382 |
\fB%b\fP |
|
383 |
The first three characters of \fB%B\fP . |
|
384 |
.TP 7 |
|
385 |
\fB%B\fP |
|
386 |
One of January, February, ..., December. |
|
387 |
.TP 7 |
|
388 |
\fB%c\fP |
|
389 |
Equivalent to \fB%a\fP \fB%b\fP \fB%e\fP \fB%T\fP \fB%Y\fP . |
|
390 |
.TP 7 |
|
391 |
\fB%p\fP |
|
392 |
One of AM or PM. |
|
393 |
.TP 7 |
|
394 |
\fB%r\fP |
|
395 |
Equivalent to \fB%I\fP : \fB%M\fP : \fB%S\fP \fB%p\fP . |
|
396 |
.TP 7 |
|
397 |
\fB%x\fP |
|
398 |
Equivalent to \fB%m\fP / \fB%d\fP / \fB%y\fP . |
|
399 |
.TP 7 |
|
400 |
\fB%X\fP |
|
401 |
Equivalent to \fB%T\fP . |
|
402 |
.TP 7 |
|
403 |
\fB%Z\fP |
|
404 |
Implementation-defined. |
|
405 |
.sp
|
|
406 |
.SH RATIONALE |
|
407 |
.LP
|
|
408 |
None. |
|
409 |
.SH FUTURE DIRECTIONS |
|
410 |
.LP
|
|
411 |
None. |
|
412 |
.SH SEE ALSO |
|
413 |
.LP
|
|
414 |
\fIasctime\fP() , \fIclock\fP() , \fIctime\fP() |
|
415 |
, \fIdifftime\fP() , \fIgetdate\fP() , \fIgmtime\fP() , \fIlocaltime\fP() |
|
416 |
, \fImktime\fP() , |
|
417 |
\fIstrptime\fP() , \fItime\fP() , \fItzset\fP() , |
|
418 |
\fIutime\fP() , Base Definitions volume of IEEE\ Std\ 1003.1-2001, |
|
419 |
Section 7.3.5, LC_TIME, \fI<time.h>\fP |
|
420 |
.SH COPYRIGHT |
|
421 |
Portions of this text are reprinted and reproduced in electronic form |
|
422 |
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology |
|
423 |
-- Portable Operating System Interface (POSIX), The Open Group Base |
|
424 |
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of |
|
425 |
Electrical and Electronics Engineers, Inc and The Open Group. In the |
|
426 |
event of any discrepancy between this version and the original IEEE and |
|
427 |
The Open Group Standard, the original IEEE and The Open Group Standard |
|
428 |
is the referee document. The original Standard can be obtained online at |
|
429 |
http://www.opengroup.org/unix/online.html . |