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  *s,  size_t  maxsize,  const char	*format, const
       struct tm *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 inte-
	     ger as a decimal number [1,99]); single digits are	preceded 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.

       %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,61];	the  range  of	values	is [00,61] rather than
	     [00,59] to	allow for the occasional leap second and even more oc-
	     casional 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    Time  zone	 name or abbreviation, or no bytes if no time zone in-
	     formation 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	repre-
	     sentation.

       %Eg   Offset from %EC of	the week-based year in the  locale's  alterna-
	     tive 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 representa-
	     tion.

       %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	repre-
	     sentation and using the locale's alternate	numeric	symbols.

       %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) us-
	     ing 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) us-
	     ing 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			   |
       +-----------------------------+-----------------------------+

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.9			  5 Feb	2001			  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.9>

home | help