trcat

STRFTIME(3)                                    Linux Programmer's Manual                                   STRFTIME(3)

NNAAMMEE
       strftime - format date and time

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<ttiimmee..hh>>

       ssiizzee__tt ssttrrffttiimmee((cchhaarr **_s,, ssiizzee__tt _m_a_x,, ccoonnsstt cchhaarr **_f_o_r_m_a_t,,
                       ccoonnsstt ssttrruucctt ttmm **_t_m));;

DDEESSCCRRIIPPTTIIOONN
       The ssttrrffttiimmee() function formats the broken-down time _t_m according to the format specification _f_o_r_m_a_t and places
       the result in the character array _s of size _m_a_x.

       The format specification is a null-terminated string and may contain special character sequences called _c_o_n_v_e_r_‐
       _s_i_o_n  _s_p_e_c_i_f_i_c_a_t_i_o_n_s,  each  of  which  is introduced by a '%' character and terminated by some other character
       known as a _c_o_n_v_e_r_s_i_o_n _s_p_e_c_i_f_i_e_r _c_h_a_r_a_c_t_e_r.  All other character sequences are _o_r_d_i_n_a_r_y _c_h_a_r_a_c_t_e_r _s_e_q_u_e_n_c_e_s.

       The characters of ordinary character sequences (including the null byte) are copied verbatim from _f_o_r_m_a_t to  _s.
       However, the characters of conversion specifications are replaced as follows:

       %%aa     The abbreviated name of the day of the week according to the current locale.

       %%AA     The full name of the day of the week according to the current locale.

       %%bb     The abbreviated month name according to the current locale.

       %%BB     The full month name according to the current locale.

       %%cc     The preferred date and time representation for the current locale.

       %%CC     The century number (year/100) as a 2-digit integer. (SU)

       %%dd     The day of the month as a decimal number (range 01 to 31).

       %%DD     Equivalent  to  %%mm//%%dd//%%yy.   (Yecch—for  Americans  only.   Americans should note that in other countries
              %%dd//%%mm//%%yy is rather common.  This means that in international context this format is ambiguous and should
              not be used.) (SU)

       %%ee     Like %%dd, the day of the month as a decimal number, but a leading zero is replaced by a space. (SU)

       %%EE     Modifier: use alternative format, see below. (SU)

       %%FF     Equivalent to %%YY--%%mm--%%dd (the ISO 8601 date format). (C99)

       %%GG     The ISO 8601 week-based year (see NOTES) with century as a decimal number.  The 4-digit year correspond‐
              ing to the ISO week number (see %%VV).  This has the same format and value as %%YY, except that if  the  ISO
              week number belongs to the previous or next year, that year is used instead. (TZ)

       %%gg     Like %%GG, but without century, that is, with a 2-digit year (00-99). (TZ)

       %%hh     Equivalent to %%bb.  (SU)

       %%HH     The hour as a decimal number using a 24-hour clock (range 00 to 23).

       %%II     The hour as a decimal number using a 12-hour clock (range 01 to 12).

       %%jj     The day of the year as a decimal number (range 001 to 366).

       %%kk     The  hour  (24-hour  clock)  as a decimal number (range 0 to 23); single digits are preceded by a blank.
              (See also %%HH.)  (TZ)

       %%ll     The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are  preceded  by  a  blank.
              (See also %%II.)  (TZ)

       %%mm     The month as a decimal number (range 01 to 12).

       %%MM     The minute as a decimal number (range 00 to 59).

       %%nn     A newline character. (SU)

       %%OO     Modifier: use alternative format, see below. (SU)

       %%pp     Either  "AM"  or  "PM"  according  to the given time value, or the corresponding strings for the current
              locale.  Noon is treated as "PM" and midnight as "AM".

       %%PP     Like %%pp but in lowercase: "am" or "pm" or a corresponding string for the current locale. (GNU)

       %%rr     The time in a.m. or p.m. notation.  In the POSIX locale this is equivalent to %%II::%%MM::%%SS %%pp.  (SU)

       %%RR     The time in 24-hour notation (%%HH::%%MM).  (SU) For a version including the seconds, see %%TT below.

       %%ss     The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)

       %%SS     The second as a decimal number (range 00 to 60).  (The range is up to 60 to allow  for  occasional  leap
              seconds.)

       %%tt     A tab character. (SU)

       %%TT     The time in 24-hour notation (%%HH::%%MM::%%SS).  (SU)

       %%uu     The day of the week as a decimal, range 1 to 7, Monday being 1.  See also %%ww.  (SU)

       %%UU     The  week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday
              as the first day of week 01.  See also %%VV and %%WW.

       %%VV     The ISO 8601 week number (see NOTES) of the current year as a decimal number, range 01 to 53, where week
              1 is the first week that has at least 4 days in the new year.  See also %%UU and %%WW.  (SU)

       %%ww     The day of the week as a decimal, range 0 to 6, Sunday being 0.  See also %%uu.

       %%WW     The  week number of the current year as a decimal number, range 00 to 53, starting with the first Monday
              as the first day of week 01.

       %%xx     The preferred date representation for the current locale without the time.

       %%XX     The preferred time representation for the current locale without the date.

       %%yy     The year as a decimal number without a century (range 00 to 99).

       %%YY     The year as a decimal number including the century.

       %%zz     The _+_h_h_m_m or _-_h_h_m_m numeric timezone (that is, the hour and minute offset from UTC). (SU)

       %%ZZ     The timezone name or abbreviation.

       %%++     The date and time in ddaattee(1) format. (TZ) (Not supported in glibc2.)

       %%%%     A literal '%' character.

       Some conversion specifications can be modified by preceding the conversion specifier character by the  EE  or  OO
       _m_o_d_i_f_i_e_r  to  indicate  that  an alternative format should be used.  If the alternative format or specification
       does not exist for the current locale, the behavior will be as if the unmodified conversion specification  were
       used.  (SU)  The Single UNIX Specification mentions %%EEcc, %%EECC, %%EExx, %%EEXX, %%EEyy, %%EEYY, %%OOdd, %%OOee, %%OOHH, %%OOII, %%OOmm, %%OOMM,
       %%OOSS, %%OOuu, %%OOUU, %%OOVV, %%OOww, %%OOWW, %%OOyy, where the effect of the OO modifier is to  use  alternative  numeric  symbols
       (say, roman numerals), and that of the E modifier is to use a locale-dependent alternative representation.

       The broken-down time structure _t_m is defined in _<_t_i_m_e_._h_>.  See also ccttiimmee(3).

