1.\" $OpenBSD: strptime.3,v 1.20 2011/09/16 19:36:07 jmc Exp $ 2.\" 3.\" Copyright (c) 1997, 1998, 2005, 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 $Mdocdate: September 16 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 SYNOPSIS 36.Fd #include <time.h> 37.Ft char * 38.Fn strptime "const char *buf" "const char *format" "struct tm *tm" 39.Sh DESCRIPTION 40The 41.Nm 42function converts the character string pointed to by 43.Fa buf 44to values which are stored in the ``tm'' structure pointed to by 45.Fa tm , 46using the format specified by 47.Fa format . 48.Pp 49The 50.Fa format 51string consists of zero or more directives. 52A directive is composed of either one or more whitespace characters as 53defined by 54.Xr isspace 3 , 55an ordinary character (neither 56.Sq % 57nor a whitespace), or a conversion 58specification. 59A conversion specification consists of a percent sign 60.Pq Sq % 61followed by one or two conversion characters which specify the 62replacement required. 63There must be whitespace or other 64non-alphanumeric characters between any two conversion specifications. 65.Pp 66The 67.Dv LC_TIME 68category defines the locale values for the conversion 69specifications. 70The following conversion specifications are supported: 71.Bl -tag -width "xxxx" 72.It Cm \&%a 73the day of week, using the locale's weekday names; 74either the abbreviated or full name may be specified. 75.It Cm \&%A 76the same as 77.Cm \&%a . 78.It Cm \&%b 79the month, using the locale's month names; 80either the abbreviated or full name may be specified. 81.It Cm \&%B 82the same as 83.Cm \&%b . 84.It Cm \&%c 85the date and time, using the locale's date and time format. 86.It Cm \&%C 87the century number [0,99]; leading zeros are permitted but not required. 88Note that the converted value is added to the current value of the 89``tm_year'' field (in order that the "\&%y" conversion be useful). 90.It Cm \&%d 91the day of month [1,31]; 92leading zeros are permitted but not required. 93.It Cm \&%D 94the date as %m/%d/%y. 95.It Cm \&%e 96the same as 97.Cm \&%d . 98.It Cm \&%F 99the date as %Y-%m-%d 100(the 101.St -iso8601 102date format). 103.It Cm \&%g 104the year corresponding to the ISO week number, without the century. 105.It Cm \&%G 106the year corresponding to the ISO week number, with the century. 107.It Cm \&%h 108the same as 109.Cm \&%b . 110.It Cm \&%H 111the hour (24-hour clock) [0,23]; 112leading zeros are permitted but not required. 113.It Cm \&%I 114the hour (12-hour clock) [1,12]; 115leading zeros are permitted but not required. 116.It Cm \&%j 117the day number of the year [1,366]; 118leading zeros are permitted but not required. 119.It Cm \&%k 120the same as 121.Cm \&%H . 122.It Cm \&%l 123the same as 124.Cm \&%I . 125.It Cm \&%m 126the month number [1,12]; 127leading zeros are permitted but not required. 128.It Cm \&%M 129the minute [0,59]; 130leading zeros are permitted but not required. 131.It Cm \&%n 132any whitespace. 133.It Cm \&%p 134the locale's equivalent of 135.Dq AM 136or 137.Dq PM . 138.It Cm \&%r 139the time as %I:%M:%S %p. 140.It Cm \&%R 141the time as %H:%M. 142.It Cm \&%S 143the seconds [0,60]; 144leading zeros are permitted but not required. 145.It Cm \&%t 146any whitespace. 147.It Cm \&%T 148the time as %H:%M:%S. 149.It Cm \&%u 150the day of the week as a decimal number, where Monday = 1. 151.It Cm \&%U 152the week number of the year (Sunday as the first day of the week) 153as a decimal number [0,53]; 154leading zeros are permitted but not required. 155All days in a year preceding the first Sunday are considered to be in week 0. 156.It Cm \&%V 157the 158.St -iso8601 159week number as a decimal number. 160If the week (starting on Monday) that contains January 1 has more than 161three days in the new year, then it is considered the first week of the 162year. 163If it has fewer than four days in the new year, then it is considered 164the last week of the previous year. 165Weeks are numbered from 1 to 53. 166.It Cm \&%w 167the weekday as a decimal number [0,6], with 0 representing Sunday; 168leading zeros are permitted but not required. 169.It Cm \&%W 170the week number of the year (Monday as the first day of the week) 171as a decimal number [0,53]; 172leading zeros are permitted but not required. 173All days in a year preceding the first Monday are considered to be in week 0. 174.It Cm \&%x 175the date, using the locale's date format. 176.It Cm \&%X 177the time, using the locale's time format. 178.It Cm \&%y 179the year within the current century. 180When a century is not otherwise 181specified, values in the range 69\-99 refer to years in the twentieth 182century (1969 to 1999 inclusive); values in the range 00\-68 refer 183to years in the twenty-first century (2000 to 2068 inclusive). 184Leading zeros are permitted but not required. 185.It Cm \&%Y 186the year, including the century (i.e., 1998). 187.It Cm \&%z 188an 189.St -iso8601 190or RFC 2822 timezone specification. 191This is one of the following: 192the offset from 193Coordinated Universal Time 194.Pq Ql UTC 195specified as: 196.Dq [+-]hhmm , 197.Dq [+-]hh:mm , 198or 199.Dq [+-]hh ; 200.Ql UTC 201specified as: 202.Dq GMT 203.Pq Ql Greenwich Mean Time , 204.Dq UT 205.Pq Ql Universal Time , 206or 207.Dq Z 208.Pq Ql Zulu Time ; 209a three character US timezone specified as: 210.Dq EDT , 211.Dq EST , 212.Dq CDT , 213.Dq CST , 214.Dq MDT , 215.Dq MST , 216.Dq PDT , 217or 218.Dq PST , 219with the first letter standing for 220.Ql Eastern 221.Pq Dq E , 222.Ql Central 223.Pq Dq C , 224.Ql Mountain 225.Pq Dq M 226or 227.Ql Pacific 228.Pq Dq P , 229and the second letter standing for 230.Ql Daylight 231.Po 232.Dq D 233or summer 234.Pc 235time 236or 237.Ql Standard 238.Pq Dq S 239time; 240a single letter military timezone specified as: 241.Dq A 242through 243.Dq I 244and 245.Dq K 246through 247.Dq Y . 248.It Cm \&%Z 249timezone name or no characters when timezone information is unavailable. 250.It Cm \&%% 251A `%' is read. 252No argument is converted. 253.El 254.Pp 255There is no way to specify whether Daylight Saving Time is in effect when 256calling 257.Nm . 258To use the resulting 259.Fa tm 260structure with functions that check the 261.Fa tm_isdst 262field, either set it to a negative value, which will cause 263.Xr mktime 3 264to attempt to divine whether Daylight Saving Time would be in effect 265for the given time, or compute the value manually. 266.Ss Modified conversion specifications 267For compatibility, certain conversion specifications can be modified 268by the 269.Cm E 270and 271.Cm O 272modifier characters to indicate that an alternative format or 273specification should be used rather than the one normally used by the 274unmodified conversion specification. 275As there are currently neither 276alternative formats nor specifications supported by the system, the 277behavior will be as if the unmodified conversion specification were 278used. 279.Pp 280Case is ignored when matching string items in 281.Fa buf , 282such as month and weekday names. 283.Sh RETURN VALUES 284If successful, the 285.Nm 286function returns a pointer to the character following the last character 287parsed. 288Otherwise, a null pointer is returned. 289.Sh SEE ALSO 290.Xr mktime 3 , 291.Xr strftime 3 292.Sh STANDARDS 293The 294.Fn strptime 295function conforms to 296.St -xpg4.2 . 297.Pp 298The 299.Ql \&%G , 300.Ql \&%g , 301.Ql \&%u , 302.Ql \&%V , 303.Ql \&%Y , 304and 305.Ql \&%Z 306conversion specifications are extensions. 307.Sh BUGS 308The 309.Cm \&%Z 310format specifier only accepts timezone 311abbreviations of the local timezone, 312or the value 313.Dq GMT . 314This limitation is caused by the ambiguity 315of overloaded timezone abbreviations, 316for example EST is both Eastern Standard 317Time and Eastern Australia Summer Time. 318