1.\" $NetBSD: strptime.3,v 1.29 2011/04/12 08:40:34 jruoho 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 April 12, 2011 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 42The 43.Fn strptime 44function converts the character string pointed to by 45.Fa buf 46to values which are stored in the 47.Va tm 48structure pointed to by 49.Fa tm , 50using the format specified by 51.Fa format . 52.Pp 53The 54.Fa format 55string consists of zero or more conversion specifications, whitespace 56characters as defined by 57.Fn isspace , 58and ordinary characters. 59All ordinary characters in 60.Fa format 61are compared directly against the corresponding characters in 62.Fa buf ; 63comparisons which fail will cause 64.Fn strptime 65to fail. 66Whitespace characters in 67.Fa format 68match any number of whitespace characters in 69.Fa buf , 70including none. 71.Pp 72A conversion specification consists of a percent sign 73.Ql % 74followed by one 75or two conversion characters which specify the replacement required. 76There must be white-space or other non-alphanumeric characters between any 77two conversion specifications. 78.Pp 79Conversion of alphanumeric strings (such as month and weekday names) is 80done without regard to case. 81Conversion specifications which cannot be matched will cause 82.Fn strptime 83to fail. 84.Pp 85The LC_TIME category defines the locale values for the conversion 86specifications. 87The following conversion specifications are supported: 88.Bl -tag -width "xxxx" 89.It Cm \&%a 90the day of week, using the locale's weekday names; 91either the abbreviated or full name may be specified. 92.It Cm \&%A 93the same as 94.Cm \&%a . 95.It Cm \&%b 96the month, using the locale's month names; 97either the abbreviated or full name may be specified. 98.It Cm \&%B 99the same as 100.Cm \&%b . 101.It Cm \&%c 102the date and time, using the locale's date and time format. 103.It Cm \&%C 104the century number [0,99]; 105leading zeros are permitted but not required. 106This conversion should be used in conjunction with the \&%y conversion. 107.It Cm \&%d 108the day of month [1,31]; 109leading zeros are permitted but not required. 110.It Cm \&%D 111the date as %m/%d/%y. 112.It Cm \&%e 113the same as 114.Cm \&%d . 115.It Cm \&%F 116the date as %Y-%m-%d 117(the ISO 8601 date format). 118.It Cm \&%g 119the year corresponding to the ISO week number, without the century. 120.Po 121A 122.Nx 123extension. 124.Pc 125.It Cm \&%G 126the year corresponding to the ISO week number, with the century. 127.Po 128A 129.Nx 130extension. 131.Pc 132.It Cm \&%h 133the same as 134.Cm \&%b . 135.It Cm \&%H 136the hour (24-hour clock) [0,23]; 137leading zeros are permitted but not required. 138.It Cm \&%I 139the hour (12-hour clock) [1,12]; 140leading zeros are permitted but not required. 141.It Cm \&%j 142the day number of the year [1,366]; 143leading zeros are permitted but not required. 144.It Cm \&%k 145the same as 146.Cm \&%H . 147.It Cm \&%l 148the same as 149.Cm \&%I . 150.It Cm \&%m 151the month number [1,12]; 152leading zeros are permitted but not required. 153.It Cm \&%M 154the minute [0,59]; 155leading zeros are permitted but not required. 156.It Cm \&%n 157any white-space, including none. 158.It Cm \&%p 159the locale's equivalent of a.m. or p.m. 160.It Cm \&%r 161the time (12-hour clock) with %p, using the locale's time format. 162.It Cm \&%R 163the time as %H:%M. 164.It Cm \&%S 165the seconds [0,61]; 166leading zeros are permitted but not required. 167.It Cm \&%s 168the number of seconds since the Epoch, UTC (see 169.Xr mktime 3 ) . 170.Po 171A 172.Nx 173extension. 174.Pc 175.It Cm \&%t 176any white-space, including none. 177.It Cm \&%T 178the time as %H:%M:%S. 179.It Cm \&%u 180the day of the week as a decimal number, where Monday = 1. 181.Po 182A 183.Nx 184extension. 185.Pc 186.It Cm \&%U 187the week number of the year (Sunday as the first day of the week) 188as a decimal number [0,53]; 189leading zeros are permitted but not required. 190All days in a year preceding the first Sunday are considered to be in week 0. 191.It Cm \&%V 192the ISO 8601:1988 week number as a decimal number. 193If the week (starting on Monday) that contains January 1 has more than 194three days in the new year, then it is considered the first week of the 195year. 196If it has fewer than four days in the new year, then it is considered 197the last week of the previous year. 198Weeks are numbered from 1 to 53. 199.Po 200A 201.Nx 202extension. 203.Pc 204.It Cm \&%w 205the weekday as a decimal number [0,6], with 0 representing Sunday; 206leading zeros are permitted but not required. 207.It Cm \&%W 208the week number of the year (Monday as the first day of the week) 209as a decimal number [0,53]; 210leading zeros are permitted but not required. 211All days in a year preceding the first Monday are considered to be in week 0. 212.It Cm \&%x 213the date, using the locale's date format. 214.It Cm \&%X 215the time, using the locale's time format. 216.It Cm \&%y 217the year within the 20th century [69,99] or the 21st century [0,68]; 218leading zeros are permitted but not required. 219If specified in conjunction 220with \&%C, specifies the year [0,99] within that century. 221.It Cm \&%Y 222the year, including the century (i.e., 1996). 223.It Cm \&%z 224an ISO 8601 or RFC-2822 timezone specification. 225This is one of the following: 226the offset from 227Coordinated Universal Time 228.Pq Ql UTC 229specified as: 230.Dq [+-]hhmm , 231.Dq [+-]hh:mm , 232or 233.Dq [+-]hh ; 234.Ql UTC 235specified as: 236.Dq GMT 237.Pq Ql Greenwich Mean Time , 238.Dq UT 239.Pq Ql Universal Time , 240or 241.Dq Z 242.Pq Ql Zulu Time ; 243a 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 , 251or 252.Dq PST , 253with 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 260or 261.Ql Pacific 262.Pq Dq P , 263and the second letter standing for 264.Ql Daylight 265.Po 266.Dq D 267or summer 268.Pc 269time 270or 271.Ql Standard 272.Pq Dq S 273time; 274a single letter military timezone specified as: 275.Dq A 276through 277.Dq I 278and 279.Dq K 280through 281.Dq Y . 282.Po 283A 284.Nx 285extension. 286.Pc 287.It Cm \&%Z 288timezone name or no characters when time zone information is unavailable. 289.Po 290A 291.Nx 292extension. 293.Pc 294.It Cm \&%% 295matches a literal `%'. 296No argument is converted. 297.El 298.Ss Modified conversion specifications 299For compatibility, certain conversion specifications can be modified 300by the 301.Cm E 302and 303.Cm O 304modifier characters to indicate that an alternative format or specification 305should be used rather than the one normally used by the unmodified 306conversion specification. 307As there are currently neither alternative formats 308nor specifications supported by the system, the behavior will be as if the 309unmodified conversion specification were used. 310.Pp 311Case is ignored when matching string items in 312.Fa buf , 313such as month and weekday names. 314.Sh RETURN VALUES 315If successful, the 316.Fn strptime 317function returns a pointer to the character following the last character 318parsed. 319Otherwise, a 320.Dv NULL 321pointer is returned. 322.Sh SEE ALSO 323.Xr ctime 3 , 324.Xr isspace 3 , 325.Xr localtime 3 , 326.Xr strftime 3 , 327.Xr tm 3 328.Sh STANDARDS 329The 330.Fn strptime 331function conforms to 332.St -xpg4 . 333.Sh BUGS 334The 335.Cm \&%Z 336format specifier only accepts timezone 337abbreviations of the local timezone, 338or the value 339.Dq GMT . 340This limitation is caused by the ambiguity 341of overloaded timezone abbreviations, 342for example EST is both Eastern Standard 343Time and Eastern Australia Summer Time. 344