Technical Reference: Base Operating System and Extensions, Volume 2

strptime Subroutine

Purpose

Converts a character string to a time value.

Library

Standard C Library (libc.a)

Syntax

#include <time.h>

char *strptime ( Buf, Format, Tm) const char *Buf, *Format; struct tm *Tm;

Description

The strptime subroutine converts the characters in the Buf parameter to values that are stored in the Tm structure, using the format specified by the Format parameter.

Parameters

Buf	Contains the character string to be converted by the strptime subroutine.
Format	Contains format specifiers for the strptime subroutine. The Format parameter contains 0 or more specifiers. Each specifier is composed of one of the following elements: One or more white-space characters An ordinary character (neither % [percent sign] nor a white-space character) A format specifier

Note

If more than one format specifier is present, they must be separated by white space or a non-percent/non-alphanumeric character. If the seperator between format specifiers is other than white space, the Buf string should hold the same seperator at the corresponding locations.

The LC_TIME category defines the locale values for the format specifiers. The following format specifiers are supported:

%a	Represents the weekday name, either abbreviated as specified by the abday statement or full as specified by the day statement.
%A	Represents the weekday name, either abbreviated as specified by the abday statement or full as specified by the day statement.
%b	Represents the month name, either abbreviated as specified by the abmon statement or full as specified by the month statement.
%B	Represents the month name, either abbreviated as specified by the abmon statement or full as specified by the month statement.
%c	Represents the date and time format defined by the d_t_fmt statement in the LC_TIME category.
%C	Represents the century number (0 through 99); leading zeros are permitted but not required.
%d	Represents the day of the month as a decimal number (01 to 31).
%D	Represents the date in %m/%d/%y format (for example, 01/31/91).
%e	Represents the day of the month as a decimal number (01 to 31).
%E	Represents the combined alternate era year and name, respectively, in %o %N format.
%h	Represents the month name, either abbreviated as specified by the abmon statement or full as specified by the month statement.
%H	Represents the 24-hour-clock hour as a decimal number (00 to 23).
%I	Represents the 12-hour-clock hour as a decimal number (01 to 12).
%j	Represents the day of the year as a decimal number (001 to 366).
%m	Represents the month of the year as a decimal number (01 to 12).
%M	Represents the minutes of the hour as a decimal number (00 to 59).
%n	Represents any white space.
%N	Represents the alternate era name.
%o	Represents the alternate era year.
%p	Represents the a.m. or p.m. string defined by the am_pm statement in the LC_TIME category.
%r	Represents 12-hour-clock time with a.m./p.m. notation as defined by the t_fmt_ampm statement, usually in the format %I:%M:%S %p.
%S	Represents the seconds of the minute as a decimal number (00 to 61). The decimal number range of 00 to 61 provides for leap seconds.
%t	Represents any white space.
%T	Represents 24-hour-clock time in the format %H:%M:%S (for example, `16:55:15`).
%U	Represents the week of the year as a decimal number (00 to 53). Sunday, or its equivalent as defined by the day statement, is considered the first day of the week for calculating the value of this field descriptor.
%w	Represents the day of the week as a decimal number (0 to 6). Sunday, or its equivalent as defined by the day statement in the LC_TIME category, is considered to be 0 for calculating the value of this field descriptor.
%W	Represents the week of the year as a decimal number (00 to 53). Monday, or its equivalent as defined by the day statement in the LC_TIME category, is considered the first day of the week for calculating the value of this field descriptor.
%x	Represents the date format defined by the d_fmt statement in the LC_TIME category.
%X	Represents the time format defined by the t_fmt statement in the LC_TIME category.
%y	Represents the year within century. Note When the environment variable XPG_TIME_FMT=ON, %y is the year within the 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 2000 to 2068, inclusive.
%Y	Represents the year as a decimal number (for example, `1989`).
%Z	Represents the time-zone name, if one can be determined (for example, `EST`). No characters are displayed if a time zone cannot be determined.
%%	Specifies a % (percent sign) character.

Some format specifiers can be modified by the E and O modifier characters to indicate an alternative format or specification. If the alternative format or specification does not exist in the current locale, the behavior will be as if the unmodified format specifier were used. The following modified format specifiers are supported:

%Ec	Represents the locale's alternative appropriate date and time as defined by the era_d_t_fmt statement.
%EC	Represents the base year (or other time period) in the locale's alternative form as defined by the era statement under the era_name category of the current era.
%Ex	Represents the alternative date as defined by the era_d_fmt statement.
%EX	Represents the locale's alternative time as defined by the era_t_fmt statement.
%Ey	Represents the offset from the %EC format specifier (year only) in the locale's alternative form.
%EY	Represents the full alternative-year format.
%Od	Represents the month using the locale's alternative numeric symbols. Leading 0's are permitted but not required.
%Oe	Represents the month using the locale's alternative numeric symbols. Leading 0's are permitted but not required.
%OH	Represents the hour in 24-hour-clock time using the locale's alternative numeric symbols.
%OI	Represents the hour in 12-hour-clock time using the locale's alternative numeric symbols.
%Om	Represents the month using the locale's alternative numeric symbols.
%OM	Represents the minutes using the locale's alternative numeric symbols.
%OS	Represents the seconds using the locale's alternative numeric symbols.
%OU	Represents the week number of the year using the locale's alternative numeric symbols. Sunday is considered the first day of the week. Use the rules corresponding to the %U format specifier.
%Ow	Represents the day of the week using the locale's alternative numeric symbols. Sunday is considered the first day of the week.
%OW	Represents the week number of the year using the locale's alternative numeric symbols. Monday is considered the first day of the week. Use the rules corresponding to the %W format specifier.
%Oy	Represents the year (offset from %C) using the locale's alternative numeric symbols.

A format specification consisting of white-space characters is performed by reading input until the first nonwhite-space character (which is not read) or up to no more characters can be read.

A format specification consisting of an ordinary character is performed by reading the next character from the Buf parameter. If this character differs from the character comprising the directive, the directive fails and the differing character and any characters following it remain unread. Case is ignored when matching Buf items, such as month or weekday names.

A series of directives composed of %n format specifiers, %t format specifiers, white-space characters, or any combination of the three items is processed by reading up to the first character that is not white space (which remains unread), or until no more characters can be read.

Tm	Specifies the structure to contain the output of the strptime subroutine. If a conversion fails, the contents of the Tm structure are undefined.

Return Values

If successful, the strptime subroutine returns a pointer to the character following the last character parsed. Otherwise, a null pointer is returned.

Related Information

The scanf (scanf, fscanf, sscanf, or wsscanf Subroutine) subroutine, strfmon Subroutine, strftime (strftime Subroutine) subroutine, time subroutine, wcsftime (wcsftime Subroutine) subroutine.

LC_TIME Category in the Locale Definition Source File Format in AIX 5L Version 5.2 Files Reference.

Subroutines, Example Programs, and Libraries in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview and List of Time and Monetary Formatting Subroutines in AIX 5L Version 5.2 National Language Support Guide and Reference.