bump patchlevel
[alioth/cvs.git] / doc / getdate.texi
index 0150ff2..b8247b8 100644 (file)
@@ -3,12 +3,17 @@
 @c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
 @c 2003, 2004, 2005 Free Software Foundation, Inc.
 
-@c Permission is granted to copy, distribute and/or modify this document
-@c under the terms of the GNU Free Documentation License, Version 1.1 or
-@c any later version published by the Free Software Foundation; with no
-@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-@c Texts.  A copy of the license is included in the ``GNU Free
-@c Documentation License'' file as part of this distribution.
+@comment This file is part of the CVS distribution.
+
+@comment CVS is free software; you can redistribute it and/or modify
+@comment it under the terms of the GNU General Public License as published by
+@comment the Free Software Foundation; either version 2, or (at your option)
+@comment any later version.
+
+@comment CVS is distributed in the hope that it will be useful,
+@comment but WITHOUT ANY WARRANTY; without even the implied warranty of
+@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+@comment GNU General Public License for more details.
 
 @node Date input formats
 @chapter Date input formats
@@ -55,8 +60,7 @@ arguments to the various programs.  The C interface (via the
 * Day of week items::              Monday and others.
 * Relative items in date strings:: next tuesday, 2 years ago.
 * Pure numbers in date strings::   19931219, 1440.
-* Seconds since the Epoch::        @@1078100502.
-* Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
+* Seconds since the Epoch::        @@1101064456
 * Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.
 @end menu
 
@@ -75,7 +79,7 @@ many flavors of items:
 
 @itemize @bullet
 @item calendar date items
-@item time of day items
+@item time of the day items
 @item time zone items
 @item day of the week items
 @item relative items
@@ -113,8 +117,7 @@ abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
 
 @cindex language, in dates
 @cindex time zone item
-The output of the @command{date} command
-is not always acceptable as a date string,
+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,
@@ -124,15 +127,21 @@ ways to do this:
 
 @example
 $ LC_ALL=C TZ=UTC0 date
-Mon Mar  1 00:21:42 UTC 2004
-$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
-2004-03-01 00:21:42Z
+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 --iso-8601=ns  # a GNU extension
+2004-02-29T16:21:42,692722128-0800
 $ date --iso-8601=ns | tr T ' '  # --iso-8601 is a GNU extension.
 2004-02-29 16:21:42,692722128-0800
 $ date --rfc-2822  # a GNU extension
-Sun, 29 Feb 2004 16:21:42 -0800
-$ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
-2004-02-29 16:21:42 -0800
+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
+$ date +'@@%s'  # %s is a MirOS extension.
+@@1101064210
 $ date +'@@%s.%N'  # %s and %N are GNU extensions.
 @@1078100502.692722128
 @end example
@@ -231,14 +240,13 @@ day.  Here are some examples, all of which represent the same time:
 20:02-0500      # In @sc{est} (U.S. Eastern Standard Time).
 @end example
 
-More generally, the time of day may be given as
+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 possibly followed by
-@samp{.} or @samp{,} and a fraction containing one or more digits.
-Alternatively,
-@samp{:@var{second}} can be omitted, in which case it is taken to
-be zero.
+59, and @var{second} is a number between 0 and 59, with an optional
+fraction separated by @samp{.} or @samp{,} consisting of digits.
+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}
@@ -299,8 +307,7 @@ unambiguous numeric time zone corrections like @samp{-0500}, as
 described in the previous section.
 
 If neither a time zone item nor a time zone correction is supplied,
-time stamps are interpreted using the rules of the default time zone
-(@pxref{Specifying time zone rules}).
+time stamps are interpreted using the rules of the default time zone.
 
 
 @node Day of week items
@@ -389,7 +396,7 @@ 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,
+where the clocks were adjusted, typically for daylight-saving time,
 the resulting date and time are adjusted accordingly.
 
 The fuzz in units can cause problems with relative items.  For
@@ -401,7 +408,7 @@ current month.  For example:
 @example
 $ date -R
 Thu, 31 Jul 2003 13:02:39 -0700
-$ date --date='-1 month' +'Last month was %B?'
+$ date --date="-1 month" +'Last month was %B?'
 Last month was July?
 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
 Last month was June!
@@ -430,7 +437,7 @@ 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 day.  @var{mm} can also be omitted.
+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
@@ -440,86 +447,49 @@ year.
 @node Seconds since the Epoch
 @section Seconds since the Epoch
 
-If you precede a number with @samp{@@}, it represents an internal time
-stamp as a count of seconds.  The number can contain an internal
-decimal point (either @samp{.} or @samp{,}); any excess precision not
-supported by the internal representation is truncated toward minus
-infinity.  Such a number cannot be combined with any other date
-item, as it specifies a complete time stamp.
+If you give a string consisting of @samp{@@} followed by a decimal
+number, it is parsed as an internal time stamp, @sc{utc} for
+@acronym{POSIX} compliant systems, @sc{tai} for systems which keep
+time correctly, and directly mapped to a kernel time.  The implementation
+handles an optional fraction separated by @samp{.} or @samp{,} and
+truncates to a supported internal precision, rounding towards the
+negative infinity.  Since the kernel time stamp represents complete
+date and time information, it cannot be combined with any other
+format given.
 
 @cindex beginning of time, for @acronym{POSIX}
 @cindex epoch, for @acronym{POSIX}
