strftime(3)						     Library Functions Manual						       strftime(3)

NAME

       strftime, wcsftime - Converts a date and time to a string or wide-character string

LIBRARY

       Standard C Library (libc)

SYNOPSIS

       #include <time.h>

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

       #include <wchar.h>

       size_t wcsftime(
	       wchar_t *wcs,
	       size_t maxsize,
	       const wchar_t *format,
	       const struct tm *timeptr);

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       strftime(), wcsftime(): XSH5.0

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Points  to the array containing the output date and time string.  Specifies the maximum number of bytes or wide characters to be written to
       the array pointed to by the s or wcs parameter.	Points to a sequence of characters that specify the format of the  date  and  time  to	be
       written	to  the  output string or wide-character string.  See the DESCRIPTION section for more information.  Points to a type tm structure
       that contains broken-down time information.  Points to the wide-character array containing the output date and time string.

DESCRIPTION

       The strftime() function places characters into the array pointed to by the s parameter as controlled by the string pointed to by the format
       parameter.

       Local time zone information is used as though the strftime() function called the tzset() function. Time information used in this subroutine
       is fetched from space containing type tm structure data, which is defined in the time.h include file. The type tm  structure  must  contain
       the time information used by this subroutine to construct the time and date string.

       The  format  string consists of characters that represent zero or more conversion specifications and ordinary characters that represent the
       date and time values and null string terminator.  Each conversion specification starts with a % (percent sign) character followed by one or
       more  characters  that  determine how the conversion specification constructs the formatted string.  Any ordinary characters (including the
       terminating null character) in the format string are copied unchanged into the s array.	When copying between objects that  overlap,  func-
       tion  behavior  is  undefined.  No more than the number of bytes specified by the maxsize parameter are written to the array (including the
       terminating null character).

       The strftime() function replaces the conversion specification with the appropriately formatted date or time value.  Ordinary characters are
       written to the output buffer unchanged.

       Each  conversion specification is replaced by the appropriate characters as described later in this section. The appropriate characters are
       determined by the LC_TIME category of the current locale and by values specified by the type tm structure pointed to by the timeptr parame-
       ter.

       The  wcsftime() function is equivalent to the strftime() function, except that: The wcs parameter points to the initial element of an array
       of wide characters into which the generated output is to be placed.  The maxsize parameter indicates the maximum number of wide	characters
       to  be  placed  in  wcs.   The  format parameter is a wide-character string and the conversion specifications are replaced by corresponding
       sequences of wide characters.

	      In the obsolete version of the wcsftime() function (which conforms to Issue 4 Revision 2 and earlier versions of the XSH	specifica-
	      tion),  the format parameter is defined to be const char* rather than const wchar_t* as currently required by the ISO C standard and
	      XSH Issue 5. See standards(5) for more information about using compile-time options and compilation environments to conform to  dif-
	      ferent levels of industry standards.  The return value indicates the number of wide characters placed in wcs.

       The format parameter has the following syntax. Each conversion specification that is included in the format parameter starts with a percent
       sign (%).  In portable applications, the % character is immediately followed by format-code.

       [ordinary-text]  [%[[-|0]width][.precision]format-code [ordinary-text]]...

       In this syntax:

       Text that is copied to the output parameter with no changes.  [Tru64 UNIX]  A decimal digit string that specifies the minimum field  width.
       If the width of the item equals or exceeds the minimum field width, the minimum is ignored. If the width of the item is less than the mini-
       mum field width, the function justifies and pads the item. The optional - (minus sign) or 0 (zero digit) control the justification and pad-
       ding  as follows: Item is right justified and spaces are added to the beginning of the item to fill the minimum width.  Item is left justi-
       fied and spaces are added to the end of the item to fill the minimum width.  Item is right justified and zeros are added to  the  beginning
       of  the item to fill the minimum width.	[Tru64 UNIX]  A decimal string that specifies the minimum number of digits to appear for the d, H,
       I, j, m, M, o, S, U, w, W, y, and Y conversion formats and the maximum number of characters to used from the a, A, b, B, c, D, E, h, n,	N,
       p, r, t, T, x, X, Z, and % conversion formats.

	      [Tru64  UNIX]  If no field width or precision is specified for the d, H, I, m, M, S, U, W, or y conversion character, a default pre-
	      cision of .2 is used. If no field width or precision is specified for the j conversion character, a default precision of 3 is  used.
	      A  conversion-code character that specifies the date and time conversion to perform. Some conversion-code characters can be preceded
	      by an E or an O modifier. The E modifier indicates that an alternative date and time representation should be used if one is defined
	      by  the  locale in which the application is running. Th O modifier indicates that alternative numeric symbols should be used if they
	      are defined by the locale in which the application is running. If the application specifies a modified conversion-code  for  format-
	      code and the application runs in a locale that does not define the alternative conversion, conversion proceeds as though the conver-
	      sion-code character were unmodified.  The following list describes the modified and unmodified conversion-code characters: The short
	      day  of  the week is output as a string as defined for the current locale (Mon, for example).  The long day of the week is output as
	      defined for the current locale (Monday, for example).  The short month is output as a string as defined for the current locale (Jan,
	      for  example).  The long month is output as a string as defined for the current locale (January, for example).  The date and time is
	      output with the default date and time as defined for the current locale.	The century is output as a decimal number in the range	00
	      to  99.  The day of the month is output as a number between 01 and 31.  The format is fixed to return %m/%d/%y. (For example, 20 Jun
	      1990 will return 06/20/90.)  The day of the month is output as a number between 1 and 31 in a 2-digit field with leading space fill.
	      Specifies  the  locale's	alternative appropriate date and time representation.  Specifies the name of the base year (period) in the
	      locale's alternative representation.  Specifies the locale's alternative date representation.  Specifies	the  locale's  alternative
	      time  representation.   Specifies  the  offset  from %EC (year only) in the locale's alternative representation.	Specifies the full
	      alternative year representation.	The hour of the day is output as a number between 00 and 23.  Same as b.  The hour of the  day	is
	      output  as a number between 01 and 12.  The Julian day of the year is output as a number between 001 and 366.  The month of the year
	      is output as a number between 01 and 12.	The minute is output as a number between 00 and 59.  Only a newline character  is  output.
	      The  locale-dependent  Emperor/Era name is output.  The locale-dependent Emperor/Era year is output.  Specifies the day of the month
	      using the locale's alternative numeric symbols.  Specifies the day of the month using  the  locale's  alternative  numeric  symbols.
	      Specifies  the  hour  (24-hour  clock) using the locale's alternative numeric symbols.  Specifies the hour (12-hour clock) using the
	      locale's alternative numeric symbols.  Specifies the month using the locale's alternative numeric symbols.   Specifies  the  minutes
	      using  the  locale's  alternative numeric symbols.  Specifies the seconds using the locale's alternative numeric symbols.  Specifies
	      the weekday as a number in the locale's alternative representation (Monday=1).  Specifies the week number of the year (Sunday as the
	      first  day  of the week) using the locale's alternative numeric symbols.	Specifies the week number of the year (Monday as the first
	      day of the week, rules corresponding to %V), using the locale's alternative numeric symbols.  Specifies the week day as a number	in
	      the  locale's  alternative representation (Sunday = 0).  Specifies the week number of the year (Monday as the first day of the week)
	      using the locale's alternative numeric symbols.  Specifies the year (offset from %C) by using the locale's alternative numeric  sym-
	      bols.  The AM or PM indicator is output as a string specified for the current locale.  The time in AM/PM notation is output, accord-
	      ing to British/US conventions (%I:%M:%S [AM|PM]).  The time in hours (24-hour clock) and minutes (%H:%M).  The second is output as a
	      number between 00 and 61.  Only a tab character is output.  The time is output as %H:%M:%S.  Specifies the weekday as a decimal num-
	      ber [1,7], with 1 representing Monday.  The week number of the year (Sunday as the first day of the week). Output format is a  deci-
	      mal  number  between 0 and 53.  The week number of the year (Monday as the first day of the week). Output format is a decimal number
	      between 1 and 53.  If the week containing January 1 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.  The day of the week is output as a number between 0 (Sunday)
	      and 6.  The week number of the year (Monday as the first day of the week). Output format is a decimal number between 0 and 53.   The
	      short  date  is  output  in the format specified for the current locale.	The time is output in the format specified for the current
	      locale.  The year is output as a number (without the century) between 00 and 99. Because this conversion code relies on a  two-digit
	      representation  of  the  year, it is not recommended. Use Y instead.  The year is output as a number (with the century) between 0000
	      and 9999.  The (standard time or daylight saving time) time zone name or abbreviation is output as a  string  from  the  environment
	      variable TZ (CDT, for example).  If no time zone information exists, no characters are output.  The % (percent) character is output.

       When a modified or unmodified conversion-code is not from the preceding list, the behavior of these functions is undefined.

