strftime(3p) - phpMan

STRFTIME(3P)               POSIX Programmer's Manual              STRFTIME(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       strftime - convert date and time to a string
SYNOPSIS
       #include <time.h>
       size_t strftime(char *restrict s, size_t maxsize,
              const char *restrict format, const struct tm *restrict timeptr);

DESCRIPTION
       The strftime() function shall place bytes into the array pointed to  by
       s  as  controlled  by  the string pointed to by format. The format is a
       character string, beginning and ending in its initial shift  state,  if
       any.  The  format string consists of zero or more conversion specifica-
       tions and ordinary characters.  A conversion specification consists  of
       a  '%' character, possibly followed by an E or O modifier, and a termi-
       nating conversion specifier character that  determines  the  conversion
       specification's behavior. All ordinary characters (including the termi-
       nating null byte) are copied unchanged into the array. If copying takes
       place  between objects that overlap, the behavior is undefined. No more
       than maxsize bytes are placed into the array. Each conversion specifier
       is  replaced  by  appropriate  characters as described in the following
       list. The appropriate characters are determined using the LC_TIME cate-
       gory of the current locale and by the values of zero or more members of
       the broken-down time structure pointed to by timeptr, as  specified  in
       brackets in the description. If any of the specified values are outside
       the normal range, the characters stored are unspecified.
       Local timezone information is used as though strftime() called tzset().
       The following conversion specifications are supported:
       %a     Replaced by the locale's abbreviated weekday name. [ tm_wday]
       %A     Replaced by the locale's full weekday name. [ tm_wday]
       %b     Replaced by the locale's abbreviated month name. [ tm_mon]
       %B     Replaced by the locale's full month name. [ tm_mon]
       %c     Replaced by the locale's appropriate date and  time  representa-
              tion.  (See the Base Definitions volume of IEEE Std 1003.1-2001,
              <time.h>.)
       %C     Replaced by the year divided by 100 and truncated to an integer,
              as a decimal number [00,99]. [ tm_year]
       %d     Replaced  by the day of the month as a decimal number [01,31]. [
              tm_mday]
       %D     Equivalent to %m / %d / %y . [ tm_mon, tm_mday, tm_year]
       %e     Replaced by the day of the month as a decimal number  [1,31];  a
              single digit is preceded by a space. [ tm_mday]
       %F     Equivalent to %Y - %m - %d (the ISO 8601:2000 standard date for-
              mat). [ tm_year, tm_mon, tm_mday]
       %g     Replaced by the last 2 digits of the week-based year (see below)
              as a decimal number [00,99]. [ tm_year, tm_wday, tm_yday]
       %G     Replaced  by the week-based year (see below) as a decimal number
              (for example, 1977). [ tm_year, tm_wday, tm_yday]
       %h     Equivalent to %b . [ tm_mon]
       %H     Replaced by  the  hour  (24-hour  clock)  as  a  decimal  number
              [00,23].  [ tm_hour]
       %I     Replaced  by  the  hour  (12-hour  clock)  as  a  decimal number
              [01,12].  [ tm_hour]
       %j     Replaced by the day of the year as a decimal number [001,366]. [
              tm_yday]
       %m     Replaced by the month as a decimal number [01,12]. [ tm_mon]
       %M     Replaced by the minute as a decimal number [00,59]. [ tm_min]
       %n     Replaced by a <newline>.
       %p     Replaced  by  the  locale's  equivalent of either a.m. or p.m. [
              tm_hour]
       %r     Replaced by the time in a.m. and p.m. notation;   in  the  POSIX
              locale this shall be equivalent to %I : %M : %S %p .  [ tm_hour,
              tm_min, tm_sec]
       %R     Replaced by the time in  24-hour  notation  (  %H  :  %M  ).   [
              tm_hour, tm_min]
       %S     Replaced by the second as a decimal number [00,60]. [ tm_sec]
       %t     Replaced by a <tab>.
       %T     Replaced  by  the  time  (  %H  :  %M : %S ). [ tm_hour, tm_min,
              tm_sec]
       %u     Replaced by the weekday as a decimal number [1,7], with 1 repre-
              senting Monday. [ tm_wday]
       %U     Replaced  by  the  week  number  of the year as a decimal number
              [00,53].  The first Sunday of January is the first day  of  week
              1;  days  in  the new year before this are in week 0. [ tm_year,
              tm_wday, tm_yday]
       %V     Replaced by the week number of the year (Monday as the first day
              of the week) as a decimal number [01,53]. If the week containing
              1 January has four or more days in the new year, then it is con-
              sidered  week  1. Otherwise, it is the last week of the previous
              year, and the next week is week 1.  Both  January  4th  and  the
              first  Thursday  of  January  are  always  in week 1. [ tm_year,
              tm_wday, tm_yday]
       %w     Replaced by the weekday as a decimal number [0,6], with 0 repre-
              senting Sunday. [ tm_wday]
       %W     Replaced  by  the  week  number  of the year as a decimal number
              [00,53].  The first Monday of January is the first day  of  week
              1;  days  in  the new year before this are in week 0. [ tm_year,
              tm_wday, tm_yday]
       %x     Replaced by the locale's appropriate date  representation.  (See
              the Base Definitions volume of IEEE Std 1003.1-2001, <time.h>.)
       %X     Replaced  by  the locale's appropriate time representation. (See
              the Base Definitions volume of IEEE Std 1003.1-2001, <time.h>.)
       %y     Replaced by the last two digits of the year as a decimal  number
              [00,99].  [ tm_year]
       %Y     Replaced  by the year as a decimal number (for example, 1997). [
              tm_year]
       %z     Replaced by the offset from UTC in  the  ISO 8601:2000  standard
              format ( +hhmm or -hhmm ), or by no characters if no timezone is
              determinable. For example, "-0430"  means  4  hours  30  minutes
              behind UTC (west of Greenwich).   If tm_isdst is zero, the stan-
              dard time offset is used. If tm_isdst is greater than zero,  the
              daylight  savings  time offset is used. If tm_isdst is negative,
              no characters are returned.  [ tm_isdst]
       %Z     Replaced by the timezone name or abbreviation, or by no bytes if
              no timezone information exists. [ tm_isdst]
       %%     Replaced by % .

       If  a conversion specification does not correspond to any of the above,
       the behavior is undefined.
       If a struct tm broken-down time structure is created by localtime()  or
       localtime_r(),  or  modified by mktime(), and the value of TZ is subse-
       quently modified, the results of the %Z and  %z  strftime()  conversion
       specifiers are undefined, when strftime() is called with such a broken-
       down time structure.
       If a struct tm broken-down time structure is  created  or  modified  by
       gmtime()  or gmtime_r(), it is unspecified whether the result of the %Z
       and %z conversion specifiers shall refer to UTC or  the  current  local
       timezone, when strftime() is called with such a broken-down time struc-
       ture.
   Modified Conversion Specifiers
       Some conversion specifiers can be modified by the E or O modifier char-
       acters  to  indicate that an alternative format or specification should
       be used rather than the one normally used by the unmodified  conversion
       specifier.  If  the  alternative format or specification does not exist
       for the current locale (see ERA  in  the  Base  Definitions  volume  of
       IEEE Std 1003.1-2001, Section 7.3.5, LC_TIME), the behavior shall be as
       if the unmodified conversion specification were used.
       %Ec    Replaced by the locale's alternative appropriate date  and  time
              representation.
       %EC    Replaced  by  the name of the base year (period) in the locale's
              alternative representation.
       %Ex    Replaced by the locale's alternative date representation.
       %EX    Replaced by the locale's alternative time representation.
       %Ey    Replaced by the offset from %EC  (year  only)  in  the  locale's
              alternative representation.
       %EY    Replaced by the full alternative year representation.
       %Od    Replaced by the day of the month, using the locale's alternative
              numeric symbols, filled as needed with leading zeros if there is
              any alternative symbol for zero; otherwise, with leading spaces.
       %Oe    Replaced by the day of the month, using the locale's alternative
              numeric symbols, filled as needed with leading spaces.
       %OH    Replaced by the hour (24-hour clock) using the locale's alterna-
              tive numeric symbols.
       %OI    Replaced by the hour (12-hour clock) using the locale's alterna-
              tive numeric symbols.
       %Om    Replaced by the month using  the  locale's  alternative  numeric
              symbols.
       %OM    Replaced  by  the minutes using the locale's alternative numeric
              symbols.
       %OS    Replaced by the seconds using the locale's  alternative  numeric
              symbols.
       %Ou    Replaced  by the weekday as a number in the locale's alternative
              representation (Monday=1).
       %OU    Replaced by the week number of the year (Sunday as the first day
              of  the  week,  rules  corresponding  to %U ) using the locale's
              alternative numeric symbols.
       %OV    Replaced by 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.
       %Ow    Replaced by the number  of  the  weekday  (Sunday=0)  using  the
              locale's alternative numeric symbols.
       %OW    Replaced by the week number of the year (Monday as the first day
              of the week) using the locale's alternative numeric symbols.
       %Oy    Replaced by the year (offset from %C ) using the locale's alter-
              native numeric symbols.

       %g,  %G,  and  %V  give  values according to the ISO 8601:2000 standard
       week-based year. In this system, weeks begin on a Monday and week 1  of
       the  year is the week that includes January 4th, which is also the week
       that includes the first Thursday of the year, and  is  also  the  first
       week  that contains at least four days in 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; thus, for Saturday 2nd January 1999,
       %G is replaced by 1998 and %V is replaced by  53.   If  December  29th,
       30th, or 31st is a Monday, it and any following days are part of week 1
       of the following year. Thus, for Tuesday  30th  December  1997,  %G  is
       replaced by 1998 and %V is replaced by 01.
       If  a  conversion  specifier  is  not one of the above, the behavior is
       undefined.
