The Unix standard defines another function to parse date strings. The interface is, mildly said, weird. But if this function fits into the application to be written it is just fine. It is a problem when using this function in multi-threaded programs or in libraries since it returns a pointer to a static variable, uses a global variable, and a global state (an environment variable).
int
will contain the error code of the last
unsuccessful call of the getdate
function. Defined values are:
DATEMSK
is not defined or null.
DATEMSK
environment variable
cannot be opened.
time_t
.
getdate
function is the simplest possible
for a function to parse a string and return the value. string is
the input string and the result is passed to the user in a statically
allocated variable.
The details about how the string is processed is hidden from the user.
In fact, it can be outside the control of the program. Which formats
are recognized is controlled by the file named by the environment
variable DATEMSK
. The content of the named file should contain
lines of valid format strings which could be passed to strptime
.
The getdate
function reads these format strings one after the
other and tries to match the input string. The first line which
completely matches the input string is used.
Elements which were not initialized through the format string get
assigned the values of the time the getdate
function is called.
The format elements recognized by getdate
are the same as for
strptime
. See above for an explanation. There are only a few
extension to the strptime
behavior:
%Z
format is given the broken-down time is based on the
current time in the timezone matched, not in the current timezone of the
runtime environment.
Note: This is not implemented (currently). The problem is that
timezone names are not unique. If a fixed timezone is assumed for a
given string (say EST
meaning US East Coast time) uses for
countries other than the USA will fail. So far we have found no good
solution for this.
tm_wday
value this weeks day is selected. Otherwise next weeks day.
It should be noted that the format in the template file need not only contain format elements. The following is a list of possible format strings (taken from the Unix standard):
%m %A %B %d, %Y %H:%M:%S %A %B %m/%d/%y %I %p %d,%m,%Y %H:%M at %A the %dst of %B in %Y run job at %I %p,%B %dnd %A den %d. %B %Y %H.%M Uhr
As one can see the template list can contain very specific strings like
run job at %I %p,%B %dnd
. Using the above list of templates and
assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can get the
following results for the given input.
@multitable {xxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
struct tm
or a null pointer if an error occurred. The
result in the variable pointed to by the return value is only valid
until the next getdate
call which makes this function unusable in
multi-threaded applications.
The errno
variable is not changed. Error conditions are
signalled using the global variable getdate_err
. See the
description above for a list of the possible error values.
Warning: The getdate
function should never be
used in SUID-programs. The reason is obvious: using the
DATEMSK
environment variable one can get the function to open
any arbitrary file and chances are high that with some bogus input
(such as a binary file) the program will crash.
getdate_r
function is the reentrant counterpart of
getdate
. It does not use the global variable getdate_err
to signal the error but instead the return value now is this error code.
The same error codes as described in the getdate_err
documentation above are used.
getdate_r
also does not store the broken-down time in a static
variable. Instead it takes an second argument which must be a pointer
to a variable of type struct tm
where the broken-down can be
stored.
This function is not defined in the Unix standard. Nevertheless it is
available on some other Unix systems as well.
As for getdate
the warning for using this function in
SUID-programs applies to getdate_r
as well.
Go to the first, previous, next, last section, table of contents.