RREETTUURRNN VVAALLUUEE
       Provided  that  the  result  string, including the terminating null byte, does not exceed _m_a_x bytes, ssttrrffttiimmee()
       returns the number of bytes (excluding the terminating null byte) placed in the array _s.  If the length of  the
       result  string (including the terminating null byte) would exceed _m_a_x bytes, then ssttrrffttiimmee() returns 0, and the
       contents of the array are undefined.

       Note that the return value 0 does not necessarily indicate an error.  For example, in many locales %%pp yields an
       empty string.  An empty _f_o_r_m_a_t string will likewise yield an empty string.

EENNVVIIRROONNMMEENNTT
       The environment variables TTZZ and LLCC__TTIIMMEE are used.

AATTTTRRIIBBUUTTEESS
       For an explanation of the terms used in this section, see aattttrriibbuutteess(7).

       ┌───────────┬───────────────┬────────────────────┐
       │IInntteerrffaaccee  │ AAttttrriibbuuttee     │ VVaalluuee              │
       ├───────────┼───────────────┼────────────────────┤
       │ssttrrffttiimmee() │ Thread safety │ MT-Safe env locale │
       └───────────┴───────────────┴────────────────────┘
CCOONNFFOORRMMIINNGG TTOO
       SVr4,  C89,  C99.  There are strict inclusions between the set of conversions given in ANSI C (unmarked), those
       given in the Single UNIX Specification (marked SU), those given in Olson's timezone package  (marked  TZ),  and
       those  given  in  glibc  (marked GNU), except that %%++ is not supported in glibc2.  On the other hand glibc2 has
       several more extensions.  POSIX.1 only refers to ANSI C; POSIX.2 describes  under  ddaattee(1)  several  extensions
       that could apply to ssttrrffttiimmee() as well.  The %%FF conversion is in C99 and POSIX.1-2001.

       In  SUSv2,  the  %%SS specifier allowed a range of 00 to 61, to allow for the theoretical possibility of a minute
       that included a double leap second (there never has been such a minute).

