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

FreeBSD Manual Pages

  
 
  

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

NAME
       strftime, cftime, ascftime - convert date and time to string

SYNOPSIS
       #include	<time.h>

       size_t  strftime(char *restrict s, size_t maxsize, const	char *restrict
       format, const struct tm *restrict timeptr);

       int cftime(char *s, char	*format, const time_t *clock);

       int ascftime(char *s, const char	*format, const struct tm *timeptr);

DESCRIPTION
       The strftime(), ascftime(), and cftime()	functions place	bytes into the
       array pointed to	by s as	controlled by the string pointed to by format.
       The format string consists of zero or  more  conversion	specifications
       and  ordinary characters.  A conversion specification consists of a '%'
       (percent) character and one or two  terminating	conversion  characters
       that  determine	the conversion specification's behavior.  All ordinary
       characters (including the terminating null byte)	are  copied  unchanged
       into  the array pointed to by s.	If copying takes place between objects
       that overlap, the behavior is undefined.	For strftime (), no more  than
       maxsize bytes are placed	into the array.

       If  format  is (char *)0, then the locale's default format is used. For
       strftime() the default format is	the same as %c;	for cftime() and ascf-
       time()  the  default  format is the same	as %C. cftime()	and ascftime()
       first try to use	the value of the environment variable CFTIME,  and  if
       that is undefined or empty, the default format is used.

       Each  conversion	specification is replaced by appropriate characters as
       described in the	following list.	The appropriate	characters are	deter-
       mined by	the LC_TIME category of	the program's locale and by the	values
       contained in the	structure pointed to by	 timeptr  for  strftime()  and
       ascftime(), and by the time represented by clock	for cftime().

       %%	Same as	%.

       %a	Locale's abbreviated weekday name.

       %A	Locale's full weekday name.

       %b	Locale's abbreviated month name.

       %B	Locale's full month name.

       %c	Locale's appropriate date and time representation.

   Default
       %C	Locale's  date and time	representation as produced by date(1).

   Standard conforming
       %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; see	standards(5).

       %d	Day of month [1,31]; single digits are preceded	by 0.

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

       %e	Day of month [1,31]; single digits are preceded	by a space.

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

       %g	Week-based year	within century [00,99].

       %G	Week-based year, including the century [0000,9999].

       %h	Locale's abbreviated month name.

       %H	Hour  (24-hour clock) [0,23]; single digits are	preceded by 0.

       %I	Hour (12-hour clock) [1,12]; single digits are preceded	by  0.

       %j	Day number of year [1,366]; single digits are preceded by 0.

       %k	Hour  (24-hour	clock) [0,23]; single digits are preceded by a
		blank.

       %l	Hour (12-hour clock) [1,12]; single digits are preceded	 by  a
		blank.

       %m	Month number [1,12]; single digits are preceded	by 0.

       %M	Minute [00,59];	leading	0 is permitted but not required.

       %n	Insert a NEWLINE.

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

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

       %R	Time as	%H:%M.

       %S	Seconds	[00,60]; the range of values is	 [00,60]  rather  than
		[00,59]	 to allow for the occasional leap second and even more
		occasional double leap second.

       %t	Insert a TAB.

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

       %u	Weekday	as a decimal number [1,7], with	1 representing Monday.
		See NOTES below.

       %U	Week  number  of year as a decimal number [00,53], with	Sunday
		as the first day of week 1.

       %V	The ISO	8601 week number as a decimal number [01,53].  In  the
		ISO 8601 week-based system, weeks begin	on a Monday and	week 1
		of the year is the week	that includes both January 4th and the
		first Thursday of the year.  If	the first Monday of January is
		the 2nd, 3rd, or 4th, the preceding days are part of the  last
		week of	the preceding year.  See NOTES below.

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

       %W	Week number of year as a decimal number	[00,53],  with	Monday
		as the first day of week 1.

       %x	Locale's appropriate date representation.

       %X	Locale's appropriate time representation.

       %y	Year within century [00,99].

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

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

       %Z	Time  zone  name  or abbreviation, or no bytes if no time zone
		information exists.

       If a conversion specification does not correspond to any	of  the	 above
       or  to  any of the modified conversion specifications listed below, the
       behavior	is undefined and 0 is returned.

       The difference between %U and %W	(and also between modified  conversion
       specifications  %OU  and	%OW) lies in which day is counted as the first
       of the week. Week number	1 is the first week in January starting	with a
       Sunday  for  %U	or  a Monday for %W. Week number 0 contains those days
       before the first	Sunday or Monday in January for	 %U  and  %W,  respec-
       tively.

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

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

       %EC	Name of	the base year (period) in the locale's alternate  rep-
		resentation.

       %Eg	Offset	from %EC of the	week-based year	in the locale's	alter-
		native representation.

       %EG	Full alternative representation	of the week-based year.

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

       %Og	Week-based year	(offset	from %C)  in  the  locale's  alternate
		representation	and  using the locale's	alternate numeric sym-
		bols.

       %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	Weekday	as a number in 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	representation
		and using the locale's alternate numeric symbols.

   Selecting the Output	Language
       By  default,  the output	of strftime(), cftime(), and ascftime()	appear
       in U.S. English.	The user can request that the  output  of  strftime(),
       cftime(),  or  ascftime()  be  in  a  specific  language	by setting the
       LC_TIME category	using setlocale().

   Time	Zone
       Local time zone information is used as though tzset(3C) were called.

