strptime - Convert a string into date and time

Definition

#include <time.h>

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

strptime converts the string indicated by *buf into individual date and time values which are stored in the structure indicated by *tm.

Parameters

const char *buf

Date and time string to be converted.

struct tm *tm

Result structure in which the converted individual date and time values are stored.
The structure is not initialized with zeros by strptime. The values set by the user remain intact as long as they are not modified by conversion statements or implicit calculations.
The structure element tm_isdst is never changed.
Date adjustment may be carried out implicitly, i.e. if the date entry is incomplete, the missing structure elements are added and a plausibility check is made between the structure elements. However, this is only made if a week number was specified via %U or %W. In this case, the year entry (tm_year) and weekday (tm_wday) are used to calculate and reassign the day in the year (tm_yday), the day of the month (tm_mday) and the month of the year (tm_mon). The weekday is assigned the value 0 if it was not explicitly specified with %w, %a or %A .

const char *format

The format string contains none, one or more conversion directives. Each conversion directive comprises one of the following elements:
one or more white-space characters (as defined in isspace)
a standard character (neither % nor white-space character)
or a conversion specification.

Each conversion specification consists of a % sign followed by a conversion character which specifies the desired conversion. Each conversion specification consists of a % character followed by a conversion character that specifies the desired conversion. With conversion specifications that expect a numeric value, the string to be converted may contain not more digits than specified in the format description. I.e. additional leading zeroes are not allowed. If between two conversion specifications there is neither a white-space character nor an non-alphanumeric character, the numbers of digits even must be the same as in the format description.

The following conversion characters are supported:

%%	Replaced by %
%a	Day of the week, whereby the name from the locale is used. Either the abbreviated or full name can be specified.
%A	Same meaning as %a
%b	Month, whereby the name from the locale is used. Either the abbreviated or full name can be specified.
%B	Same meaning as %b
%c	Date and time display according to the definition in the locale.
%C	Century (four-digit year number divided by 100 as whole number) (00-99).
%d	Day of the month (01-31).
%D	Date as %m/%d/%y
%e	Same meaning as %d
%h	Same meaning as %b
%H	Hour (00-23), 24-hour clock.
%I	Hour (01-12), 12-hour clock.
%j	Day of the year (001-366).
%m	Number of the month (01-12).
%M	Minute (00-59)
%n	Replaced by a white-space character.
%p	Equivalent identifier of the locale for AM or PM.
%r	Time in the format %I:%M:%S%p
%R	Time in the format %H:%M
%S	Seconds (00-61), permits leap seconds
%t	Replaced by a white-space character.
%T	Time in the format %H:%M:%S
%U	Number of the week in the year (00-53). The first week begins with the first Sunday of the year. All days before the first Sunday of the year belong to week 0.
%w	Day of the week as a number (0-6), Sunday = 0.
%W	Number of the week in the year (00-53), Monday is the first day of week 1. All days before the first Monday of the year belong to week 0.
%x	Date as represented in the locale.
%X	Time as represented in the locale.
%y	Two-digit year number (00-99). Year numbers between 00 and 68 are interpreted as the years 2000 through 2068, while year numbers between 69 and 99 are interpreted as the years 1969 through 1999.
%Y	Four-digit year number in the form ccyy (e.g. 1966 or 2001).

A conversion directive comprising white-space characters is implemented by reading the input up to the first character that is not a white-space character (this character remains unread) or until no further characters exist.

A conversion directive comprising a standard character is implemented by reading the next character from the buffer. If the character read from the buffer does not match the character in the conversion directive, the action fails and the buffer character and all subsequent characters remain unread.

A sequence of conversion directives comprising %n, %t, white-space characters, and combinations thereof is implemented by reading up to the first character that is not a white-space character (this character remains unread) or until no further characters exist.

All other conversion specifications are implemented by reading all characters until a character matching the next conversion directive is read (this character remains in the buffer) or until no further characters exist. The characters that have been read are then compared with the values in the locale that correspond to the conversion specification. If the appropriate value is found in the locale, the corresponding structure elements of the tm structure are set to the values corresponding to this information.
The search is not case-sensitive if elements such as the names of days or months are being compared.
If no appropriate value is found in the locale, strptime fails and no further characters are read.

Return val.

Pointer to the character behind the last character read

if successful

NULL pointer

in all other cases                                                      

Note

The special handling of white-space characters and many “identical formats” should make it easier to implement identical format strings for strftime and strptime.

See also

scanf, strftime, time.