strptime(S)

Syntax

#include <time.h>

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

Description

The format is made up of zero or more directives, each of which can contain one of the following: one or more white-spaces as recognized by isspace(S); an ordinary character other than a % or a white-space character; a conversion specification.

Each conversion specification is introduced by the percent character (%). A conversion character following the percent character indicates the type of conversion to be applied. Conversion specifications must be separated by white-space or other non-alphanumeric characters. The following conversion specifications may be used:

%a, %A

day of week; both the abbreviated or full weekday name of the locale may be used in the input.

%b, %B

month; both the abbreviated or full month name of the locale may be used.

%c

date and time; locale's date and time format is used (as in %x %X described below).

%C

century number (in the range [0,99]); leading zeros may be used but are not required. Year values in the range 69-99 refer to years in the twentieth century (1969 to 1999 inclusive); values in the range 00-68 refer to years in the twenty-first century (2000 to 2068 inclusive).

%d

day of month in the range [1,31]; leading zeros may be used but are not required.

%D

date; the expected format: %m/%d/%y.

%e

equivalent to %d.

%h

equivalent to %b.

%H

hour in the range [0,23] (24-hour clock); leading zeros may be used but are not required.

%I

hour in the range [1,12] (12-hour clock); leading zeros may be used but are not required.

%j

day number of the year [1,366]; leading zeros may be used but are not required.

%m

month number [1,12]; leading zeros may be used but are not required.

%M

minute [0-59]; leading zeros may be used but are not required.

%n

any white space

%p

locale's equivalent of a.m or p.m

%r

time; the expected format: %I:%M:%S %p. Note the space between %S and %p.

%R

time; the expected format: %H:%M.

%S

seconds [0,61]; leading zeros may be used but are not required.

%t

any white space.

%T

time; the expected format: %H:%M:%S.

%U

week number of the year as a decimal number in the range of [0, 53] (a week is treated as starting from Sunday); leading zeros may be used but are not required.

%w

weekday as a decimal number [0,6], with Sunday being 0; leading zeros may be used but are not required.

%W

week number of the year as a decimal number [0, 53] a week is treated as starting from Monday); leading zeros may be used but are not required.

%x

date; use the locale's date format.

%X

time; use the locale's time format.

%y

year within century. When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969 to 1999 inclusive); values in the range 00-68 refer to years in the twenty-first century (2000 to 2068 inclusive). Leading zeros may be used but are not required.

%Y

year, including the century (for example, 1992).

%%

the percent sign %.

Modified directives

%Ec

date and time in locale's alternative representation.

%EC

name of the base year in the locale's alternative representation.

%Ex

date in locale's alternative representation.

%EX

time in locale's alternative representation.

%Ey

offset from %EC (year only) in the locale's alternative representation.

%EY

the full alternative year representation, including the century.

%Od

day of the month expressed in the locale's alternative numeric symbols; leading zeros may be used but are not required.

%Oe

equivalent to %Od .

%OH

hour (24-hour clock), expressed in the locale's alternative numeric symbols.

%OI

hour (12-hour clock), expressed in the locale's alternative numeric symbols.

%Om

month, expressed in the locale's alternative numeric symbols.

%OM

minutes, expressed in the locale's alternative numeric symbols.

%OS

seconds, expressed in the locale's alternative numeric symbols.

%OU

week number of the year (a week is treated as starting from Sunday). Expressed in the locale's alternative numeric symbols.

%Ow

number of the weekday (Sunday being zero), expressed in the locale's alternative numeric symbols.

%OW

week number of the year (a week is treated as starting from Monday), expressed in the locale's alternative numeric symbols.

%Oy

year (offset from %C) in the locale's alternative representation, expressed in the locale's alternative numeric symbols.

To execute a series of directives composed of %n, %t, white spaces or any combination of them, strptime( ) simply scans the input buffer until the first non-white-space character is encountered, or until no more characters can be scanned. No value is stored for this type of directives.

To execute a directive composed of an ordinary character, strptime( ) first read the next character from the input buffer. These two characters must agree for the directive to succeed. No value is stored for this type of directives either. If the two characters disagree, the directive fails, and the differing and subsequent characters in the input buffer remain unscanned.

To execute any other conversion directives, strptime( ) scans characters from the input buffer and then compares against the locale values associated with the conversion specifier. The values these characters represent should be within the correct range. If a match is found, i.e., if these characters (in the format of the conversion specifier) represent valid values, the appropriate tm structure members will have their values set corresponding to the locale information. Values of other structure members in the structure tm remain unchanged. Case is ignored when items, such as month or weekday names, are matched in buf. If there is no match, strptime( ) fails and no more characters will be scanned.

For example, in the POSIX locale, the program fragment below:

   struct tm tm;
    ...
   memset ((void *) &tm, 0, sizeof(struct tm));
   strptime("Jan 1, 1993, 10:20 pm", "%b %d, %Y, %R %p", &tm);
    ...

   tm_sec = 0     tm_min  = 20     tm_hour = 22     tm_day = 1
   tm_mon = 0     tm_year = 93     tm_wday = 5      tm_yday= 0  

   strptime("Jan 1, 1993, 10:20 p.m", "%b %d, %Y, %R %p", &tm);

More information on how and where values such as weekday names are defined may be found in localedef(C) or timtbl(M).

Return values

Diagnostics

[ENOSYS]

The functionality is not implemented.

Notes

A few formats used by strftime( ) are very similar to formats described here. Several equivalent formats and the special processing of white-space characters are provided in strptime so that identical format strings accepted by strptime may also be accepted by strftime.

See also

Standards conformance