RETURN VALUE
       If the total number of resulting bytes including the  terminating  null
       byte  is  not  more than maxsize, strftime() shall return the number of
       bytes placed into the array pointed to by s, not including  the  termi-
       nating  null  byte.  Otherwise, 0 shall be returned and the contents of
       the array are unspecified.
ERRORS
       No errors are defined.
       The following sections are informative.
EXAMPLES
   Getting a Localized Date String
       The following example first sets the locale to the user's default.  The
       locale  information  will  be  used in the nl_langinfo() and strftime()
       functions. The nl_langinfo() function returns the localized date string
       which specifies how the date is laid out. The strftime() function takes
       this information and, using the tm structure  for  values,  places  the
       date and time information into datestring.

              #include <time.h>
              #include <locale.h>
              #include <langinfo.h>
              ...
              struct tm *tm;
              char datestring[256];
              ...
              setlocale (LC_ALL, "");
              ...
              strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm);
              ...
APPLICATION USAGE
       The  range of values for %S is [00,60] rather than [00,59] to allow for
       the occasional leap second.
       Some of the conversion specifications are duplicates  of  others.  They
       are  included  for  compatibility  with  nl_cxtime() and nl_ascxtime(),
       which were published in Issue 2.
       Applications should use %Y (4-digit years) in preference to %y (2-digit
       years).
       In  the C locale, the E and O modifiers are ignored and the replacement
       strings for the following specifiers are:
       %a     The first three characters of %A .
       %A     One of Sunday, Monday, ..., Saturday.
       %b     The first three characters of %B .
       %B     One of January, February, ..., December.
       %c     Equivalent to %a %b %e %T %Y .
       %p     One of AM or PM.
       %r     Equivalent to %I : %M : %S %p .
       %x     Equivalent to %m / %d / %y .
       %X     Equivalent to %T .
       %Z     Implementation-defined.

RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       asctime(), clock(), ctime(), difftime(),  getdate(),  gmtime(),  local-
       time(),  mktime(),  strptime(),  time(), tzset(), utime(), Base Defini-
       tions volume of IEEE Std 1003.1-2001, Section 7.3.5, LC_TIME, <time.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                         STRFTIME(3P)