1.\" $NetBSD: strptime.3,v 1.21 2008/04/30 13:10:51 martin 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 25, 2008 30.Os 31.Dt STRPTIME 3 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 \&%h 119the same as 120.Cm \&%b . 121.It Cm \&%H 122the hour (24-hour clock) [0,23]; 123leading zeros are permitted but not required. 124.It Cm \&%I 125the hour (12-hour clock) [1,12]; 126leading zeros are permitted but not required. 127.It Cm \&%j 128the day number of the year [1,366]; 129leading zeros are permitted but not required. 130.It Cm \&%k 131the same as 132.Cm \&%H . 133.It Cm \&%l 134the same as 135.Cm \&%I . 136.It Cm \&%m 137the month number [1,12]; 138leading zeros are permitted but not required. 139.It Cm \&%M 140the minute [0,59]; 141leading zeros are permitted but not required. 142.It Cm \&%n 143any white-space, including none. 144.It Cm \&%p 145the locale's equivalent of a.m. or p.m. 146.It Cm \&%r 147the time (12-hour clock) with %p, using the locale's time format. 148.It Cm \&%R 149the time as %H:%M. 150.It Cm \&%S 151the seconds [0,61]; 152leading zeros are permitted but not required. 153.It Cm \&%t 154any white-space, including none. 155.It Cm \&%T 156the time as %H:%M:%S. 157.It Cm \&%U 158the week number of the year (Sunday as the first day of the week) 159as a decimal number [0,53]; 160leading zeros are permitted but not required. 161All days in a year preceding the first Sunday are considered to be in week 0. 162.It Cm \&%w 163the weekday as a decimal number [0,6], with 0 representing Sunday; 164leading zeros are permitted but not required. 165.It Cm \&%W 166the week number of the year (Monday as the first day of the week) 167as a decimal number [0,53]; 168leading zeros are permitted but not required. 169All days in a year preceding the first Monday are considered to be in week 0. 170.It Cm \&%x 171the date, using the locale's date format. 172.It Cm \&%X 173the time, using the locale's time format. 174.It Cm \&%y 175the year within the 20th century [69,99] or the 21st century [0,68]; 176leading zeros are permitted but not required. 177If specified in conjunction 178with \&%C, specifies the year [0,99] within that century. 179.It Cm \&%Y 180the year, including the century (i.e., 1996). 181.It Cm \&%Z 182timezone name or no characters when time zone information is unavailable. 183.Po 184A 185.Nx 186extension. 187.Pc 188.It Cm \&%% 189matches a literal `%'. 190No argument is converted. 191.El 192.Ss Modified conversion specifications 193For compatibility, certain conversion specifications can be modified 194by the 195.Cm E 196and 197.Cm O 198modifier characters to indicate that an alternative format or specification 199should be used rather than the one normally used by the unmodified 200conversion specification. 201As there are currently neither alternative formats 202nor specifications supported by the system, the behavior will be as if the 203unmodified conversion specification were used. 204.Pp 205Case is ignored when matching string items in 206.Fa buf , 207such as month and weekday names. 208.Sh RETURN VALUES 209If successful, the 210.Fn strptime 211function returns a pointer to the character following the last character 212parsed. 213Otherwise, a null pointer is returned. 214.Sh SEE ALSO 215.Xr ctime 3 , 216.Xr isspace 3 , 217.Xr localtime 3 , 218.Xr strftime 3 219.Sh STANDARDS 220The 221.Fn strptime 222function conforms to 223.St -xpg4 . 224.Sh BUGS 225The 226.Cm \&%Z 227format specifier only accepts timezone 228abbreviations of the local timezone, 229or the value 230.Dq GMT . 231This limitation is caused by the ambiguity 232of overloaded timezone abbreviations, 233for example EST is both Eastern Standard 234Time and Eastern Australia Summer Time. 235