 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
getdate(3)
NAME
getdate, getdate_r - Convert formatted string into time/date structure
SYNOPSIS
#include<time.h>
struct tm *getdate(
const char *string );
The following function declarations do not conform to current standards and
are supported only for backward compatibility:
#include<time.h>
struct tm *getdate(
const char *string );
struct tm *getdate_r(
char *string,
struct tm *ptr,
int *getdate_err );
LIBRARY
Standard C Library (libc)Standard C Library (libc.so, libc.a)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
getdate(): XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
string
Points to the user-definable date and/or time specifications.
ptr Points to a time structure.
getdate_err
Points 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. 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 external variable or macro getdate_err is used by getdate() to return
error values.
The following field descriptors are supported:
%% Literal % character
%a Abbreviated weekday name
%A Full weekday name
%b Abbreviated month name
%B Full month name
%c Locale's appropriate date and time representation
%d Day of month: 1 through 31, with optional leading zero
%D Date string formatted as %m/%d/%y
%e Same as %d.
%h Abbreviated month name **Same as %b.????????????
%H Hour: 00 through 23
%I Hour: 01 through 12
%m Month number: 01 through 12
%M Minute: 00 through 59
%n Literal newline character \n
%p Locale's equivalent to AM or PM string
%r Locale's appropriate representation of time (formatted as %I:%M:%S %p
in the POSIX locale).
%R Time formatted as %H:%M
%S Seconds: 00 through 61. Leap seconds, through the use of algorithms,
are allowed but are not predictable.
%t Whitespace up through literal tab
%T Locale's appropriate representation of time in AM and PM notation
(%H:%M:%S in the POSIX locale).
%w Weekday number: 0 (Sunday) through 6 (Saturday)
%x Date formatted as specified by locale
%X Time formatted as specified by locale
%y Year (excluding century). When a century is not otherwise specified
(for example, with %C), 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).
%Y Year (including century) as ccyy (for example, 1996)
%Z Time zone name or no characters if no time zone exists. If the time
zone supplied by %Z is not the time zone that getdate() expects, an
invalid input specification error will result. The getdate() function
calculates an expected time zone based on information supplied to the
function (such as the hour, day, and month).
If the string parameter specifies the date and time incompletely, the
following rules apply:
1. If %Z is being scanned, getdate() initializes the broken-down time to
be the current time in the scanned time zone. Otherwise, it
initializes the broken-down time based on the current local time as if
localtime() had been called.
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, it returns a null pointer 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.
[1] The DATEMSK environment variable either is not set or refers to a null
string.
[2] The file containing the templates could not be opened for reading.
[3] Attempts to fstat() the template file failed.
[4] The template file is not a regular file.
[5] An error occurred while reading the template file.
[6] Memory allocation failed.
[7] No template file line matches the argument string.
[8] The input specification is invalid (for example, February 31). A time
is specified that cannot be represented in a time_t
APPLICATION USAGE
Applications should use %Y (4-digit years) instead of %y (2-digit years).
SEE ALSO
Functions: ctime(3), ctype(3), setlocale(3), strftime(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|