strptime()— Convert String to Date/Time

Format

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

Language Level: XPG4

Threadsafe: Yes.

Locale Sensitive: The behavior of this function might be affected by the LC_CTYPE, LC_TIME, and LC_TOD categories of the current locale. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.

Description

The strptime() function converts the character string pointed to by buf to values that are stored in the tm structure pointed to by tm, using the format specified by format.

The format contains zero or more directives. A directive contains either an ordinary character (not % or a white space), or a conversion specification. Each conversion specification is composed of a % character followed by one or more conversion characters, which specify the replacement required. There must be a white space or other delimiter in both buf and format to be guaranteed that the function will behave as expected. There must be a delimiter between two string-to-number conversions, or the first number conversion may convert characters that belong to the second conversion specifier.

Any whitespace (as specified by isspace()) encountered before a directive is scanned in either the format string or the input string will be ignored. A directive that is an ordinary character must exactly match the next scanned character in the input string. Case is relevant when matching ordinary character directives. If the ordinary character directive in the format string does not match the character in the input string, strptime is not successful. No more characters will be scanned.

Any other conversion specification is matched by scanning characters in the input string until a character that is not a possible character for that specification is found or until no more characters can be scanned. If the specification was string-to-number, the possible character range is +,- or a character specified by isdigit(). Number specifiers do not require leading zeros. If the specification needs to match a field in the current locale, scanning is repeated until a match is found. Case is ignored when matching fields in the locale. If a match is found, the structure pointed to by tm will be updated with the corresponding locale information. If no match is found, strptime is not successful. No more characters will be scanned.

Missing fields in the tm structure may be filled in by strftime if given enough information. For example, if a date is given, tm_yday can be calculated.

Each standard conversion specification is replaced by appropriate characters as described in the following table:

Modified Conversion Specifiers

Some conversion specifiers can be modified by the E or O modifier characters to indicate that an alternate format or specification should be used. If a modified conversion specifier uses a field in the current locale that is unavailable, then the behavior will be as if the unmodified conversion specification were used. For example, if the era string is the empty string "", which means that era is unavailable, then %EY would act like %Y.

Return Value

On successful completion, the strptime() function returns a pointer to the character following the last character parsed. Otherwise, a null pointer is returned. The value of errno may be set to ECONVERT (conversion error).

Example that uses strptime()

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

int main(void)
{
    char buf[100];
    time_t t;
    struct tm *timeptr,result;

    setlocale(LC_ALL,"/QSYS.LIB/EN_US.LOCALE");
    t = time(NULL);
    timeptr = localtime(&t);
    strftime(buf,sizeof(buf), "%a %m/%d/%Y %r", timeptr);

    if(strptime(buf, "%a %m/%d/%Y %r",&result) == NULL)
          printf("\nstrptime failed\n");
   else
   {
          printf("tm_hour:  %d\n",result.tm_hour);
          printf("tm_min:  %d\n",result.tm_min);
          printf("tm_sec:  %d\n",result.tm_sec);
          printf("tm_mon:  %d\n",result.tm_mon);
          printf("tm_mday:  %d\n",result.tm_mday);
          printf("tm_year:  %d\n",result.tm_year);
          printf("tm_yday:  %d\n",result.tm_yday);
          printf("tm_wday:  %d\n",result.tm_wday);
   }

   return 0;
}

/************************************************************
     The output should be similar to:
     Tue 10/30/2001 10:59:10 AM
     tm_hour:  10
     tm_min:  59
     tm_sec:  10
     tm_mon:  9
     tm_mday:  30
     tm_year:  101
     tm_yday:  302
     tm_wday:  2
************************************************************/

Related Information

• asctime() — Convert Time to Character String
• asctime_r() — Convert Time to Character String (Restartable)
• ctime() — Convert Time to Character String
• ctime64() — Convert Time to Character String
• ctime64_r() — Convert Time to Character String (Restartable)
• ctime_r() — Convert Time to Character String (Restartable)
• gmtime() — Convert Time
• gmtime64() — Convert Time
• gmtime64_r() — Convert Time (Restartable)
• gmtime_r() — Convert Time (Restartable)
• localtime() — Convert Time
• localtime64() — Convert Time
• localtime64_r() — Convert Time (Restartable)
• localtime_r() — Convert Time (Restartable)
• setlocale() — Set Locale
• strftime() — Convert Date/Time to String
• time() — Determine Current Time
• time64() — Determine Current Time
• <time.h>
• wcsptime()— Convert Wide Character String to Date/Time