NNOOTTEESS
   IISSOO 88660011 wweeeekk ddaatteess
       %%GG, %%gg, and %%VV yield values calculated from the week-based year defined by the ISO 8601 standard.  In this sys‐
       tem,  weeks start on a Monday, and are numbered from 01, for the first week, up to 52 or 53, for the last week.
       Week 1 is the first week where four or more days fall within the new year (or, synonymously, week  01  is:  the
       first  week  of the year that contains a Thursday; or, the week that has 4 January in it).  When three of fewer
       days of the first calendar week of the new year fall within that year, then  the  ISO  8601  week-based  system
       counts  those  days as part of week 53 of the preceding year.  For example, 1 January 2010 is a Friday, meaning
       that just three days of that calendar week fall in 2010.  Thus, the ISO 8601 week-based system considers  these
       days  to be part of week 53 (%%VV) of the year 2009 (%%GG); week 01 of ISO 8601 year 2010 starts on Monday, 4 Janu‐
       ary 2010.

   GGlliibbcc nnootteess
       Glibc provides some  extensions  for  conversion  specifications.   (These  extensions  are  not  specified  in
       POSIX.1-2001,  but a few other systems provide similar features.)  Between the '%' character and the conversion
       specifier character, an optional _f_l_a_g and field _w_i_d_t_h may be specified.  (These precede the EE or  OO  modifiers,
       if present.)

       The following flag characters are permitted:

       __      (underscore) Pad a numeric result string with spaces.

       --      (dash) Do not pad a numeric result string.

       00      Pad  a numeric result string with zeros even if the conversion specifier character uses space-padding by
              default.

       ^^      Convert alphabetic characters in result string to uppercase.

       ##      Swap the case of the result string.  (This flag works only with certain conversion specifier characters,
              and of these, it is only really useful with %%ZZ.)

       An optional decimal width specifier may follow the (possibly absent) flag.  If the natural size of the field is
       smaller than this width, then the result string is padded (on the left) to the specified width.

BBUUGGSS
       If the output string would exceed _m_a_x bytes, _e_r_r_n_o is _n_o_t set.  This makes it impossible  to  distinguish  this
       error  case from cases where the _f_o_r_m_a_t string legitimately produces a zero-length output string.  POSIX.1-2001
       does _n_o_t specify any _e_r_r_n_o settings for ssttrrffttiimmee().

       Some buggy versions of ggcccc(1) complain about the use of %%cc: _w_a_r_n_i_n_g_: _`_%_c_' _y_i_e_l_d_s _o_n_l_y _l_a_s_t _2 _d_i_g_i_t_s _o_f _y_e_a_r  _i_n
       _s_o_m_e _l_o_c_a_l_e_s.  Of course programmers are encouraged to use %%cc, it gives the preferred date and time representa‐
       tion.  One meets all kinds of strange obfuscations to circumvent this ggcccc(1) problem.  A relatively  clean  one
       is to add an intermediate function

           size_t
           my_strftime(char *s, size_t max, const char *fmt,
                       const struct tm *tm)
           {
               return strftime(s, max, fmt, tm);
           }

       Nowadays, ggcccc(1) provides the _-_W_n_o_-_f_o_r_m_a_t_-_y_2_k option to prevent the warning, so that the above workaround is no
       longer required.

EEXXAAMMPPLLEE
       RRFFCC 22882222--ccoommpplliiaanntt ddaattee ffoorrmmaatt (with an English locale for %a and %b)

         "%a, %d %b %Y %T %z"

       RRFFCC 882222--ccoommpplliiaanntt ddaattee ffoorrmmaatt (with an English locale for %a and %b)

         "%a, %d %b %y %T %z"

   EExxaammppllee pprrooggrraamm
       The program below can be used to experiment with ssttrrffttiimmee().

       Some examples of the result string produced by the glibc implementation of ssttrrffttiimmee() are as follows:

           $ ..//aa..oouutt ''%%mm''
           Result string is "11"
           $ ..//aa..oouutt ''%%55mm''
           Result string is "00011"
           $ ..//aa..oouutt ''%%__55mm''
           Result string is "   11"

   PPrrooggrraamm ssoouurrccee
       #include <time.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           char outstr[200];
           time_t t;
           struct tm *tmp;

           t = time(NULL);
           tmp = localtime(&t);
           if (tmp == NULL) {
               perror("localtime");
               exit(EXIT_FAILURE);
           }

           if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
               fprintf(stderr, "strftime returned 0");
               exit(EXIT_FAILURE);
           }

           printf("Result string is \"%s\"\n", outstr);
           exit(EXIT_SUCCESS);
       }

SSEEEE AALLSSOO
       ddaattee(1), ttiimmee(2), ccttiimmee(3), sseettllooccaallee(3), sspprriinnttff(3), ssttrrppttiimmee(3)

CCOOLLOOPPHHOONN
       This page is part of release 4.04 of the Linux _m_a_n_-_p_a_g_e_s project.  A description of  the  project,  information
       about    reporting    bugs,    and    the    latest    version    of    this    page,    can    be   found   at
       http://www.kernel.org/doc/man-pages/.

GNU                                                   2015-03-02                                           STRFTIME(3)