### strptime -- Convert to Formatted Date and Time

Format

>     #include <time.h>
>     char *strptime(const char *buf, const char *fmt, struct tm *tm);

Language Level: XPG4
strptime uses the format specified by fmt to convert the character string pointed to by buf to values that are stored in the structure pointed to by tm.

The *fmt 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 the isspace function)
- An ordinary character (neither % nor a white-space character)
- A conversion specifier.

Each conversion specifier consists of a % character followed by a conversion character that specifies the replacement required. There must be white-space or other non-alphanumeric characters between any two conversion specifiers.

For a directive composed of white-space characters, strptime scans input up to the first character that is not white space (which remains unscanned), or until no more characters can be scanned.

For a directive that is an ordinary character, strptime scans the next character from the buffer. If the scanned character differs from the one comprising the directive, the directive fails and the differing and subsequent characters remain unscanned.

For a series of directives composed of %n, %t, white-space characters, or any combination, strptime scans up to the first character that is not white space (which remains unscanned), or until no more characters can be scanned.

For any other conversion specification, strptime scans characters until a character matching the next directive is scanned, or until no more characters can be scanned. It then compares these characters, excepting the one matching the next directive, to the locale values associated with the conversion specifier. If a match is found, strptime sets the appropriate tm structure members to values corresponding to the locale information. Case is ignored when items in buf are matched, such as month or weekday names. If no match is found, strptime fails and no more characters are scanned.

The following tables list the conversion specifiers for strptime.

Conversion Specifiers Used by strptime:

Specifier | Meaning
%a | Day of week, using locale's abbreviated or full weekday name.
%A | Day of week, using locale's abbreviated or full weekday name.
%b | Month, using locale's abbreviated or full month name.
%B | Month, using locale's abbreviated or full month name.
%c | Date and time, using locale's date and time.
%C | Century number (year divided by 100 and truncated to an integer).
%d | Day of the month (1-31; leading zeros permitted but not required).
%D | Date as %m/%d/%y.
%e | Day of the month (1-31; leading zeros permitted but not required).
%h | Month, using locale's abbreviated or full month name.
%H | Hour (0-23; leading zeros permitted but not required).
%I | Hour (0-12; leading zeros permitted but not required).
%j | Day number of the year (001-366).
%m | Month number (1-12; leading zeros permitted but not required).
%M | Minute (0-59; leading zeros permitted but not required).
%n | Newline character.
%p | Locale's equivalent of AM or PM.
%r | Time as %I:%M:%S a.m. or %I:%M:%S p.m.
%R | Time in 24 hour notation (%H%M)
%S | Seconds (0-61; leading zeros permitted but not required).
%t | Tab character.
%T | Time as %H:%M:%S.
%U | Week number of the year (0-53; where Sunday is the first day of the week; leading zeros permitted but not required).
%w | Weekday (0-6; where Sunday is 0; leading zeros permitted but not required).
%W | Week number of the year (0-53; where Monday is the first day of the week; leading zeros permitted but not required).
%x | Date, using locale's date format.
%X | Time, using locale's time format.
%y | Year within century (0-99; leading zeros permitted but not required). Note: all years in the range 00-68 are treated as 2000 to 2068.
%Y | Year, including century.
%Z | Time zone name.
%% | Replace with %.

Some directives can be modified by the E or O modifier characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified directive. If the alternative format or specification does not exist in the current locale, the behavior will be as if the unmodified directive were used.

Modified Directives Used by strptime:

Specifier | Meaning
--- | ---
%Ec | Replace with the locale's alternative date and time representation.
%EC | Replace with the name of the base year (period) in the locale's alternative representation.
%Ex | Replace with the locale's alternative date representation.
%EX | Replace with the locale's alternative time representation.
%Ey | Replace with the offset from %EC (year only) in the locale's alternative representation.
%EY | Replace with the full alternative year representation.
%Od | Replace with the day of month, using the locale's alternative numeric symbols, filled as needed with leading zeroes if there is any alternative symbol for zero; otherwise, fill with leading spaces.
%Oe | Replace with the day of the month, using the locale's alternative numeric symbols, filled as needed with leading spaces.
%OH | Replace with the hour (24-hour clock), using the locale's alternative numeric symbols.
%OI | Replace with the hour (12-hour clock), using the locale's alternative numeric symbols.
%Om | Replace with the month, using the locale's alternative numeric symbols.
%OM | Replace with the minutes, using the locale's alternative numeric symbols.
%OS | Replace with the seconds, using the locale's alternative numeric symbols.
%OU | Replace with 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.
%Ow | Replace with the weekday (Sunday=0), using the locale's alternative numeric symbols.
%OW | Replace with the week number of the year (Monday as the first day of the week), using the locale's alternative numeric symbols.
%Oy | Replace with the year (offset from %C) in the locale's alternative representation, using the locale's alternative numeric symbols.

Return Value
If successful, strptime returns a pointer to the character following the last character parsed. Otherwise, a null pointer is returned.

Example
This example uses strptime to convert a string to the structure xmas, then prints the contents of the structure.

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

    int main(void)
    {
       struct tm xmas;

       if (NULL == strptime("12/25/94 12:00:01", "%D %T", &xmas)) {
          printf("strptime() failed.\n");
          exit(EXIT_FAILURE);
       }
       printf("tm_sec  = %3d\n", xmas.tm_sec );
       printf("tm_min  = %3d\n", xmas.tm_min );
       printf("tm_hour = %3d\n", xmas.tm_hour);
       printf("tm_mday = %3d\n", xmas.tm_mday);
       printf("tm_mon  = %3d\n", xmas.tm_mon );
       printf("tm_year = %3d\n", xmas.tm_year);
       return 0;

       /***********************************************************
          The output should be similar to :

          tm_sec  =   1
          tm_min  =   0
          tm_hour =  12
          tm_mday =  25
          tm_mon  =  12
          tm_year =  94
       ***********************************************************/
    }

asctime -- Convert Time to Character String
ctime -- Convert Time to Character String
gmtime -- Convert Time
localtime -- Convert Time
time -- Determine Current Time
strftime -- Convert to Formatted Time
wcsftime -- Convert to Formatted Date and Time
<time.h>