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 as-
       cftime(), 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 be-
       fore the	first Sunday or	Monday in January for %U and %W, respectively.

   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 re-
       lease. 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 re-
       lease. 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