1.\" $NetBSD: strptime.3,v 1.39 2024/09/07 20:48:02 rillig 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 February 24, 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 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,60]; 166leading zeros are permitted but not required. 167.It Cm \&%s 168the number of seconds since the Epoch, UTC (see 169.Xr mktime 3 ) . 170.Po 171A 172.Nx 173extension. 174.Pc 175.It Cm \&%t 176any white-space, including none. 177.It Cm \&%T 178the time as %H:%M:%S. 179.It Cm \&%u 180the day of the week as a decimal number, where Monday = 1. 181.Po 182A 183.Nx 184extension. 185.Pc 186.It Cm \&%U 187the week number of the year (Sunday as the first day of the week) 188as a decimal number [0,53]; 189leading zeros are permitted but not required. 190All days in a year preceding the first Sunday are considered to be in week 0. 191.It Cm \&%V 192the ISO 8601:1988 week number as a decimal number. 193If the week (starting on Monday) that contains January 1 has more than 194three days in the new year, then it is considered the first week of the 195year. 196If it has fewer than four days in the new year, then it is considered 197the last week of the previous year. 198Weeks are numbered from 1 to 53. 199.Po 200A 201.Nx 202extension. 203.Pc 204.It Cm \&%w 205the weekday as a decimal number [0,6], with 0 representing Sunday; 206leading zeros are permitted but not required. 207.It Cm \&%W 208the week number of the year (Monday as the first day of the week) 209as a decimal number [0,53]; 210leading zeros are permitted but not required. 211All days in a year preceding the first Monday are considered to be in week 0. 212.It Cm \&%x 213the date, using the locale's date format. 214.It Cm \&%X 215the time, using the locale's time format. 216.It Cm \&%y 217the year within the 20th century [69,99] or the 21st century [0,68]; 218leading zeros are permitted but not required. 219If specified in conjunction 220with \&%C, specifies the year [0,99] within that century. 221.It Cm \&%Y 222the year, including the century (i.e., 1996). 223.It Cm \&%z 224an ISO 8601, RFC-2822, or RFC-3339 time zone specification. 225.Po 226A 227.Nx 228extension. 229.Pc 230This is one of the following: 231.Bl -dash -offset indent -compact 232.It 233The offset from Coordinated Universal Time 234.Pq Ql UTC 235specified as: 236.Bl -bullet -offset indent -compact 237.It 238[+-]hhmm 239.It 240[+-]hh:mm 241.It 242[+-]hh 243.El 244.It 245.Ql UTC 246specified as: 247.Bl -bullet -offset indent -compact 248.It 249UTC 250.Pq Ql Coordinated Universal Time 251.It 252GMT 253.Pq Ql Greenwich Mean Time 254.It 255UT 256.Pq Ql Universal Time 257.It 258Z 259.Pq Ql Zulu Time 260.El 261.It 262A three character US time zone specified as: 263.Bl -bullet -offset indent -compact 264.It 265EDT 266.It 267EST 268.It 269CDT 270.It 271CST 272.It 273MDT 274.It 275MST 276.It 277PDT 278.It 279PST 280.El 281with the first letter standing for 282.Ql Eastern 283.Pq Dq E , 284.Ql Central 285.Pq Dq C , 286.Ql Mountain 287.Pq Dq M 288or 289.Ql Pacific 290.Pq Dq P , 291and the second letter standing for 292.Ql Daylight 293.Po 294.Dq D 295or summer 296.Pc 297time 298or 299.Ql Standard 300.Pq Dq S 301time 302.It 303a single letter military or nautical time zone specified as: 304.Bl -bullet -offset indent -compact 305.It 306.Dq A 307through 308.Dq I 309.It 310.Dq K 311through 312.Dq Y 313.It 314.Dq J 315.Pq non-nautical local time zone 316.El 317.It 318An arbitrary timezone name that can be loaded from the database. 319.El 320.It Cm \&%Z 321time zone name or no characters when time zone information is unavailable. 322.Po 323A 324.Nx 325extension. 326.Pc 327.It Cm \&%% 328matches a literal `%'. 329No argument is converted. 330.El 331.Ss Modified conversion specifications 332For compatibility, certain conversion specifications can be modified 333by the 334.Cm E 335and 336.Cm O 337modifier characters to indicate that an alternative format or specification 338should be used rather than the one normally used by the unmodified 339conversion specification. 340As there are currently neither alternative formats 341nor specifications supported by the system, the behavior will be as if the 342unmodified conversion specification were used. 343.Pp 344Case is ignored when matching string items in 345.Fa buf , 346such as month and weekday names. 347.Sh RETURN VALUES 348If successful, the 349.Fn strptime 350function returns a pointer to the character following the last character 351parsed. 352Otherwise, a 353.Dv NULL 354pointer is returned. 355.Sh SEE ALSO 356.Xr ctime 3 , 357.Xr isspace 3 , 358.Xr localtime 3 , 359.Xr strftime 3 , 360.Xr tm 3 361.Sh STANDARDS 362The 363.Fn strptime 364function conforms to 365.St -xpg4 . 366.Sh BUGS 367The 368.Cm \&%Z 369format specifier only accepts time zone 370abbreviations of the local time zone, 371or the values 372.Dq GMT 373or 374.Dq UTC . 375This limitation is caused by the ambiguity 376of overloaded time zone abbreviations, 377for example EST is both Eastern Standard 378Time and Eastern Australia Summer Time. 379