RETURN VALUES
       The strftime(), cftime(), and ascftime()	functions return the number of
       characters  placed  into	 the  array pointed to by s, not including the
       terminating null	character. If the total	number of resulting characters
       including  the  terminating  null character is more than	maxsize, strf-
       time() returns 0	and the	contents of the	array are indeterminate.

EXAMPLES
       Example 1: An example of	the strftime() function.

       The following example illustrates the use of strftime() for  the	 POSIX
       locale.	It  shows what the string in str would look like if the	struc-
       ture pointed to by tmptr	contains the values corresponding to Thursday,
       August 28, 1986 at 12:44:36.

       strftime	(str, strsize, "%A %b %d %j", tmptr)

       This results in str containing "Thursday	Aug 28 240".

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |MT-Safe			   |
       |CSI			     |Enabled			   |
       |Interface Stability	     |strftime() is Standard.	   |
       +-----------------------------+-----------------------------+

SEE ALSO
       date(1),	ctime(3C), mktime(3C), setlocale(3C), strptime(3C), tzset(3C),
       TIMEZONE(4), zoneinfo(4), attributes(5),	environ(5), standards(5)

NOTES
       The conversion specification for	 %V  was  changed  in  the  Solaris  7
       release.	 This  change  was based on the	public review draft of the ISO
       C9x standard at that time. Previously, the specification	stated that if
       the week	containing 1 January had fewer than four days in the new year,
       it became week 53 of the	previous year. The ISO C9x standard  committee
       subsequently recognized that that specification had been	incorrect.

       The  conversion specifications for %g, %G, %Eg, %EG, and	%Og were added
       in the Solaris 7	release.  This change was based	on the	public	review
       draft  of  the  ISO C9x standard	at that	time. These specifications are
       evolving.  If the ISO C9x standard is finalized with a  different  con-
       clusion,	 these	specifications	will  change to	conform	to the ISO C9x
       standard	decision.

       The conversion specification for	 %u  was  changed  in  the  Solaris  8
       release.	This change was	based on the XPG4 specification.

       If  using the %Z	specifier and zoneinfo timezones and if	the input date
       is outside the range 20:45:52 UTC, December  13,	1901 to	03:14:07  UTC,
       January 19, 2038, the timezone name may not be correct.

SunOS 5.10			  1 Nov	2003			  strftime(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ATTRIBUTES | SEE ALSO | NOTES

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

home | help