1strptime(3C) Standard C Library Functions strptime(3C)
2
3
4
6 strptime - date and time conversion
7
9 #include <time.h>
10
11 char *strptime(const char *restrict buf,
12 const char *restrict format, struct tm *restrict tm);
13
14
15 Non-zeroing Behavior
16 cc [flag...] file... -D_STRPTIME_DONTZERO [library...]
17 #include <time.h>
18
19 char *strptime(const char *restrict buf,
20 const char *restrict format, struct tm *restrict tm);
21
22
24 The strptime() function converts the character string pointed to by buf
25 to values which are stored in the tm structure pointed to by tm, using
26 the format specified by format.
27
28
29 The format argument is composed of zero or more conversion specifica‐
30 tions. Each conversion specification is composed of a "%" (percent)
31 character followed by one or two conversion characters which specify
32 the replacement required. One or more white space characters (as speci‐
33 fied by isspace(3C)) may precede or follow a conversion specification.
34 There must be white-space or other non-alphanumeric characters between
35 any two conversion specifications.
36
37
38 A non-zeroing version of strptime(), described below under Non-zeroing
39 Behavior, is provided if _STRPTIME_DONTZERO is defined.
40
41 Conversion Specifications
42 The following conversion specifications are supported:
43
44 %% Same as %.
45
46
47 %a Day of week, using the locale's weekday names; either the abbre‐
48 viated or full name may be specified.
49
50
51 %A Same as %a.
52
53
54 %b Month, using the locale's month names; either the abbreviated or
55 full name may be specified.
56
57
58 %B Same as %b.
59
60
61 %c Locale's appropriate date and time representation.
62
63
64 %C Century number (the year divided by 100 and truncated to an inte‐
65 ger as a decimal number [1,99]); single digits are preceded by 0.
66 If %C is used without the %y specifier, strptime() assumes the
67 year offset is zero in whichever century is specified. Note the
68 behavior of %C in the absence of %y is not specified by any of
69 the standards or specifications described on the standards(5)
70 manual page, so portable applications should not depend on it.
71 This behavior may change in a future release.
72
73
74 %d Day of month [1,31]; leading zero is permitted but not required.
75
76
77 %D Date as %m/%d/%y.
78
79
80 %e Same as %d.
81
82
83 %h Same as %b.
84
85
86 %H Hour (24-hour clock) [0,23]; leading zero is permitted but not
87 required.
88
89
90 %I Hour (12-hour clock) [1,12]; leading zero is permitted but not
91 required.
92
93
94 %j Day number of the year [1,366]; leading zeros are permitted but
95 not required.
96
97
98 %m Month number [1,12]; leading zero is permitted but not required.
99
100
101 %M Minute [0-59]; leading zero is permitted but not required.
102
103
104 %n Any white space.
105
106
107 %p Locale's equivalent of either a.m. or p.m.
108
109
110 %r Appropriate time representation in the 12-hour clock format with
111 %p.
112
113
114 %R Time as %H:%M.
115
116
117 SUSv3
118 %S Seconds [0,60]; leading zero is permitted but not required. The
119 range of values is [00,60] rather than [00,59] to allow for the
120 occasional leap second.
121
122
123 Default and other standards
124 %S Seconds [0,61]; leading zero is permitted but not required. The
125 range of values is [00,61] rather than [00,59] to allow for the
126 occasional leap second and even more occasional double leap sec‐
127 ond.
128
129
130 %t Any white space.
131
132
133 %T Time as %H:%M:%S.
134
135
136 %U Week number of the year as a decimal number [0,53], with Sunday
137 as the first day of the week; leading zero is permitted but not
138 required.
139
140
141 %w Weekday as a decimal number [0,6], with 0 representing Sunday.
142
143
144 %W Week number of the year as a decimal number [0,53], with Monday
145 as the first day of the week; leading zero is permitted but not
146 required.
147
148
149 %x Locale's appropriate date representation.
150
151
152 %X Locale's appropriate time representation.
153
154
155 %y Year within century. When a century is not otherwise specified,
156 values in the range 69-99 refer to years in the twentieth century
157 (1969 to 1999 inclusive); values in the range 00-68 refer to
158 years in the twenty-first century (2000 to 2068 inclusive).
159
160
161 %Y Year, including the century (for example, 1993).
162
163
164 %Z Time zone name or no characters if no time zone exists.
165
166
167 Modified Conversion Specifications
168 Some conversion specifications can be modified by the E and O modifier
169 characters to indicate that an alternate format or specification should
170 be used rather than the one normally used by the unmodified specifica‐
171 tion. If the alternate format or specification does not exist in the
172 current locale, the behavior will be as if the unmodified conversion
173 specification were used.
174
175 %Ec Locale's alternate appropriate date and time representation.
176
177
178 %EC Name of the base year (era) in the locale's alternate represen‐
179 tation.
180
181
182 %Ex Locale's alternate date representation.
183
184
185 %EX Locale's alternate time representation.
186
187
188 %Ey Offset from %EC (year only) in the locale's alternate represen‐
189 tation.
190
191
192 %EY Full alternate year representation.
193
194
195 %Od Day of the month using the locale's alternate numeric symbols.
196
197
198 %Oe Same as %Od.
199
200
201 %OH Hour (24-hour clock) using the locale's alternate numeric sym‐
202 bols.
203
204
205 %OI Hour (12-hour clock) using the locale's alternate numeric sym‐
206 bols.
207
208
209 %Om Month using the locale's alternate numeric symbols.
210
211
212 %OM Minutes using the locale's alternate numeric symbols.
213
214
215 %OS Seconds using the locale's alternate numeric symbols.
216
217
218 %OU Week number of the year (Sunday as the first day of the week)
219 using the locale's alternate numeric symbols.
220
221
222 %Ow Number of the weekday (Sunday=0) using the locale's alternate
223 numeric symbols.
224
225
226 %OW Week number of the year (Monday as the first day of the week)
227 using the locale's alternate numeric symbols.
228
229
230 %Oy Year (offset from %C) in the locale's alternate representation
231 and using the locale's alternate numeric symbols.
232
233
234 General Specifications
235 A conversion specification that is an ordinary character is executed by
236 scanning the next character from the buffer. If the character scanned
237 from the buffer differs from the one comprising the specification, the
238 specification fails, and the differing and subsequent characters remain
239 unscanned.
240
241
242 A series of specifications composed of %n, %t, white-space characters
243 or any combination is executed by scanning up to the first character
244 that is not white space (which remains unscanned), or until no more
245 characters can be scanned. White space is defined by isspace(3C).
246
247
248 Any other conversion specification is executed by scanning characters
249 until a character matching the next specification is scanned, or until
250 no more characters can be scanned. These characters, except the one
251 matching the next specification, are then compared to the locale values
252 associated with the conversion specifier. If a match is found, values
253 for the appropriate tm structure members are set to values correspond‐
254 ing to the locale information. If no match is found, strptime() fails
255 and no more characters are scanned.
256
257
258 The month names, weekday names, era names, and alternate numeric sym‐
259 bols can consist of any combination of upper and lower case letters.
260 The user can request that the input date or time specification be in a
261 specific language by setting the LC_TIME category using setlocale(3C).
262
263 Non-zeroing Behavior
264 In addition to the behavior described above by various standards, the
265 Solaris implementation of strptime() provides the following extensions.
266 These may change at any time in the future. Portable applications
267 should not depend on these extended features:
268
269 o If _STRPTIME_DONTZERO is not defined, the tm struct is
270 zeroed on entry and strptime() updates the fields of the tm
271 struct associated with the specifiers in the format string.
272
273 o If _STRPTIME_DONTZERO is defined, strptime() does not zero
274 the tm struct on entry. Additionally, for some specifiers,
275 strptime() will use some values in the input tm struct to
276 recalculate the date and re-assign the appropriate members
277 of the tm struct.
278
279
280 The following describes extended features regardless of whether _STRP‐
281 TIME_DONTZERO is defined or not defined:
282
283 o If %j is specified, tm_yday is set; if year is given, and
284 if month and day are not given, strptime() calculates and
285 sets tm_mon, tm_mday, and tm_year.
286
287 o If %U or %W is specified and if weekday and year are given
288 and month and day of month are not given, strptime() calcu‐
289 lates and sets tm_mon, tm_mday, tm_wday, and tm_year.
290
291
292 The following describes extended features when _STRPTIME_DONTZERO is
293 not defined:
294
295 o If %C is specified and %y is not specified, strp‐
296 time()assumes 0 as the year offset, then calculates the
297 year, and assigns tm_year.
298
299
300 The following describes extended features when _STRPTIME_DONTZERO is
301 defined:
302
303 o If %C is specified and %y is not specified, strptime()
304 assumes the year offset of the year value of the tm_year
305 member of the input tm struct, then calculates the year and
306 assigns tm_year.
307
308 o If %j is specified and neither %y, %Y, nor %C are specified,
309 and neither month nor day of month are specified, strptime()
310 assumes the year value given by the value of the tm_year
311 field of the input tm struct. Then, in addition to setting
312 tm_yday, strptime() uses day-of-year and year values to cal‐
313 culate the month and day-of-month, and assigns tm_month and
314 tm_mday.
315
316 o If %U or %W is specified, and if weekday and/or year are not
317 given, and month and day of month are not given, strptime()
318 will assume the weekday value and/or the year value as the
319 value of the tm_wday field and/or tm_year field of the input
320 tm struct. Then, strptime() will calculate the month and
321 day-of-month and assign tm_month, tm_mday, and/or tm_year.
322
323 o If %p is specified and if hour is not specified, strptime()
324 will reference, and if needed, update the tm_hour member. If
325 the am_pm input is p.m. and the input tm_hour value is
326 between 0 - 11, strptime() will add 12 hours and update
327 tm_hour. If the am_pm input is a.m. and input tm_hour value
328 is between 12 - 23, strptime() will subtract 12 hours and
329 update tm_hour.
330
332 Upon successful completion, strptime() returns a pointer to the charac‐
333 ter following the last character parsed. Otherwise, a null pointer is
334 returned.
335
337 Several "same as" formats, and the special processing of white-space
338 characters are provided in order to ease the use of identical format
339 strings for strftime(3C) and strptime().
340
341
342 The strptime() function tries to calculate tm_year, tm_mon, and tm_mday
343 when given incomplete input. This allows the struct tm created by
344 strptime() to be passed to mktime(3C) to produce a time_t value for
345 dates and times that are representable by a time_t. As an example,
346 since mktime() ignores tm_yday, strptime() calculates tm_mon and
347 tm_mday as well as filling in tm_yday when %j is specified without oth‐
348 erwise specifying a month and day within month.
349
351 See attributes(5) for descriptions of the following attributes:
352
353
354
355
356 ┌─────────────────────────────┬─────────────────────────────┐
357 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
358 ├─────────────────────────────┼─────────────────────────────┤
359 │CSI │Enabled │
360 ├─────────────────────────────┼─────────────────────────────┤
361 │Interface Stability │Committed │
362 ├─────────────────────────────┼─────────────────────────────┤
363 │MT-Level │MT-Safe │
364 ├─────────────────────────────┼─────────────────────────────┤
365 │Standard │See standards(5). │
366 └─────────────────────────────┴─────────────────────────────┘
367
369 ctime(3C), getdate(3C), isspace(3C), mktime(3C), setlocale(3C), strf‐
370 time(3C), attributes(5), environ(5), standards(5)
371
372
373
374SunOS 5.11 27 Aug 2007 strptime(3C)