getdate, getdate_r - Convert formatted string into
time/date structure
#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 );
Standard C Library (libc)Standard C Library (libc.so,
libc.a)
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.
Points to the user-definable date and/or time specifications.
Points to a time structure. Points to the local
getdate_err.
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 Abbreviated 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 Locale's equivalent to AM or PM
string Locale's appropriate representation of time (formatted
as %I:%M:%S %p in the POSIX locale). Time formatted
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 twentyfirst
century (2000 to 2068, inclusive). Year (including
century) as ccyy (for example, 1996) 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: 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. 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.
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.
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 either is not set or refers to a null
string. The file containing the templates could not be
opened for reading. Attempts to fstat() the template file
failed. The template file is not a regular file. An
error occurred while reading the template file. Memory
allocation failed. No template file line matches the
argument string. The input specification is invalid (for
example, February 31). A time is specified that cannot be
represented in a time_t
Applications should use %Y (4-digit years) instead of %y
(2-digit years).
Functions: ctime(3), ctype(3), setlocale(3), strftime(3)
Standards: standards(5)
getdate(3)
[ Back ] |
