coreutils: General date syntax
1
1 29.1 General date syntax
1 ========================
1
1 A “date” is a string, possibly empty, containing many items separated by
1 whitespace. The whitespace may be omitted when no ambiguity arises.
1 The empty string means the beginning of today (i.e., midnight). Order
1 of the items is immaterial. A date string may contain many flavors of
1 items:
1
1 • calendar date items
1 • time of day items
1 • time zone items
1 • combined date and time of day items
1 • day of the week items
1 • relative items
1 • pure numbers.
1
1 We describe each of these item types in turn, below.
1
1 A few ordinal numbers may be written out in words in some contexts.
1 This is most useful for specifying day of the week items or relative
1 items (see below). Among the most commonly used ordinal numbers, the
1 word ‘last’ stands for -1, ‘this’ stands for 0, and ‘first’ and ‘next’
1 both stand for 1. Because the word ‘second’ stands for the unit of time
1 there is no way to write the ordinal number 2, but for convenience
1 ‘third’ stands for 3, ‘fourth’ for 4, ‘fifth’ for 5, ‘sixth’ for 6,
1 ‘seventh’ for 7, ‘eighth’ for 8, ‘ninth’ for 9, ‘tenth’ for 10,
1 ‘eleventh’ for 11 and ‘twelfth’ for 12.
1
1 When a month is written this way, it is still considered to be
1 written numerically, instead of being “spelled in full”; this changes
1 the allowed strings.
1
1 In the current implementation, only English is supported for words
1 and abbreviations like ‘AM’, ‘DST’, ‘EST’, ‘first’, ‘January’, ‘Sunday’,
1 ‘tomorrow’, and ‘year’.
1
1 The output of the ‘date’ command is not always acceptable as a date
1 string, not only because of the language problem, but also because there
1 is no standard meaning for time zone items like ‘IST’. When using
1 ‘date’ to generate a date string intended to be parsed later, specify a
1 date format that is independent of language and that does not use time
1 zone items other than ‘UTC’ and ‘Z’. Here are some ways to do this:
1
1 $ LC_ALL=C TZ=UTC0 date
1 Mon Mar 1 00:21:42 UTC 2004
1 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
1 2004-03-01 00:21:42Z
1 $ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
1 2004-02-29 16:21:42.692722128-08:00
1 $ date --rfc-2822 # a GNU extension
1 Sun, 29 Feb 2004 16:21:42 -0800
1 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
1 2004-02-29 16:21:42 -0800
1 $ date +'@%s.%N' # %s and %N are GNU extensions.
1 @1078100502.692722128
1
1 Alphabetic case is completely ignored in dates. Comments may be
1 introduced between round parentheses, as long as included parentheses
1 are properly nested. Hyphens not followed by a digit are currently
1 ignored. Leading zeros on numbers are ignored.
1
1 Invalid dates like ‘2005-02-29’ or times like ‘24:00’ are rejected.
1 In the typical case of a host that does not support leap seconds, a time
1 like ‘23:59:60’ is rejected even if it corresponds to a valid leap
1 second.
1