strftime.man - 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.man (5821B)
---
1 .TH STRFTIME 3 scc\-VERSION
2 .SH NAME
3 strftime - format a broken-down time value into a string
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 writes characters into the array pointed to by
17 .I s
18 under control of the string pointed to by
19 .IR format .
20
21 The
22 .I format
23 string is a multibyte character sequence that begins and ends
24 in its initial shift state.
25 It consists of zero or more conversion specifiers
26 interspersed with ordinary characters.
27 Each conversion specifier begins with a
28 .B %
29 character, optionally followed by an
30 .B E
31 or
32 .B O
33 modifier, and ends with a character that determines what is substituted.
34 Ordinary characters, including the terminating null byte,
35 are copied to the output without modification.
36 No more than
37 .I maxsize
38 characters are placed into the array.
39
40 The following conversion specifiers are recognized:
41 .TP
42 .B %a
43 The abbreviated weekday name for the current locale.
44 .TP
45 .B %A
46 The full weekday name for the current locale.
47 .TP
48 .B %b
49 The abbreviated month name for the current locale.
50 .TP
51 .B %B
52 The full month name for the current locale.
53 .TP
54 .B %c
55 The preferred date and time representation for the current locale.
56 .TP
57 .B %C
58 The year divided by 100, truncated to an integer (the century).
59 .TP
60 .B %d
61 The day of the month as a two-digit decimal number (01 to 31).
62 .TP
63 .B %D
64 Equivalent to "%m/%d/%y".
65 .TP
66 .B %e
67 The day of the month as a decimal number; single digits are padded with a space.
68 .TP
69 .B %F
70 Equivalent to "%Y-%m-%d" (ISO 8601 date format).
71 .TP
72 .B %G
73 The ISO 8601 week-based year, including the century.
74 (Derived from
75 .BR tm_year ,
76 .BR tm_yday ,
77 and
78 .BR tm_wday .)
79 .TP
80 .B %g
81 Like
82 .B %G
83 but without the century (two-digit year, 00 to 99).
84 (Derived from
85 .BR tm_year ,
86 .BR tm_yday ,
87 and
88 .BR tm_wday .)
89 .TP
90 .B %h
91 Equivalent to
92 .BR %b .
93 (Derived from
94 .BR tm_mon .)
95 .TP
96 .B %H
97 The hour on a 24-hour clock as a two-digit decimal number (00 to 23).
98 (Derived from
99 .BR tm_hour .)
100 .TP
101 .B %I
102 The hour on a 12-hour clock as a two-digit decimal number (01 to 12).
103 (Derived from
104 .BR tm_hour .)
105 .TP
106 .B %j
107 The day of the year as a three-digit decimal number (001 to 366).
108 (Derived from
109 .BR tm_yday .)
110 .TP
111 .B %m
112 The month as a two-digit decimal number (01 to 12).
113 (Derived from
114 .BR tm_mon .)
115 .TP
116 .B %M
117 The minute as a two-digit decimal number (00 to 59).
118 .TP
119 .B %n
120 A newline character.
121 .TP
122 .B %p
123 Either "AM" or "PM" according to the time of day.
124 (Derived from
125 .BR tm_hour .)
126 .TP
127 .B %r
128 The locale's 12-hour clock time.
129 .TP
130 .B %R
131 The time in 24-hour notation (%H:%M).
132 .TP
133 .B %S
134 The second as a two-digit decimal number (00 to 60).
135 (Derived from
136 .BR tm_sec .)
137 .TP
138 .B %t
139 A tab character.
140 .TP
141 .B %T
142 The time in 24-hour notation (%H:%M:%S).
143 .TP
144 .B %u
145 The weekday as a decimal number per ISO 8601 (1 to 7, Monday = 1).
146 (Derived from
147 .BR tm_wday .)
148 .TP
149 .B %U
150 The week number of the year as a two-digit decimal (00 to 53),
151 counting from the first Sunday as day 1 of week 1.
152 (Derived from
153 .BR tm_year ,
154 .BR tm_wday ,
155 .BR tm_yday .)
156 .TP
157 .B %V
158 The ISO 8601 week number of the year (01 to 53),
159 where week 1 is the first week containing at least four days of the new year.
160 .TP
161 .B %w
162 The weekday as a decimal number (0 to 6, Sunday = 0).
163 .TP
164 .B %W
165 The week number of the year as a two-digit decimal (00 to 53),
166 counting from the first Monday as day 1 of week 1.
167 (Derived from
168 .B tm_yday
169 and
170 .BR tm_wday .)
171 .TP
172 .B %x
173 The preferred date representation for the current locale, without the time.
174 .TP
175 .B %X
176 The preferred time representation for the current locale, without the date.
177 .TP
178 .B %y
179 The year without the century (00 to 99).
180 .TP
181 .B %Y
182 The year including the century.
183 .TP
184 .B %z
185 The UTC offset as +hhmm or -hhmm (ISO 8601 format).
186 .TP
187 .B %Z
188 The timezone name or abbreviation.
189 .TP
190 .B %%
191 A literal percent sign.
192 .P
193 The
194 .B E
195 and
196 .B O
197 modifier characters may precede certain conversion specifiers
198 to request an alternative locale-specific representation.
199 When no alternative exists, the modifier is ignored.
200
201 The C standard recognizes the following modified specifiers:
202 .BR %Ec ,
203 .BR %EC ,
204 .BR %Ex ,
205 .BR %EX ,
206 .BR %Ey ,
207 .BR %EY ,
208 .BR %Od ,
209 .BR %Oe ,
210 .BR %OH ,
211 .BR %OI ,
212 .BR %Om ,
213 .BR %OM ,
214 .BR %OS ,
215 .BR %Ou ,
216 .BR %OU ,
217 .BR %OV ,
218 .BR %Ow ,
219 .BR %OW ,
220 .BR %Oy .
221 The
222 .B O
223 modifier requests locale alternative numeric symbols;
224 the
225 .B E
226 modifier requests a locale-dependent alternative representation.
227
228 In the "C" locale, both modifiers are ignored and
229 the following substitutions apply:
230 .TP
231 .B %a
232 the first three characters of %A
233 .TP
234 .B %A
235 one of Sunday, Monday, ..., Saturday
236 .TP
237 .B %b
238 the first three characters of %B
239 .TP
240 .B %B
241 one of January, February, ..., December
242 .TP
243 .B %c
244 equivalent to %a %b %e %T %Y
245 .TP
246 .B %p
247 one of AM or PM
248 .TP
249 .B %r
250 equivalent to %I:%M:%S %p
251 .TP
252 .B %x
253 equivalent to %m/%d/%y
254 .TP
255 .B %X
256 equivalent to %T
257 .TP
258 .B %Z
259 the timezone name or abbreviation
260 .SH RETURN VALUE
261 When the formatted result, including the terminating null byte,
262 fits within
263 .I maxsize
264 characters,
265 .B strftime
266 returns the number of characters written, excluding the null byte.
267 If the result does not fit, zero is returned and the contents
268 of the array are unspecified.
269 .SH NOTES
270 ISO 8601 week-based years begin on Monday, with week 1 defined as
271 the week containing January 4th (equivalently, the first week with
272 at least four days in the new year, or the week containing the
273 first Thursday of the year).
274 The specifiers
275 .BR %g ,
276 .BR %G ,
277 and
278 .B %V
279 follow this convention. For example, Saturday January 2nd 1999
280 falls in week 53 of 1998 (%G = 1998, %V = 53);
281 Tuesday December 30th 1997 falls in week 1 of 1998 (%G = 1998, %V = 01).
282 .SH STANDARDS
283 ISO/IEC 9899:1999 Section 7.23.3.5 Paragraph 1,2,3,4,5,6,7
284 .SH SEE ALSO
285 .BR time.h (3)