1.\" $NetBSD: strptime.3,v 1.12 2002/02/07 07:00:34 ross 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 January 20, 1998 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. All ordinary characters in 66.Fa format 67are compared directly against the corresponding characters in 68.Fa buf ; 69comparisons which fail will cause 70.Fn strptime 71to fail. Whitespace characters in 72.Fa format 73match any number of whitespace characters in 74.Fa buf , 75including none. 76.Pp 77A conversion specification consists of a percent sign 78.Ql % 79followed by one 80or two conversion characters which specify the replacement required. 81There must be white-space or other non-alphanumeric characters between any 82two conversion specifications. 83.Pp 84Conversion of alphanumeric strings (such as month and weekday names) is 85done without regard to case. Conversion specifications which cannot be 86matched will cause 87.Fn strptime 88to fail. 89.Pp 90The LC_TIME category defines the locale values for the conversion 91specifications. The following conversion specifications are supported: 92.Bl -tag -width "xxxx" 93.It Cm \&%a 94the day of week, using the locale's weekday names; 95either the abbreviated or full name may be specified. 96.It Cm \&%A 97the same as 98.Cm \&%a . 99.It Cm \&%b 100the month, using the locale's month names; 101either the abbreviated or full name may be specified. 102.It Cm \&%B 103the same as 104.Cm \&%b . 105.It Cm \&%c 106the date and time, using the locale's date and time format. 107.It Cm \&%C 108the century number [0,99]; 109leading zeros are permitted but not required. This conversion 110should be used in conjunction with the \&%y conversion. 111.It Cm \&%d 112the day of month [1,31]; 113leading zeros are permitted but not required. 114.It Cm \&%D 115the date as %m/%d/%y. 116.It Cm \&%e 117the same as 118.Cm \&%d . 119.It Cm \&%h 120the same as 121.Cm \&%b . 122.It Cm \&%H 123the hour (24-hour clock) [0,23]; 124leading zeros are permitted but not required. 125.It Cm \&%I 126the hour (12-hour clock) [1,12]; 127leading zeros are permitted but not required. 128.It Cm \&%j 129the day number of the year [1,366]; 130leading zeros are permitted but not required. 131.It Cm \&%k 132the same as 133.Cm \&%H . 134.It Cm \&%l 135the same as 136.Cm \&%I . 137.It Cm \&%m 138the month number [1,12]; 139leading zeros are permitted but not required. 140.It Cm \&%M 141the minute [0,59]; 142leading zeros are permitted but not required. 143.It Cm \&%n 144any white-space, including none. 145.It Cm \&%p 146the locale's equivalent of a.m. or p.m.. 147.It Cm \&%r 148the time (12-hour clock) with %p, using the locale's time format. 149.It Cm \&%R 150the time as %H:%M. 151.It Cm \&%S 152the seconds [0,61]; 153leading zeros are permitted but not required. 154.It Cm \&%t 155any white-space, including none. 156.It Cm \&%T 157the time as %H:%M:%S. 158.It Cm \&%U 159the week number of the year (Sunday as the first day of the week) 160as a decimal number [0,53]; 161leading zeros are permitted but not required. 162All days in a year preceding the first Sunday are considered to be in week 0. 163.It Cm \&%w 164the weekday as a decimal number [0,6], with 0 representing Sunday; 165leading zeros are permitted but not required. 166.It Cm \&%W 167the week number of the year (Monday as the first day of the week) 168as a decimal number [0,53]; 169leading zeros are permitted but not required. 170All days in a year preceding the first Monday are considered to be in week 0. 171.It Cm \&%x 172the date, using the locale's date format. 173.It Cm \&%X 174the time, using the locale's time format. 175.It Cm \&%y 176the year within the 20th century [69,99] or the 21st century [0,68]; 177leading zeros are permitted but not required. If specified in conjunction 178with \&%C, specifies the year [0,99] within that century. 179.It Cm \&%Y 180the year, including the century (i.e., 1996). 181.It Cm \&%% 182A `%' is written. No argument is converted. 183.El 184.Ss Modified conversion specifications 185For compatibility, certain conversion specifications can be modified 186by the 187.Cm E 188and 189.Cm O 190modifier characters to indicate that an alternative format or specification 191should be used rather than the one normally used by the unmodified 192conversion specification. As there are currently neither alternative formats 193nor specifications supported by the system, the behavior will be as if the 194unmodified conversion specification were used. 195.Sh RETURN VALUES 196If successful, the 197.Fn strptime 198function returns a pointer to the character following the last character 199parsed. Otherwise, a null pointer is returned. 200.Sh SEE ALSO 201.Xr ctime 3 , 202.Xr isspace 3 , 203.Xr localtime 3 , 204.Xr strftime 3 205.Sh STANDARDS 206The 207.Fn strptime 208function conforms to 209.St -xpg4 . 210