1 @c GNU date syntax documentation
3 @c Copyright (C) 1994-2006, 2009-2011 Free Software Foundation, Inc.
5 @c Permission is granted to copy, distribute and/or modify this document
6 @c under the terms of the GNU Free Documentation License, Version 1.3 or
7 @c any later version published by the Free Software Foundation; with no
8 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
9 @c Texts. A copy of the license is included in the ``GNU Free
10 @c Documentation License'' file as part of this distribution.
12 @node Date input formats
13 @chapter Date input formats
15 @cindex date input formats
16 @findex parse_datetime
21 Our units of temporal measurement, from seconds on up to months, are so
22 complicated, asymmetrical and disjunctive so as to make coherent mental
23 reckoning in time all but impossible. Indeed, had some tyrannical god
24 contrived to enslave our minds to time, to make it all but impossible
25 for us to escape subjection to sodden routines and unpleasant surprises,
26 he could hardly have done better than handing down our present system.
27 It is like a set of trapezoidal building blocks, with no vertical or
28 horizontal surfaces, like a language in which the simplest thought
29 demands ornate constructions, useless particles and lengthy
30 circumlocutions. Unlike the more successful patterns of language and
31 science, which enable us to face experience boldly or at least
32 level-headedly, our system of temporal calculation silently and
33 persistently encourages our terror of time.
35 @dots{} It is as though architects had to measure length in feet, width
36 in meters and height in ells; as though basic instruction manuals
37 demanded a knowledge of five different languages. It is no wonder then
38 that we often look into our own immediate past or future, last Tuesday
39 or a week from Sunday, with feelings of helpless confusion. @dots{}
41 --- Robert Grudin, @cite{Time and the Art of Living}.
44 This section describes the textual date representations that @sc{gnu}
45 programs accept. These are the strings you, as a user, can supply as
46 arguments to the various programs. The C interface (via the
47 @code{parse_datetime} function) is not described here.
50 * General date syntax:: Common rules.
51 * Calendar date items:: 19 Dec 1994.
52 * Time of day items:: 9:20pm.
53 * Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
54 * Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500
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 parse_datetime:: 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 combined date and time of day items
81 @item day of the week items
86 @noindent We describe each of these item types in turn, below.
88 @cindex numbers, written-out
89 @cindex ordinal numbers
90 @findex first @r{in date strings}
91 @findex next @r{in date strings}
92 @findex last @r{in date strings}
93 A few ordinal numbers may be written out in words in some contexts. This is
94 most useful for specifying day of the week items or relative items (see
95 below). Among the most commonly used ordinal numbers, the word
96 @samp{last} stands for @math{-1}, @samp{this} stands for 0, and
97 @samp{first} and @samp{next} both stand for 1. Because the word
98 @samp{second} stands for the unit of time there is no way to write the
99 ordinal number 2, but for convenience @samp{third} stands for 3,
100 @samp{fourth} for 4, @samp{fifth} for 5,
101 @samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
102 @samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
103 @samp{twelfth} for 12.
105 @cindex months, written-out
106 When a month is written this way, it is still considered to be written
107 numerically, instead of being ``spelled in full''; this changes the
110 @cindex language, in dates
111 In the current implementation, only English is supported for words and
112 abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
113 @samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
115 @cindex language, in dates
116 @cindex time zone item
117 The output of the @command{date} command
118 is not always acceptable as a date string,
119 not only because of the language problem, but also because there is no
120 standard meaning for time zone items like @samp{IST}. When using
121 @command{date} to generate a date string intended to be parsed later,
122 specify a date format that is independent of language and that does not
123 use time zone items other than @samp{UTC} and @samp{Z}. Here are some
127 $ LC_ALL=C TZ=UTC0 date
128 Mon Mar 1 00:21:42 UTC 2004
129 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
131 $ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
132 2004-02-29 16:21:42.692722128-08:00
133 $ date --rfc-2822 # a GNU extension
134 Sun, 29 Feb 2004 16:21:42 -0800
135 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
136 2004-02-29 16:21:42 -0800
137 $ date +'@@%s.%N' # %s and %N are GNU extensions.
138 @@1078100502.692722128
141 @cindex case, ignored in dates
142 @cindex comments, in dates
143 Alphabetic case is completely ignored in dates. Comments may be introduced
144 between round parentheses, as long as included parentheses are properly
145 nested. Hyphens not followed by a digit are currently ignored. Leading
146 zeros on numbers are ignored.
148 Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
149 rejected. In the typical case of a host that does not support leap
150 seconds, a time like @samp{23:59:60} is rejected even if it
151 corresponds to a valid leap second.
154 @node Calendar date items
155 @section Calendar date items
157 @cindex calendar date item
159 A @dfn{calendar date item} specifies a day of the year. It is
160 specified differently, depending on whether the month is specified
161 numerically or literally. All these strings specify the same calendar date:
164 1972-09-24 # @sc{iso} 8601.
165 72-9-24 # Assume 19xx for 69 through 99,
166 # 20xx for 00 through 68.
167 72-09-24 # Leading zeros are ignored.
168 9/24/72 # Common U.S. writing.
170 24 Sept 72 # September has a special abbreviation.
171 24 Sep 72 # Three-letter abbreviations always allowed.
177 The year can also be omitted. In this case, the last specified year is
178 used, or the current year if none. For example:
187 @cindex @sc{iso} 8601 date format
188 @cindex date format, @sc{iso} 8601
189 For numeric months, the @sc{iso} 8601 format
190 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
191 any positive number, @var{month} is a number between 01 and 12, and
192 @var{day} is a number between 01 and 31. A leading zero must be present
193 if a number is less than ten. If @var{year} is 68 or smaller, then 2000
194 is added to it; otherwise, if @var{year} is less than 100,
195 then 1900 is added to it. The construct
196 @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
197 is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
199 @cindex month names in date strings
200 @cindex abbreviations for months
201 Literal months may be spelled out in full: @samp{January},
202 @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
203 @samp{July}, @samp{August}, @samp{September}, @samp{October},
204 @samp{November} or @samp{December}. Literal months may be abbreviated
205 to their first three letters, possibly followed by an abbreviating dot.
206 It is also permitted to write @samp{Sept} instead of @samp{September}.
208 When months are written literally, the calendar date may be given as any
212 @var{day} @var{month} @var{year}
213 @var{day} @var{month}
214 @var{month} @var{day} @var{year}
215 @var{day}-@var{month}-@var{year}
218 Or, omitting the year:
221 @var{month} @var{day}
225 @node Time of day items
226 @section Time of day items
228 @cindex time of day item
230 A @dfn{time of day item} in date strings specifies the time on a given
231 day. Here are some examples, all of which represent the same time:
237 20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
240 More generally, the time of day may be given as
241 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
242 a number between 0 and 23, @var{minute} is a number between 0 and
243 59, and @var{second} is a number between 0 and 59 possibly followed by
244 @samp{.} or @samp{,} and a fraction containing one or more digits.
246 @samp{:@var{second}} can be omitted, in which case it is taken to
247 be zero. On the rare hosts that support leap seconds, @var{second}
250 @findex am @r{in date strings}
251 @findex pm @r{in date strings}
252 @findex midnight @r{in date strings}
253 @findex noon @r{in date strings}
254 If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
255 or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
256 @samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
257 indicates the first half of the day, @samp{pm} indicates the second
258 half of the day. In this notation, 12 is the predecessor of 1:
259 midnight is @samp{12am} while noon is @samp{12pm}.
260 (This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
261 as opposed to the old tradition derived from Latin
262 which uses @samp{12m} for noon and @samp{12pm} for midnight.)
264 @cindex time zone correction
265 @cindex minutes, time zone correction by
266 The time may alternatively be followed by a time zone correction,
267 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
268 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
270 The zone minutes term, @var{mm}, may be omitted, in which case
271 the one- or two-digit correction is interpreted as a number of hours.
272 You can also separate @var{hh} from @var{mm} with a colon.
273 When a time zone correction is given this way, it
274 forces interpretation of the time relative to
275 Coordinated Universal Time (@sc{utc}), overriding any previous
276 specification for the time zone or the local time zone. For example,
277 @samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
278 ahead of @sc{utc} (e.g., India).
279 This is the best way to
280 specify a time zone correction by fractional parts of an hour.
281 The maximum zone correction is 24 hours.
283 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
287 @node Time zone items
288 @section Time zone items
290 @cindex time zone item
292 A @dfn{time zone item} specifies an international time zone, indicated
293 by a small set of letters, e.g., @samp{UTC} or @samp{Z}
294 for Coordinated Universal
295 Time. Any included periods are ignored. By following a
296 non-daylight-saving time zone by the string @samp{DST} in a separate
297 word (that is, separated by some white space), the corresponding
298 daylight saving time zone may be specified.
299 Alternatively, a non-daylight-saving time zone can be followed by a
300 time zone correction, to add the two values. This is normally done
301 only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
304 Time zone items other than @samp{UTC} and @samp{Z}
305 are obsolescent and are not recommended, because they
306 are ambiguous; for example, @samp{EST} has a different meaning in
307 Australia than in the United States. Instead, it's better to use
308 unambiguous numeric time zone corrections like @samp{-0500}, as
309 described in the previous section.
311 If neither a time zone item nor a time zone correction is supplied,
312 time stamps are interpreted using the rules of the default time zone
313 (@pxref{Specifying time zone rules}).
316 @node Combined date and time of day items
317 @section Combined date and time of day items
319 @cindex combined date and time of day item
321 A @dfn{combined date and time of day item} specifies the time on a
322 specific day of the year. This type is needed for formats that cannot
323 be represented by individual calendar date (@pxref{Calendar date items})
324 and time of day (@pxref{Time of day items}) items due to ambiguity.
327 # ISO 8601 extended date and time of day format
328 1972-09-24T20:02:00,000000-0500
331 @cindex @sc{iso} 8601 date and time of day format
332 @cindex date and time of day format, @sc{iso} 8601
334 The @sc{iso} 8601 extended date and time of day format is an @sc{iso}
335 8601 date, a @samp{T} character separator, followed by an @sc{iso} 8601 time
339 @node Day of week items
340 @section Day of week items
342 @cindex day of week item
344 The explicit mention of a day of the week will forward the date
345 (only if necessary) to reach that day of the week in the future.
347 Days of the week may be spelled out in full: @samp{Sunday},
348 @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
349 @samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
350 first three letters, optionally followed by a period. The special
351 abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
352 @samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
355 @findex next @var{day}
356 @findex last @var{day}
357 A number may precede a day of the week item to move forward
358 supplementary weeks. It is best used in expression like @samp{third
359 monday}. In this context, @samp{last @var{day}} or @samp{next
360 @var{day}} is also acceptable; they move one week before or after
361 the day that @var{day} by itself would represent.
363 A comma following a day of the week item is ignored.
366 @node Relative items in date strings
367 @section Relative items in date strings
369 @cindex relative items in date strings
370 @cindex displacement of dates
372 @dfn{Relative items} adjust a date (or the current date if none) forward
373 or backward. The effects of relative items accumulate. Here are some
383 @findex year @r{in date strings}
384 @findex month @r{in date strings}
385 @findex fortnight @r{in date strings}
386 @findex week @r{in date strings}
387 @findex day @r{in date strings}
388 @findex hour @r{in date strings}
389 @findex minute @r{in date strings}
390 The unit of time displacement may be selected by the string @samp{year}
391 or @samp{month} for moving by whole years or months. These are fuzzy
392 units, as years and months are not all of equal duration. More precise
393 units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
394 days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
395 @samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
396 @samp{sec} worth one second. An @samp{s} suffix on these units is
397 accepted and ignored.
399 @findex ago @r{in date strings}
400 The unit of time may be preceded by a multiplier, given as an optionally
401 signed number. Unsigned numbers are taken as positively signed. No
402 number at all implies 1 for a multiplier. Following a relative item by
403 the string @samp{ago} is equivalent to preceding the unit by a
404 multiplier with value @math{-1}.
406 @findex day @r{in date strings}
407 @findex tomorrow @r{in date strings}
408 @findex yesterday @r{in date strings}
409 The string @samp{tomorrow} is worth one day in the future (equivalent
410 to @samp{day}), the string @samp{yesterday} is worth
411 one day in the past (equivalent to @samp{day ago}).
413 @findex now @r{in date strings}
414 @findex today @r{in date strings}
415 @findex this @r{in date strings}
416 The strings @samp{now} or @samp{today} are relative items corresponding
417 to zero-valued time displacement, these strings come from the fact
418 a zero-valued time displacement represents the current time when not
419 otherwise changed by previous items. They may be used to stress other
420 items, like in @samp{12:00 today}. The string @samp{this} also has
421 the meaning of a zero-valued time displacement, but is preferred in
422 date strings like @samp{this thursday}.
424 When a relative item causes the resulting date to cross a boundary
425 where the clocks were adjusted, typically for daylight saving time,
426 the resulting date and time are adjusted accordingly.
428 The fuzz in units can cause problems with relative items. For
429 example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
430 because 2003-06-31 is an invalid date. To determine the previous
431 month more reliably, you can ask for the month before the 15th of the
432 current month. For example:
436 Thu, 31 Jul 2003 13:02:39 -0700
437 $ date --date='-1 month' +'Last month was %B?'
439 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
443 Also, take care when manipulating dates around clock changes such as
444 daylight saving leaps. In a few cases these have added or subtracted
445 as much as 24 hours from the clock, so it is often wise to adopt
446 universal time by setting the @env{TZ} environment variable to
447 @samp{UTC0} before embarking on calendrical calculations.
449 @node Pure numbers in date strings
450 @section Pure numbers in date strings
452 @cindex pure numbers in date strings
454 The precise interpretation of a pure decimal number depends
455 on the context in the date string.
457 If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
458 other calendar date item (@pxref{Calendar date items}) appears before it
459 in the date string, then @var{yyyy} is read as the year, @var{mm} as the
460 month number and @var{dd} as the day of the month, for the specified
463 If the decimal number is of the form @var{hh}@var{mm} and no other time
464 of day item appears before it in the date string, then @var{hh} is read
465 as the hour of the day and @var{mm} as the minute of the hour, for the
466 specified time of day. @var{mm} can also be omitted.
468 If both a calendar date and a time of day appear to the left of a number
469 in the date string, but no relative item, then the number overrides the
473 @node Seconds since the Epoch
474 @section Seconds since the Epoch
476 If you precede a number with @samp{@@}, it represents an internal time
477 stamp as a count of seconds. The number can contain an internal
478 decimal point (either @samp{.} or @samp{,}); any excess precision not
479 supported by the internal representation is truncated toward minus
480 infinity. Such a number cannot be combined with any other date
481 item, as it specifies a complete time stamp.
483 @cindex beginning of time, for @acronym{POSIX}
484 @cindex epoch, for @acronym{POSIX}
485 Internally, computer times are represented as a count of seconds since
486 an epoch---a well-defined point of time. On @acronym{GNU} and
487 @acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
488 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
489 00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
490 @acronym{POSIX}-compliant systems support such times as an extension
491 to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
492 represents 1969-12-31 23:59:59 @sc{utc}.
494 Traditional Unix systems count seconds with 32-bit two's-complement
495 integers and can represent times from 1901-12-13 20:45:52 through
496 2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
497 of seconds with nanosecond subcounts, and can represent all the times
498 in the known lifetime of the universe to a resolution of 1 nanosecond.
500 On most hosts, these counts ignore the presence of leap seconds.
501 For example, on most hosts @samp{@@915148799} represents 1998-12-31
502 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
503 @sc{utc}, and there is no way to represent the intervening leap second
504 1998-12-31 23:59:60 @sc{utc}.
506 @node Specifying time zone rules
507 @section Specifying time zone rules
510 Normally, dates are interpreted using the rules of the current time
511 zone, which in turn are specified by the @env{TZ} environment
512 variable, or by a system default if @env{TZ} is not set. To specify a
513 different set of default time zone rules that apply just to one date,
514 start the date with a string of the form @samp{TZ="@var{rule}"}. The
515 two quote characters (@samp{"}) must be present in the date, and any
516 quotes or backslashes within @var{rule} must be escaped by a
519 For example, with the @acronym{GNU} @command{date} command you can
520 answer the question ``What time is it in New York when a Paris clock
521 shows 6:30am on October 31, 2004?'' by using a date beginning with
522 @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
525 $ export TZ="America/New_York"
526 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
527 Sun Oct 31 01:30:00 EDT 2004
530 In this example, the @option{--date} operand begins with its own
531 @env{TZ} setting, so the rest of that operand is processed according
532 to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
533 06:30} as if it were in Paris. However, since the output of the
534 @command{date} command is processed according to the overall time zone
535 rules, it uses New York time. (Paris was normally six hours ahead of
536 New York in 2004, but this example refers to a brief Halloween period
537 when the gap was five hours.)
539 A @env{TZ} value is a rule that typically names a location in the
540 @uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
541 A recent catalog of location names appears in the
542 @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
543 Gateway}. A few non-@acronym{GNU} hosts require a colon before a
544 location name in a @env{TZ} setting, e.g.,
545 @samp{TZ=":America/New_York"}.
547 The @samp{tz} database includes a wide variety of locations ranging
548 from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
549 if you are at sea and have your own private time zone, or if you are
550 using a non-@acronym{GNU} host that does not support the @samp{tz}
551 database, you may need to use a @acronym{POSIX} rule instead. Simple
552 @acronym{POSIX} rules like @samp{UTC0} specify a time zone without
553 daylight saving time; other rules can specify simple daylight saving
554 regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
555 libc, The GNU C Library}.
557 @node Authors of parse_datetime
558 @section Authors of @code{parse_datetime}
559 @c the anchor keeps the old node name, to try to avoid breaking links
560 @anchor{Authors of get_date}
562 @cindex authors of @code{parse_datetime}
564 @cindex Bellovin, Steven M.
567 @cindex MacKenzie, David
568 @cindex Meyering, Jim
570 @code{parse_datetime} started life as @code{getdate}, as originally
571 implemented by Steven M. Bellovin
572 (@email{smb@@research.att.com}) while at the University of North Carolina
573 at Chapel Hill. The code was later tweaked by a couple of people on
574 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
575 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
576 revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
577 Paul Eggert and others, including renaming it to @code{get_date} to
578 avoid a conflict with the alternative Posix function @code{getdate},
579 and a later rename to @code{parse_datetime}. The Posix function
580 @code{getdate} can parse more locale-specific dates using
581 @code{strptime}, but relies on an environment variable and external
582 file, and lacks the thread-safety of @code{parse_datetime}.
586 This chapter was originally produced by Fran@,{c}ois Pinard
587 (@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
588 and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).