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 ab-
		breviated 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  re-
		quired.

       %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 re-
		quired.

       %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  in-
	    put	 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