getdate.texi

Linux下文件工具。

@node Date input formats
@chapter Date input formats

@cindex date input formats
@findex getdate

First, a quote:

@quotation
Our units of temporal measurement, from seconds on up to months, are so
complicated, asymmetrical and disjunctive so as to make coherent mental
reckoning in time all but impossible.  Indeed, had some tyrannical god
contrived to enslave our minds to time, to make it all but impossible
for us to escape subjection to sodden routines and unpleasant surprises,
he could hardly have done better than handing down our present system.
It is like a set of trapezoidal building blocks, with no vertical or
horizontal surfaces, like a language in which the simplest thought
demands ornate constructions, useless particles and lengthy
circumlocutions.  Unlike the more successful patterns of language and
science, which enable us to face experience boldly or at least
level-headedly, our system of temporal calculation silently and
persistently encourages our terror of time.

@dots{}  It is as though architects had to measure length in feet, width
in meters and height in ells; as though basic instruction manuals
demanded a knowledge of five different languages.  It is no wonder then
that we often look into our own immediate past or future, last Tuesday
or a week from Sunday, with feelings of helpless confusion.  @dots{}

--- Robert Grudin, @cite{Time and the Art of Living}.
@end quotation

This section describes the textual date representations that @sc{gnu}
programs accept.  These are the strings you, as a user, can supply as
arguments to the various programs.  The C interface (via the
@code{getdate} function) is not described here.

@cindex beginning of time, for @acronym{POSIX}
@cindex epoch, for @acronym{POSIX}
Although the date syntax here can represent any possible time since the
year zero, computer integers often cannot represent such a wide range of
time.  On @acronym{POSIX} systems, the clock starts at 1970-01-01 00:00:00
@sc{utc}: @acronym{POSIX} does not require support for times before the
@acronym{POSIX} Epoch and times far in the future.  Traditional Unix systems
have 32-bit signed @code{time_t} and can represent times from 1901-12-13
20:45:52 through 2038-01-19 03:14:07 @sc{utc}.  Systems with 64-bit
signed @code{time_t} can represent all the times in the known
lifetime of the universe.

@menu
* General date syntax::            Common rules.
* Calendar date items::            19 Dec 1994.
* Time of day items::              9:20pm.
* Time zone items::                @sc{est}, @sc{pdt}, @sc{gmt}, ...
* Day of week items::              Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings::   19931219, 1440.
* Authors of getdate::             Bellovin, Eggert, Salz, Berets, et al.
@end menu


@node General date syntax
@section General date syntax

@cindex general date syntax

@cindex items in date strings
A @dfn{date} is a string, possibly empty, containing many items
separated by whitespace.  The whitespace may be omitted when no
ambiguity arises.  The empty string means the beginning of today (i.e.,
midnight).  Order of the items is immaterial.  A date string may contain
many flavors of items:

@itemize @bullet
@item calendar date items
@item time of the day items
@item time zone items
@item day of the week items
@item relative items
@item pure numbers.
@end itemize

@noindent We describe each of these item types in turn, below.

@cindex numbers, written-out
@cindex ordinal numbers
@findex first @r{in date strings}
@findex next @r{in date strings}
@findex last @r{in date strings}
A few numbers may be written out in words in most contexts.  This is
most useful for specifying day of the week items or relative items (see
below).  Here is the list: @samp{first} for 1, @samp{next} for 2,
@samp{third} for 3, @samp{fourth} for 4, @samp{fifth} for 5,
@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
@samp{twelfth} for 12.  Also, @samp{last} means exactly @math{-1}.

@cindex months, written-out
When a month is written this way, it is still considered to be written
numerically, instead of being ``spelled in full''; this changes the
allowed strings.

@cindex language, in dates
In the current implementation, only English is supported for words and
abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.

@cindex language, in dates
@cindex time zone item
The output of @command{date} is not always acceptable as a date string,
not only because of the language problem, but also because there is no
standard meaning for time zone items like @samp{IST}.  When using
@command{date} to generate a date string intended to be parsed later,
specify a date format that is independent of language and that does not
use time zone items other than @samp{UTC} and @samp{Z}.  Here are some
ways to do this:

@example
$ LC_ALL=C TZ=UTC0 date
Fri Dec 15 19:48:05 UTC 2000
$ TZ=UTC0 date +"%Y-%m-%d %H:%M:%SZ"
2000-12-15 19:48:05Z
$ date --iso-8601=seconds  # a GNU extension
2000-12-15T11:48:05-0800
$ date --rfc-822  # a GNU extension
Fri, 15 Dec 2000 11:48:05 -0800
$ date +"%Y-%m-%d %H:%M:%S %z"  # %z is a GNU extension.
2000-12-15 11:48:05 -0800
@end example

@cindex case, ignored in dates
@cindex comments, in dates
Alphabetic case is completely ignored in dates.  Comments may be introduced
between round parentheses, as long as included parentheses are properly
nested.  Hyphens not followed by a digit are currently ignored.  Leading
zeros on numbers are ignored.


@node Calendar date items
@section Calendar date items

@cindex calendar date item

A @dfn{calendar date item} specifies a day of the year.  It is
specified differently, depending on whether the month is specified
numerically or literally.  All these strings specify the same calendar date:

@example
1972-09-24     # @sc{iso} 8601.
72-9-24        # Assume 19xx for 69 through 99,
               # 20xx for 00 through 68.
72-09-24       # Leading zeros are ignored.
9/24/72        # Common U.S. writing.
24 September 1972
24 Sept 72     # September has a special abbreviation.
24 Sep 72      # Three-letter abbreviations always allowed.
Sep 24, 1972
24-sep-72
24sep72
@end example

The year can also be omitted.  In this case, the last specified year is
used, or the current year if none.  For example:

@example
9/24
sep 24
@end example

Here are the rules.

@cindex @sc{iso} 8601 date format
@cindex date format, @sc{iso} 8601
For numeric months, the @sc{iso} 8601 format
@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
any positive number, @var{month} is a number between 01 and 12, and
@var{day} is a number between 01 and 31.  A leading zero must be present
if a number is less than ten.  If @var{year} is 68 or smaller, then 2000
is added to it; otherwise, if @var{year} is less than 100,
then 1900 is added to it.  The construct
@samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
is accepted.  Also @samp{@var{month}/@var{day}}, omitting the year.

@cindex month names in date strings
@cindex abbreviations for months
Literal months may be spelled out in full: @samp{January},
@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
@samp{July}, @samp{August}, @samp{September}, @samp{October},
@samp{November} or @samp{December}.  Literal months may be abbreviated
to their first three letters, possibly followed by an abbreviating dot.
It is also permitted to write @samp{Sept} instead of @samp{September}.

When months are written literally, the calendar date may be given as any
of the following:

@example
@var{day} @var{month} @var{year}
@var{day} @var{month}
@var{month} @var{day} @var{year}
@var{day}-@var{month}-@var{year}
@end example

Or, omitting the year:

@example
@var{month} @var{day}
@end example


@node Time of day items
@section Time of day items