EXAMPLES

       The following example uses strftime() to display the current date:

       #include <time.h> #include <locale.h> #include <stdio.h> #define SLENGTH 80

       main() {
	   char nowstr[SLENGTH];
	   time_t nowbin;
	   const struct tm *nowstruct;

	   (void)setlocale(LC_ALL, "");

	   if (time(&nowbin) == (time_t) - 1)
	       printf("Could not get time of day from time()
");

	   nowstruct = localtime(&nowbin);

	   if (strftime(nowstr, SLENGTH, "%A %x", nowstruct) == (size_t) 0)
	       printf("Could not get string from strftime()
");

	   printf("Today's date is %s
", nowstr); }

NOTES

       The  %S	seconds  field can contain a value up to 61 seconds rather than up to 59 seconds to allow leap seconds that are sometimes added to
       years to keep clocks in correspondence with the solar year.

RETURN VALUES

       The strftime() function returns the number of bytes written into the array pointed to by the s parameter when the total number of resulting
       bytes,  including  the  terminating  null byte, is not more than the value of the maxsize parameter.  The returned value does not count the
       terminating null byte in the number of bytes written into the array.  Otherwise, a value of 0 cast to size_t is returned and  the  contents
       of the array are undefined.

       The  wcsftime() function returns the number of wide characters written into the array pointed to by the wcs parameter when the total number
       of resulting wide characters, including the terminating null wide character, is not more than the value	of  the  maxsize  parameter.   The
       returned  value	does  not count the terminating null wide character in the number of wide characters written into the array.  Otherwise, a
       value of 0 cast to size_t is returned and the contents of the array are undefined.

RELATED INFORMATION

       Functions: ctime(3), mbstowcs(3), setlocale(3), strptime(3)

       Standards: standards(5) delim off

																       strftime(3)