Section: POSIX Programmer's Manual (3P)
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
--- convert user format date and time
struct tm *getdate(const char *string);
function shall convert a string representation of a date or time
into a broken-down time.
The external variable or macro
which has type
is used by
to return error values. It is unspecified whether
is a macro or an identifier declared with external linkage, and whether
or not it is a modifiable lvalue. If a macro definition is suppressed
in order to access an actual object, or a program defines an identifier
with the name
the behavior is undefined.
Templates are used to parse and interpret the input string. The
templates are contained in a text file identified by the environment
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:
Abbreviated weekday name.
Full weekday name.
Abbreviated month name.
Full month name.
Locale's appropriate date and time representation.
Century number [00,99]; leading zeros are permitted but not required.
Day of month [01,31]; the leading 0 is optional.
Abbreviated month name.
Month number [01,12].
Locale's equivalent of either AM or PM.
The locale's appropriate representation of time in AM and PM notation.
In the POSIX locale, this shall be equivalent to
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.
Weekday number (Sunday = [0,6]).
Locale's appropriate date representation.
Locale's appropriate time representation.
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
It is expected that in a future version of this standard the default
century inferred from a 2-digit year will change. (This would apply
to all commands accepting a 2-digit year as input.)
(for example, 2001).
Timezone name or no characters if no timezone exists. If the
timezone supplied by
is not the timezone that
expects, an invalid input specification error shall result. The
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
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
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 white space in either the template file
shall be ignored.
The results are undefined if the conversion specifications
include unsupported conversion specifications.
The following rules apply for converting the input specification into
the internal format:
is being scanned, then
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
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
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
If a conversion specification in the DATEMSK file does not correspond
to one of the conversion specifications above, the behavior is
function need not be thread-safe.
Upon successful completion,
shall return a pointer to a
Otherwise, it shall return a null pointer and set
to indicate the error.
function shall fail in the following cases, setting
to the value shown in the list below. Any changes to
environment variable is null or undefined.
The template file cannot be opened for reading.
Failed to get file status information.
The template file is not a regular file.
An I/O error is encountered while reading the template file.
Memory allocation failed (not enough memory available).
There is no line in the template that matches the input.
Invalid input specification. For example, February 31; or a time is
specified that cannot be represented in a
(representing the time in seconds since the Epoch).
The following sections are informative.
The following example shows the possible contents of a template:
%A %B %d, %Y, %H:%M:%S
%m/%d/%y %I %p
at %A the %dst of %B in %Y
run job at %I %p,%B %dnd
%A den %d. %B %Y %H.%M Uhr
The following are examples of valid input specifications for the
template in Example 1:
getdate("10/1/87 4 PM");
getdate("Friday September 18, 1987, 10:30:30");
getdate("at monday the 1st of december in 1986");
getdate("run job at 3 PM, december 2nd");
category is set to a German locale that includes
as a weekday name and
as a month name, the following would be valid:
getdate("freitag den 10. oktober 1986 10.30 Uhr");
The following example shows how local date and time specification can
be defined in the template:
|getdate("Friday 12:00:00")||%A %H:%M:%S|
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
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
did not require that
declare the external variable
this volume of POSIX.1-2008 does require it. The standard developers encourage applications
to remove declarations of
and instead incorporate the declaration by including
Applications should use
(4-digit years) in preference to
In standard locales, the conversion specifications
do not include unsupported conversion specifiers and so the text
regarding results being undefined is not a problem in that case.
The Base Definitions volume of POSIX.1-2008,
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see