-\1f
-File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats
-
-7.6 Relative items in date strings
-==================================
-
-"Relative items" adjust a date (or the current date if none) forward or
-backward. The effects of relative items accumulate. Here are some
-examples:
-
- 1 year
- 1 year ago
- 3 years
- 2 days
-
- The unit of time displacement may be selected by the string `year'
-or `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 `fortnight' which is worth 14 days, `week' worth 7 days, `day'
-worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
-seconds, and `second' or `sec' worth one second. An `s' suffix on
-these units is accepted and ignored.
-
- 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 `ago' is equivalent to preceding the unit
-by a multiplier with value -1.
-
- The string `tomorrow' is worth one day in the future (equivalent to
-`day'), the string `yesterday' is worth one day in the past (equivalent
-to `day ago').
-
- The strings `now' or `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 `12:00 today'. The string `this' also has the meaning
-of a zero-valued time displacement, but is preferred in date strings
-like `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.
-
- The fuzz in units can cause problems with relative items. For
-example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
-2003-06-31 is an invalid date. To determine the previous month more
-reliably, you can ask for the month before the 15th of the current
-month. For example:
-
- $ date -R
- Thu, 31 Jul 2003 13:02:39 -0700
- $ 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!
-
- Also, take care when manipulating dates around clock changes such as
-daylight saving leaps. In a few cases these have added or subtracted
-as much as 24 hours from the clock, so it is often wise to adopt
-universal time by setting the `TZ' environment variable to `UTC0'
-before embarking on calendrical calculations.
-
-\1f
-File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats
-
-7.7 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 YYYYMMDD and no other calendar
-date item (*note Calendar date items::) appears before it in the date
-string, then YYYY is read as the year, MM as the month number and DD as
-the day of the month, for the specified calendar date.
-
- If the decimal number is of the form HHMM and no other time of day
-item appears before it in the date string, then HH is read as the hour
-of the day and MM as the minute of the hour, for the specified time of
-day. 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.
-
-\1f
-File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
-
-7.8 Seconds since the Epoch
-===========================
-
-If you precede a number with `@', it represents an internal time stamp
-as a count of seconds. The number can contain an internal decimal
-point (either `.' or `,'); 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.
-
- Internally, computer times are represented as a count of seconds
-since an epoch--a well-defined point of time. On GNU and POSIX
-systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this
-time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and
-most other POSIX-compliant systems support such times as an extension
-to POSIX, using negative counts, so that `@-1' represents 1969-12-31
-23:59:59 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 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 hosts, these counts ignore the presence of leap seconds.
-For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
-UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
-way to represent the intervening leap second 1998-12-31 23:59:60 UTC.
-
-\1f
-File: tar.info, Node: Specifying time zone rules, Next: Authors of parse_datetime, Prev: Seconds since the Epoch, Up: Date input formats
-
-7.9 Specifying time zone rules
-==============================
-
-Normally, dates are interpreted using the rules of the current time
-zone, which in turn are specified by the `TZ' environment variable, or
-by a system default if `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 `TZ="RULE"'. The two quote characters (`"')
-must be present in the date, and any quotes or backslashes within RULE
-must be escaped by a backslash.
-
- For example, with the GNU `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 `TZ="Europe/Paris"' as shown
-in the following shell transcript:
-
- $ export TZ="America/New_York"
- $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
- Sun Oct 31 01:30:00 EDT 2004
-
- In this example, the `--date' operand begins with its own `TZ'
-setting, so the rest of that operand is processed according to
-`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
-were in Paris. However, since the output of the `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 `TZ' value is a rule that typically names a location in the `tz'
-database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of
-location names appears in the TWiki Date and Time Gateway
-(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
-colon before a location name in a `TZ' setting, e.g.,
-`TZ=":America/New_York"'.
-
- The `tz' database includes a wide variety of locations ranging from
-`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
-and have your own private time zone, or if you are using a non-GNU host
-that does not support the `tz' database, you may need to use a POSIX
-rule instead. Simple POSIX rules like `UTC0' specify a time zone
-without daylight saving time; other rules can specify simple daylight
-saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ
-Variable.
-
-\1f
-File: tar.info, Node: Authors of parse_datetime, Prev: Specifying time zone rules, Up: Date input formats
-
-7.10 Authors of `parse_datetime'
-================================
-
-`parse_datetime' started life as `getdate', as originally implemented
-by Steven M. Bellovin (<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
-(<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990.
-Various revisions for the GNU system were made by David MacKenzie, Jim
-Meyering, Paul Eggert and others, including renaming it to `get_date' to
-avoid a conflict with the alternative Posix function `getdate', and a
-later rename to `parse_datetime'. The Posix function `getdate' can
-parse more locale-specific dates using `strptime', but relies on an
-environment variable and external file, and lacks the thread-safety of
-`parse_datetime'.
-
- This chapter was originally produced by Franc,ois Pinard
-(<pinard@iro.umontreal.ca>) from the `parse_datetime.y' source code,
-and then edited by K. Berry (<kb@cs.umb.edu>).
-