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



NAME

       strptime  -  convert  a string representation of time to a
       time tm structure


SYNOPSIS

       #define _XOPEN_SOURCE /* glibc2 needs this */
       #include <time.h>

       char *strptime(const char *s, const char  *format,  struct
       tm *tm);


DESCRIPTION

       strptime() is the complementary function to strftime() and
       converts the character string pointed to by  s  to  values
       which  are  stored  in  the tm structure pointed to by tm,
       using the format specified by format.  Here  format  is  a
       character  string  that  consists of field descriptors and
       text characters,  reminiscent  of  scanf(3).   Each  field
       descriptor  consists  of a % character followed by another
       character that specifies the  replacement  for  the  field
       descriptor.   All  other  characters  in the format string
       must have  a  matching  character  in  the  input  string.
       Exceptions are white spaces in the format string which can
       match zero or more white space  characters  in  the  input
       string.

       The  strptime()  function  processes the input string from
       right to left.  Each of the three possible input  elements
       (white  space,  literal,  or format) are handled one after
       the other.  If the input cannot be matched to  the  format
       string  the  function  stops.  The remainder of the format
       and input strings are not processed.

       The following field descriptors are supported:

       %%     the % character

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

       %b or %B or %h
              month,  using  locale's  month  names;  either  the
              abbreviated or full name may be specified

       %c     date and time as %x %X

       %C     date and time, in  locale's  long-format  date  and
              time representation

       %d or %e
              day  of  month  (1-31; leading zeroes are permitted
              but not required)




GNU                     26 September 1994                       1





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


       %D     date as %m/%d/%y

       %H or %k
              hour (0-23; leading zeroes are  permitted  but  not
              required)

       %I or %l
              hour  (0-12;  leading  zeroes are permitted but not
              required)

       %j     day number of year (001-366)

       %m     month number (1-12; leading  zeroes  are  permitted
              but not required)

       %M     minute  (0-59; leading zeroes are permitted but not
              required)

       %p     locale's equivalent of AM or PM

       %r     time as %I:%M:%S %p

       %R     time as %H:%M

       %S     seconds (0-61; leading zeroes are permitted but not
              required. Extra second allowed for leap years)

       %T     time as %H:%M:%S

       %w     weekday  number  (0-6) with Sunday as the first day
              of the week

       %x     date, using locale's date format

       %X     time, using locale's time format

       %y     year within century (0-99; leading zeroes are  per-
              mitted  but  not  required.   When a century is not
              otherwise specified,  values  in  the  range  69-99
              refer  to  years  in the twentieth century (1969 to
              1999 inclusive); values in the range 00-68 refer to
              years  in  the  twenty-first  century (2000 to 2068
              inclusive).

       %Y     year, including century (for example, 1988)

       Case is ignored when matching items such as month or week-
       day names.

       Some field descriptors can be modified by the E and O mod-
       ifier characters to indicate that an alternative format or
       specification should be used. If the alternative format or
       specification does not exist in the  current  locale,  the
       unmodified field descriptors is used.



GNU                     26 September 1994                       2





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


       The E modifier specifies that the input string may contain
       alternative locale-dependent versions of the date and time
       representation:

       %Ec    the  locale's alternative date and time representa-
              tion.

       %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  %EC  (year only) in the locale's
              alternative representation.

       %EY    the full alternative year representation.

       The O modifier specifies that the numerical input  may  be
       in an alternative locale-dependent format:

       %Od or %Oe
              the day of the month using the locale's alternative
              numeric symbols; leading zeros  are  permitted  but
              not required.

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

       %OI    the hour (12-hour clock) using the locale's  alter-
              native 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  %C)  using  the  locale's



GNU                     26 September 1994                       3





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


              alternative numeric symbols.

       The broken-down time structure tm is defined  in  <time.h>
       as follows:

              struct tm
              {
                      int     tm_sec;         /* seconds */
                      int     tm_min;         /* minutes */
                      int     tm_hour;        /* hours */
                      int     tm_mday;        /* day of the month */
                      int     tm_mon;         /* month */
                      int     tm_year;        /* year */
                      int     tm_wday;        /* day of the week */
                      int     tm_yday;        /* day in the year */
                      int     tm_isdst;       /* daylight saving time */
              };


RETURN VALUE

       The return value of the function is a pointer to the first
       character not processed in this function  call.   In  case
       the input string contains more characters than required by
       the format string the return value points right after  the
       last  consumed  input  character.  In case the whole input
       string is consumed the return value points to the NUL byte
       at  the  end  of the string.  If strptime() fails to match
       all of the format string and therefore an  error  occurred
       the function returns NULL.


NOTES

       In  principle,  this  function  does not initialize tm but
       only stores the values  specified.   This  means  that  tm
       should  be  initialized before the call.  Details differ a
       bit between different Unix systems.  The GNU  libc  imple-
       mentation  does  not  touch  those  fields  which  are not
       explicitly  specified,  except  that  it  recomputes   the
       tm_wday  and  tm_yday  field if any of the year, month, or
       day elements changed.

       This function is available since libc 4.6.8.  Linux  libc4
       and  libc5  includes define the prototype unconditionally;
       glibc2   includes   provide   a   prototype   only    when
       _XOPEN_SOURCE  or  _GNU_SOURCE  are  defined.  The E and O
       locale modifier characters are accepted since libc 5.4.13.
       The  'y' (year in century) specification is taken to spec-
       ify a year in the 20th century by libc4 and libc5.  It  is
       taken to be a year in the range 1950-2049 by glibc 2.0. It
       is taken to be a year in 1969-2068 by glibc 2.1.


SEE ALSO

       time(2), scanf(3), setlocale(3), strftime(3)






GNU                     26 September 1994                       4