git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\"
	2	.\" Copyright (c) 1997 Joerg Wunsch
	3	.\"
	4	.\" All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\"
	15	.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
	16	.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	17	.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
	18	.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
	19	.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	20	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	21	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	22	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	23	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
	24	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	25	.\"
	26	.\" $FreeBSD$
	27	.\" "
	28	.Dd October 2, 2014
	29	.Dt STRPTIME 3
	30	.Os
	31	.Sh NAME
	32	.Nm strptime ,
	33	.Nm strptime_l
	34	.Nd parse date and time string
	35	.Sh LIBRARY
	36	.Lb libc
	37	.Sh SYNOPSIS
	38	.In time.h
	39	.Ft char *
	40	.Fo strptime
	41	.Fa "const char * restrict buf"
	42	.Fa "const char * restrict format"
	43	.Fa "struct tm * restrict timeptr"
	44	.Fc
	45	.In time.h
	46	.In xlocale.h
	47	.Ft char *
	48	.Fn strptime_l "const char * restrict buf" "const char * restrict format" "struct tm * restrict timeptr" "locale_t loc"
	49	.Sh DESCRIPTION
	50	The
	51	.Fn strptime
	52	function parses the string in the buffer
	53	.Fa buf
	54	according to the string pointed to by
	55	.Fa format ,
	56	and fills in the elements of the structure pointed to by
	57	.Fa timeptr .
	58	The resulting values will be relative to the local time zone.
	59	Thus, it can be considered the reverse operation of
	60	.Xr strftime 3 .
	61	The
	62	.Fn strptime_l
	63	function does the same as
	64	.Fn strptime ,
	65	but takes an explicit locale rather than using the current locale.
	66	.Pp
	67	The
	68	.Fa format
	69	string consists of zero or more conversion specifications and
	70	ordinary characters.
	71	All ordinary characters are matched exactly with the buffer, where
	72	white space in the format string will match any amount of white space
	73	in the buffer.
	74	All conversion specifications are identical to those described in
	75	.Xr strftime 3 .
	76	.Pp
	77	Two-digit year values, including formats
	78	.Fa %y
	79	and
	80	.Fa \&%D ,
	81	are now interpreted as beginning at 1969 per POSIX requirements.
	82	Years 69-00 are interpreted in the 20th century (1969-2000), years
	83	01-68 in the 21st century (2001-2068).
	84	The
	85	.Fa \&%U
	86	and
	87	.Fa %W
	88	format specifiers accept any value within the range 00 to 53.
	89	.Pp
	90	If the
	91	.Fa format
	92	string does not contain enough conversion specifications to completely
	93	specify the resulting
	94	.Vt struct tm ,
	95	the unspecified members of
	96	.Va timeptr
	97	are left untouched.
	98	For example, if
	99	.Fa format
	100	is
	101	.Dq Li "%H:%M:%S" ,
	102	only
	103	.Va tm_hour ,
	104	.Va tm_sec
	105	and
	106	.Va tm_min
	107	will be modified.
	108	If time relative to today is desired, initialize the
	109	.Fa timeptr
	110	structure with today's date before passing it to
	111	.Fn strptime .
	112	.Sh RETURN VALUES
	113	Upon successful completion,
	114	.Fn strptime
	115	returns the pointer to the first character in
	116	.Fa buf
	117	that has not been required to satisfy the specified conversions in
	118	.Fa format .
	119	It returns
	120	.Dv NULL
	121	if one of the conversions failed.
	122	.Fn strptime_l
	123	returns the same values as
	124	.Fn strptime .
	125	.Sh LEGACY DESCRIPTION
	126	In legacy mode, the
	127	.Fa %Y
	128	format specifier expects exactly 4 digits (leaving any trailing digits for the
	129	next specifier).
	130	.Sh SEE ALSO
	131	.Xr date 1 ,
	132	.Xr scanf 3 ,
	133	.Xr strftime 3 ,
	134	.Xr xlocale 3
	135	.Sh HISTORY
	136	The
	137	.Fn strptime
	138	function appeared in
	139	.Fx 3.0 .
	140	.Sh AUTHORS
	141	The
	142	.Fn strptime
	143	function has been contributed by Powerdog Industries.
	144	.Pp
	145	This man page was written by
	146	.An J\(:org Wunsch .
	147	.Sh BUGS
	148	Both the
	149	.Fa %e
	150	and
	151	.Fa %l
	152	format specifiers may incorrectly scan one too many digits
	153	if the intended values comprise only a single digit
	154	and that digit is followed immediately by another digit.
	155	Both specifiers accept zero-padded values,
	156	even though they are both defined as taking unpadded values.
	157	.Pp
	158	The
	159	.Fa %p
	160	format specifier has no effect unless it is parsed
	161	.Em after
	162	hour-related specifiers.
	163	Specifying
	164	.Fa %l
	165	without
	166	.Fa %p
	167	will produce undefined results.
	168	Note that 12AM
	169	(ante meridiem)
	170	is taken as midnight
	171	and 12PM
	172	(post meridiem)
	173	is taken as noon.
	174	.Pp
	175	The
	176	.Fa %Z
	177	format specifier only accepts time zone abbreviations of the local time zone,
	178	or the value "GMT".
	179	This limitation is because of ambiguity due to of the over loading of time
	180	zone abbreviations.
	181	One such example is
	182	.Fa EST
	183	which is both Eastern Standard Time and Eastern Australia Summer Time.
	184	.Pp
	185	The
	186	.Fn strptime
	187	function does not correctly handle multibyte characters in the
	188	.Fa format
	189	argument.