| blob | 95843accc07af36369017a87c083e75f0f274bdc |
1 .\" $NetBSD: strptime.3,v 1.27 2009/05/24 02:30:17 ginsbach Exp $
2 .\"
3 .\" Copyright (c) 1997, 1998, 2008 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This file was contributed to The NetBSD Foundation by Klaus Klein.
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 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 .\" POSSIBILITY OF SUCH DAMAGE.
28 .\"
29 .Dd May 24, 2009
30 .Dt STRPTIME 3
31 .Os
32 .Sh NAME
33 .Nm strptime
34 .Nd converts a character string to a time value
35 .Sh LIBRARY
36 .Lb libc
37 .Sh SYNOPSIS
38 .In time.h
39 .Ft char *
40 .Fn strptime "const char * restrict buf" "const char * restrict format" "struct tm * restrict tm"
41 .Sh DESCRIPTION
42 The
43 .Fn strptime
44 function converts the character string pointed to by
45 .Fa buf
46 to values which are stored in the
47 .Va tm
48 structure pointed to by
49 .Fa tm ,
50 using the format specified by
51 .Fa format .
52 .Pp
53 The
54 .Fa format
55 string consists of zero or more conversion specifications, whitespace
56 characters as defined by
57 .Fn isspace ,
58 and ordinary characters.
59 All ordinary characters in
60 .Fa format
61 are compared directly against the corresponding characters in
62 .Fa buf ;
63 comparisons which fail will cause
64 .Fn strptime
65 to fail.
66 Whitespace characters in
67 .Fa format
68 match any number of whitespace characters in
69 .Fa buf ,
70 including none.
71 .Pp
72 A conversion specification consists of a percent sign
73 .Ql %
74 followed by one
75 or two conversion characters which specify the replacement required.
76 There must be white-space or other non-alphanumeric characters between any
77 two conversion specifications.
78 .Pp
79 Conversion of alphanumeric strings (such as month and weekday names) is
80 done without regard to case.
81 Conversion specifications which cannot be matched will cause
82 .Fn strptime
83 to fail.
84 .Pp
85 The LC_TIME category defines the locale values for the conversion
86 specifications.
87 The following conversion specifications are supported:
88 .Bl -tag -width "xxxx"
89 .It Cm \&%a
90 the day of week, using the locale's weekday names;
91 either the abbreviated or full name may be specified.
92 .It Cm \&%A
93 the same as
94 .Cm \&%a .
95 .It Cm \&%b
96 the month, using the locale's month names;
97 either the abbreviated or full name may be specified.
98 .It Cm \&%B
99 the same as
100 .Cm \&%b .
101 .It Cm \&%c
102 the date and time, using the locale's date and time format.
103 .It Cm \&%C
104 the century number [0,99];
105 leading zeros are permitted but not required.
106 This conversion should be used in conjunction with the \&%y conversion.
107 .It Cm \&%d
108 the day of month [1,31];
109 leading zeros are permitted but not required.
110 .It Cm \&%D
111 the date as %m/%d/%y.
112 .It Cm \&%e
113 the same as
114 .Cm \&%d .
115 .It Cm \&%F
116 the date as %Y-%m-%d
117 (the ISO 8601 date format).
118 .It Cm \&%g
119 the year corresponding to the ISO week number, without the century.
120 .Po
121 A
122 .Nx
123 extension.
124 .Pc
125 .It Cm \&%G
126 the year corresponding to the ISO week number, with the century.
127 .Po
128 A
129 .Nx
130 extension.
131 .Pc
132 .It Cm \&%h
133 the same as
134 .Cm \&%b .
135 .It Cm \&%H
136 the hour (24-hour clock) [0,23];
137 leading zeros are permitted but not required.
138 .It Cm \&%I
139 the hour (12-hour clock) [1,12];
140 leading zeros are permitted but not required.
141 .It Cm \&%j
142 the day number of the year [1,366];
143 leading zeros are permitted but not required.
144 .It Cm \&%k
145 the same as
146 .Cm \&%H .
147 .It Cm \&%l
148 the same as
149 .Cm \&%I .
150 .It Cm \&%m
151 the month number [1,12];
152 leading zeros are permitted but not required.
153 .It Cm \&%M
154 the minute [0,59];
155 leading zeros are permitted but not required.
156 .It Cm \&%n
157 any white-space, including none.
158 .It Cm \&%p
159 the locale's equivalent of a.m. or p.m.
160 .It Cm \&%r
161 the time (12-hour clock) with %p, using the locale's time format.
162 .It Cm \&%R
163 the time as %H:%M.
164 .It Cm \&%S
165 the seconds [0,61];
166 leading zeros are permitted but not required.
167 .It Cm \&%s
168 the number of seconds since the Epoch, UTC (see
169 .Xr mktime 3 ) .
170 .Po
171 A
172 .Nx
173 extension.
174 .Pc
175 .It Cm \&%t
176 any white-space, including none.
177 .It Cm \&%T
178 the time as %H:%M:%S.
179 .It Cm \&%u
180 the day of the week as a decimal number, where Monday = 1.
181 .Po
182 A
183 .Nx
184 extension.
185 .Pc
186 .It Cm \&%U
187 the week number of the year (Sunday as the first day of the week)
188 as a decimal number [0,53];
189 leading zeros are permitted but not required.
190 All days in a year preceding the first Sunday are considered to be in week 0.
191 .It Cm \&%V
192 the ISO 8601:1988 week number as a decimal number.
193 If the week (starting on Monday) that contains January 1 has more than
194 three days in the new year, then it is considered the first week of the
195 year.
196 If it has fewer than four days in the new year, then it is considered
197 the last week of the previous year.
198 Weeks are numbered from 1 to 53.
199 .Po
200 A
201 .Nx
202 extension.
203 .Pc
204 .It Cm \&%w
205 the weekday as a decimal number [0,6], with 0 representing Sunday;
206 leading zeros are permitted but not required.
207 .It Cm \&%W
208 the week number of the year (Monday as the first day of the week)
209 as a decimal number [0,53];
210 leading zeros are permitted but not required.
211 All days in a year preceding the first Monday are considered to be in week 0.
212 .It Cm \&%x
213 the date, using the locale's date format.
214 .It Cm \&%X
215 the time, using the locale's time format.
216 .It Cm \&%y
217 the year within the 20th century [69,99] or the 21st century [0,68];
218 leading zeros are permitted but not required.
219 If specified in conjunction
220 with \&%C, specifies the year [0,99] within that century.
221 .It Cm \&%Y
222 the year, including the century (i.e., 1996).
223 .It Cm \&%z
224 an ISO 8601 or RFC-2822 timezone specification.
225 This is one of the following:
226 the offset from
227 Coordinated Universal Time
228 .Pq Ql UTC
229 specified as:
230 .Dq [+-]hhmm ,
231 .Dq [+-]hh:mm ,
232 or
233 .Dq [+-]hh ;
234 .Ql UTC
235 specified as:
236 .Dq GMT
237 .Pq Ql Greenwich Mean Time ,
238 .Dq UT
239 .Pq Ql Universal Time ,
240 or
241 .Dq Z
242 .Pq Ql Zulu Time ;
243 a three character US timezone specified as:
244 .Dq EDT ,
245 .Dq EST ,
246 .Dq CDT ,
247 .Dq CST ,
248 .Dq MDT ,
249 .Dq MST ,
250 .Dq PDT ,
251 or
252 .Dq PST ,
253 with the first letter standing for
254 .Ql Eastern
255 .Pq Dq E ,
256 .Ql Central
257 .Pq Dq C ,
258 .Ql Mountain
259 .Pq Dq M
260 or
261 .Ql Pacific
262 .Pq Dq P ,
263 and the second letter standing for
264 .Ql Daylight
265 .Po
266 .Dq D
267 or summer
268 .Pc
269 time
270 or
271 .Ql Standard
272 .Pq Dq S
273 time;
274 a single letter military timezone specified as:
275 .Dq A
276 through
277 .Dq I
278 and
279 .Dq K
280 through
281 .Dq Y .
282 .Po
283 A
284 .Nx
285 extension.
286 .Pc
287 .It Cm \&%Z
288 timezone name or no characters when time zone information is unavailable.
289 .Po
290 A
291 .Nx
292 extension.
293 .Pc
294 .It Cm \&%%
295 matches a literal `%'.
296 No argument is converted.
297 .El
298 .Ss Modified conversion specifications
299 For compatibility, certain conversion specifications can be modified
300 by the
301 .Cm E
302 and
303 .Cm O
304 modifier characters to indicate that an alternative format or specification
305 should be used rather than the one normally used by the unmodified
306 conversion specification.
307 As there are currently neither alternative formats
308 nor specifications supported by the system, the behavior will be as if the
309 unmodified conversion specification were used.
310 .Pp
311 Case is ignored when matching string items in
312 .Fa buf ,
313 such as month and weekday names.
314 .Sh RETURN VALUES
315 If successful, the
316 .Fn strptime
317 function returns a pointer to the character following the last character
318 parsed.
319 Otherwise, a null pointer is returned.
320 .Sh SEE ALSO
321 .Xr ctime 3 ,
322 .Xr isspace 3 ,
323 .Xr localtime 3 ,
324 .Xr strftime 3
325 .Sh STANDARDS
326 The
327 .Fn strptime
328 function conforms to
329 .St -xpg4 .
330 .Sh BUGS
331 The
332 .Cm \&%Z
333 format specifier only accepts timezone
334 abbreviations of the local timezone,
335 or the value
336 .Dq GMT .
337 This limitation is caused by the ambiguity
338 of overloaded timezone abbreviations,
339 for example EST is both Eastern Standard
340 Time and Eastern Australia Summer Time.