NAME

getdate − Converts formatted string into time/date structure

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include<time.h>
extern int getdate_err; struct tm ∗getdate(
char ∗string); struct tm ∗getdate_r(
char ∗string,
struct tm ∗ptr,
int ∗getdate_err);

PARAMETERS

stringPoints to the user-definable date and/or time specifications. 

ptrPoints to a time structure. 

getdate_errPoints to the local getdate_err. 

DESCRIPTION

The getdate() function fills a struct tm based on a combination of the supplied string argument and the template file of allowable formats for that argument. 

The template file is obtained from the DATEMSK environment variable.  As the pathname is passed to fopen(), it must either be a fully qualified pathname, or must refer to a file in the current directory whenever getdate() is called. 

The template file is read line by line, and each line is parsed against the argument string in an attempt to make a match.  All comparisons are made without regard to case insensitive.  A matching template line will result in a valid struct tm being filled in and returned.  In the event that no match is found, an error is returned in getdate_err. 

Each line of the template file provides a possible format to match against the input string.  The format is specified by combining special time/date specifier characters preceded by % to indicate the particular time/date functions desired.  The specifiers are listed below. 

SpecifierResult matched in argument string

%%Literal % character

%aAbbreviated day of the week

%AFull name of the day of the week

%bAbbreviated month of the year

%BFull name of the month of the year

%cLocale’s appropriate date and time representation

%dMonth day 1 through 31, with optional leading zero

%DDate string formatted as %m/%d/%y

%eMonth day 1 through 31, with optional leading zero

%hAbbreviated month of the year

%HHour 00 through 24

%IHour 01 through 12

%mMonth 01 through 12

%MMinute 00 through 59

%SSecond 00 through 59

%nLiteral newline character \n

%pLocale’s AM or PM string

%RTime formatted as %H:%M

%rTime formatted as %I:%M:%S %p

%tWhitespace up through literal tab

%TTime formatted as %H:%M:%S

%wWeekday number, Sunday as zero through Saturday as 6

%xDate formatted as specified by locale

%XTime formatted as specified by locale

%yYear of century 00 through 99

%YYear formatted 19%y

%ZTime Zone (if any)

If the string parameter specifies the date and time incompletely, the following rules apply:

     1.The tm structure is initially filled in with the current date and time. 

     2.If a year is specified alone, the remainder of the date defaults to January 1. 

     3.If a month is specified without a day of the month or day of the week, the next month matching that month is used, starting with the current month.  The year advances if the matching month is beyond the current year.  The day of the month defaults to the 1st. 

     4.If a day of the week is specified, the next date matching that day is used, starting with the current day.  The month advances if the matching day is beyond the end of the current month.  The year may advance similarly. 

     5.In cases 2, 3 and 4, the time of day is not altered unless it is explicitly specified.  If time alone is specified, the date defaults to today (the current day), unless the time specified is earlier than now (the current time), in which case the date defaults to tomorrow. 

RETURN VALUES

Upon successful completion, the getdate() function returns a pointer to a struct tm. Otherwise, NULL is returned and the external variable getdate_err is set to indicate the error. 

Upon successful completion, the getdate_r function returns pointer struct tm. Otherwise, NULL is returned and the int value pointed to by the getdate_err pointer is set to indicate the error. 

ERRORS

If an error is detected, getdate() will return NULL and set the error number in getdate_err.  The possible error numbers and their meanings are listed below. 

NumberDescription

1The DATEMSK environment variable either is not set or refers to a null string. 

2The file containing the templates could not be opened for reading. 

3Attempts to fstat() the template file failed. 

4The template file is not a regular file. 

5An error occurred while reading the template file. 

6(This error is not currently assigned.) 

7No template file line matches the argument string. 

8The date specified is unreasonable (for example, June 31). 

RELATED INFORMATION

Functions: ctime(3), ctype(3), setlocale(3), strftime(3).