Syntax | #include <time.h> struct tm *getdate (const char *string); extern int getdate_err; |
Description | getdate() converts user-definable date and/or time specifications from string into a tm-structure. The structure declaration can be found in the time.h file (see also ctime() ).
User-defined templates are used for dismantling and interpreting the input string. These templates are text files, which the user creates; they are specified via the DATEMSK environment variable. Each line of the template represents an acceptable date and/or time specification, with some of the field descriptors which are also used by the date command being used here. The first line in the template that matches the input specification is used for interpretation and conversion into the internal time format. If the operation is successful, the getdate() function returns a pointer to a structure of type tm; otherwise, NULL is returned and the global variable getdate_err is set. The following field descriptors are supported: %%
| same as % | %a
| abbreviated weekday name | %A
| weekday name in full | %b
| abbreviated month name | %B
| month name in full | %c
| local date and time representation | %d
| day of the month (01 - 31; the leading 0 is optional) | %e
| same as %d | %D
| date as %m/%d/%y | %h
| abbreviated month name | %H
| hour (00 - 23) | %I
| hour (01 - 12) | %m
| month number (01 - 12) | %M
| minute (00 - 59) | %n
| same as \n | %p
| local equivalent of AM or PM, but the effects of using algorithms are unpredictable. | %r
| time as %I:%M:%S %p | %R
| time as %H:%M | %S
| second (00-61). Leap seconds are allowed, but the effects of using algorithms are unpredictable. | %t
| insert tab | %T
| time as %H:%M:%S | %w
| weekday number (0 - 6; Sunday = 0) | %x
| local date representation | %X
| local time representation | %y
| year in current century (00 - 99) | %Y
| year as ccyy (e.g. 1997) | %Z
| name of time zone, or no character if no time zone exists. If the time zone under %Z is not the one expected by getdate(), an input error occurs. getdate() computes an appropriate time zone based on the information passed to the function (e.g. hour, day and month). |
When comparing the template and the input specification, getdate() does not distinguish between upper and lowercase. The month and weekday names can consist of any combination of lowercase and uppercase letters. The user can define that the specification of the input time or the input date is language-dependent by setting the values LC_TIME and LC_CTYPE in setlocale(). The descriptors for which digits must be specified have at most two positions. Leading zeros are allowed but they can also be omitted. Blanks in the template or in string are ignored. The field descriptors %c, %x and %X are rejected if they contain invalid field descriptors. The following rules apply to the conversion of input specifications into the internal format: If %Z is specified, getdate() sets the elements of the tm structure to the current time of the specified time zone. Otherwise the formatted time is initialized with the current local time as if localtime() had been executed. If only the weekday is given, the current day is assumed if the specified weekday is identical to the current day. If the given day is before the current one, the weekday is taken from the next week. If only the month is specified, the current month is assumed if the specified month is the same as the current month. If the specified month is earlier than the current month, the next year is assumed if no year is otherwise specified. (The first day of the month is assumed if no day is specified.) If the hour, minute and second are not specified, the current hour, minute and second are taken. If no date is specified, the current day is assumed if the specified hour is later than the current one. If the specified hour is earlier than the current one, the next day is assumed.
getdate() uses the external variable or the getdate_err macro to return the error weight.
|
Return val. | Pointer to a tm structure |
|
| if successful. |
| Null pointer | if an error occurs. getdate_err is set to indicate the error. |
Errors | getdate() will fail if any of the following errors occur. The error weights are returned in getdate_err. The contents of errno are not significant here.
|
| 1
2
3
4
5
6
| The DATEMSK environment variable is undefined or zero. The template file cannot be opened for reading. The file status could not be read. The template file is not a regular file. An error occurred during reading of the template file. malloc() could not be executed successfully, as there was not enough memory available.
|
| 7
8
| There is no line in the template file which matches the input. The input format is invalid, e.g. February 31, or a time was specified which
cannot be represented in a time_t type; time_t contains the time in
seconds since 00:00:00 UTC, which corresponds to January 1, 1970. |
Notes | The following getdate() calls modify the contents of getdate_err. The declaration of the external variable getdate_err is contained in the header file time.h. getdate_err should therefore not be explicitly declared in the program; time.h should be inserted instead. Dates before 1970 and after 2037 are invalid. |
Example 1 | 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
|
Example 2 | Some examples of valid input specifications for the temple in example 1:
getdate("10/1/87 4 PM");
getdate("Friday");
getdate("Friday September 19 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 environment variable is set or if LANG is set to german, the following specification is valid: getdate("Freitag den 10. Oktober 1986 10.30 Uhr") ;
|
Example 3 | Local time and date specifications are also supported. Example 3 shows how these can be defined in templates. Call | Line in template file | 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
|
|
Example 4 | The following examples clarify the above rules. It is assumed that the current date and time are Monday September 22, 1986, 12:19:47 EDT and that the LANG and LC_TIME environment variables are not set. Input | Line in template file | Date | Mon
| %a
| Mon Sep 22 12:19:48 EDT 1986
| Sun
| %a
| Sun Sep 28 12:19:49 EDT 1986
| Fri
| %a
| Fri Sep 26 12:19:49 EDT 1986
| September
| %B
| Mon Sep 1:19:49 EDT 1986
| January
| %B
| Thu Jan 1:19:49 EST 1987
| December
| %B
| Mon Dec 1:19:49 EST 1986
| Sep Mon
| %b %a
| Mon Sep 1:19:50 EDT 1986
| Jan Fri
| %b %a
| Fri Jan 2 12:19:50 EST 1987
| Dec Mon
| %b %a
| Mon Dec 1:19:50 EST 1986
| Jan Wed 198
| %b %a %Y
| Wed Jan 4 12:19:51 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
|
|
See also | ctime(), localtime(), setlocale(), strftime(), times(), time.h.
|
