scc

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