Originální popis anglicky:
getdate - convert user format date and time
Návod, kniha: POSIX Programmer's Manual
#include <time.h>
struct tm *getdate(const char *
string);
The
getdate() function shall convert a string representation of a date or
time into a broken-down time.
The external variable or macro
getdate_err is used by
getdate() to
return error values.
Templates are used to parse and interpret the input string. The templates are
contained in a text file identified by the environment variable
DATEMSK
. The
DATEMSK variable should be set to indicate the full pathname
of the file that contains the templates. The first line in the template that
matches the input specification is used for interpretation and conversion into
the internal time format.
The following conversion specifications shall be supported:
- %%
- Equivalent to % .
- %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.
- %d
- Day of month [01,31]; the leading 0 is optional.
- %D
- Date as %m / %d / %y .
- %e
- Equivalent to %d .
- %h
- Abbreviated month name.
- %H
- Hour [00,23].
- %I
- Hour [01,12].
- %m
- Month number [01,12].
- %M
- Minute [00,59].
- %n
- Equivalent to <newline>.
- %p
- Locale's equivalent of either AM or PM.
- %r
- The locale's appropriate representation of time in AM and
PM notation. In the POSIX locale, this shall be 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
- Equivalent to <tab>.
- %T
- Time as %H : %M : %S .
- %w
- Weekday number (Sunday = [0,6]).
- %x
- Locale's appropriate date representation.
- %X
- Locale's appropriate time representation.
- %y
- Year within century. When a century is not otherwise
specified, values in the range [69,99] shall refer to years 1969 to 1999
inclusive, and values in the range [00,68] shall refer to years 2000 to
2068 inclusive.
- Note:
It is expected that in a future version of
IEEE Std 1003.1-2001 the default century inferred from a 2-digit
year will change. (This would apply to all commands accepting a 2-digit year
as input.)
- %Y
- Year as "ccyy" (for example, 2001).
- %Z
- Timezone name or no characters if no timezone exists. If
the timezone supplied by %Z is not the timezone that
getdate() expects, an invalid input specification error shall
result. The getdate() function calculates an expected timezone
based on information supplied to the function (such as the hour, day, and
month).
The match between the template and input specification performed by
getdate() shall be case-insensitive.
The month and weekday names can consist of any combination of upper and
lowercase letters. The process can request that the input date or time
specification be in a specific language by setting the
LC_TIME category
(see
setlocale() ).
Leading zeros are not necessary for the descriptors that allow leading zeros.
However, at most two digits are allowed for those descriptors, including
leading zeros. Extra whitespace in either the template file or in
string shall be ignored.
The results are undefined if the conversion specifications
%c ,
%x
, and
%X include unsupported conversion specifications.
The following rules apply for converting the input specification into the
internal format:
- *
- If %Z is being scanned, then getdate() shall
initialize the broken-down time to be the current time in the scanned
timezone. Otherwise, it shall initialize the broken-down time based on the
current local time as if localtime() had been called.
- *
- If only the weekday is given, the day chosen shall be the
day, starting with today and moving into the future, which first matches
the named day.
- *
- If only the month (and no year) is given, the month chosen
shall be the month, starting with the current month and moving into the
future, which first matches the named month. The first day of the month
shall be assumed if no day is given.
- *
- If no hour, minute, and second are given, the current hour,
minute, and second shall be assumed.
- *
- If no date is given, the hour chosen shall be the hour,
starting with the current hour and moving into the future, which first
matches the named hour.
If a conversion specification in the DATEMSK file does not correspond to one of
the conversion specifications above, the behavior is unspecified.
The
getdate() function need not be reentrant. A function that is not
required to be reentrant is not required to be thread-safe.
Upon successful completion,
getdate() shall return a pointer to a
struct tm. Otherwise, it shall return a null pointer and set
getdate_err to indicate the error.
The
getdate() function shall fail in the following cases, setting
getdate_err to the value shown in the list below. Any changes to
errno are unspecified.
- 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 I/O error is encountered while reading the template
file.
- 6.
- Memory allocation failed (not enough memory
available).
- 7.
- There is no line in the template that matches the
input.
- 8.
- Invalid input specification. For example, February 31; or a
time is specified that cannot be represented in a time_t
(representing the time in seconds since the Epoch).
The following sections are informative.
- 1.
- The following example shows the possible contents of a
template:
%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
- 2.
- The following are examples of valid input specifications
for the template in Example 1:
getdate("10/1/87 4 PM");
getdate("Friday");
getdate("Friday September 18, 1987, 10:30:30");
getdate("24,9,1986 10:30");
getdate("at monday the 1st of december in 1986");
getdate("run job at 3 PM, december 2nd");
If the
LC_TIME category is set to a German locale that includes
freitag as a weekday name and
oktober as a month name, the
following would be valid:
getdate("freitag den 10. oktober 1986 10.30 Uhr");
- 3.
- The following example shows how local date and time
specification can be defined in the template:
| Invocation |
Line in Template |
| getdate("11/27/86") |
%m/%d/%y |
| getdate("27.11.86") |
%d.%m.%y |
| getdate("86-11-27") |
%y-%m-%d |
| getdate("Friday 12:00:00") |
%A %H:%M:%S |
- 4.
- The following examples help to illustrate the above rules
assuming that the current date is Mon Sep 22 12:19:47 EDT 1986 and the
LC_TIME category is set to the default C locale:
| Input |
Line in Template |
Date |
| Mon |
%a |
Mon Sep 22 12:19:47 EDT 1986 |
| Sun |
%a |
Sun Sep 28 12:19:47 EDT 1986 |
| Fri |
%a |
Fri Sep 26 12:19:47 EDT 1986 |
| September |
%B |
Mon Sep 1 12:19:47 EDT 1986 |
| January |
%B |
Thu Jan 1 12:19:47 EST 1987 |
| December |
%B |
Mon Dec 1 12:19:47 EST 1986 |
| Sep Mon |
%b %a |
Mon Sep 1 12:19:47 EDT 1986 |
| Jan Fri |
%b %a |
Fri Jan 2 12:19:47 EST 1987 |
| Dec Mon |
%b %a |
Mon Dec 1 12:19:47 EST 1986 |
| Jan Wed 1989 |
%b %a %Y |
Wed Jan 4 12:19:47 EST 1989 |
| Fri 9 |
%a %H |
Fri Sep 26 09:00:00 EDT 1986 |
| Feb 10:30 |
%b %H:%S |
Sun Feb 1 10:00:30 EST 1987 |
| 10:30 |
%H:%M |
Tue Sep 23 10:30:00 EDT 1986 |
| 13:30 |
%H:%M |
Mon Sep 22 13:30:00 EDT 1986 |
Although historical versions of
getdate() did not require that
<time.h> declare the external variable
getdate_err, this
volume of IEEE Std 1003.1-2001 does require it. The standard
developers encourage applications to remove declarations of
getdate_err
and instead incorporate the declaration by including
<time.h>.
Applications should use
%Y (4-digit years) in preference to
%y
(2-digit years).
In standard locales, the conversion specifications
%c ,
%x , and
%X do not include unsupported conversion specifiers and so the text
regarding results being undefined is not a problem in that case.
None.
ctime() ,
localtime() ,
setlocale() ,
strftime() ,
times() , the Base Definitions volume of
IEEE Std 1003.1-2001,
<time.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
