getdate.3p (10807B)
- '\" et
- .TH GETDATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- 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.
- .\"
- .SH NAME
- getdate
- \(em convert user format date and time
- .SH SYNOPSIS
- .LP
- .nf
- #include <time.h>
- .P
- struct tm *getdate(const char *\fIstring\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIgetdate\fR()
- function shall convert a string representation of a date or time
- into a broken-down time.
- .P
- The external variable or macro
- .IR getdate_err ,
- which has type
- .BR int ,
- is used by
- \fIgetdate\fR()
- to return error values. It is unspecified whether
- .IR getdate_err
- 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
- .IR getdate_err ,
- the behavior is undefined.
- .P
- Templates are used to parse and interpret the input string. The
- templates are contained in a text file identified by the environment
- variable
- .IR DATEMSK .
- The
- .IR 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.
- .P
- The following conversion specifications shall be supported:
- .IP "\fR%%\fR" 8
- Equivalent to
- .BR % .
- .IP "\fR%a\fR" 8
- Abbreviated weekday name.
- .IP "\fR%A\fR" 8
- Full weekday name.
- .IP "\fR%b\fR" 8
- Abbreviated month name.
- .IP "\fR%B\fR" 8
- Full month name.
- .IP "\fR%c\fR" 8
- Locale's appropriate date and time representation.
- .IP "\fR%C\fR" 8
- Century number [00,99]; leading zeros are permitted but not required.
- .IP "\fR%d\fR" 8
- Day of month [01,31]; the leading 0 is optional.
- .IP "\fR%D\fR" 8
- Date as
- .BR %m /\c
- .BR %d /\c
- .BR %y .
- .IP "\fR%e\fR" 8
- Equivalent to
- .BR %d .
- .IP "\fR%h\fR" 8
- Abbreviated month name.
- .IP "\fR%H\fR" 8
- Hour [00,23].
- .IP "\fR%I\fR" 8
- Hour [01,12].
- .IP "\fR%m\fR" 8
- Month number [01,12].
- .IP "\fR%M\fR" 8
- Minute [00,59].
- .IP "\fR%n\fR" 8
- Equivalent to
- <newline>.
- .IP "\fR%p\fR" 8
- Locale's equivalent of either AM or PM.
- .IP "\fR%r\fR" 8
- The locale's appropriate representation of time in AM and PM notation.
- In the POSIX locale, this shall be equivalent to
- .BR %I :\c
- .BR %M :\c
- .BR %S
- .BR %p .
- .IP "\fR%R\fR" 8
- Time as
- .BR %H :\c
- .BR %M .
- .IP "\fR%S\fR" 8
- 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.
- .IP "\fR%t\fR" 8
- Equivalent to
- <tab>.
- .IP "\fR%T\fR" 8
- Time as
- .BR %H :\c
- .BR %M :\c
- .BR %S .
- .IP "\fR%w\fR" 8
- Weekday number (Sunday = [0,6]).
- .IP "\fR%x\fR" 8
- Locale's appropriate date representation.
- .IP "\fR%X\fR" 8
- Locale's appropriate time representation.
- .IP "\fR%y\fR" 8
- 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.
- .RS 8
- .TP 10
- .BR Note:
- 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.)
- .P
- .RE
- .IP "\fR%Y\fR" 8
- Year as
- .BR \(dqccyy\(dq
- (for example, 2001).
- .IP "\fR%Z\fR" 8
- Timezone name or no characters if no timezone exists. If the
- timezone supplied by
- .BR %Z
- is not the timezone that
- \fIgetdate\fR()
- expects, an invalid input specification error shall result. The
- \fIgetdate\fR()
- function calculates an expected timezone based on information supplied
- to the function (such as the hour, day, and month).
- .P
- The match between the template and input specification performed by
- \fIgetdate\fR()
- shall be case-insensitive.
- .P
- 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
- .IR LC_TIME
- category
- (see
- .IR "\fIsetlocale\fR\^(\|)").
- .P
- 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
- or in
- .IR string
- shall be ignored.
- .P
- The results are undefined if the conversion specifications
- .BR %c ,
- .BR %x ,
- and
- .BR %X
- include unsupported conversion specifications.
- .P
- The following rules apply for converting the input specification into
- the internal format:
- .IP " *" 4
- If
- .BR %Z
- is being scanned, then
- \fIgetdate\fR()
- 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
- \fIlocaltime\fR()
- had been called.
- .IP " *" 4
- 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.
- .IP " *" 4
- 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.
- .IP " *" 4
- If no hour, minute, and second are given, the current hour, minute, and
- second shall be assumed.
- .IP " *" 4
- 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.
- .P
- If a conversion specification in the DATEMSK file does not correspond
- to one of the conversion specifications above, the behavior is
- unspecified.
- .P
- The
- \fIgetdate\fR()
- function need not be thread-safe.
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIgetdate\fR()
- shall return a pointer to a
- .BR "struct tm" .
- Otherwise, it shall return a null pointer and set
- .IR getdate_err
- to indicate the error.
- .SH ERRORS
- The
- \fIgetdate\fR()
- function shall fail in the following cases, setting
- .IR getdate_err
- to the value shown in the list below. Any changes to
- .IR errno
- are unspecified.
- .IP " 1." 4
- The
- .IR DATEMSK
- environment variable is null or undefined.
- .IP " 2." 4
- The template file cannot be opened for reading.
- .IP " 3." 4
- Failed to get file status information.
- .IP " 4." 4
- The template file is not a regular file.
- .IP " 5." 4
- An I/O error is encountered while reading the template file.
- .IP " 6." 4
- Memory allocation failed (not enough memory available).
- .IP " 7." 4
- There is no line in the template that matches the input.
- .IP " 8." 4
- Invalid input specification. For example, February 31; or a time is
- specified that cannot be represented in a
- .BR time_t
- (representing the time in seconds since the Epoch).
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .IP " 1." 4
- The following example shows the possible contents of a template:
- .RS 4
- .sp
- .RS 4
- .nf
- %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
- .fi
- .P
- .RE
- .RE
- .IP " 2." 4
- The following are examples of valid input specifications for the
- template in Example 1:
- .RS 4
- .sp
- .RS 4
- .nf
- 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");
- .fi
- .P
- .RE
- .P
- If the
- .IR LC_TIME
- category is set to a German locale that includes
- .IR freitag
- as a weekday name and
- .IR oktober
- as a month name, the following would be valid:
- .sp
- .RS 4
- .nf
- getdate("freitag den 10. oktober 1986 10.30 Uhr");
- .fi
- .P
- .RE
- .RE
- .IP " 3." 4
- The following example shows how local date and time specification can
- be defined in the template:
- .TS
- box tab(!) center;
- cB | cB
- lf5 | lf5.
- 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
- .TE
- .IP " 4." 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
- .IR LC_TIME
- category is set to the default C or POSIX locale:
- .TS
- box tab(!) center;
- cB | cB | cB
- lf5 | lf5 | l.
- 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
- .TE
- .SH "APPLICATION USAGE"
- Although historical versions of
- \fIgetdate\fR()
- did not require that
- .IR <time.h>
- declare the external variable
- .IR getdate_err ,
- this volume of POSIX.1\(hy2017 does require it. The standard developers encourage applications
- to remove declarations of
- .IR getdate_err
- and instead incorporate the declaration by including
- .IR <time.h> .
- .P
- Applications should use
- .BR %Y
- (4-digit years) in preference to
- .BR %y
- (2-digit years).
- .SH RATIONALE
- In standard locales, the conversion specifications
- .BR %c ,
- .BR %x ,
- and
- .BR %X
- do not include unsupported conversion specifiers and so the text
- regarding results being undefined is not a problem in that case.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIctime\fR\^(\|)",
- .IR "\fIlocaltime\fR\^(\|)",
- .IR "\fIsetlocale\fR\^(\|)",
- .IR "\fIstrftime\fR\^(\|)",
- .IR "\fItimes\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<time.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- 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
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .