| STRPTIME(3P) | POSIX Programmer's Manual | STRPTIME(3P) |
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.
strptime — date and time conversion
#include <time.h>
char *strptime(const char *restrict buf, const char *restrict format,
struct tm *restrict tm);
The strptime() function shall convert the character string pointed to by buf to values which are stored in the tm structure pointed to by tm, using the format specified by format.
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 isspace()); 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:
The conversions are determined using the LC_TIME 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:
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 C or Y.
Some conversion specifiers can be modified by the E and O 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.
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 %n, %t, 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 tm structure members are set to values corresponding to the locale information. Case is ignored when matching items in buf such as month or weekday names. If no match is found, strptime() fails and no more characters are scanned.
Upon successful completion, strptime() shall return a pointer to the character following the last character parsed. Otherwise, a null pointer shall be returned.
No errors are defined.
The following sections are informative.
The following example demonstrates the use of strptime() to convert a string into broken-down time. The broken-down time is then converted into seconds since the Epoch using mktime().
#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);"
Several ``equivalent to'' formats and the special processing of white-space characters are provided in order to ease the use of identical format strings for strftime() and strptime().
It should be noted that dates constructed by the strftime() function with the %Y or %C%y conversion specifiers may have values larger than 9999. If the strptime() function is used to read such values using %C%y or %Y, the year values will be truncated to four digits. Applications should use %+w%y or %+xY 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 strftime().
It is unspecified whether multiple calls to strptime() using the same tm structure will update the current contents of the structure or overwrite all contents of the structure. Conforming applications should make a single call to strptime() with a format and all data needed to completely specify the date and time being converted.
See the RATIONALE section for strftime().
None.
fprintf(), fscanf(), strftime(), time()
The Base Definitions volume of POSIX.1‐2017, <time.h>
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 .
| 2017 | IEEE/The Open Group |