Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
strptime(3C)		 Standard C Library Functions		  strptime(3C)

NAME
       strptime	- date and time	conversion

SYNOPSIS
       #include	<time.h>

       char  *strptime(const  char *restrict buf, const	char *restrict format,
       struct tm *restrict tm);

   Non-zeroing Behavior
       cc [flag... ] file... -D_STRPTIME_DONTZERO [library...]
       #include	<time.h>

       char *strptime(const char *restrict buf,	const char  *restrict  format,
       struct tm *restrict tm);

DESCRIPTION
       The strptime() function converts	the character string pointed to	by buf
       to values which are stored in the tm structure pointed to by tm,	 using
       the format specified by format.

       The  format  argument is	composed of zero or more conversion specifica-
       tions. Each conversion specification is composed	 of  a	"%"  (percent)
       character  followed  by	one or two conversion characters which specify
       the replacement required. One or	more white space characters (as	speci-
       fied  by	isspace(3C)) may precede or follow a conversion	specification.
       There must be white-space or other non-alphanumeric characters  between
       any two conversion specifications.

       A  non-zeroing version of strptime(), described below under Non-zeroing
       Behavior, is provided if	_STRPTIME_DONTZERO is defined.

   Conversion Specifications
       The following conversion	specifications are supported:

       %%	Same as	%.

       %a	Day of week, using the locale's	 weekday  names;   either  the
		abbreviated or full name may be	specified.

       %A	Same as	%a.

       %b	Month, using the locale's month	names;	either the abbreviated
		or full	name may be specified.

       %B	Same as	%b.

       %c	Locale's appropriate date and time representation.

       %C	Century	number (the year divided by 100	and  truncated	to  an
		integer	 as  a	decimal	number [1,99]);	single digits are pre-
		ceded by 0. If %C is used without the %y specifier, strptime()
		assumes	the year offset	is zero	in whichever century is	speci-
		fied.	Note the behavior of %C	in the absence of  %y  is  not
		specified  by any of the standards or specifications described
		on the standards(5)  manual  page,  so	portable  applications
		should not depend on it.  This behavior	may change in a	future
		release.

       %d	Day of	month  [1,31];	leading	 zero  is  permitted  but  not
		required.

       %D	Date as	%m/%d/%y.

       %e	Same as	%d.

       %F	Equivalent  to	%Y-%m-%d (the ISO 8601:2000 standard date for-
		mat).

       %h	Same as	%b.

       %H	Hour (24-hour clock) [0,23];  leading zero  is	permitted  but
		not required.

       %I	Hour  (12-hour	clock)	[1,12];	 leading zero is permitted but
		not required.

       %j	Day number of the year [1,366];	 leading zeros	are  permitted
		but not	required.

       %m	Month  number  [1,12];	leading	 zero  is  permitted  but  not
		required.

       %M	Minute [0-59]; leading zero is permitted but not required.

       %n	Any white space.

       %p	Locale's equivalent of either a.m. or p.m.

       %r	Appropriate time representation	in the	12-hour	 clock	format
		with %p.

       %R	Time as	%H:%M.

   SUSv3
       %S	Seconds	 [0,60];  leading  zero	is permitted but not required.
		The range of values  is	[00,60]	rather than [00,59]  to	 allow
		for the	occasional leap	second.

   Default and other standards
       %S	Seconds	 [0,61];  leading  zero	is permitted but not required.
		The range of values  is	[00,61]	rather than [00,59]  to	 allow
		for the	occasional leap	second and even	more occasional	double
		leap second.

       %t	Any white space.

       %T	Time as	%H:%M:%S.

       %U	Week number of the year	as a decimal number [0,53], with  Sun-
		day  as	 the  first day	of the week; leading zero is permitted
		but not	required.

       %w	Weekday	as a decimal number [0,6], with	0 representing Sunday.

       %W	Week  number of	the year as a decimal number [0,53], with Mon-
		day as the first day of	the week; leading  zero	 is  permitted
		but not	required.

       %x	Locale's appropriate date representation.

       %X	Locale's appropriate time representation.

       %y	Year  within  century.	When a century is not otherwise	speci-
		fied, values in	the range 69-99	refer to years in the  twenti-
		eth  century  (1969  to	 1999  inclusive); values in the range
		00-68 refer to years in	the twenty-first century (2000 to 2068
		inclusive).

       %Y	Year, including	the century (for example, 1993).

       %z	Replaced  by  offset from UTC in ISO 8601:2000 standard	format
		Replaced by offset from	UTC in ISO 8601:2000  standard	format
		determinable.  For  example,  "-0430" means 4 hours 30 minutes
		behind UTC (west of Greenwich).	 If tm_isdst is	0,  the	 stan-
		dard  time  offset is used. If tm_isdst	is greater than	0, the
		daylight savings time offset if	used. If tm_isdst is negative,
		no characters are returned.

       %Z	Time zone name or no characters	if no time zone	exists.

   Modified Conversion Specifications
       Some  conversion	specifications can be modified by the E	and O modifier
       characters to indicate that an alternate	format or specification	should
       be  used	rather than the	one normally used by the unmodified specifica-
       tion. If	the alternate format or	specification does not	exist  in  the
       current	locale,	 the  behavior will be as if the unmodified conversion
       specification were used.

       %Ec	Locale's alternate appropriate date and	time representation.

       %EC	Name of	the base year (era) in the locale's  alternate	repre-
		sentation.

       %Ex	Locale's alternate date	representation.

       %EX	Locale's alternate time	representation.

       %Ey	Offset	from  %EC (year	only) in the locale's alternate	repre-
		sentation.

       %EY	Full alternate year representation.

       %Od	Day of the month using the locale's alternate numeric symbols.

       %Oe	Same as	%Od.

       %OH	Hour (24-hour clock) using the locale's	alternate numeric sym-
		bols.

       %OI	Hour (12-hour clock) using the locale's	alternate numeric sym-
		bols.

       %Om	Month using the	locale's alternate numeric symbols.

       %OM	Minutes	using the locale's alternate numeric symbols.

       %OS	Seconds	using the locale's alternate numeric symbols.

       %OU	Week  number of	the year (Sunday as the	first day of the week)
		using the locale's alternate numeric symbols.

       %Ow	Number of the weekday (Sunday=0) using the  locale's alternate
		numeric	symbols.

       %OW	Week  number of	the year (Monday as the	first day of the week)
		using the locale's alternate numeric symbols.

       %Oy	Year (offset from %C) in the locale's  alternate   representa-
		tion and using the locale's alternate numeric symbols.

   General Specifications
       A conversion specification that is an ordinary character	is executed by
       scanning	the next character from	the buffer. If the  character  scanned
       from  the buffer	differs	from the one comprising	the specification, the
       specification fails, and	the differing and subsequent characters	remain
       unscanned.

       A  series  of specifications composed of	%n, %t,	white-space characters
       or any combination is executed by scanning up to	 the  first  character
       that  is	 not  white  space (which remains unscanned), or until no more
       characters can be scanned.  White space is defined by isspace(3C).

       Any other conversion specification is executed by  scanning  characters
       until  a	character matching the next specification is scanned, or until
       no more characters can be scanned. These	 characters,  except  the  one
       matching	the next specification,	are then compared to the locale	values
       associated with the conversion specifier.  If a match is	found,	values
       for the appropriate  tm structure members are set to values correspond-
       ing to the locale information. If no match is found,  strptime()	 fails
       and no more characters are scanned.

       The  month  names, weekday names, era names, and	alternate numeric sym-
       bols can	consist	of any combination of upper and	 lower	case  letters.
       The  user can request that the input date or time specification be in a
       specific	language by setting the	LC_TIME	category using	setlocale(3C).

   Non-zeroing Behavior
       In  addition  to	the behavior described above by	various	standards, the
       Solaris implementation of strptime() provides the following extensions.
       These  may  change  at  any  time in the	future.	 Portable applications
       should not depend on these extended features:

	 o  If _STRPTIME_DONTZERO is not defined, the tm struct	is  zeroed  on
	    entry  and	strptime() updates the fields of the tm	struct associ-
	    ated with the specifiers in	the format string.

	 o  If _STRPTIME_DONTZERO is defined, strptime() does not zero the  tm
	    struct  on	entry.	 Additionally, for some	specifiers, strptime()
	    will use some values in the	input tm  struct  to  recalculate  the
	    date and re-assign the appropriate members of the tm struct.

       The  following describes	extended features regardless of	whether	_STRP-
       TIME_DONTZERO is	defined	or not defined:

	 o  If %j is specified,	tm_yday	is set;	 if  year  is  given,  and  if
	    month  and	day  are  not  given,  strptime()  calculates and sets
	    tm_mon, tm_mday, and tm_year.

	 o  If %U or %W	is specified and if weekday and	 year  are  given  and
	    month  and	day  of	month are not given, strptime()	calculates and
	    sets tm_mon, tm_mday, tm_wday, and tm_year.

       The following describes extended	features  when	_STRPTIME_DONTZERO  is
       not defined:

	 o  If %C is specified and %y is not specified,	strptime()assumes 0 as
	    the	year offset, then calculates the year, and assigns tm_year.

       The following describes extended	features  when	_STRPTIME_DONTZERO  is
       defined:

	 o  If %C is specified and %y is not specified,	strptime() assumes the
	    year offset	of the year value of the tm_year member	of  the	 input
	    tm struct, then calculates the year	and assigns tm_year.

	 o  If	%j  is specified and neither %y, %Y, nor %C are	specified, and
	    neither month nor day of month are specified,  strptime()  assumes
	    the	 year  value  given  by	 the value of the tm_year field	of the
	    input tm struct.  Then, in addition	to setting tm_yday, strptime()
	    uses  day-of-year  and year	values to calculate the	month and day-
	    of-month, and assigns tm_month and tm_mday.

	 o  If %U or %W	is specified, and  if  weekday	and/or	year  are  not
	    given,  and	 month and day of month	are not	given, strptime() will
	    assume the weekday value and/or the	year value as the value	of the
	    tm_wday  field and/or tm_year field	of the input tm	struct.	 Then,
	    strptime() will calculate the month	and  day-of-month  and	assign
	    tm_month, tm_mday, and/or tm_year.

	 o  If	%p  is specified and if	hour is	not specified, strptime() will
	    reference, and if needed, update the tm_hour member. If the	 am_pm
	    input is p.m. and the input	tm_hour	value is between 0 - 11, strp-
	    time() will	add 12 hours and update	tm_hour.  If the  am_pm	 input
	    is	a.m.  and  input  tm_hour value	is between 12 -	23, strptime()
	    will subtract 12 hours and update tm_hour.

RETURN VALUES
       Upon successful completion, strptime() returns a	pointer	to the charac-
       ter  following  the last	character parsed. Otherwise, a null pointer is
       returned.

USAGE
       Several "same as" formats, and the special  processing  of  white-space
       characters  are	provided in order to ease the use of identical	format
       strings for strftime(3C)	and strptime().

       The strptime() function tries to	calculate tm_year, tm_mon, and tm_mday
       when  given  incomplete	input.	 This  allows the struct tm created by
       strptime() to be	passed to mktime(3C) to	produce	 a  time_t  value  for
       dates  and  times  that	are representable by a time_t.	As an example,
       since  mktime()	ignores	 tm_yday,  strptime()  calculates  tm_mon  and
       tm_mday as well as filling in tm_yday when %j is	specified without oth-
       erwise specifying a month and day within	month.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       ctime(3C), getdate(3C), isspace(3C), mktime(3C),	 setlocale(3C),	 strf-
       time(3C), attributes(5),	environ(5), standards(5)

SunOS 5.10			  1 Nov	2003			  strptime(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | USAGE | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=strptime&sektion=3c&manpath=SunOS+5.10>

home | help