-Internally, computer times are represented as a count of seconds since
-an epoch---a well-defined point of time.  On @acronym{GNU} and
-@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
-@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
-00:00:01 @sc{utc}, and so forth.  @acronym{GNU} and most other
-@acronym{POSIX}-compliant systems support such times as an extension
-to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
-represents 1969-12-31 23:59:59 @sc{utc}.
-
-Traditional Unix systems count seconds with 32-bit two's-complement
-integers and can represent times from 1901-12-13 20:45:52 through
-2038-01-19 03:14:07 @sc{utc}.  More modern systems use 64-bit counts
-of seconds with nanosecond subcounts, and can represent all the times
-in the known lifetime of the universe to a resolution of 1 nanosecond.
-
-On most systems, these counts ignore the presence of leap seconds.
-For example, on most systems @samp{@@915148799} represents 1998-12-31
-23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
-@sc{utc}, and there is no way to represent the intervening leap second
-1998-12-31 23:59:60 @sc{utc}.
-
-@node Specifying time zone rules
-@section Specifying time zone rules
-
-@vindex TZ
-Normally, dates are interpreted using the rules of the current time
-zone, which in turn are specified by the @env{TZ} environment
-variable, or by a system default if @env{TZ} is not set.  To specify a
-different set of default time zone rules that apply just to one date,
-start the date with a string of the form @samp{TZ="@var{rule}"}.  The
-two quote characters (@samp{"}) must be present in the date, and any
-quotes or backslashes within @var{rule} must be escaped by a
-backslash.
-
-For example, with the @acronym{GNU} @command{date} command you can
-answer the question ``What time is it in New York when a Paris clock
-shows 6:30am on October 31, 2004?'' by using a date beginning with
-@samp{TZ="Europe/Paris"} as shown in the following shell transcript:
-
-@example
-$ export TZ="America/New_York"
-$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
-Sun Oct 31 01:30:00 EDT 2004
-@end example
+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.  @acronym{GNU} and
+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}, such
+that @samp{@@0} represents the epoch, @samp{@@1} represents 1970-01-01
+00:00:01 @sc{utc}, and so forth, whereas @samp{@@-1}, not mandated by
+@acronym{POSIX}, represents 1969-12-31 23:59:59 @sc{utc}.  Systems with
+64-bit signed @code{time_t} can represent all the times in the known
+lifetime of the universe. Modern @acronym{UNIX} systems also can give
+precise timecounters in the nanosecond or even attosecond range with
+a resolution often only a small multiply, like 10000, of the CPU
+frequency (on fast machines).
+
+@acronym{POSIX} conformant systems do not count leap seconds, and their
+kernel time is a seconds-since-epoch representation of @sc{utc} (which
+is a calendar time); the MirOS family of operating systems keeps time
+as seconds since the epoch, @sc{tai}, correctly counting leap seconds
+and providing conversion functions.  Most MirOS ports have already
+switched to a 64-bit signed @code{time_t}, some are using a
+@sc{djb}-compatible @code{tai_t} internally.  The rest of this
+document has not been throughoutly checked for @sc{utc} vs @sc{tai}
+correctness.  For @acronym{POSIX}ly broken systems, @samp{@@915148799}
+represents 1998-12-31 23:59:59 @sc{utc}, @samp{@@915148800} represents
+1999-01-01 00:00:00 @sc{utc}, and there is no way to represent the
+intervening leap second 1998-12-31 23:59:60 @sc{utc}.  Also, calculation
+of time deltas is wrong, such as the age of the MirOS founder is already
+off by more than 10 seconds in 2000.
 
-In this example, the @option{--date} operand begins with its own
-@env{TZ} setting, so the rest of that operand is processed according
-to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
-06:30} as if it were in Paris.  However, since the output of the
-@command{date} command is processed according to the overall time zone
-rules, it uses New York time.  (Paris was normally six hours ahead of
-New York in 2004, but this example refers to a brief Halloween period
-when the gap was five hours.)
-
-A @env{TZ} value is a rule that typically names a location in the
-@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
-A recent catalog of location names appears in the
-@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
-Gateway}.  A few non-@acronym{GNU} hosts require a colon before a
-location name in a @env{TZ} setting, e.g.,
-@samp{TZ=":America/New_York"}.
-
-The @samp{tz} database includes a wide variety of locations ranging
-from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
-if you are at sea and have your own private time zone, or if you are
-using a non-@acronym{GNU} host that does not support the @samp{tz}
-database, you may need to use a @acronym{POSIX} rule instead.  Simple
-@acronym{POSIX} rules like @samp{UTC0} specify a time zone without
-daylight saving time; other rules can specify simple daylight saving
-regimes.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
-libc, The GNU C Library}.
 
 @node Authors of get_date
 @section Authors of @code{get_date}
@@ -545,3 +515,11 @@ Paul Eggert and others.
 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}).
+
+The version of this chapter you are reading comes with CVS 1.12 and
+the MirOS family of operating systems; it is based upon an older
+version of the @acronym{GNU} coreutils manual which is not yet
+restricted by the licencing conditions of the GNU Free Documentation
+License, but more freely redistributable.  Appropriate changes for
+the in-tree @code{get_date} version of CVS have been applied.
+The MirOS version is maintained by Thorsten Glaser @email{tg@@mirbsd.de}.