1.\" $NetBSD: strptime.3,v 1.14 2002/10/01 18:16:00 wiz Exp $ 2.\" 3.\" Copyright (c) 1997, 1998 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.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the NetBSD 19.\" Foundation, Inc. and its contributors. 20.\" 4. Neither the name of The NetBSD Foundation nor the names of its 21.\" contributors may be used to endorse or promote products derived 22.\" from this software without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 25.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 26.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 27.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 28.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34.\" POSSIBILITY OF SUCH DAMAGE. 35.\" 36.Dd August 18, 2002 37.Os 38.Dt STRPTIME 3 39.Sh NAME 40.Nm strptime 41.Nd converts a character string to a time value 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.Fd #include \*[Lt]time.h\*[Gt] 46.Ft char * 47.Fn strptime "const char * restrict buf" "const char * restrict format" "struct tm * restrict tm" 48.Sh DESCRIPTION 49The 50.Fn strptime 51function converts the character string pointed to by 52.Fa buf 53to values which are stored in the 54.Va tm 55structure pointed to by 56.Fa tm , 57using the format specified by 58.Fa format . 59.Pp 60The 61.Fa format 62string consists of zero or more conversion specifications, whitespace 63characters as defined by 64.Fn isspace , 65and ordinary characters. 66All ordinary characters in 67.Fa format 68are compared directly against the corresponding characters in 69.Fa buf ; 70comparisons which fail will cause 71.Fn strptime 72to fail. 73Whitespace characters in 74.Fa format 75match any number of whitespace characters in 76.Fa buf , 77including none. 78.Pp 79A conversion specification consists of a percent sign 80.Ql % 81followed by one 82or two conversion characters which specify the replacement required. 83There must be white-space or other non-alphanumeric characters between any 84two conversion specifications. 85.Pp 86Conversion of alphanumeric strings (such as month and weekday names) is 87done without regard to case. 88Conversion specifications which cannot be matched will cause 89.Fn strptime 90to fail. 91.Pp 92The LC_TIME category defines the locale values for the conversion 93specifications. 94The following conversion specifications are supported: 95.Bl -tag -width "xxxx" 96.It Cm \&%a 97the day of week, using the locale's weekday names; 98either the abbreviated or full name may be specified. 99.It Cm \&%A 100the same as 101.Cm \&%a . 102.It Cm \&%b 103the month, using the locale's month names; 104either the abbreviated or full name may be specified. 105.It Cm \&%B 106the same as 107.Cm \&%b . 108.It Cm \&%c 109the date and time, using the locale's date and time format. 110.It Cm \&%C 111the century number [0,99]; 112leading zeros are permitted but not required. 113This conversion should be used in conjunction with the \&%y conversion. 114.It Cm \&%d 115the day of month [1,31]; 116leading zeros are permitted but not required. 117.It Cm \&%D 118the date as %m/%d/%y. 119.It Cm \&%e 120the same as 121.Cm \&%d . 122.It Cm \&%h 123the same as 124.Cm \&%b . 125.It Cm \&%H 126the hour (24-hour clock) [0,23]; 127leading zeros are permitted but not required. 128.It Cm \&%I 129the hour (12-hour clock) [1,12]; 130leading zeros are permitted but not required. 131.It Cm \&%j 132the day number of the year [1,366]; 133leading zeros are permitted but not required. 134.It Cm \&%k 135the same as 136.Cm \&%H . 137.It Cm \&%l 138the same as 139.Cm \&%I . 140.It Cm \&%m 141the month number [1,12]; 142leading zeros are permitted but not required. 143.It Cm \&%M 144the minute [0,59]; 145leading zeros are permitted but not required. 146.It Cm \&%n 147any white-space, including none. 148.It Cm \&%p 149the locale's equivalent of a.m. or p.m. 150.It Cm \&%r 151the time (12-hour clock) with %p, using the locale's time format. 152.It Cm \&%R 153the time as %H:%M. 154.It Cm \&%S 155the seconds [0,61]; 156leading zeros are permitted but not required. 157.It Cm \&%t 158any white-space, including none. 159.It Cm \&%T 160the time as %H:%M:%S. 161.It Cm \&%U 162the week number of the year (Sunday as the first day of the week) 163as a decimal number [0,53]; 164leading zeros are permitted but not required. 165All days in a year preceding the first Sunday are considered to be in week 0. 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 20th century [69,99] or the 21st century [0,68]; 180leading zeros are permitted but not required. 181If specified in conjunction 182with \&%C, specifies the year [0,99] within that century. 183.It Cm \&%Y 184the year, including the century (i.e., 1996). 185.It Cm \&%% 186A `%' is written. 187No argument is converted. 188.El 189.Ss Modified conversion specifications 190For compatibility, certain conversion specifications can be modified 191by the 192.Cm E 193and 194.Cm O 195modifier characters to indicate that an alternative format or specification 196should be used rather than the one normally used by the unmodified 197conversion specification. 198As there are currently neither alternative formats 199nor specifications supported by the system, the behavior will be as if the 200unmodified conversion specification were used. 201.Pp 202Case is ignored when matching string items in 203.Fa buf , 204such as month and weekday names. 205.Sh RETURN VALUES 206If successful, the 207.Fn strptime 208function returns a pointer to the character following the last character 209parsed. 210Otherwise, a null pointer is returned. 211.Sh SEE ALSO 212.Xr ctime 3 , 213.Xr isspace 3 , 214.Xr localtime 3 , 215.Xr strftime 3 216.Sh STANDARDS 217The 218.Fn strptime 219function conforms to 220.St -xpg4 . 221