STRPTIME(3)                POSIX Programmer's Manual               STRPTIME(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       strptime -- date and time conversion

SSYYNNOOPPSSIISS
       #include <time.h>

       char *strptime(const char *restrict _b_u_f, const char *restrict _f_o_r_m_a_t,
           struct tm *restrict _t_m);

DDEESSCCRRIIPPTTIIOONN
       The _s_t_r_p_t_i_m_e() function shall convert the character string pointed to
       by _b_u_f to values which are stored in the ttmm structure pointed to by _t_m,
       using the format specified by _f_o_r_m_a_t.

       The format is composed of zero or more directives. Each directive is
       composed of one of the following: one or more white-space characters
       (as specified by _i_s_s_p_a_c_e()); an ordinary character (neither ''%%'' nor a
       white-space character); or a conversion specification.

       Each conversion specification is introduced by the ''%%'' character after
       which the following appear in sequence:

        *  An optional flag, the zero character (''00'') or the <plus-sign>
           character (''++''), which is ignored.

        *  An optional field width. If a field width is specified, it shall be
           interpreted as a string of decimal digits that will determine the
           maximum number of bytes converted for the conversion rather than
           the number of bytes specified below in the description of the
           conversion specifiers.

        *  An optional EE or OO modifier.

        *  A terminating conversion specifier character that indicates the
           type of conversion to be applied.

       The conversions are determined using the _L_C___T_I_M_E category of the
       current locale. The application shall ensure that there is white-space
       or other non-alphanumeric characters between any two conversion
       specifications unless all of the adjacent conversion specifications
       convert a known, fixed number of characters. In the following list, the
       maximum number of characters scanned (excluding the one matching the
       next directive) is as follows:

        *  If a maximum field width is specified, then that number

        *  Otherwise, the pattern ""{{xx}}"" indicates that the maximum is _x

        *  Otherwise, the pattern ""[[xx,,yy]]"" indicates that the value shall fall
           within the range given (both bounds being inclusive), and the
           maximum number of characters scanned shall be the maximum required
           to represent any value in the range without leading zeros and
           without a leading <plus-sign>

       The following conversion specifiers are supported.

       The results are unspecified if a modifier is specified with a flag or
       with a minimum field width, or if a field width is specified for any
       conversion specifier other than CC or YY.

       a       The day of the week, using the locale's weekday names; either
               the abbreviated or full name may be specified.

       A       Equivalent to %%aa.

       b       The month, using the locale's month names; either the
               abbreviated or full name may be specified.

       B       Equivalent to %%bb.

       c       Replaced by the locale's appropriate date and time
               representation.

       C       All but the last two digits of the year {2}; leading zeros
               shall be permitted but shall not be required. A leading ''++'' or
               ''--'' character shall be permitted before any leading zeros but
               shall not be required.

       d       The day of the month [01,31]; leading zeros shall be permitted
               but shall not be required.

       D       The date as %%mm/%%dd/%%yy.

       e       Equivalent to %%dd.

       h       Equivalent to %%bb.

       H       The hour (24-hour clock) [00,23]; leading zeros shall be
               permitted but shall not be required.

       I       The hour (12-hour clock) [01,12]; leading zeros shall be
               permitted but shall not be required.

       j       The day number of the year [001,366]; leading zeros shall be
               permitted but shall not be required.

       m       The month number [01,12]; leading zeros shall be permitted but
               shall not be required.

       M       The minute [00,59]; leading zeros shall be permitted but shall
               not be required.

       n       Any white space.

       p       The locale's equivalent of a.m. or p.m.

       r       12-hour clock time using the AM/PM notation if tt__ffmmtt__aammppmm is
               not an empty string in the _L_C___T_I_M_E portion of the current
               locale; in the POSIX locale, this shall be equivalent to
               %%II:%%MM:%%SS %%pp.

       R       The time as %%HH:%%MM.

       S       The seconds [00,60]; leading zeros shall be permitted but shall
               not be required.

       t       Any white space.

       T       The time as %%HH:%%MM:%%SS.

       U       The week number of the year (Sunday as the first day of the
               week) as a decimal number [00,53]; leading zeros shall be
               permitted but shall not be required.

       w       The weekday as a decimal number [0,6], with 0 representing
               Sunday.

       W       The week number of the year (Monday as the first day of the
               week) as a decimal number [00,53]; leading zeros shall be
               permitted but shall not be required.

       x       The date, using the locale's date format.

       X       The time, using the locale's time format.

       y       The last two digits of the year. When _f_o_r_m_a_t contains neither a
               CC conversion specifier nor a YY conversion specifier, values in
               the range [69,99] shall refer to years 1969 to 1999 inclusive
               and values in the range [00,68] shall refer to years 2000 to
               2068 inclusive; leading zeros shall be permitted but shall not
               be required. A leading ''++'' or ''--'' character shall be permitted
               before any leading zeros but shall not be required.

               NNoottee::     It is expected that in a future version of this
                         standard the default century inferred from a 2-digit
                         year will change. (This would apply to all commands
                         accepting a 2-digit year as input.)

       Y       The full year {4}; leading zeros shall be permitted but shall
               not be required. A leading ''++'' or ''--'' character shall be
               permitted before any leading zeros but shall not be required.

       %       Replaced by %%.

   MMooddiiffiieedd CCoonnvveerrssiioonn SSppeecciiffiieerrss
       Some conversion specifiers can be modified by the EE and OO modifier
       characters 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 in the current locale, the behavior shall be as if the
       unmodified conversion specification were used.

       %Ec     The locale's alternative appropriate date and time
               representation.

       %EC     The name of the base year (period) in the locale's alternative
               representation.

       %Ex     The locale's alternative date representation.

       %EX     The locale's alternative time representation.

       %Ey     The offset from %%EECC (year only) in the locale's alternative
               representation.

       %EY     The full alternative year representation.

       %Od     The day of the month using the locale's alternative numeric
               symbols; leading zeros shall be permitted but shall not be
               required.

       %Oe     Equivalent to %%OOdd.

       %OH     The hour (24-hour clock) using the locale's alternative numeric
               symbols.

       %OI     The hour (12-hour clock) using the locale's alternative numeric
               symbols.

       %Om     The month using the locale's alternative numeric symbols.

       %OM     The minutes using the locale's alternative numeric symbols.

       %OS     The seconds using the locale's alternative numeric symbols.

       %OU     The week number of the year (Sunday as the first day of the
               week) using the locale's alternative numeric symbols.

       %Ow     The number of the weekday (Sunday=0) using the locale's
               alternative numeric symbols.

       %OW     The week number of the year (Monday as the first day of the
               week) using the locale's alternative numeric symbols.

       %Oy     The year (offset from %%CC) using the locale's alternative
               numeric symbols.

       A conversion specification composed of white-space characters is
       executed by scanning input up to the first character that is not white-
       space (which remains unscanned), or until no more characters can be
       scanned.

       A conversion specification that is an ordinary character is executed by
       scanning the next character from the buffer. If the character scanned
       from the buffer differs from the one comprising the directive, the
       directive fails, and the differing and subsequent characters remain
       unscanned.

       A series of conversion specifications composed of %%nn, %%tt, white-space
       characters, or any combination is executed by scanning up to the first
       character that is not white space (which remains unscanned), or until
       no more characters can be scanned.

       Any other conversion specification is executed by scanning characters
       until a character matching the next directive is scanned, or until no
       more characters can be scanned. These characters, except the one
       matching the next directive, are then compared to the locale values
       associated with the conversion specifier. If a match is found, values
       for the appropriate ttmm structure members are set to values
       corresponding to the locale information. Case is ignored when matching
       items in _b_u_f such as month or weekday names. If no match is found,
       _s_t_r_p_t_i_m_e() fails and no more characters are scanned.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _s_t_r_p_t_i_m_e() shall return a pointer to the
       character following the last character parsed. Otherwise, a null
       pointer shall be returned.

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   CCoonnvveerrtt aa DDaattee--PPlluuss--TTiimmee SSttrriinngg ttoo BBrrookkeenn--DDoowwnn TTiimmee aanndd TThheenn iinnttoo SSeeccoonnddss
       The following example demonstrates the use of _s_t_r_p_t_i_m_e() to convert a
       string into broken-down time. The broken-down time is then converted
       into seconds since the Epoch using _m_k_t_i_m_e().


           #include <time.h>
           ...

           struct tm tm;
           time_t t;

           if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL)
               /* Handle error */;

           printf("year: %d; month: %d; day: %d;\n",
                   tm.tm_year, tm.tm_mon, tm.tm_mday);
           printf("hour: %d; minute: %d; second: %d\n",
                   tm.tm_hour, tm.tm_min, tm.tm_sec);
           printf("week day: %d; year day: %d\n", tm.tm_wday, tm.tm_yday);

           tm.tm_isdst = -1;      /* Not set by strptime(); tells mktime()
                                     to determine whether daylight saving time
                                     is in effect */
           t = mktime(&tm);
           if (t == -1)
               /* Handle error */;
           printf("seconds since the Epoch: %ld\n", (long) t);"

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Several ``equivalent to'' formats and the special processing of white-
       space characters are provided in order to ease the use of identical
       _f_o_r_m_a_t strings for _s_t_r_f_t_i_m_e() and _s_t_r_p_t_i_m_e().

       It should be noted that dates constructed by the _s_t_r_f_t_i_m_e() function
       with the %%YY or %%CC%%yy conversion specifiers may have values larger than
       9999. If the _s_t_r_p_t_i_m_e() function is used to read such values using %%CC%%yy
       or %%YY, the year values will be truncated to four digits. Applications
       should use %%++_w%%yy or %%++_xYY with _w and _x set large enough to contain the
       full value of any years that will be printed or scanned.

       See also the APPLICATION USAGE section in _s_t_r_f_t_i_m_e().

       It is unspecified whether multiple calls to _s_t_r_p_t_i_m_e() using the same
       ttmm structure will update the current contents of the structure or
       overwrite all contents of the structure. Conforming applications should
       make a single call to _s_t_r_p_t_i_m_e() with a format and all data needed to
       completely specify the date and time being converted.

RRAATTIIOONNAALLEE
       See the RATIONALE section for _s_t_r_f_t_i_m_e().

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _f_p_r_i_n_t_f(), _f_s_c_a_n_f(), _s_t_r_f_t_i_m_e(), _t_i_m_e()

       The Base Definitions volume of POSIX.1-2017, <<ttiimmee..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                          STRPTIME(3)
