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 strptime()
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:
Specifier | Meaning |
---|---|
%a | Name of day of the week, can be either the full name or an abbreviation. |
%A | Same as %a. |
%b | Month name, can be either the full name or an abbreviation. |
%B | Same as %b. |
%c | Date/time, in the format of the locale. |
%C | Century number [00–99]. Calculates the year if a two-digit year is used. |
%d | Day of the month [1–31]. |
%D | Date format, same as %m/%d/%y. |
%e | Same as %d. |
%g | 2 digit year portion of ISO week date [00–99]. |
%G | 4 digit year portion of ISO week date. Can be negative. |
%h | Same as %b. |
%H | Hour in 24-hour format [0–23]. |
%I | Hour in 12-hour format [1-12]. |
%j | Day of the year [1-366]. |
%m | Month [1-12]. |
%M | Minute [0-59]. |
%n | Skip all whitespaces until a newline character is found. |
%p | AM or PM string, used for calculating the hour if 12-hour format is used. |
%r | Time in AM/PM format of the locale. If not available in the locale time format, defaults to the POSIX time AM/PM format: %I:%M:%S %p. |
%R | 24-hour time format without seconds, same as %H:%M. |
%S | Second [00-61]. The range for seconds allows for a leap second and a double leap second. |
%t | Skip all whitespaces until a tab character is found. |
%T | 24 hour time format with seconds, same as %H:%M:%S . |
%u | Weekday [1–7]. Monday is 1 and Sunday is 7. |
%U | Week number of the year [0-53], Sunday is the first day of the week. Used in calculating the day of the year. |
%V | ISO week number of the year [1-53]. Monday is the first day of the week. If the week containing January 1st has four or more days in the new year, it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1 of the new year. Used in calculating the day of the year. |
%w | Weekday [0 -6]. Sunday is 0. |
%W | Week number of the year [0-53]. Monday is the first day of the week. Used in calculating the day of the year. |
%x | Date in the format of the locale. |
%X | Time in the format of the locale. |
%y | 2-digit year [0-99]. |
%Y | 4-digit year. Can be negative. |
%z | UTC offset. Output is a string with
format +HHMM or -HHMM , where + indicates
east of GMT, - indicates west of GMT, HH indicates the number of hours
from GMT, and MM indicates the number of minutes from GMT. |
%Z | Time zone name. |
%% | % character. |
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.
Specifier | Meaning |
---|---|
%Ec | Date/time for current era. |
%EC | Era name. |
%Ex | Date for current era. |
%EX | Time for current era. |
%Ey | Era year. This is the offset from the base year. |
%EY | Year for the current era. |
%Od | Day of the month using alternate digits. |
%Oe | Same as %Od. |
%OH | Hour in 24-hour format using alternate digits. |
%OI | Hour in 12-hour format using alternate digits. |
%Om | Month using alternate digits. |
%OM | Minutes using alternate digits. |
%OS | Seconds using alternate digits. |
%Ou | Day of the week using alternate digits. Monday is 1 and Sunday is 7. |
%OU | Week number of the year using alternate digits. Sunday is the first day of the week. |
%OV | ISO week number of the year using alternate digits. See %V for explanation of ISO week number. |
%Ow | Weekday using alternate digit. Sunday is 0 and Saturday is 6. |
%OW | Week number of the year using alternate digits. Monday is the first day of the week. |
%Oy | 2-digit year using alternate digits. |
%OZ | Abbreviated time zone name. |
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
#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