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