1.\" $NetBSD: strptime.3,v 1.22 2008/11/04 18:37:28 christos 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 November 4, 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 \&%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 \&%t 168any white-space, including none. 169.It Cm \&%T 170the time as %H:%M:%S. 171.It Cm \&%u 172the day of the week as a decimal number, where Monday = 1. 173.Po 174A 175.Nx 176extension. 177.Pc 178.It Cm \&%U 179the week number of the year (Sunday as the first day of the week) 180as a decimal number [0,53]; 181leading zeros are permitted but not required. 182All days in a year preceding the first Sunday are considered to be in week 0. 183.It Cm \&%V 184the ISO 8601:1988 week number as a decimal number. 185If the week (starting on Monday) that contains January 1 has more than 186three days in the new year, then it is considered the first week of the 187year. 188If it has fewer than four days in the new year, then it is considered 189the last week of the previous year. 190Weeks are numbered from 1 to 53. 191A 192.Nx 193extension. 194.It Cm \&%w 195the weekday as a decimal number [0,6], with 0 representing Sunday; 196leading zeros are permitted but not required. 197.It Cm \&%W 198the week number of the year (Monday as the first day of the week) 199as a decimal number [0,53]; 200leading zeros are permitted but not required. 201All days in a year preceding the first Monday are considered to be in week 0. 202.It Cm \&%x 203the date, using the locale's date format. 204.It Cm \&%X 205the time, using the locale's time format. 206.It Cm \&%y 207the year within the 20th century [69,99] or the 21st century [0,68]; 208leading zeros are permitted but not required. 209If specified in conjunction 210with \&%C, specifies the year [0,99] within that century. 211.It Cm \&%Y 212the year, including the century (i.e., 1996). 213.It Cm \&%z 214an ISO 8601 timezone specification. 215This is either, 216.Dq Z 217for 218.Ql UTC , 219or the offset specified as: 220.Dq [+-]hhmm 221or 222.Dq [+-]hh:mm 223or 224.Dq [+-]hh . 225.Po 226A 227.Nx 228extension. 229.Pc 230.It Cm \&%Z 231timezone name or no characters when time zone information is unavailable. 232.Po 233A 234.Nx 235extension. 236.Pc 237.It Cm \&%% 238matches a literal `%'. 239No argument is converted. 240.El 241.Ss Modified conversion specifications 242For compatibility, certain conversion specifications can be modified 243by the 244.Cm E 245and 246.Cm O 247modifier characters to indicate that an alternative format or specification 248should be used rather than the one normally used by the unmodified 249conversion specification. 250As there are currently neither alternative formats 251nor specifications supported by the system, the behavior will be as if the 252unmodified conversion specification were used. 253.Pp 254Case is ignored when matching string items in 255.Fa buf , 256such as month and weekday names. 257.Sh RETURN VALUES 258If successful, the 259.Fn strptime 260function returns a pointer to the character following the last character 261parsed. 262Otherwise, a null pointer is returned. 263.Sh SEE ALSO 264.Xr ctime 3 , 265.Xr isspace 3 , 266.Xr localtime 3 , 267.Xr strftime 3 268.Sh STANDARDS 269The 270.Fn strptime 271function conforms to 272.St -xpg4 . 273.Sh BUGS 274The 275.Cm \&%Z 276format specifier only accepts timezone 277abbreviations of the local timezone, 278or the value 279.Dq GMT . 280This limitation is caused by the ambiguity 281of overloaded timezone abbreviations, 282for example EST is both Eastern Standard 283Time and Eastern Australia Summer Time. 284