1strptime(3C)             Standard C Library Functions             strptime(3C)
2
3
4

NAME

6       strptime - date and time conversion
7

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

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

USAGE

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

ATTRIBUTES

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

SEE ALSO

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)
Impressum