287 lines
8.7 KiB
Plaintext
287 lines
8.7 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3c.getdate @(#)getdate 40.15 of 5/22/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} getdate 3C "C Development Set" "\&"
|
|
.if \nX=1 .ds x} getdate 3C "C Development Set"
|
|
.if \nX=2 .ds x} getdate 3C "" "\&"
|
|
.if \nX=3 .ds x} getdate "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4getdate\f1 \- convert user format date and time
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\f4#include <time.h>\f1
|
|
.PP
|
|
\f4struct tm \(**getdate (const char \(**string);\f1
|
|
\f4extern int getdate_err;\f1
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\f4getdate\fP
|
|
The \f4getdate\fP function converts a string representation of a
|
|
date or time into a broken-down time.
|
|
.PP
|
|
The external variable or macro \f4getdate_err\fP is used by \f4getdate()\fP to return
|
|
error values.
|
|
.PP
|
|
Templates are used to parse and interpret the input string. The templates are
|
|
contained in a text file identified by the environment variable \f4DATEMSK.\fP
|
|
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.
|
|
.PP
|
|
The following field descriptors are supported:
|
|
.TP 5
|
|
\f4%%\fP
|
|
same as \f4%\fP
|
|
.TP 5
|
|
\f4%a\fP
|
|
abbreviated weekday name
|
|
.TP 5
|
|
\f4%A\fP
|
|
full weekday name
|
|
.TP 5
|
|
\f4%b\fP
|
|
abbreviated month name
|
|
.TP 5
|
|
\f4%B\fP
|
|
full month name
|
|
.TP 5
|
|
\f4%c\fP
|
|
locale's appropriate date and time representation
|
|
.TP 5
|
|
\f4%C\fP
|
|
century number (00-99; leading zeros are permitted but not required)
|
|
.TP 5
|
|
\f4%d\fP
|
|
day of month (01-31; the leading 0 is optional)
|
|
.TP 5
|
|
\f4%D\fP
|
|
date as %m/%d/%y
|
|
.TP 5
|
|
\f4%e\fP
|
|
same as \f4%\fPd
|
|
.TP 5
|
|
\f4%h\fP
|
|
abbreviated month name
|
|
.TP 5
|
|
\f4%H\fP
|
|
hour (00-23)
|
|
.TP 5
|
|
\f4%I\fP
|
|
hour (01-12)
|
|
.TP 5
|
|
\f4%m\fP
|
|
month number (01-12)
|
|
.TP 5
|
|
\f4%M\fP
|
|
minute (00-59)
|
|
.TP 5
|
|
\f4%n\fP
|
|
same as new line
|
|
.TP 5
|
|
\f4%p\fP
|
|
locale's equivalent of either AM or PM
|
|
.TP 5
|
|
\f4%r\fP
|
|
The locale's appropriate representation of time in AM and PM notation.
|
|
In the POSIX locale, this is equivalent to %I:%M:%S %p
|
|
.TP 5
|
|
\f4%R\fP
|
|
time as %H:%M
|
|
.TP 5
|
|
\f4%S\fP
|
|
seconds (00-61). Leap seconds are allowed but are not predictable through use of algorithms.
|
|
.TP 5
|
|
\f4%t\fP
|
|
same as tab
|
|
.TP 5
|
|
\f4%T\fP
|
|
time as %H:%M:%S
|
|
.TP 5
|
|
\f4%w\fP
|
|
weekday number (Sunday = 0 - 6)
|
|
.TP 5
|
|
\f4%x\fP
|
|
locale's appropriate date representation
|
|
.TP 5
|
|
\f4%X\fP
|
|
locale's appropriate time representation
|
|
.TP 5
|
|
\f4%y\fP
|
|
year within century. When a century is not otherwise specified, values in the range
|
|
69-99 refer to years in the twentieth century (1969 to 1999 inclusive); values in the
|
|
range 00-68 refer to years in the twenty-first century (2000 to 2068 inclusive).
|
|
.TP 5
|
|
\f4%Y\fP
|
|
year as ccyy (for example, 1994)
|
|
.TP 5
|
|
\f4%Z\fP
|
|
time zone name or no characters if no time zone exists.
|
|
If the time zone supplied by \f4%Z\fP is not the time zone that \f4getdate()\fP
|
|
expects, an invalid input specification error will result. The \f4getdate()\fP
|
|
function calculates an expected time zone based on information
|
|
supplied to the function (such as the hour, day, and month).
|
|
.PP
|
|
The match between the template and input specification performed by
|
|
\f4getdate()\fP is case insensitive.
|
|
.PP
|
|
The month and weekday names can consist of any combination of upper and
|
|
lower case letters. The process can request that the input date or time
|
|
specification be in a specific language by setting the \f4LC_TIME\fP category
|
|
(see \f4setlocale()\fP).
|
|
.PP
|
|
Leading 0's are not necessary for the descriptors that allow leading 0's.
|
|
However, at most two digits are allowed for those descriptors,
|
|
including leading 0's. Extra whitespace in either the template file or
|
|
in \f4string\fP is ignored.
|
|
.PP
|
|
The field descriptors \f4%c\fP, \f4%x\fP, and \f4%X\fP will not be supported if
|
|
they include unsupported field descriptors.
|
|
.PP
|
|
The following rules apply for converting the input specification into the internal format:
|
|
.IP
|
|
If \f4%Z\fP is being scanned, then \f4getdate()\fP initialises the broken-down
|
|
time to be the current time in the scanned time zone.
|
|
Otherwise it initialises the broken-down time based on the current local time as if
|
|
\f4localtime()\fP had been called.
|
|
.IP
|
|
If only the weekday is given, today is assumed if the given day is
|
|
equal to the current day and next week if it is less.
|
|
.IP
|
|
If only the month is given, the current month is assumed if the given month
|
|
is equal to the current month and next year if it is less and
|
|
no year is given (the first day of month is assumed if no day is given).
|
|
.IP
|
|
If no hour, minute and second are given the current hour, minute and second are assumed,
|
|
.IP
|
|
If no date is given, today is assumed if the given hour is greater than
|
|
the current hour and tomorrow is assumed if it is less.
|
|
.PP
|
|
If a field descriptor specification in the \f4DATEMSK\fP file does not correspond to
|
|
one of the field descriptors above, the behaviour is unspecified.
|
|
.SH RETURN VALUE
|
|
Upon successful completion, \f4getdate()\fP returns a pointer to a \f4struct tm.\fP
|
|
Otherwise, it returns a null pointer and \f4getdate_err\fP is set to indicate the error.
|
|
.SH ERRORS
|
|
The \f4getdate()\fP function will fail in the following cases, setting \f4getdate_err\fP
|
|
to the value shown in the list below. Any changes to errno are unspecified.
|
|
.TP 5
|
|
1
|
|
The \f4DATEMSK\fP environment variable is null or undefined.
|
|
.TP 5
|
|
2
|
|
The template file cannot be opened for reading.
|
|
.TP 5
|
|
3
|
|
Failed to get file status information.
|
|
.TP 5
|
|
4
|
|
The template file is not a regular file.
|
|
.TP 5
|
|
5
|
|
An I/O error is encountered while reading the template file.
|
|
.TP 5
|
|
6
|
|
Memory allocation failed (not enough memory available).
|
|
.TP 5
|
|
7
|
|
There is no line in the template that matches the input.
|
|
.TP 5
|
|
8
|
|
Invalid input specification. For example, February 31; or a time is
|
|
specified that can not be represented in a \f4time_t\fP
|
|
(representing the time in seconds since 00:00:00 UTC, January 1, 1970).
|
|
.SH EXAMPLE
|
|
Example 1:
|
|
.PP
|
|
The following example shows the possible contents of a template:
|
|
.IP
|
|
%m
|
|
.IP
|
|
%A %B %d, %Y, %H:%M:%S
|
|
.IP
|
|
%A
|
|
.IP
|
|
%B
|
|
.IP
|
|
%m/%d/%y %I %p
|
|
.IP
|
|
%d,%m,%Y %H:%M
|
|
.IP
|
|
at %A the %dst of %B in %Y
|
|
.IP
|
|
run job at %I %p,%B %dnd
|
|
.IP
|
|
%A den %d. %B %Y %H.%M Uhr
|
|
.PP
|
|
Example 2:
|
|
.PP
|
|
The following are examples of valid input specifications for the template in Example 1:
|
|
.IP
|
|
getdate("10/1/87 4 PM");
|
|
.IP
|
|
getdate("Friday");
|
|
.IP
|
|
getdate("Friday September 18, 1987, 10:30:30");
|
|
.IP
|
|
getdate("24,9,1986 10:30");
|
|
.IP
|
|
getdate("at monday the 1st of december in 1986");
|
|
.IP
|
|
getdate("run job at 3 PM, december 2nd");
|
|
.PP
|
|
If the \f4LC_TIME\fP category is set to a German locale that includes
|
|
\f4freitag\fP as a weekday name and \f4oktober\fP as a month name,
|
|
the following would be valid:
|
|
.IP
|
|
getdate("freitag den 10. oktober 1986 10.30 Uhr");
|
|
.PP
|
|
Example 3:
|
|
.PP
|
|
The following examples shows how local date and time specification
|
|
can be defined in the template.
|
|
.PP
|
|
.nf
|
|
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
|
|
.fi
|
|
.PP
|
|
Example 4:
|
|
.PP
|
|
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 \f4LC_TIME\fP category is set to the default \f4"C"\fP locale.
|
|
.PP
|
|
.nf
|
|
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
|
|
.PP
|
|
.SH APPLICATION USAGE
|
|
Although historical versions of \f4getdate()\fP did not require that \f4<time.h>\fP
|
|
declare the external variable \f4getdate_err\fP, this document does require it.
|
|
The Open Group encourages applications to remove declarations of \f4getdate_err\fP
|
|
and instead incorporate the declaration by including \f4<time.h>\fP.
|
|
.SH SEE ALSO
|
|
\f4ctime()\fP, \f4ctype()\fP, \f4localtime()\fP, \f4setlocale()\fP,
|
|
\f4strftime()\fP, \f4times()\fP, \f4<time.h>\fP
|