getdate.texi

Linux下文件工具。

@cindex time of day item

A @dfn{time of day item} in date strings specifies the time on a given
day.  Here are some examples, all of which represent the same time:

@example
20:02:0
20:02
8:02pm
20:02-0500      # In @sc{est} (U.S. Eastern Standard Time).
@end example

More generally, the time of the day may be given as
@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
a number between 0 and 23, @var{minute} is a number between 0 and
59, and @var{second} is a number between 0 and 59.  Alternatively,
@samp{:@var{second}} can be omitted, in which case it is taken to
be zero.

@findex am @r{in date strings}
@findex pm @r{in date strings}
@findex midnight @r{in date strings}
@findex noon @r{in date strings}
If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
@samp{:@var{minute}} may be omitted (taken to be zero).  @samp{am}
indicates the first half of the day, @samp{pm} indicates the second
half of the day.  In this notation, 12 is the predecessor of 1:
midnight is @samp{12am} while noon is @samp{12pm}.
(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
as opposed to the old tradition derived from Latin
which uses @samp{12m} for noon and @samp{12pm} for midnight.)

@cindex time zone correction
@cindex minutes, time zone correction by
The time may alternatively be followed by a time zone correction,
expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
of zone minutes.  When a time zone correction is given this way, it
forces interpretation of the time relative to
Coordinated Universal Time (@sc{utc}), overriding any previous
specification for the time zone or the local time zone.  The @var{minute}
part of the time of the day may not be elided when a time zone correction
is used.  This is the best way to specify a time zone correction by
fractional parts of an hour.

Either @samp{am}/@samp{pm} or a time zone correction may be specified,
but not both.


@node Time zone items
@section Time zone items

@cindex time zone item

A @dfn{time zone item} specifies an international time zone, indicated
by a small set of letters, e.g., @samp{UTC} or @samp{Z}
for Coordinated Universal
Time.  Any included periods are ignored.  By following a
non-daylight-saving time zone by the string @samp{DST} in a separate
word (that is, separated by some white space), the corresponding
daylight saving time zone may be specified.

Time zone items other than @samp{UTC} and @samp{Z}
are obsolescent and are not recommended, because they
are ambiguous; for example, @samp{EST} has a different meaning in
Australia than in the United States.  Instead, it's better to use
unambiguous numeric time zone corrections like @samp{-0500}, as
described in the previous section.


@node Day of week items
@section Day of week items

@cindex day of week item

The explicit mention of a day of the week will forward the date
(only if necessary) to reach that day of the week in the future.

Days of the week may be spelled out in full: @samp{Sunday},
@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
@samp{Friday} or @samp{Saturday}.  Days may be abbreviated to their
first three letters, optionally followed by a period.  The special
abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
also allowed.

@findex next @var{day}
@findex last @var{day}
A number may precede a day of the week item to move forward
supplementary weeks.  It is best used in expression like @samp{third
monday}.  In this context, @samp{last @var{day}} or @samp{next
@var{day}} is also acceptable; they move one week before or after
the day that @var{day} by itself would represent.

A comma following a day of the week item is ignored.


@node Relative items in date strings
@section Relative items in date strings

@cindex relative items in date strings
@cindex displacement of dates

@dfn{Relative items} adjust a date (or the current date if none) forward
or backward.  The effects of relative items accumulate.  Here are some
examples:

@example
1 year
1 year ago
3 years
2 days
@end example

@findex year @r{in date strings}
@findex month @r{in date strings}
@findex fortnight @r{in date strings}
@findex week @r{in date strings}
@findex day @r{in date strings}
@findex hour @r{in date strings}
@findex minute @r{in date strings}
The unit of time displacement may be selected by the string @samp{year}
or @samp{month} for moving by whole years or months.  These are fuzzy
units, as years and months are not all of equal duration.  More precise
units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
@samp{sec} worth one second.  An @samp{s} suffix on these units is
accepted and ignored.

@findex ago @r{in date strings}
The unit of time may be preceded by a multiplier, given as an optionally
signed number.  Unsigned numbers are taken as positively signed.  No
number at all implies 1 for a multiplier.  Following a relative item by
the string @samp{ago} is equivalent to preceding the unit by a
multiplier with value @math{-1}.

@findex day @r{in date strings}
@findex tomorrow @r{in date strings}
@findex yesterday @r{in date strings}
The string @samp{tomorrow} is worth one day in the future (equivalent
to @samp{day}), the string @samp{yesterday} is worth
one day in the past (equivalent to @samp{day ago}).

@findex now @r{in date strings}
@findex today @r{in date strings}
@findex this @r{in date strings}
The strings @samp{now} or @samp{today} are relative items corresponding
to zero-valued time displacement, these strings come from the fact
a zero-valued time displacement represents the current time when not
otherwise changed by previous items.  They may be used to stress other
items, like in @samp{12:00 today}.  The string @samp{this} also has
the meaning of a zero-valued time displacement, but is preferred in
date strings like @samp{this thursday}.

When a relative item causes the resulting date to cross a boundary
where the clocks were adjusted, typically for daylight-saving time,
the resulting date and time are adjusted accordingly.


@node Pure numbers in date strings
@section Pure numbers in date strings

@cindex pure numbers in date strings

The precise interpretation of a pure decimal number depends
on the context in the date string.

If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
other calendar date item (@pxref{Calendar date items}) appears before it
in the date string, then @var{yyyy} is read as the year, @var{mm} as the
month number and @var{dd} as the day of the month, for the specified
calendar date.

If the decimal number is of the form @var{hh}@var{mm} and no other time
of day item appears before it in the date string, then @var{hh} is read
as the hour of the day and @var{mm} as the minute of the hour, for the
specified time of the day.  @var{mm} can also be omitted.

If both a calendar date and a time of day appear to the left of a number
in the date string, but no relative item, then the number overrides the
year.


@node Authors of getdate
@section Authors of @code{getdate}

@cindex authors of @code{getdate}

@cindex Bellovin, Steven M.
@cindex Salz, Rich
@cindex Berets, Jim
@cindex MacKenzie, David
@cindex Meyering, Jim
@cindex Eggert, Paul
@code{getdate} was originally implemented by Steven M. Bellovin
(@email{smb@@research.att.com}) while at the University of North Carolina
at Chapel Hill.  The code was later tweaked by a couple of people on
Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
and Jim Berets (@email{jberets@@bbn.com}) in August, 1990.  Various
revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
Paul Eggert and others.

@cindex Pinard, F.
@cindex Berry, K.
This chapter was originally produced by Fran@,{c}ois Pinard
(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).