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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
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
       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 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
	     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    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	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)
	     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			   |
       +-----------------------------+-----------------------------+

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.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:
<http://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3c&manpath=SunOS+5.9>

home | help