1 @c GNU date syntax documentation
3 @c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
4 @c 2004, 2005, 2006, 2009, 2010 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.3 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 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
60 * Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
64 @node General date syntax
65 @section General date syntax
67 @cindex general date syntax
69 @cindex items in date strings
70 A @dfn{date} is a string, possibly empty, containing many items
71 separated by whitespace. The whitespace may be omitted when no
72 ambiguity arises. The empty string means the beginning of today (i.e.,
73 midnight). Order of the items is immaterial. A date string may contain
74 many flavors of items:
77 @item calendar date items
78 @item time of day items
80 @item day of the week items
85 @noindent We describe each of these item types in turn, below.
87 @cindex numbers, written-out
88 @cindex ordinal numbers
89 @findex first @r{in date strings}
90 @findex next @r{in date strings}
91 @findex last @r{in date strings}
92 A few ordinal numbers may be written out in words in some contexts. This is
93 most useful for specifying day of the week items or relative items (see
94 below). Among the most commonly used ordinal numbers, the word
95 @samp{last} stands for @math{-1}, @samp{this} stands for 0, and
96 @samp{first} and @samp{next} both stand for 1. Because the word
97 @samp{second} stands for the unit of time there is no way to write the
98 ordinal number 2, but for convenience @samp{third} stands for 3,
99 @samp{fourth} for 4, @samp{fifth} for 5,
100 @samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
101 @samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
102 @samp{twelfth} for 12.
104 @cindex months, written-out
105 When a month is written this way, it is still considered to be written
106 numerically, instead of being ``spelled in full''; this changes the
109 @cindex language, in dates
110 In the current implementation, only English is supported for words and
111 abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
112 @samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
114 @cindex language, in dates
115 @cindex time zone item
116 The output of the @command{date} command
117 is not always acceptable as a date string,
118 not only because of the language problem, but also because there is no
119 standard meaning for time zone items like @samp{IST}. When using
120 @command{date} to generate a date string intended to be parsed later,
121 specify a date format that is independent of language and that does not
122 use time zone items other than @samp{UTC} and @samp{Z}. Here are some
126 $ LC_ALL=C TZ=UTC0 date
127 Mon Mar 1 00:21:42 UTC 2004
128 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
130 $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
131 2004-02-29 16:21:42,692722128-0800
132 $ date --rfc-2822 # a GNU extension
133 Sun, 29 Feb 2004 16:21:42 -0800
134 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
135 2004-02-29 16:21:42 -0800
136 $ date +'@@%s.%N' # %s and %N are GNU extensions.
137 @@1078100502.692722128
140 @cindex case, ignored in dates
141 @cindex comments, in dates
142 Alphabetic case is completely ignored in dates. Comments may be introduced
143 between round parentheses, as long as included parentheses are properly
144 nested. Hyphens not followed by a digit are currently ignored. Leading
145 zeros on numbers are ignored.
147 Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
148 rejected. In the typical case of a host that does not support leap
149 seconds, a time like @samp{23:59:60} is rejected even if it
150 corresponds to a valid leap second.
153 @node Calendar date items
154 @section Calendar date items
156 @cindex calendar date item
158 A @dfn{calendar date item} specifies a day of the year. It is
159 specified differently, depending on whether the month is specified
160 numerically or literally. All these strings specify the same calendar date:
163 1972-09-24 # @sc{iso} 8601.
164 72-9-24 # Assume 19xx for 69 through 99,
165 # 20xx for 00 through 68.
166 72-09-24 # Leading zeros are ignored.
167 9/24/72 # Common U.S. writing.
169 24 Sept 72 # September has a special abbreviation.
170 24 Sep 72 # Three-letter abbreviations always allowed.
176 The year can also be omitted. In this case, the last specified year is
177 used, or the current year if none. For example:
186 @cindex @sc{iso} 8601 date format
187 @cindex date format, @sc{iso} 8601
188 For numeric months, the @sc{iso} 8601 format
189 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
190 any positive number, @var{month} is a number between 01 and 12, and
191 @var{day} is a number between 01 and 31. A leading zero must be present
192 if a number is less than ten. If @var{year} is 68 or smaller, then 2000
193 is added to it; otherwise, if @var{year} is less than 100,
194 then 1900 is added to it. The construct
195 @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
196 is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
198 @cindex month names in date strings
199 @cindex abbreviations for months
200 Literal months may be spelled out in full: @samp{January},
201 @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
202 @samp{July}, @samp{August}, @samp{September}, @samp{October},
203 @samp{November} or @samp{December}. Literal months may be abbreviated
204 to their first three letters, possibly followed by an abbreviating dot.
205 It is also permitted to write @samp{Sept} instead of @samp{September}.
207 When months are written literally, the calendar date may be given as any
211 @var{day} @var{month} @var{year}
212 @var{day} @var{month}
213 @var{month} @var{day} @var{year}
214 @var{day}-@var{month}-@var{year}
217 Or, omitting the year:
220 @var{month} @var{day}
224 @node Time of day items
225 @section Time of day items
227 @cindex time of day item
229 A @dfn{time of day item} in date strings specifies the time on a given
230 day. Here are some examples, all of which represent the same time:
236 20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
239 More generally, the time of day may be given as
240 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
241 a number between 0 and 23, @var{minute} is a number between 0 and
242 59, and @var{second} is a number between 0 and 59 possibly followed by
243 @samp{.} or @samp{,} and a fraction containing one or more digits.
245 @samp{:@var{second}} can be omitted, in which case it is taken to
246 be zero. On the rare hosts that support leap seconds, @var{second}
249 @findex am @r{in date strings}
250 @findex pm @r{in date strings}
251 @findex midnight @r{in date strings}
252 @findex noon @r{in date strings}
253 If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
254 or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
255 @samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
256 indicates the first half of the day, @samp{pm} indicates the second
257 half of the day. In this notation, 12 is the predecessor of 1:
258 midnight is @samp{12am} while noon is @samp{12pm}.
259 (This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
260 as opposed to the old tradition derived from Latin
261 which uses @samp{12m} for noon and @samp{12pm} for midnight.)
263 @cindex time zone correction
264 @cindex minutes, time zone correction by
265 The time may alternatively be followed by a time zone correction,
266 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
267 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
269 The zone minutes term, @var{mm}, may be omitted, in which case
270 the one- or two-digit correction is interpreted as a number of hours.
271 You can also separate @var{hh} from @var{mm} with a colon.
272 When a time zone correction is given this way, it
273 forces interpretation of the time relative to
274 Coordinated Universal Time (@sc{utc}), overriding any previous
275 specification for the time zone or the local time zone. For example,
276 @samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
277 ahead of @sc{utc} (e.g., India).
278 This is the best way to
279 specify a time zone correction by fractional parts of an hour.
280 The maximum zone correction is 24 hours.
282 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
286 @node Time zone items
287 @section Time zone items
289 @cindex time zone item
291 A @dfn{time zone item} specifies an international time zone, indicated
292 by a small set of letters, e.g., @samp{UTC} or @samp{Z}
293 for Coordinated Universal
294 Time. Any included periods are ignored. By following a
295 non-daylight-saving time zone by the string @samp{DST} in a separate
296 word (that is, separated by some white space), the corresponding
297 daylight saving time zone may be specified.
298 Alternatively, a non-daylight-saving time zone can be followed by a
299 time zone correction, to add the two values. This is normally done
300 only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
303 Time zone items other than @samp{UTC} and @samp{Z}
304 are obsolescent and are not recommended, because they
305 are ambiguous; for example, @samp{EST} has a different meaning in
306 Australia than in the United States. Instead, it's better to use
307 unambiguous numeric time zone corrections like @samp{-0500}, as
308 described in the previous section.
310 If neither a time zone item nor a time zone correction is supplied,
311 time stamps are interpreted using the rules of the default time zone
312 (@pxref{Specifying time zone rules}).
315 @node Day of week items
316 @section Day of week items
318 @cindex day of week item
320 The explicit mention of a day of the week will forward the date
321 (only if necessary) to reach that day of the week in the future.
323 Days of the week may be spelled out in full: @samp{Sunday},
324 @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
325 @samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
326 first three letters, optionally followed by a period. The special
327 abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
328 @samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
331 @findex next @var{day}
332 @findex last @var{day}
333 A number may precede a day of the week item to move forward
334 supplementary weeks. It is best used in expression like @samp{third
335 monday}. In this context, @samp{last @var{day}} or @samp{next
336 @var{day}} is also acceptable; they move one week before or after
337 the day that @var{day} by itself would represent.
339 A comma following a day of the week item is ignored.
342 @node Relative items in date strings
343 @section Relative items in date strings
345 @cindex relative items in date strings
346 @cindex displacement of dates
348 @dfn{Relative items} adjust a date (or the current date if none) forward
349 or backward. The effects of relative items accumulate. Here are some
359 @findex year @r{in date strings}
360 @findex month @r{in date strings}
361 @findex fortnight @r{in date strings}
362 @findex week @r{in date strings}
363 @findex day @r{in date strings}
364 @findex hour @r{in date strings}
365 @findex minute @r{in date strings}
366 The unit of time displacement may be selected by the string @samp{year}
367 or @samp{month} for moving by whole years or months. These are fuzzy
368 units, as years and months are not all of equal duration. More precise
369 units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
370 days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
371 @samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
372 @samp{sec} worth one second. An @samp{s} suffix on these units is
373 accepted and ignored.
375 @findex ago @r{in date strings}
376 The unit of time may be preceded by a multiplier, given as an optionally
377 signed number. Unsigned numbers are taken as positively signed. No
378 number at all implies 1 for a multiplier. Following a relative item by
379 the string @samp{ago} is equivalent to preceding the unit by a
380 multiplier with value @math{-1}.
382 @findex day @r{in date strings}
383 @findex tomorrow @r{in date strings}
384 @findex yesterday @r{in date strings}
385 The string @samp{tomorrow} is worth one day in the future (equivalent
386 to @samp{day}), the string @samp{yesterday} is worth
387 one day in the past (equivalent to @samp{day ago}).
389 @findex now @r{in date strings}
390 @findex today @r{in date strings}
391 @findex this @r{in date strings}
392 The strings @samp{now} or @samp{today} are relative items corresponding
393 to zero-valued time displacement, these strings come from the fact
394 a zero-valued time displacement represents the current time when not
395 otherwise changed by previous items. They may be used to stress other
396 items, like in @samp{12:00 today}. The string @samp{this} also has
397 the meaning of a zero-valued time displacement, but is preferred in
398 date strings like @samp{this thursday}.
400 When a relative item causes the resulting date to cross a boundary
401 where the clocks were adjusted, typically for daylight saving time,
402 the resulting date and time are adjusted accordingly.
404 The fuzz in units can cause problems with relative items. For
405 example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
406 because 2003-06-31 is an invalid date. To determine the previous
407 month more reliably, you can ask for the month before the 15th of the
408 current month. For example:
412 Thu, 31 Jul 2003 13:02:39 -0700
413 $ date --date='-1 month' +'Last month was %B?'
415 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
419 Also, take care when manipulating dates around clock changes such as
420 daylight saving leaps. In a few cases these have added or subtracted
421 as much as 24 hours from the clock, so it is often wise to adopt
422 universal time by setting the @env{TZ} environment variable to
423 @samp{UTC0} before embarking on calendrical calculations.
425 @node Pure numbers in date strings
426 @section Pure numbers in date strings
428 @cindex pure numbers in date strings
430 The precise interpretation of a pure decimal number depends
431 on the context in the date string.
433 If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
434 other calendar date item (@pxref{Calendar date items}) appears before it
435 in the date string, then @var{yyyy} is read as the year, @var{mm} as the
436 month number and @var{dd} as the day of the month, for the specified
439 If the decimal number is of the form @var{hh}@var{mm} and no other time
440 of day item appears before it in the date string, then @var{hh} is read
441 as the hour of the day and @var{mm} as the minute of the hour, for the
442 specified time of day. @var{mm} can also be omitted.
444 If both a calendar date and a time of day appear to the left of a number
445 in the date string, but no relative item, then the number overrides the
449 @node Seconds since the Epoch
450 @section Seconds since the Epoch
452 If you precede a number with @samp{@@}, it represents an internal time
453 stamp as a count of seconds. The number can contain an internal
454 decimal point (either @samp{.} or @samp{,}); any excess precision not
455 supported by the internal representation is truncated toward minus
456 infinity. Such a number cannot be combined with any other date
457 item, as it specifies a complete time stamp.
459 @cindex beginning of time, for @acronym{POSIX}
460 @cindex epoch, for @acronym{POSIX}
461 Internally, computer times are represented as a count of seconds since
462 an epoch---a well-defined point of time. On @acronym{GNU} and
463 @acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
464 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
465 00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
466 @acronym{POSIX}-compliant systems support such times as an extension
467 to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
468 represents 1969-12-31 23:59:59 @sc{utc}.
470 Traditional Unix systems count seconds with 32-bit two's-complement
471 integers and can represent times from 1901-12-13 20:45:52 through
472 2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
473 of seconds with nanosecond subcounts, and can represent all the times
474 in the known lifetime of the universe to a resolution of 1 nanosecond.
476 On most hosts, these counts ignore the presence of leap seconds.
477 For example, on most hosts @samp{@@915148799} represents 1998-12-31
478 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
479 @sc{utc}, and there is no way to represent the intervening leap second
480 1998-12-31 23:59:60 @sc{utc}.
482 @node Specifying time zone rules
483 @section Specifying time zone rules
486 Normally, dates are interpreted using the rules of the current time
487 zone, which in turn are specified by the @env{TZ} environment
488 variable, or by a system default if @env{TZ} is not set. To specify a
489 different set of default time zone rules that apply just to one date,
490 start the date with a string of the form @samp{TZ="@var{rule}"}. The
491 two quote characters (@samp{"}) must be present in the date, and any
492 quotes or backslashes within @var{rule} must be escaped by a
495 For example, with the @acronym{GNU} @command{date} command you can
496 answer the question ``What time is it in New York when a Paris clock
497 shows 6:30am on October 31, 2004?'' by using a date beginning with
498 @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
501 $ export TZ="America/New_York"
502 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
503 Sun Oct 31 01:30:00 EDT 2004
506 In this example, the @option{--date} operand begins with its own
507 @env{TZ} setting, so the rest of that operand is processed according
508 to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
509 06:30} as if it were in Paris. However, since the output of the
510 @command{date} command is processed according to the overall time zone
511 rules, it uses New York time. (Paris was normally six hours ahead of
512 New York in 2004, but this example refers to a brief Halloween period
513 when the gap was five hours.)
515 A @env{TZ} value is a rule that typically names a location in the
516 @uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
517 A recent catalog of location names appears in the
518 @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
519 Gateway}. A few non-@acronym{GNU} hosts require a colon before a
520 location name in a @env{TZ} setting, e.g.,
521 @samp{TZ=":America/New_York"}.
523 The @samp{tz} database includes a wide variety of locations ranging
524 from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
525 if you are at sea and have your own private time zone, or if you are
526 using a non-@acronym{GNU} host that does not support the @samp{tz}
527 database, you may need to use a @acronym{POSIX} rule instead. Simple
528 @acronym{POSIX} rules like @samp{UTC0} specify a time zone without
529 daylight saving time; other rules can specify simple daylight saving
530 regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
531 libc, The GNU C Library}.
533 @node Authors of get_date
534 @section Authors of @code{get_date}
536 @cindex authors of @code{get_date}
538 @cindex Bellovin, Steven M.
541 @cindex MacKenzie, David
542 @cindex Meyering, Jim
544 @code{get_date} was originally implemented by Steven M. Bellovin
545 (@email{smb@@research.att.com}) while at the University of North Carolina
546 at Chapel Hill. The code was later tweaked by a couple of people on
547 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
548 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
549 revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
550 Paul Eggert and others.
554 This chapter was originally produced by Fran@,{c}ois Pinard
555 (@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
556 and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).