1 @c GNU date syntax documentation
3 @c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
4 @c 2003, 2004 Free Software Foundation, Inc.
6 @c Permission is granted to copy, distribute and/or modify this document
7 @c under the terms of the GNU Free Documentation License, Version 1.1 or
8 @c any later version published by the Free Software Foundation; with no
9 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
10 @c Texts. A copy of the license is included in the ``GNU Free
11 @c Documentation License'' file as part of this distribution.
13 @node Date input formats
14 @chapter Date input formats
16 @cindex date input formats
22 Our units of temporal measurement, from seconds on up to months, are so
23 complicated, asymmetrical and disjunctive so as to make coherent mental
24 reckoning in time all but impossible. Indeed, had some tyrannical god
25 contrived to enslave our minds to time, to make it all but impossible
26 for us to escape subjection to sodden routines and unpleasant surprises,
27 he could hardly have done better than handing down our present system.
28 It is like a set of trapezoidal building blocks, with no vertical or
29 horizontal surfaces, like a language in which the simplest thought
30 demands ornate constructions, useless particles and lengthy
31 circumlocutions. Unlike the more successful patterns of language and
32 science, which enable us to face experience boldly or at least
33 level-headedly, our system of temporal calculation silently and
34 persistently encourages our terror of time.
36 @dots{} It is as though architects had to measure length in feet, width
37 in meters and height in ells; as though basic instruction manuals
38 demanded a knowledge of five different languages. It is no wonder then
39 that we often look into our own immediate past or future, last Tuesday
40 or a week from Sunday, with feelings of helpless confusion. @dots{}
42 --- Robert Grudin, @cite{Time and the Art of Living}.
45 This section describes the textual date representations that @sc{gnu}
46 programs accept. These are the strings you, as a user, can supply as
47 arguments to the various programs. The C interface (via the
48 @code{get_date} function) is not described here.
51 * General date syntax:: Common rules.
52 * Calendar date items:: 19 Dec 1994.
53 * Time of day items:: 9:20pm.
54 * Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}, ...
55 * Day of week items:: Monday and others.
56 * Relative items in date strings:: next tuesday, 2 years ago.
57 * Pure numbers in date strings:: 19931219, 1440.
58 * Seconds since the Epoch:: @@1078100502.
59 * Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
63 @node General date syntax
64 @section General date syntax
66 @cindex general date syntax
68 @cindex items in date strings
69 A @dfn{date} is a string, possibly empty, containing many items
70 separated by whitespace. The whitespace may be omitted when no
71 ambiguity arises. The empty string means the beginning of today (i.e.,
72 midnight). Order of the items is immaterial. A date string may contain
73 many flavors of items:
76 @item calendar date items
77 @item time of the day items
79 @item day of the week items
84 @noindent We describe each of these item types in turn, below.
86 @cindex numbers, written-out
87 @cindex ordinal numbers
88 @findex first @r{in date strings}
89 @findex next @r{in date strings}
90 @findex last @r{in date strings}
91 A few numbers may be written out in words in most contexts. This is
92 most useful for specifying day of the week items or relative items (see
93 below). Here is the list: @samp{first} for 1, @samp{next} for 2,
94 @samp{third} for 3, @samp{fourth} for 4, @samp{fifth} for 5,
95 @samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
96 @samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
97 @samp{twelfth} for 12. Also, @samp{last} means exactly @math{-1}.
99 @cindex months, written-out
100 When a month is written this way, it is still considered to be written
101 numerically, instead of being ``spelled in full''; this changes the
104 @cindex language, in dates
105 In the current implementation, only English is supported for words and
106 abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
107 @samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
109 @cindex language, in dates
110 @cindex time zone item
111 The output of @command{date} is not always acceptable as a date string,
112 not only because of the language problem, but also because there is no
113 standard meaning for time zone items like @samp{IST}. When using
114 @command{date} to generate a date string intended to be parsed later,
115 specify a date format that is independent of language and that does not
116 use time zone items other than @samp{UTC} and @samp{Z}. Here are some
120 $ LC_ALL=C TZ=UTC0 date
121 Mon Mar 1 00:21:42 UTC 2004
122 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
124 $ date --iso-8601=ns # a GNU extension
125 2004-02-29T16:21:42,692722128-0800
126 $ date --rfc-2822 # a GNU extension
127 Sun, 29 Feb 2004 16:21:42 -0800
128 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
129 2004-02-29 16:21:42 -0800
130 $ date +'@@%s.%N' # %s and %N are GNU extensions.
131 @@1078100502.692722128
134 @cindex case, ignored in dates
135 @cindex comments, in dates
136 Alphabetic case is completely ignored in dates. Comments may be introduced
137 between round parentheses, as long as included parentheses are properly
138 nested. Hyphens not followed by a digit are currently ignored. Leading
139 zeros on numbers are ignored.
142 @node Calendar date items
143 @section Calendar date items
145 @cindex calendar date item
147 A @dfn{calendar date item} specifies a day of the year. It is
148 specified differently, depending on whether the month is specified
149 numerically or literally. All these strings specify the same calendar date:
152 1972-09-24 # @sc{iso} 8601.
153 72-9-24 # Assume 19xx for 69 through 99,
154 # 20xx for 00 through 68.
155 72-09-24 # Leading zeros are ignored.
156 9/24/72 # Common U.S. writing.
158 24 Sept 72 # September has a special abbreviation.
159 24 Sep 72 # Three-letter abbreviations always allowed.
165 The year can also be omitted. In this case, the last specified year is
166 used, or the current year if none. For example:
175 @cindex @sc{iso} 8601 date format
176 @cindex date format, @sc{iso} 8601
177 For numeric months, the @sc{iso} 8601 format
178 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
179 any positive number, @var{month} is a number between 01 and 12, and
180 @var{day} is a number between 01 and 31. A leading zero must be present
181 if a number is less than ten. If @var{year} is 68 or smaller, then 2000
182 is added to it; otherwise, if @var{year} is less than 100,
183 then 1900 is added to it. The construct
184 @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
185 is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
187 @cindex month names in date strings
188 @cindex abbreviations for months
189 Literal months may be spelled out in full: @samp{January},
190 @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
191 @samp{July}, @samp{August}, @samp{September}, @samp{October},
192 @samp{November} or @samp{December}. Literal months may be abbreviated
193 to their first three letters, possibly followed by an abbreviating dot.
194 It is also permitted to write @samp{Sept} instead of @samp{September}.
196 When months are written literally, the calendar date may be given as any
200 @var{day} @var{month} @var{year}
201 @var{day} @var{month}
202 @var{month} @var{day} @var{year}
203 @var{day}-@var{month}-@var{year}
206 Or, omitting the year:
209 @var{month} @var{day}
213 @node Time of day items
214 @section Time of day items
216 @cindex time of day item
218 A @dfn{time of day item} in date strings specifies the time on a given
219 day. Here are some examples, all of which represent the same time:
225 20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
228 More generally, the time of the day may be given as
229 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
230 a number between 0 and 23, @var{minute} is a number between 0 and
231 59, and @var{second} is a number between 0 and 59 possibly followed by
232 @samp{.} or @samp{,} and a fraction containing one or more digits.
234 @samp{:@var{second}} can be omitted, in which case it is taken to
237 @findex am @r{in date strings}
238 @findex pm @r{in date strings}
239 @findex midnight @r{in date strings}
240 @findex noon @r{in date strings}
241 If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
242 or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
243 @samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
244 indicates the first half of the day, @samp{pm} indicates the second
245 half of the day. In this notation, 12 is the predecessor of 1:
246 midnight is @samp{12am} while noon is @samp{12pm}.
247 (This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
248 as opposed to the old tradition derived from Latin
249 which uses @samp{12m} for noon and @samp{12pm} for midnight.)
251 @cindex time zone correction
252 @cindex minutes, time zone correction by
253 The time may alternatively be followed by a time zone correction,
254 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
255 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
256 of zone minutes. When a time zone correction is given this way, it
257 forces interpretation of the time relative to
258 Coordinated Universal Time (@sc{utc}), overriding any previous
259 specification for the time zone or the local time zone. The @var{minute}
260 part of the time of the day may not be elided when a time zone correction
261 is used. This is the best way to specify a time zone correction by
262 fractional parts of an hour.
264 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
268 @node Time zone items
269 @section Time zone items
271 @cindex time zone item
273 A @dfn{time zone item} specifies an international time zone, indicated
274 by a small set of letters, e.g., @samp{UTC} or @samp{Z}
275 for Coordinated Universal
276 Time. Any included periods are ignored. By following a
277 non-daylight-saving time zone by the string @samp{DST} in a separate
278 word (that is, separated by some white space), the corresponding
279 daylight saving time zone may be specified.
281 Time zone items other than @samp{UTC} and @samp{Z}
282 are obsolescent and are not recommended, because they
283 are ambiguous; for example, @samp{EST} has a different meaning in
284 Australia than in the United States. Instead, it's better to use
285 unambiguous numeric time zone corrections like @samp{-0500}, as
286 described in the previous section.
289 @node Day of week items
290 @section Day of week items
292 @cindex day of week item
294 The explicit mention of a day of the week will forward the date
295 (only if necessary) to reach that day of the week in the future.
297 Days of the week may be spelled out in full: @samp{Sunday},
298 @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
299 @samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
300 first three letters, optionally followed by a period. The special
301 abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
302 @samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
305 @findex next @var{day}
306 @findex last @var{day}
307 A number may precede a day of the week item to move forward
308 supplementary weeks. It is best used in expression like @samp{third
309 monday}. In this context, @samp{last @var{day}} or @samp{next
310 @var{day}} is also acceptable; they move one week before or after
311 the day that @var{day} by itself would represent.
313 A comma following a day of the week item is ignored.
316 @node Relative items in date strings
317 @section Relative items in date strings
319 @cindex relative items in date strings
320 @cindex displacement of dates
322 @dfn{Relative items} adjust a date (or the current date if none) forward
323 or backward. The effects of relative items accumulate. Here are some
333 @findex year @r{in date strings}
334 @findex month @r{in date strings}
335 @findex fortnight @r{in date strings}
336 @findex week @r{in date strings}
337 @findex day @r{in date strings}
338 @findex hour @r{in date strings}
339 @findex minute @r{in date strings}
340 The unit of time displacement may be selected by the string @samp{year}
341 or @samp{month} for moving by whole years or months. These are fuzzy
342 units, as years and months are not all of equal duration. More precise
343 units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
344 days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
345 @samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
346 @samp{sec} worth one second. An @samp{s} suffix on these units is
347 accepted and ignored.
349 @findex ago @r{in date strings}
350 The unit of time may be preceded by a multiplier, given as an optionally
351 signed number. Unsigned numbers are taken as positively signed. No
352 number at all implies 1 for a multiplier. Following a relative item by
353 the string @samp{ago} is equivalent to preceding the unit by a
354 multiplier with value @math{-1}.
356 @findex day @r{in date strings}
357 @findex tomorrow @r{in date strings}
358 @findex yesterday @r{in date strings}
359 The string @samp{tomorrow} is worth one day in the future (equivalent
360 to @samp{day}), the string @samp{yesterday} is worth
361 one day in the past (equivalent to @samp{day ago}).
363 @findex now @r{in date strings}
364 @findex today @r{in date strings}
365 @findex this @r{in date strings}
366 The strings @samp{now} or @samp{today} are relative items corresponding
367 to zero-valued time displacement, these strings come from the fact
368 a zero-valued time displacement represents the current time when not
369 otherwise changed by previous items. They may be used to stress other
370 items, like in @samp{12:00 today}. The string @samp{this} also has
371 the meaning of a zero-valued time displacement, but is preferred in
372 date strings like @samp{this thursday}.
374 When a relative item causes the resulting date to cross a boundary
375 where the clocks were adjusted, typically for daylight-saving time,
376 the resulting date and time are adjusted accordingly.
378 The fuzz in units can cause problems with relative items. For
379 example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
380 because 2003-06-31 is an invalid date. To determine the previous
381 month more reliably, you can ask for the month before the 15th of the
382 current month. For example:
386 Thu, 31 Jul 2003 13:02:39 -0700
387 $ date --date='-1 month' +'Last month was %B?'
389 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
393 Also, take care when manipulating dates around clock changes such as
394 daylight saving leaps. In a few cases these have added or subtracted
395 as much as 24 hours from the clock, so it is often wise to adopt
396 universal time by setting the @env{TZ} environment variable to
397 @samp{UTC0} before embarking on calendrical calculations.
399 @node Pure numbers in date strings
400 @section Pure numbers in date strings
402 @cindex pure numbers in date strings
404 The precise interpretation of a pure decimal number depends
405 on the context in the date string.
407 If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
408 other calendar date item (@pxref{Calendar date items}) appears before it
409 in the date string, then @var{yyyy} is read as the year, @var{mm} as the
410 month number and @var{dd} as the day of the month, for the specified
413 If the decimal number is of the form @var{hh}@var{mm} and no other time
414 of day item appears before it in the date string, then @var{hh} is read
415 as the hour of the day and @var{mm} as the minute of the hour, for the
416 specified time of the day. @var{mm} can also be omitted.
418 If both a calendar date and a time of day appear to the left of a number
419 in the date string, but no relative item, then the number overrides the
423 @node Seconds since the Epoch
424 @section Seconds since the Epoch
426 If you precede a number with @samp{@@}, it represents an internal time
427 stamp as a count of seconds. The number can contain an internal
428 decimal point (either @samp{.} or @samp{,}); any excess precision not
429 supported by the internal representation is truncated toward minus
432 @cindex beginning of time, for @acronym{POSIX}
433 @cindex epoch, for @acronym{POSIX}
434 Internally, computer times are represented as a count of seconds since
435 an epoch---a well-defined point of time. On @acronym{GNU} and
436 @acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
437 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
438 00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
439 @acronym{POSIX}-compliant systems support such times as an extension
440 to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
441 represents 1969-12-31 23:59:59 @sc{utc}.
443 Traditional Unix systems count seconds with 32-bit two's-complement
444 integers and can represent times from 1901-12-13 20:45:52 through
445 2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
446 of seconds with nanosecond subcounts, and can represent all the times
447 in the known lifetime of the universe to a resolution of 1 nanosecond.
449 On most systems, these counts ignore the presence of leap seconds.
450 For example, on most systems @samp{@@915148799} represents 1998-12-31
451 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
452 @sc{utc}, and there is no way to represent the intervening leap second
453 1998-12-31 23:59:60 @sc{utc}.
455 @node Authors of get_date
456 @section Authors of @code{get_date}
458 @cindex authors of @code{get_date}
460 @cindex Bellovin, Steven M.
463 @cindex MacKenzie, David
464 @cindex Meyering, Jim
466 @code{get_date} was originally implemented by Steven M. Bellovin
467 (@email{smb@@research.att.com}) while at the University of North Carolina
468 at Chapel Hill. The code was later tweaked by a couple of people on
469 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
470 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
471 revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
472 Paul Eggert and others.
476 This chapter was originally produced by Fran@,{c}ois Pinard
477 (@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
478 and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).