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

FreeBSD Manual Pages

  
 
  

home | help
strftime(3C)							  strftime(3C)

NAME
       strftime() - convert date and time to string

SYNOPSIS
DESCRIPTION
       The  function converts the contents of a	structure (see ctime(3C)) to a
       formatted date and time string.

       places characters into the array	pointed	to by s	as controlled  by  the
       string  pointed	to  by	format.	 The format string consists of zero or
       more directives and ordinary characters.	 A  directive  consists	 of  a
       character,  an  optional	field width and	precision specification, and a
       terminating character that determines the  directive's  behavior.   All
       ordinary	 characters  (including	 the  terminating  null	 character are
       copied unchanged	into the array.	 No more than maxsize  characters  are
       placed  into  the array.	 Each directive	is replaced by the appropriate
       characters as described in the following	list.  The appropriate charac-
       ters are	determined by the program's locale, by the values contained in
       the structure pointed to	by timeptr, and	by  the	 environment  variable
       (see External Influences	below).

   Directives
       The  following  directives,  shown without the optional field width and
       precision specification,	are replaced by	the indicated characters:

	      Locale's abbreviated weekday name.
	      Locale's full weekday name.
	      Locale's abbreviated month name.
	      Locale's full month name.
	      Locale's appropriate date	and time representation.
	      The century number (the year divided by 100 and truncated	to  an
	      integer)
			as a decimal number [00-99].
	      Day of the month as a decimal number [01,31].
	      Equivalent to the	directive string
	      Day  of  the month as a decimal number [1,31]; a single digit is
	      preceded by a space.
	      Equivalent to
	      Hour (24-hour clock) as a	decimal	number [00,23].
	      Hour (12-hour clock) as a	decimal	number [01,12].
	      Day of the year as a decimal number [001,366].
	      Month as a decimal number	[01,12].
	      Minute as	a decimal number [00,59].
	      The New-line character.
	      Locale's equivalent of either
			AM or PM.
	      The time in AM and PM notation; in  the  POSIX  locale  this  is
	      equivalent to
	      The time in 24 hour notation
	      Second as	a decimal number [00,61].
	      The Tab character.
	      The time in hours, minutes, and seconds
	      The weekday as a decimal number [1(Monday),7].
	      Week number of the year
			(Sunday	 as  the  first	 day of	the week) as a decimal
			number [00,53].	 All days in a new year	preceding  the
			first Sunday are considered to be in week 0.
	      The  week	 number	 of  the  year (Monday as the first day	of the
	      week) as a
			decimal	number [01,53].	 If the	week containing	 Janu-
			ary 1st	has four or more days in the new year, then it
			is considered week 1; otherwise, it is the  last  week
			of the previous	year, and the next week	is week	1.
	      Weekday as a decimal number [0(Sunday),6].
	      Week number of the year
			(Monday	 as  the  first	 day of	the week) as a decimal
			number [00,53].	 All days in a new year	preceding  the
			first Monday are considered to be in week 0.
	      Locale's appropriate date	representation.
	      Locale's appropriate time	representation.
	      Year without century as a	decimal	number [00,99].
	      Year with	century	as a decimal number.
	      Time zone	name (or by no characters if no	time zone exists).
	      The percent (%) character.

       The  following  directives are provided for backward compatibility with
       the directives supported	by date(1) and the ctime(3C) functions.	 These
       directives  may be removed in a future release.	It is recommended that
       the directives above be used in preference to those below.

	      Locale's combined	Emperor/Era name and year (use
			instead).

	      Locale's full month name (use
			instead).

	      Locale's Emperor/Era name	(use
			instead).

	      Locale's Emperor/Era year	(use
			instead).

	      Time zone	name (or by no characters if no	time zone exists) (use
			instead).

       If a directive is not one of the	above, the behavior is undefined.

   Modified Conversion Specifiers
       Some conversion specifiers can be modified by the E or O	modifier char-
       acters  to  indicate that an alternative	format or specification	should
       be used rather than the one normally used by the	unmodified  conversion
       specifier.   If	the alternative	format or specification	does not exist
       for the current locale, the behavior will be as if the unmodified  con-
       version specification were used.	 Alternative numeric symbols refers to
       those symbols defined by	the (see langinfo(5)) in the locale.

	      The locales alternative appropriate date	and  time  representa-
	      tion.

	      The  name	 of the	base year (period/Emperor/Era) in the locale's
	      alternative
			representation.

	      The locale's alternative date representation

	      The locale's alternative time representation.

	      The offset from
			(year only) in the  locale's  alternative  representa-
			tion.

	      The full alternative year	representation.

	      The  day	of  the	 month,	using the locale's alternative numeric
	      symbols,
			filled as needed with leading zeros if	there  is  any
			alternative  symbol  for  zero,	otherwise with leading
			spaces.

	      the day of the month, using  the	locale's  alternative  numeric
	      symbols, filled as needed	with leading spaces.

	      The  hour	(24-hour clock)	using the locale's alternative numeric
	      symbols.

	      The hour (12-hour	clock) using the locale's alternative  numeric
	      symbols.

	      The month	using the locale's alternative numeric symbols.

	      The minutes using	the locale's alternative numeric symbols.

	      The seconds using	the locale's alternative numeric symbols.

	      The  weekday as a	number in the locale's alternative representa-
	      tion (Monday=1).

	      The week number of the year
			(Sunday	as the first day of  the  week,	 rules	corre-
			sponding  to  using  the  locale's alternative numeric
			symbols.

	      The week number of the year
			(Monday	as the first day of  the  week,	 rules	corre-
			sponding  to  using  that locale's alternative numeric
			symbols.

	      The number of the	weekday	(Sunday=0) using the locale's alterna-
	      tive numeric symbols.

	      The  week	 number	 of  the  year (Monday as the first day	of the
	      week) using the locale's alternative numeric symbols.

	      The year (offset from
			in the locale's	alternative representation  and	 using
			the locale's alternative symbols.

   Field Width and Precision
       An  optional  field  width  and precision specification can immediately
       follow the initial of a directive in the	following order:

       The decimal digit string
		      w	specifies a minimum field width	in which the result of
		      the  conversion  is  right-  or  left-justified.	 It is
		      right-justified (with space padding) by default.	If the
		      optional	flag  is  specified, it	is left-justified with
		      space padding on the right.  If  the  optional  flag  is
		      specified,  it  is right-justified and padded with zeros
		      on the left.

       The decimal digit string
		      p	specifies the minimum number of	digits to  appear  for
		      the  and	directives, and	the maximum number of bytes to
		      be used from the and directives.	In the first case,  if
		      a	 directive supplies fewer digits than specified	by the
		      precision, it will be expanded with leading  zeros.   In
		      the second case, if a directive supplies more bytes than
		      specified	by the precision, excess bytes will  truncated
		      on the right.

       If  no  field width or precision	is specified for a or directive, a de-
       fault of	is used	for all	but for	which is used.

EXTERNAL INFLUENCES
   Locale
       The category determines the characters to be substituted	for those  di-
       rectives	described above	as being from the locale.

       The  category  determines the interpretation of the bytes within	format
       as single and/or	multi-byte characters.

       The category determines the characters used to form numbers  for	 those
       directives that produce numbers in the output.  If (see langinfo(5)) is
       defined for the locale, the characters so specified are used  in	 place
       of  the	default	 ASCII characters.  If both and	is defined for the lo-
       cale, will take precedence over

   Environment Variables
       determines the time zone	name substituted for the and directives.   The
       time zone name is determined by calling the function which sets the ex-
       ternal variable (see ctime(3C)).

   International Code Set Support
       Single- and multi-byte character	code sets are supported.

RETURN VALUE
       If the total number of resulting	bytes including	the  terminating  null
       byte  is	not more than maxsize, returns the number of bytes placed into
       the array pointed to by s, not including	 the  terminating  null	 byte.
       Otherwise,  zero	is returned and	the contents of	the array are indeter-
       minate.

EXAMPLES
       If the timeptr argument contains	the following values:

       the following combinations of the category and format  strings  produce
       the indicated output:

	      LC_TIME	     Format String	 Output
	      -----------------------------------------------------
	      en_US.roman8   %x			 Mon, Jul 4, 1988
	      de_De.roman8   %x			 Mo., 4. Juli 1988
	      en_US.roman8   %X			 03:09:04 PM
	      fr_FR.roman8   %X			 15h09 04
	      any*	     %H:%M:%S		 15:09:04
	      any*	     %.1H:%.1M:%.1S	 15:9:4
	      any*	     %2.1H:%-3M:%03.1S	 15:9  :004

       *  The  directives used in these	examples are not affected by the cate-
       gory of the locale.

WARNINGS
       If the arguments	s and format are defined such that they	 overlap,  the
       behavior	is undefined.

       The  function  is  called  upon every invocation	of (whether or not the
       time zone name is copied	to the output array).

       The range of values for ([0,61])	extends	to 61 to allow for  the	 occa-
       sional  one  or two leap	seconds.  However, the system does not accumu-
       late leap seconds and the structure generated by	the functions and (see
       ctime(3C)) never	reflects any leap seconds.

       Results	are  undefined if values contained in the structure pointed to
       by timeptr exceed the ranges defined for	the structure (see  ctime(3C))
       or  are	not consistent (such as	if the element is set to 0, indicating
       the first day of	January, while the element is set to 11, indicating  a
       day in December).

AUTHOR
       was developed by	HP.

SEE ALSO
       date(1),	  ctime(3C),  getdate(3C),  setlocale(3C),  environ(5),	 lang-
       info(5),	thread_safety(5).

STANDARDS CONFORMANCE
								  strftime(3C)

NAME | SYNOPSIS | DESCRIPTION | EXTERNAL INFLUENCES | RETURN VALUE | EXAMPLES | WARNINGS | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3c&manpath=HP-UX+11.22>

home | help