Converts a character string into date and time values that are
stored in a tm structure. Conversion is controlled by a format
string.
Format
#include <time.h>
char *strptime (const char *buf, const char *format, struct tm
*timeptr);
1 – Function Variants
The strptime function has variants named _strptime32 and _
strptime64 for use with 32-bit and 64-bit pointer sizes,
respectively.
2 – Arguments
buf
A pointer to the character string to convert.
format
A pointer to the string that defines how the input string is
converted.
timeptr
A pointer to the local time structure. The tm structure is
defined in the <time.h> header file.
3 – Description
The strptime function converts the string pointed to by buf into
values that are stored in the structure pointed to by timeptr.
The string pointed to by format defines how the conversion is
performed.
The strptime function modifies only those fields in the tm
structure that have corresponding conversion specifications
in the format. In particular, strptime never sets the tm_isdst
member of the tm structure.
The format string consists of zero or more directives. A
directive is composed of one of the following:
o One or more white-space characters (as defined by the isspace
function). This directive causes the function to read input up
to the first character that is not a white-space character.
o Any character other than the percent character (%) or a white-
space character. This directive causes the function to read
the next character. The character read must be the same as the
character that comprises the directive. If the character is
different, the function fails.
o A conversion specification. A conversion specification defines
how characters in the input string are interpreted as values
that are then stored in the tm structure. A conversion
specification consists of a percent (%) character followed
by a conversion specifier. strptime Conversion Specifications
lists the valid conversion specifications.
The strptime function uses fields in the LC_TIME category of the
program's current locale to provide a value.
NOTE
To be compliant with X/Open CAE Specification System
Interfaces and Headers Issue 5 (commonly known as XPG5), the
strptime function processes the "%y" directive differently
than in previous versions of the C RTL.
With Version 6.4 and higher of the C compiler, for a two-
digit year within the century if no century is specified,
"%y" directive values range from:
o 69 to 99 refer to years in the twentieth century (1969 to
1999 inclusive)
o 00 to 68 refer to years in the twenty-first century (2000
to 2068 inclusive)
In previous (XPG4-compliant) versions of the C RTL,
strptime interpreted a two-digit year with no century
specified as a year within the twentieth century.
The XPG5-compliant strptime is now the default version in
the C RTL.
To obtain the old, XPG4-compliant strptime function
behavior, specify one of the following:
o Define the DECC$XPG4_STRPTIME logical name as follows:
$ DEFINE DECC$XPG4_STRPTIME ENABLE
or:
o Call the XPG4 strptime directly as the function
decc$strptime_xpg4.
To return to using the XPG5 strptime version, DEASSIGN the
DECC$XPG4_STRPTIME logical name:
$ DEASSIGN DECC$XPG4_STRPTIME
Table REF-9 strptime Conversion Specifications
SpecificaReplaced by
%a The weekday name. This is either the abbreviated or the
full name.
%A Same as %a.
%b The month name. This is either the abbreviated or the
full name.
%B Same as %b.
%c The date and time using the locale's date format.
%Ec The locale's alternative date and time representation.
%C The century number (the year divided by 100 and
truncated to an integer) as a decimal number (00 - 99).
Leading zeros are permitted.
%EC The name of the base year (period) in the locale's
alternative representation.
%d The day of the month as a decimal number (01 - 31).
Leading zeros are permitted.
%Od The day of the month using the locale's alternative
numeric symbols.
%D Same as %m/%d/%y.
%e Same as %d.
%Oe The date of the month using the locale's alternative
numeric symbols.
%h Same as %b.
%H The hour (24-hour clock) as a decimal number (00 - 23).
Leading zeros are permitted.
%OH The hour (24-hour clock) using the locale's alternative
numeric symbols.
%I The hour (12-hour clock) as a decimal number (01 - 12).
Leading zeros are permitted.
%OI The hour (12-hour clock) using the locale's alternative
numeric symbols.
%j The day of the year as a decimal number (001 - 366).
%m The month as a decimal number (01 - 12). Leading zeros
are permitted.
%Om The month using the locale's alternative numeric
symbols.
%M The minute as a decimal number (00 - 59). Leading zeros
are permitted.
%OM The minutes using the locale's alternative numeric
symbols.
%n Any white-space character.
%p The locale's equivalent of the AM/PM designations
associated with a 12-hour clock.
%r The time in AM/PM notation (%I:%M:%S %p).
%R The time in 24-hour notation (%H:%M).
%S The second as a decimal number (00 - 61). Leading zeros
are permitted.
%OS The seconds using the locale's alternative numeric
symbols.
%t Any white-space character.
%T The time (%H:%M:%S).
%U The week number of the year (the first Sunday as the
first day of week 1) as a decimal number (00 - 53).
Leading zeros are permitted.
%OU The week number of the year (Sunday as the first day
of the week) using the locale's alternative numeric
symbols.
%w The weekday as a decimal number (0 [Sunday] - 6).
Leading zeros are permitted.
%Ow The weekday as a number (Sunday=0) using the locale's
alternative numeric symbols.
%W The week number of the year (the first Monday as the
first day of week 1) as a decimal number (00 - 53).
Leading zeros are permitted.
%OW The week number of the year (Monday as the first day
of the week) using the locale's alternative numeric
symbols.
%x The locale's appropriate date representation.
%Ex The locale's alternative date representation.
%EX The locale's alternative time representation.
%X The locale's appropriate time representation.
%y The year without century as a decimal number (00 - 99).
%Ey The offset from the base year (%EC) in the locale's
alternative representation.
%Oy The year without the century using the locale's
alternative numeric symbols.
%Y The year with century as a decimal number.
%EY The locale's full alternative year representation.
%% Literal % character.
4 – Return Values
x A pointer to the character following the last
character parsed.
NULL Indicates that an error occurred. The contents
of the tm structure are undefined.
5 – Example
#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <time.h>
#include <locale.h>
#include <errno.h>
#define NUM_OF_DATES 7
#define BUF_SIZE 256
/* This program takes a number of date and time strings and */
/* converts them into tm structs using strptime(). These tm */
/* structs are then passed to strftime() which will reverse the */
/* process. The resulting strings are then compared with the */
/* originals and if a difference is found then an error is */
/* displayed. */
main()
{
int count,
i;
char buffer[BUF_SIZE];
char *ret_val;
struct tm time_struct;
char dates[NUM_OF_DATES][BUF_SIZE] =
{
"Thursday 01 January 1970 00:08:20",
"Tuesday 29 February 1972 08:26:40",
"Tuesday 31 December 1991 23:59:59",
"Wednesday 01 January 1992 00:00:00",
"Sunday 03 May 1992 13:33:20",
"Monday 04 May 1992 17:20:00",
"Friday 15 May 1992 03:20:00"};
for (i = 0; i < NUM_OF_DATES; i++) {
/* Convert to a tm structure */
ret_val = strptime(dates[i], "%A %d %B %Y %T", &time_struct);
/* Check the return value */
if (ret_val == (char *) NULL) {
perror("strptime");
exit(EXIT_FAILURE);
}
/* Convert the time structure back to a formatted string */
count = strftime(buffer, BUF_SIZE, "%A %d %B %Y %T",&time_struct);
/* Check the return value */
if (count == 0) {
perror("strftime");
exit(EXIT_FAILURE);
}
/* Check the result */
if (strcmp(buffer, dates[i]) != 0) {
printf("Error: Converted string differs from the original\n");
}
else {
printf("Successfully converted <%s>\n", dates[i]);
}
}
}
Running the example program produces the following result:
Successfully converted <Thursday 01 January 1970 00:08:20>
Successfully converted <Tuesday 29 February 1972 08:26:40>
Successfully converted <Tuesday 31 December 1991 23:59:59>
Successfully converted <Wednesday 01 January 1992 00:00:00>
Successfully converted <Sunday 03 May 1992 13:33:20>
Successfully converted <Monday 04 May 1992 17:20:00>
Successfully converted <Friday 15 May 1992 03:20:00>