Home
strftime.3 - scc - simple c99 compiler
HTML git clone git://git.simple-cc.org/scc
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
strftime.3 (6954B)
---
1 .TH STRFTIME 3
2 .SH NAME
3 strftime - formats the broken-down time according to specified format
4 .SH SYNOPSIS
5 #include <time.h>
6
7 .nf
8 size_t strftime(char * restrict s,
9 size_t maxsize,
10 const char * restrict format,
11 const struct tm * restrict timeptr);
12 .fi
13 .SH DESCRIPTION
14 The
15 .BR strftime ()
16 function places characters into the array pointed to by
17 .I s
18 as controlled by the string pointed to by
19 .IR format .
20
21 The
22 .I format
23 shall be a multibyte character sequence,
24 beginning and ending in its initial shift state.
25 The
26 .I format
27 shall consist of zero or more conversion specifiers and
28 ordinary characters.
29 A conversion specifier consists of a % character,
30 possibly followed by an E or O modifier character,
31 followed by a character that determines the behavior of the conversion
32 specifier.
33 All ordinary characters
34 (including the terminating null character) are copied unchanged into the
35 array.
36 No more than
37 .I maxsize
38 characters are placed into the array.
39
40 The format specification is a null-terminated string and
41 shall contain special character sequences, called conversion specifiers,
42 which get replaced with the appropriate characters as described in the
43 following list:
44 .TP
45 .B %a
46 The abbreviated name of the day of the week according to the current
47 locale.
48 .TP
49 .B %A
50 THe full name of the day of the week according to the current locale.
51 .TP
52 .B %b
53 The abbreviated name of the month according to the current locale.
54 .TP
55 .B %B
56 The full name of the month according to the current locale.
57 .TP
58 .B %c
59 The preferred date and time representation for the current locale.
60 .TP
61 .B %C
62 The decimal number representing the year divided by 100 and truncated
63 to an integer (century number).
64 .TP
65 .B %d
66 The day of the month as a decimal number between 01 and 31.
67 .TP
68 .B %D
69 Equivalent to "%m/%d/%y"
70 .TP
71 .B %e
72 The day of the month as a decimal number between 0 and 31;
73 a single digit is preceded by a space.
74 .TP
75 .B %F
76 Equivalent to "%y-%m-%d"
77 (the ISO 8601 date format).
78 .TP
79 .B %G
80 The ISO 8601 week-based-year with century as a decimal number.
81 The 4-digit year corresponding to the ISO week number. (Calculated
82 from
83 .BR tm_year ,
84 .BR tm_yday ,
85 and
86 .BR tm_wday )
87 .TP
88 .B %g
89 Like
90 .B %G
91 but without century, that is, with a 2-digit year (00-99).
92 (Calculated from
93 .BR tm_year ,
94 .BR tm_yday ,
95 and
96 .BR tm_wday )
97 .TP
98 .B %h
99 Equivalent to
100 .BR %b .
101 (Calculated from
102 .BR tm_mon )
103 .TP
104 .B %H
105 The hour as a decimal number using a 24-hour clock between
106 00 and 23.
107 (Calculated from
108 .BR tm_hour )
109 .TP
110 .B %I
111 The hour as a decimal number using a 12-hour clock between 01 and 12
112 (Calculated from
113 .BR tm_hour )
114 .TP
115 .B %j
116 The day of the year as a decimal number between 001 and 366.
117 (Calculated from
118 .BR tm_yday )
119 .TP
120 .B %m
121 The month as a decimal number between 01 and 12
122 (Calculated from
123 .BR tm_mon )
124 .TP
125 .B %M
126 The minute as a decimal number between 00 and 59
127 .TP
128 .B %n
129 A newline character.
130 .TP
131 .B %p
132 Either "AM" or "PM" according to the given time value.
133 (Calculated from
134 .BR tm_hour )
135 .B %r
136 The locale's 12-hour clock time.
137 .TP
138 .B %R
139 The time in 24-hour notation (%H:%M).
140 .TP
141 .B %S
142 The second as a decimal number between 00 and 60.
143 (Calculated from
144 .BR tm_sec ).
145 .TP
146 .B %t
147 A tab character.
148 .TP
149 .B %T
150 The time in 24-hour notation (%H:%M:%S).
151 .TP
152 .B %u
153 The day of the week (ISO 8601) as a decimal between 1 and 7,
154 Monday being 1.
155 (Calculated from
156 .BR tm_wday )
157 .TP
158 .B %U
159 The week number of the current year as a decimal number
160 between 00 and 53,
161 starting with the first Sunday as the first day of week 01. (Calculated from
162 .BR tm_year ,
163 .BR tm_wday ,
164 .BR tm_yday )
165 .TP
166 .B %V
167 The ISO 8601 week (see NOTES) number of the current year as a decimal number
168 between 01 and 53,
169 where week 1 is the first week that has at least 4 days in the new year.
170 .TP
171 .B %w
172 The day of the week as a decimal between 0 and 6,
173 Sunday being 0.
174 .TP
175 .B %W
176 The week number of the current year as a decimal number
177 between 00 and 53,
178 starting with the first Monday as the first day of week 01.
179 (Calculated from
180 .B tm_yday
181 and
182 .BR tm_wday ).
183 .TP
184 .B %x
185 The preferred date representation for the current locale without the
186 time.
187 .TP
188 .B %X
189 The preferred time representation for the current locale without the
190 date.
191 .TP
192 .B %y
193 The year as a decimal number without a century between 00 and 99.
194 .TP
195 .B %Y
196 The year as a decimal number including the century.
197 .TP
198 .B %z
199 The +hhmm or -hhmm numeric timezone
200 (that is, the hour and minute offset from UTC in ISO 8601 format).
201 .TP
202 .B %Z
203 The timezone name or abbreviation.
204 .TP
205 .B %%
206 This is replaced with %.
207 .P
208 Some conversion specifiers can be modified by the inclusion of an
209 .B E
210 or
211 .B O
212 modifier character to indicate an alternative format or specification.
213 If the alternative format or character doesn't exist for the current locale,
214 the modifier is ignored.
215
216 The C Standard mentions the following specifiers:
217 .BR %Ec ,
218 .BR %EC ,
219 .BR %Ex ,
220 .BR %EX ,
221 .BR %Ey ,
222 .BR %EY ,
223 .BR %Od ,
224 .BR %Oe ,
225 .BR %OH ,
226 .BR %OI ,
227 .BR %Om ,
228 .BR %OM ,
229 .BR %OS ,
230 .BR %Ou ,
231 .BR %OU ,
232 .BR %OV ,
233 .BR %Ow ,
234 .BR %OW ,
235 .BR %Oy ,
236 where the effect of the
237 .B O
238 modifier is to use
239 alternative numeric symbols, and that of the
240 .B E
241 modifier is to use a locale-dependent alternative representation.
242
243 In the "C" locale, the E and O modifiers are ignored and the
244 replacement strings for the following specifiers are:
245 .TP
246 .B %a
247 the first three characters of %A
248 .TP
249 .B %A
250 one of Sunday ,Monday, ..., Saturday
251 .TP
252 .B %b
253 the first three characters of %B
254 .TP
255 .B %B
256 one of January, February, ..., December
257 .TP
258 .B %c
259 equivalent to %a %b %e %T %Y
260 .TP
261 .B %p
262 one of AM or PM
263 .TP
264 .B %r
265 equivalent to %I:%M:%S %p
266 .TP
267 .B %x
268 equivalent to %m/%d/%y
269 .TP
270 .B %X
271 equivalent to %T
272 .TP
273 .B %Z
274 The timezone name or abbreviation.
275 .SH RETURN VALUE
276 If the total number of resulting characters
277 including the terminating null character doesn't exceed
278 .IR maxsize ,
279 then
280 .I strftime
281 function returns the number of characters
282 placed into the array pointed to by
283 .I s
284 not including the terminating null character. Otherwise, zero is
285 returned and the contents of the array are indeterminate.
286 .SH NOTES
287 In the ISO 8601 week-based year, weeks begin on a Monday and week 1
288 of the year is the week that includes January 4th, which also includes
289 the first Thursday of the year, and is also the first week that
290 contains at least four days in the year. As mentioned above,
291 .B %g, %G,
292 and
293 .B %V
294 are dependent on ISO 8601 week-based year, and the following examples
295 are provided for illustrative purposes:
296
297 If the first Monday of January is the 2nd, 3rd, or 4th,
298 the preceding days are part of the last week of the preceding year;
299 thus, for Saturday 2nd January 1999,
300 .B %G
301 is replaced by 1998 and
302 .B %V
303 is replaced with 53. Similarly,
304 if December 29th, 30th or 31st is a Monday,
305 it and following days are part of week 1 and hence,
306 for Tuesday 30th December 1997,
307 .B %G
308 is replaced by 1998 and
309 .B %V
310 is replaced with 01.
311 .SH STANDARDS
312 ISO/IEC 9899:1999 Section 7.23.3.5 Paragraph 1,2,3,4,5,6,7
313 .SH SEE ALSO
314 .BR time.h (3)