DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

strptime(S-osr5)


strptime -- date and time conversion

Syntax

cc . . . -lc

#include <time.h>

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

Description

strptime(S-osr5) scans the input character string representing a date and time value and pointed to by buf, converts the string to date and time values, and stores these output values in the tm structure pointed to by tm. The input string is interpreted and converted according to the format specified by the character string pointed to by format.

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-osr5); 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

If an alternative format or specification exists in the current locale, the E and O modifier characters can modify some directives to use the alternative format. The modifier is ignored if alternative format does not exist. The following modifications may be requested:

%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.
strptime executes most directives in two steps: the input buffer buf is first scanned until a character matching the next directive is encountered or no more characters can be scanned; comparisons or the conversion and storing of values are then performed as directed. The character belonging to the next directive remains un-scanned.

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);
    ...
will cause the following structure members of tm to take the values below:
   tm_sec = 0     tm_min  = 20     tm_hour = 22     tm_day = 1
   tm_mon = 0     tm_year = 93     tm_wday = 5      tm_yday= 0  
However, the statement below will fail:
   strptime("Jan 1, 1993, 10:20 p.m", "%b %d, %Y, %R %p", &tm);
because of the extra dot (.) between "p" and "m".

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

Return values

strptime( ) returns a pointer to the character immediately after the last character has been parsed successfully. Otherwise, it returns a null pointer.

Diagnostics

strptime( ) will fail if the following is true:

[ENOSYS]
The functionality is not implemented.

Notes

The range of %S is [0, 61] rather than [0, 59] to allow for the occasional leap second, and the even more rare double leap second.

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

locale(M) localedef(C), localedef(F), scanf(S-osr5), setlocale(S-osr5), strftime(S-osr5), time(S-osr5)

Standards conformance

strptime( ) is conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992.
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 -- 02 June 2005