1.\" $OpenBSD: strptime.3,v 1.30 2019/07/19 18:58:03 schwarze 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: July 19 2019 $ 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 following conversion specifications are supported: 69.Bl -tag -width "xxxx" 70.It Cm \&%a 71the day of week, using the locale's weekday names; 72either the abbreviated or full name may be specified. 73.It Cm \&%A 74the same as 75.Cm \&%a . 76.It Cm \&%b 77the month, using the locale's month names; 78either the abbreviated or full name may be specified. 79.It Cm \&%B 80the same as 81.Cm \&%b . 82.It Cm \&%c 83the date and time, using the locale's date and time format. 84.It Cm \&%C 85the century number [0,99]; leading zeros are permitted but not required. 86Note that the converted value is added to the current value of the 87.Fa tm_year 88field (in order that the "\&%y" conversion be useful). 89.It Cm \&%d 90the day of month [1,31]; 91leading zeros are permitted but not required. 92.It Cm \&%D 93the date as %m/%d/%y. 94.It Cm \&%e 95the day of month [1,31]; 96leading spaces or zeros are permitted but not required. 97.It Cm \&%F 98the date as %Y-%m-%d 99(the 100.St -iso8601 101date format). 102.It Cm \&%g 103the year corresponding to the ISO week number, without the century. 104.It Cm \&%G 105the year corresponding to the ISO week number, with the century. 106.It Cm \&%h 107the same as 108.Cm \&%b . 109.It Cm \&%H 110the hour (24-hour clock) [0,23]; 111leading zeros are permitted but not required. 112.It Cm \&%I 113the hour (12-hour clock) [1,12]; 114leading zeros are permitted but not required. 115.It Cm \&%j 116the day number of the year [1,366]; 117leading zeros are permitted but not required. 118.It Cm \&%k 119the same as 120.Cm \&%H . 121.It Cm \&%l 122the same as 123.Cm \&%I . 124.It Cm \&%m 125the month number [1,12]; 126leading zeros are permitted but not required. 127.It Cm \&%M 128the minute [0,59]; 129leading zeros are permitted but not required. 130.It Cm \&%n 131any whitespace. 132.It Cm \&%p 133the locale's equivalent of 134.Dq AM 135or 136.Dq PM . 137.It Cm \&%r 138the time as %I:%M:%S %p. 139.It Cm \&%R 140the time as %H:%M. 141.It Cm \&%S 142the seconds [0,60]; 143leading zeros are permitted but not required. 144.It Cm \&%s 145the number of seconds since the Epoch, UTC (see 146.Xr mktime 3 ) . 147.It Cm \&%t 148any whitespace. 149.It Cm \&%T 150the time as %H:%M:%S. 151.It Cm \&%u 152the day of the week as a decimal number, where Monday = 1. 153.It Cm \&%U 154the week number of the year (Sunday as the first day of the week) 155as a decimal number [0,53]; 156leading zeros are permitted but not required. 157All days in a year preceding the first Sunday are considered to be in week 0. 158.It Cm \&%V 159the 160.St -iso8601 161week number as a decimal number. 162If the week (starting on Monday) that contains January 1 has more than 163three days in the new year, then it is considered the first week of the 164year. 165If it has fewer than four days in the new year, then it is considered 166the last week of the previous year. 167Weeks are numbered from 1 to 53. 168.It Cm \&%w 169the weekday as a decimal number [0,6], with 0 representing Sunday; 170leading zeros are permitted but not required. 171.It Cm \&%W 172the week number of the year (Monday as the first day of the week) 173as a decimal number [0,53]; 174leading zeros are permitted but not required. 175All days in a year preceding the first Monday are considered to be in week 0. 176.It Cm \&%x 177the date, using the locale's date format. 178.It Cm \&%X 179the time, using the locale's time format. 180.It Cm \&%y 181the year within the current century. 182When a century is not otherwise 183specified, values in the range 69\-99 refer to years in the twentieth 184century (1969 to 1999 inclusive); values in the range 00\-68 refer 185to years in the twenty-first century (2000 to 2068 inclusive). 186Leading zeros are permitted but not required. 187.It Cm \&%Y 188the year, including the century (i.e., 1998). 189.It Cm \&%z 190an 191.St -iso8601 192or RFC 5322 timezone specification. 193This is one of the following: 194the offset from 195Coordinated Universal Time 196.Pq Ql UTC 197specified as: 198.Dq [+-]hhmm , 199.Dq [+-]hh:mm , 200or 201.Dq [+-]hh ; 202.Ql UTC 203specified as: 204.Dq GMT 205.Pq Ql Greenwich Mean Time , 206.Dq UT 207.Pq Ql Universal Time , 208or 209.Dq Z 210.Pq Ql Zulu Time ; 211a three character US timezone specified as: 212.Dq EDT , 213.Dq EST , 214.Dq CDT , 215.Dq CST , 216.Dq MDT , 217.Dq MST , 218.Dq PDT , 219or 220.Dq PST , 221with the first letter standing for 222.Ql Eastern 223.Pq Dq E , 224.Ql Central 225.Pq Dq C , 226.Ql Mountain 227.Pq Dq M 228or 229.Ql Pacific 230.Pq Dq P , 231and the second letter standing for 232.Ql Daylight 233.Po 234.Dq D 235or summer 236.Pc 237time 238or 239.Ql Standard 240.Pq Dq S 241time. 242.It Cm \&%Z 243timezone name or no characters when timezone information is unavailable. 244.It Cm \&%% 245A `%' is read. 246No argument is converted. 247.El 248.Pp 249The 250.Ox 251implementation always uses the C locale and ignores the 252global locale and the thread-specific locale. 253Alternative conversion modifiers have no effect. 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 the X/Open System Interfaces option of 296.St -p1003.1-2008 , 297except that flags and field width specifications are not supported. 298.Pp 299The 300.Ql \&%F , 301.Ql \&%g , 302.Ql \&%G , 303.Ql \&%k , 304.Ql \&%l , 305.Ql \&%s , 306.Ql \&%u , 307.Ql \&%V , 308.Ql \&%z , 309and 310.Ql \&%Z 311conversion specifications are extensions. 312.Sh CAVEATS 313On systems other than 314.Ox , 315the 316.Dv LC_TIME 317.Xr locale 1 318category can cause parsing failures; see CAVEATS in 319.Xr setlocale 3 320for details. 321.Sh BUGS 322The 323.Cm \&%Z 324format specifier only accepts timezone 325abbreviations of the local timezone, 326or the value 327.Dq GMT . 328This limitation is caused by the ambiguity 329of overloaded timezone abbreviations, 330for example EST is both Eastern Standard 331Time and Eastern Australia Summer Time. 332