coreutils: Relative items in date strings
1
1 29.7 Relative items in date strings
1 ===================================
1
1 “Relative items” adjust a date (or the current date if none) forward or
1 backward. The effects of relative items accumulate. Here are some
1 examples:
1
1 1 year
1 1 year ago
1 3 years
1 2 days
1
1 The unit of time displacement may be selected by the string ‘year’ or
1 ‘month’ for moving by whole years or months. These are fuzzy units, as
1 years and months are not all of equal duration. More precise units are
1 ‘fortnight’ which is worth 14 days, ‘week’ worth 7 days, ‘day’ worth 24
1 hours, ‘hour’ worth 60 minutes, ‘minute’ or ‘min’ worth 60 seconds, and
1 ‘second’ or ‘sec’ worth one second. An ‘s’ suffix on these units is
1 accepted and ignored.
1
1 The unit of time may be preceded by a multiplier, given as an
1 optionally signed number. Unsigned numbers are taken as positively
1 signed. No number at all implies 1 for a multiplier. Following a
1 relative item by the string ‘ago’ is equivalent to preceding the unit by
1 a multiplier with value -1.
1
1 The string ‘tomorrow’ is worth one day in the future (equivalent to
1 ‘day’), the string ‘yesterday’ is worth one day in the past (equivalent
1 to ‘day ago’).
1
1 The strings ‘now’ or ‘today’ are relative items corresponding to
1 zero-valued time displacement, these strings come from the fact a
1 zero-valued time displacement represents the current time when not
1 otherwise changed by previous items. They may be used to stress other
1 items, like in ‘12:00 today’. The string ‘this’ also has the meaning of
1 a zero-valued time displacement, but is preferred in date strings like
1 ‘this thursday’.
1
1 When a relative item causes the resulting date to cross a boundary
1 where the clocks were adjusted, typically for daylight saving time, the
1 resulting date and time are adjusted accordingly.
1
1 The fuzz in units can cause problems with relative items. For
1 example, ‘2003-07-31 -1 month’ might evaluate to 2003-07-01, because
1 2003-06-31 is an invalid date. To determine the previous month more
1 reliably, you can ask for the month before the 15th of the current
1 month. For example:
1
1 $ date -R
1 Thu, 31 Jul 2003 13:02:39 -0700
1 $ date --date='-1 month' +'Last month was %B?'
1 Last month was July?
1 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
1 Last month was June!
1
1 Also, take care when manipulating dates around clock changes such as
1 daylight saving leaps. In a few cases these have added or subtracted as
1 much as 24 hours from the clock, so it is often wise to adopt universal
1 time by setting the ‘TZ’ environment variable to ‘UTC0’ before embarking
1 on calendrical calculations.
1