| blob | d039b52f3941f024ae7e960d0fc5c98793609526 |
1 .\" Copyright (c) 1989, 1991 The Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to Berkeley by
5 .\" the American National Standards Committee X3, on Information
6 .\" Processing Systems.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91
33 .\" $NetBSD: strftime.3,v 1.29 2012/04/06 11:35:39 wiz Exp $
34 .\"
35 .Dd April 14, 2011
36 .Dt STRFTIME 3
37 .Os
38 .Sh NAME
39 .Nm strftime ,
40 .Nm strftime_z
41 .Nd format date and time
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In time.h
46 .Ft size_t
47 .Fn strftime "char * restrict buf" "size_t maxsize" "const char * restrict format" "const struct tm * restrict timeptr"
48 .Ft size_t
49 .Fn strftime_z "const timezone_t tz" "char * restrict buf" "size_t maxsize" "const char * restrict format" "const struct tm * restrict timeptr"
50 .Sh DESCRIPTION
51 The
52 .Fn strftime
53 function formats the information from
54 .Fa timeptr
55 into the buffer
56 .Fa buf
57 according to the string pointed to by
58 .Fa format .
59 .Pp
60 The
61 .Fa format
62 string consists of zero or more conversion specifications and
63 ordinary characters.
64 All ordinary characters are copied directly into the buffer.
65 A conversion specification consists of a percent sign
66 .Ql %
67 and one other character.
68 .Pp
69 No more than
70 .Fa maxsize
71 characters will be placed into the array.
72 If the total number of resulting characters, including the terminating
73 null character, is not more than
74 .Fa maxsize ,
75 .Fn strftime
76 returns the number of characters in the array, not counting the
77 terminating null.
78 Otherwise, zero is returned and the contents of the array are undefined.
79 .Pp
80 Each conversion specification is replaced by the characters as
81 follows which are then copied into the buffer.
82 .Bl -tag -width "xxxx"
83 .It Cm \&%A
84 is replaced by the locale's full weekday name.
85 .It Cm %a
86 is replaced by the locale's abbreviated weekday name.
87 .It Cm \&%B
88 is replaced by the locale's full month name.
89 .It Cm \&%b No or Cm \&%h
90 is replaced by the locale's abbreviated month name.
91 .It Cm \&%C
92 is replaced by the century (a year divided by 100 and truncated to an integer)
93 as a decimal number [00,99].
94 .It Cm \&%c
95 is replaced by the locale's appropriate date and time representation.
96 .It Cm \&%D
97 is replaced by the date in the format
98 .Dq Li %m/%d/%y .
99 .It Cm \&%d
100 is replaced by the day of the month as a decimal number [01,31].
101 .It Cm \&%e
102 is replaced by the day of month as a decimal number [1,31];
103 single digits are preceded by a blank.
104 .It Cm \&%F
105 is replaced by the date in the format
106 .Dq Li %Y-%m-%d
107 (the ISO 8601 date format).
108 .It Cm \&%G
109 is replaced by the ISO 8601 year with century as a decimal number.
110 .It Cm \&%g
111 is replaced by the ISO 8601 year without century as a decimal number (00-99).
112 This is the year that includes the greater part of the week.
113 (Monday as the first day of a week).
114 See also the
115 .Ql \&%V
116 conversion specification.
117 .It Cm \&%H
118 is replaced by the hour (24-hour clock) as a decimal number [00,23].
119 .It Cm \&%I
120 is replaced by the hour (12-hour clock) as a decimal number [01,12].
121 .It Cm \&%j
122 is replaced by the day of the year as a decimal number [001,366].
123 .It Cm \&%k
124 is replaced by the hour (24-hour clock) as a decimal number [0,23];
125 single digits are preceded by a blank.
126 .It Cm \&%l
127 is replaced by the hour (12-hour clock) as a decimal number [1,12];
128 single digits are preceded by a blank.
129 .It Cm \&%M
130 is replaced by the minute as a decimal number [00,59].
131 .It Cm %m
132 is replaced by the month as a decimal number [01,12].
133 .It Cm %n
134 is replaced by a newline.
135 .It Cm %p
136 is replaced by the locale's equivalent of either
137 .Dq Tn AM
138 or
139 .Dq Tn PM .
140 .It Cm \&%R
141 is replaced by the time in the format
142 .Dq Li %H:%M .
143 .It Cm \&%r
144 is replaced by the locale's representation of 12-hour clock time
145 using AM/PM notation.
146 .It Cm \&%S
147 is replaced by the second as a decimal number [00,61].
148 The range of
149 seconds is (00-61) instead of (00-59) to allow for the periodic occurrence
150 of leap seconds and double leap seconds.
151 .It Cm %s
152 is replaced by the number of seconds since the Epoch, UTC (see
153 .Xr mktime 3 ) .
154 .It Cm \&%T
155 is replaced by the time in the format
156 .Dq Li %H:%M:%S .
157 .It Cm \&%t
158 is replaced by a tab.
159 .It Cm \&%U
160 is replaced by the week number of the year (Sunday as the first day of
161 the week) as a decimal number [00,53].
162 .It Cm \&%u
163 is replaced by the weekday (Monday as the first day of the week)
164 as a decimal number [1,7].
165 .It Cm \&%V
166 is replaced by the week number of the year (Monday as the first day of
167 the week) as a decimal number [01,53]. According to ISO 8601 the week
168 containing January 1 is week 1 if it has four or more days in the new year,
169 otherwise it is week 53 of the previous year, and the next week is week 1.
170 The year is given by the
171 .Ql \&%G
172 conversion specification.
173 .It Cm \&%v
174 is replaced by the date in the format
175 .Dq Li %e-%b-%Y .
176 .It Cm \&%W
177 is replaced by the week number of the year (Monday as the first day of
178 the week) as a decimal number [00,53].
179 .It Cm \&%w
180 is replaced by the weekday (Sunday as the first day of the week)
181 as a decimal number [0,6].
182 .It Cm \&%X
183 is replaced by the locale's appropriate time representation.
184 .It Cm \&%x
185 is replaced by the locale's appropriate date representation.
186 .It Cm \&%Y
187 is replaced by the year with century as a decimal number.
188 .It Cm \&%y
189 is replaced by the year without century as a decimal number [00,99].
190 .It Cm \&%Z
191 is replaced by the time zone name.
192 .It Cm \&%z
193 is replaced by the offset from UTC in the ISO 8601 format
194 .Dq Li [-]hhmm .
195 .It Cm %%
196 is replaced by
197 .Ql % .
198 .El
199 .Pp
200 The
201 .Fn strftime_z
202 function is similar to
203 .Fn strftime ,
204 but it also takes a
205 .Ft "const timezone_t"
206 .Fa tz
207 argument.
208 .Sh SEE ALSO
209 .Xr date 1 ,
210 .Xr printf 1 ,
211 .Xr ctime 3 ,
212 .Xr printf 3 ,
213 .Xr strptime 3 ,
214 .Xr tm 3
215 .Sh STANDARDS
216 The
217 .Fn strftime
218 function
219 conforms to
220 .St -isoC-99 .
221 The
222 .Ql \&%C ,
223 .Ql \&%D ,
224 .Ql \&%e ,
225 .Ql \&%g ,
226 .Ql \&%G ,
227 .Ql \&%h ,
228 .Ql \&%k ,
229 .Ql \&%l ,
230 .Ql \&%n ,
231 .Ql \&%r ,
232 .Ql \&%R ,
233 .Ql \&%s ,
234 .Ql \&%t ,
235 .Ql \&%T ,
236 .Ql \&%u ,
237 .Ql \&%V ,
238 and
239 .Ql \&%v
240 conversion specifications are extensions.
241 .Pp
242 Use of the ISO 8601 conversions may produce non-intuitive results.
243 Week 01 of a year is per definition the first week which has the Thursday
244 in this year, which is equivalent to the week which contains the fourth
245 day of January.
246 In other words, the first week of a new year is the week which has the
247 majority of its days in the new year.
248 Week 01 might also contain days from the previous year and the week
249 before week 01 of a year is the last week (52 or 53) of the previous
250 year even if it contains days from the new year.
251 A week starts with Monday (day 1) and ends with Sunday (day 7).
252 For example, the first week of the year 1997 lasts from
253 1996-12-30 to 1997-01-05.
254 .Sh BUGS
255 There is no conversion specification for the phase of the moon.
256 .Pp
257 A return value of zero does not necessarily indicate an error.
258 If the resulting string is an empty string, the result value is
259 zero and it is not possible to distinguish between success and error.
260 For example, in many locales
261 .Cm \&%p
262 yields an empty string.
263 This problem can be avoided by inserting an extra space at the
264 beginning of the format string and then skipping over it or removing
265 it from the result.