Manual Page Result
0
Command: getdate_r | Section: 3 | Source: Digital UNIX | File: getdate_r.3.gz
getdate(3) Library Functions Manual getdate(3)
NAME
getdate, getdate_r - Convert formatted string into time/date structure
LIBRARY
Standard C Library (libc.so, libc.a)
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(
char *string);
struct tm *getdate_r(
char *string,
struct tm *ptr,
int *getdate_err);
STANDARDS
Interfaces documented on this reference page conform to industry stan-
dards as follows:
getdate(): XPG4-UNIX
Refer to the standards(5) reference page for more information about in-
dustry standards and associated tags.
PARAMETERS
Points to the user-definable date and/or time specifications. Points
to a time structure. 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 quali-
fied pathname, or must refer to a file in the current directory when-
ever 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 re-
turn error values.
The following field descriptors are supported: Literal % character Ab-
breviated weekday name Full weekday name Abbreviated month name Full
month name Locale's appropriate date and time representation Day of
month: 1 through 31, with optional leading zero Date string formatted
as %m/%d/%y Same as %d. Abbreviated month name **Same as
%b.???????????? Hour: 00 through 23 Hour: 01 through 12 Month number:
01 through 12 Minute: 00 through 59 Literal newline character \n Lo-
cale's equivalent to AM or PM string Locale's appropriate representa-
tion of time (formatted as %I:%M:%S %p in the POSIX locale). Time for-
matted as %H:%M Seconds: 00 through 61. Leap seconds, through the use
of algorithms, are allowed but are not predictable. Whitespace up
through literal tab Locale's appropriate representation of time in AM
and PM notation (%H:%M:%S in the POSIX locale). Weekday number: 0
(Sunday) through 6 (Saturday) Date formatted as specified by locale
Time formatted as specified by locale 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). Year (including century) as
ccyy (for example, 1996) Time zone (if any)
If the string parameter specifies the date and time incompletely, the
following rules apply: 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 lo-
cal time as if localtime() had been called. If a year is specified
alone, the remainder of the date defaults to January 1. 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. 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. 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. The DATEMSK environment variable is null or unde-
fined. The template file cannot be opened for reading. Failed to get
file status information. The template file is not a regular file. An
I/O error occurred while reading the template file. Memory allocation
failed (not enough memory available). The template does not have a
line that matches the input. Invalid input specification (for example,
February 31). A time is specified that cannot be represented in a
time_t (representing the time in seconds since 00:00:00 UTC, January 1,
1970).
APPLICATION USAGE
Applications should use %Y (4-digit years) instead of %y (2-digit
years).
RELATED INFORMATION
Functions: ctime(3), ctype(3), setlocale(3), strftime(3)
Standards: standards(5) delim off
getdate(3)