Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
XPG4.2
Single UNIX Specification, Version 3
Language Environment®
|
both |
|
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <time.h>
struct tm *getdate(const char *string);
extern int getdate_err;
#define _LARGE_TIME_API
#include <time.h>
struct tm *getdate64(const char *string);
General description
The getdate()
function converts definable date and/or time specifications pointed
to by string into a tm structure. The tm
structure declaration is in the header <time.h>.
Templates
are used to parse and interpret the input string. The templates are
contained in text files created by the process and identified using
the environment variable DATEMSK. The DATEMSK variable
should be set to indicate the full path name of the file that contains
the templates. The first line in the template that matches the input
specification is used for the interpretation and conversion into the
internal time format.
The following field descriptors are supported:
- %%
- same as %.
- %a
- abbreviated weekday name
- %A
- full weekday name
- %b
- abbreviated month name
- %B
- full month name
- %c
- locale's appropriate date and time representation
- %C
- Century number [00,99]; leading zeros are permitted but not required.
Used in conjuction with %y
- %d
- day of month (01-31; the leading 0 is optional)
- %D
- date as %m/%d/%y
- %e
- same as %d
- %h
- same as %b
- %H
- hour (00-23; the leading 0 is optional)
- %I
- hour (01-12; the leading 0 is optional)
- %m
- month number (00-11; the leading 0 is optional)
- %M
- minute (00-59; the leading 0 is optional)
- %n
- same as \n
- %p
- locale's equivalent of either AM or PM
- %r
- locale's 12 hour time representation. In the POSIX locale this
is equivalent to %I:%M:%S %p
- %R
- time as %H:%M
- %S
- Seconds [00,60]. The range goes to 60 (rather than stopping at
59) to allow positive leap seconds to be expressed. Since leap seconds
cannot be predicted by any algorithm, leap second data must come from
some external source.
- %t
- same as \t (tab)
- %T
- time as %H:%M:%S
- %w
- weekday number (0-6; 0 indicates Sunday)
- %x
- locale's date representation. In the POSIX locale this is equivalent
to %m/%d/%y.
- %X
- locale's time representation. In the POSIX locale this is equivalent
to %H:%M:%S.
- %y
- year within century. When a century is not otherwise specified,
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). 31-bit supports
values in the range 00-37 and 64-bit supports values in the range
00-68.
- %Y
-
year as ccyy (1969-9999)
31-bit the upper bound for
%Y is 2037.
64-bit the upper bound for %Y is 9999.
- %Z
- time zone name or no characters if no time zone exists. If the
time zone supplied for %Z is not the time zone getdate() expects,
a non-valid input specification error will result. The getdate() function
calculates an expected time zone based on time and date information
supplied to it.
The match between the template and input specification
performed by getdate() is case insensitive.
The month and weekday
names can consist of any combination of uppercase or lowercase letters.
The process can request that the input date and time specification
be in a specific language by setting the LC_TIME category
(see setlocale()).
Leading 0's are not necessary for the descriptors
that allow leading 0's. However, at most two digits are allowed for
those descriptors, including leading 0's. Extra white space in either
the template file or in string is ignored.
The
field descriptors %c, %x, and %X will not be supported if they include
unsupported field descriptors.
The following rules apply for
converting the input specification into a tm structure:
- If only weekday is given, today is assumed if the given day is
equal to the current day and next week if it is less,
- If only the month is given, the current month is assumed if the
given month is equal to the current month and next year if it is less
and no year is given (the first day of the month is assumed if no
day is given),
- If no hour, minute, and second are given, the current hour, minute
and second are assumed,
- If no date is given, today is assumed if the given hour is greater
than the current hour and tomorrow is assumed if it is less.
Notes: - When converting an input specification into a tm structure, the
getdate() function assumes current time and date values for missing
fields as indicated in the previous list. The function treats these
values as local time, based on the customization of time zone data.
- When neither the TZ (POSIX) nor _TZ (non-POSIX) environment variable
is defined, the current locale is interrogated for time zone information.
If neither TZ nor _TZ is defined and LC_TOD time zone information
is not present in the current locale, a default value is applied to
local time. POSIX programs simply default to Coordinated Universal
Time (UTC), while non-POSIX programs establish an offset from UTC
based on the setting of the system clock. For more information about
customizing a time zone to work with local time, see “Customizing
a time zone” in z/OS XL C/C++ Programming Guide.
If a field descriptor in the template file is
not one of the supported field descriptors, then the following behaviors
exist when the descriptor is encountered:
- In an ASCII application, it is ignored (treated as non-matching)
and processing continues to the next template.
- In an EBCDIC application, it causes the function to return unsuccessful
with getdate_err being set to the value 8.
The function getdate64() will behave exactly like getdate()
except it will convert definable date or time specifications pointed
to by string into a tm structure of calendar
times beyond 03:14:07 UTC on January 19, 2038 with a limit of 23:59:59
UTC on December 31, 9999.
Returned value
If successful, getdate()
returns a pointer to a tm structure.
If unsuccessful, getdate()
returns a NULL pointer and sets the external variable getdate_err to
a value indicating the error.
The tm structure to which getdate()
returns a pointer is not shared with any other functions. Also, the
getdate() function produces a tm structure unique to the thread on
which it runs.
As is true for all external variables, C/370™ allocates storage for the getdate_err external
variable in writable static storage which is shared among all threads.
Thus, getdate_err is not intrinsically “thread-safe”.
C/370 allocates storage on a per
thread basis for an analog of getdate_err. The __gderr()
function returns a pointer to this storage. It is recommended that
multithread applications and applications running from a DLL use the
__gderr() function rather than getdate_err if getdate()
returns a NULL pointer to determine in a thread-safe manner why getdate()
was unsuccessful.
The __gderr() is defined as follows:
#include <time.h>
int *__gderr(void);
The __gderr() function returns a pointer
to the thread-specific value of
getdate_err. The
getdate64() function affects the same pointer to the thread-specific
value of getdate_err as the getdate() function does.
The following
is a list of
getdate_err settings and their description:
- 1
- The DATEMSK environment variable is NULL or undefined.
- 2
- The template file cannot be opened for reading.
- 3
- Failed to get file status information.
- 4
- The template file is not a regular file.
- 5
- An error was encountered while reading the template file.
- 6
- Memory allocation failed (not enough memory available).
- 7
- No line in the template file matches the input specification.
- 8
- Non-valid input specification. For example, February 31; or a
time that can not be represented in a time_t (representing the time
is seconds since Epoch - midnight, January 1, 1970 (UTC)).
- 9
- Unable to determine current time.
Note: This value is unique
for z/OS® UNIX services.