1 @c GNU date syntax documentation
3 @c Copyright (C) 1994-2006, 2009-2012 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.
149 Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
150 rejected. In the typical case of a host that does not support leap
151 seconds, a time like @samp{23:59:60} is rejected even if it
152 corresponds to a valid leap second.
155 @node Calendar date items
156 @section Calendar date items
158 @cindex calendar date item
160 A @dfn{calendar date item} specifies a day of the year. It is
161 specified differently, depending on whether the month is specified
162 numerically or literally. All these strings specify the same calendar date:
165 1972-09-24 # @sc{iso} 8601.
166 72-9-24 # Assume 19xx for 69 through 99,
167 # 20xx for 00 through 68.
168 72-09-24 # Leading zeros are ignored.
169 9/24/72 # Common U.S. writing.
171 24 Sept 72 # September has a special abbreviation.
172 24 Sep 72 # Three-letter abbreviations always allowed.
178 The year can also be omitted. In this case, the last specified year is
179 used, or the current year if none. For example:
188 @cindex @sc{iso} 8601 date format
189 @cindex date format, @sc{iso} 8601
190 For numeric months, the @sc{iso} 8601 format
191 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
192 any positive number, @var{month} is a number between 01 and 12, and
193 @var{day} is a number between 01 and 31. A leading zero must be present
194 if a number is less than ten. If @var{year} is 68 or smaller, then 2000
195 is added to it; otherwise, if @var{year} is less than 100,
196 then 1900 is added to it. The construct
197 @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
198 is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
200 @cindex month names in date strings
201 @cindex abbreviations for months
202 Literal months may be spelled out in full: @samp{January},
203 @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
204 @samp{July}, @samp{August}, @samp{September}, @samp{October},
205 @samp{November} or @samp{December}. Literal months may be abbreviated
206 to their first three letters, possibly followed by an abbreviating dot.
207 It is also permitted to write @samp{Sept} instead of @samp{September}.
209 When months are written literally, the calendar date may be given as any
213 @var{day} @var{month} @var{year}
214 @var{day} @var{month}
215 @var{month} @var{day} @var{year}
216 @var{day}-@var{month}-@var{year}
219 Or, omitting the year:
222 @var{month} @var{day}
226 @node Time of day items
227 @section Time of day items
229 @cindex time of day item
231 A @dfn{time of day item} in date strings specifies the time on a given
232 day. Here are some examples, all of which represent the same time:
238 20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
242 More generally, the time of day may be given as
243 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
244 a number between 0 and 23, @var{minute} is a number between 0 and
245 59, and @var{second} is a number between 0 and 59 possibly followed by
246 @samp{.} or @samp{,} and a fraction containing one or more digits.
248 @samp{:@var{second}} can be omitted, in which case it is taken to
249 be zero. On the rare hosts that support leap seconds, @var{second}
252 @findex am @r{in date strings}
253 @findex pm @r{in date strings}
254 @findex midnight @r{in date strings}
255 @findex noon @r{in date strings}
256 If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
257 or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
258 @samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
259 indicates the first half of the day, @samp{pm} indicates the second
260 half of the day. In this notation, 12 is the predecessor of 1:
261 midnight is @samp{12am} while noon is @samp{12pm}.
262 (This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
263 as opposed to the old tradition derived from Latin
264 which uses @samp{12m} for noon and @samp{12pm} for midnight.)
266 @cindex time zone correction
267 @cindex minutes, time zone correction by
268 The time may alternatively be followed by a time zone correction,
269 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
270 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
272 The zone minutes term, @var{mm}, may be omitted, in which case
273 the one- or two-digit correction is interpreted as a number of hours.
274 You can also separate @var{hh} from @var{mm} with a colon.
275 When a time zone correction is given this way, it
276 forces interpretation of the time relative to
277 Coordinated Universal Time (@sc{utc}), overriding any previous
278 specification for the time zone or the local time zone. For example,
279 @samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
280 ahead of @sc{utc} (e.g., India).
281 This is the best way to
282 specify a time zone correction by fractional parts of an hour.
283 The maximum zone correction is 24 hours.
285 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
289 @node Time zone items
290 @section Time zone items
292 @cindex time zone item
294 A @dfn{time zone item} specifies an international time zone, indicated
295 by a small set of letters, e.g., @samp{UTC} or @samp{Z}
296 for Coordinated Universal
297 Time. Any included periods are ignored. By following a
298 non-daylight-saving time zone by the string @samp{DST} in a separate
299 word (that is, separated by some white space), the corresponding
300 daylight saving time zone may be specified.
301 Alternatively, a non-daylight-saving time zone can be followed by a
302 time zone correction, to add the two values. This is normally done
303 only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
306 Time zone items other than @samp{UTC} and @samp{Z}
307 are obsolescent and are not recommended, because they
308 are ambiguous; for example, @samp{EST} has a different meaning in
309 Australia than in the United States. Instead, it's better to use
310 unambiguous numeric time zone corrections like @samp{-0500}, as
311 described in the previous section.
313 If neither a time zone item nor a time zone correction is supplied,
314 time stamps are interpreted using the rules of the default time zone
315 (@pxref{Specifying time zone rules}).
318 @node Combined date and time of day items
319 @section Combined date and time of day items
321 @cindex combined date and time of day item
323 A @dfn{combined date and time of day item} specifies the time on a
324 specific day of the year. This type is needed for formats that cannot
325 be represented by individual calendar date (@pxref{Calendar date items})
326 and time of day (@pxref{Time of day items}) items due to ambiguity.
329 # ISO 8601 extended date and time of day format
330 1972-09-24T20:02:00,000000-0500
333 @cindex @sc{iso} 8601 date and time of day format
334 @cindex date and time of day format, @sc{iso} 8601
336 The @sc{iso} 8601 extended date and time of day format is an @sc{iso}
337 8601 date, a @samp{T} character separator, followed by an @sc{iso} 8601 time
341 @node Day of week items
342 @section Day of week items
344 @cindex day of week item
346 The explicit mention of a day of the week will forward the date
347 (only if necessary) to reach that day of the week in the future.
349 Days of the week may be spelled out in full: @samp{Sunday},
350 @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
351 @samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
352 first three letters, optionally followed by a period. The special
353 abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
354 @samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
357 @findex next @var{day}
358 @findex last @var{day}
359 A number may precede a day of the week item to move forward
360 supplementary weeks. It is best used in expression like @samp{third
361 monday}. In this context, @samp{last @var{day}} or @samp{next
362 @var{day}} is also acceptable; they move one week before or after
363 the day that @var{day} by itself would represent.
365 A comma following a day of the week item is ignored.
368 @node Relative items in date strings
369 @section Relative items in date strings
371 @cindex relative items in date strings
372 @cindex displacement of dates
374 @dfn{Relative items} adjust a date (or the current date if none) forward
375 or backward. The effects of relative items accumulate. Here are some
385 @findex year @r{in date strings}
386 @findex month @r{in date strings}
387 @findex fortnight @r{in date strings}
388 @findex week @r{in date strings}
389 @findex day @r{in date strings}
390 @findex hour @r{in date strings}
391 @findex minute @r{in date strings}
392 The unit of time displacement may be selected by the string @samp{year}
393 or @samp{month} for moving by whole years or months. These are fuzzy
394 units, as years and months are not all of equal duration. More precise
395 units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
396 days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
397 @samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
398 @samp{sec} worth one second. An @samp{s} suffix on these units is
399 accepted and ignored.
401 @findex ago @r{in date strings}
402 The unit of time may be preceded by a multiplier, given as an optionally
403 signed number. Unsigned numbers are taken as positively signed. No
404 number at all implies 1 for a multiplier. Following a relative item by
405 the string @samp{ago} is equivalent to preceding the unit by a
406 multiplier with value @math{-1}.
408 @findex day @r{in date strings}
409 @findex tomorrow @r{in date strings}
410 @findex yesterday @r{in date strings}
411 The string @samp{tomorrow} is worth one day in the future (equivalent
412 to @samp{day}), the string @samp{yesterday} is worth
413 one day in the past (equivalent to @samp{day ago}).
415 @findex now @r{in date strings}
416 @findex today @r{in date strings}
417 @findex this @r{in date strings}
418 The strings @samp{now} or @samp{today} are relative items corresponding
419 to zero-valued time displacement, these strings come from the fact
420 a zero-valued time displacement represents the current time when not
421 otherwise changed by previous items. They may be used to stress other
422 items, like in @samp{12:00 today}. The string @samp{this} also has
423 the meaning of a zero-valued time displacement, but is preferred in
424 date strings like @samp{this thursday}.
426 When a relative item causes the resulting date to cross a boundary
427 where the clocks were adjusted, typically for daylight saving time,
428 the resulting date and time are adjusted accordingly.
430 The fuzz in units can cause problems with relative items. For
431 example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
432 because 2003-06-31 is an invalid date. To determine the previous
433 month more reliably, you can ask for the month before the 15th of the
434 current month. For example:
438 Thu, 31 Jul 2003 13:02:39 -0700
439 $ date --date='-1 month' +'Last month was %B?'
441 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
445 Also, take care when manipulating dates around clock changes such as
446 daylight saving leaps. In a few cases these have added or subtracted
447 as much as 24 hours from the clock, so it is often wise to adopt
448 universal time by setting the @env{TZ} environment variable to
449 @samp{UTC0} before embarking on calendrical calculations.
451 @node Pure numbers in date strings
452 @section Pure numbers in date strings
454 @cindex pure numbers in date strings
456 The precise interpretation of a pure decimal number depends
457 on the context in the date string.
459 If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
460 other calendar date item (@pxref{Calendar date items}) appears before it
461 in the date string, then @var{yyyy} is read as the year, @var{mm} as the
462 month number and @var{dd} as the day of the month, for the specified
465 If the decimal number is of the form @var{hh}@var{mm} and no other time
466 of day item appears before it in the date string, then @var{hh} is read
467 as the hour of the day and @var{mm} as the minute of the hour, for the
468 specified time of day. @var{mm} can also be omitted.
470 If both a calendar date and a time of day appear to the left of a number
471 in the date string, but no relative item, then the number overrides the
475 @node Seconds since the Epoch
476 @section Seconds since the Epoch
478 If you precede a number with @samp{@@}, it represents an internal time
479 stamp as a count of seconds. The number can contain an internal
480 decimal point (either @samp{.} or @samp{,}); any excess precision not
481 supported by the internal representation is truncated toward minus
482 infinity. Such a number cannot be combined with any other date
483 item, as it specifies a complete time stamp.
485 @cindex beginning of time, for POSIX
486 @cindex epoch, for POSIX
487 Internally, computer times are represented as a count of seconds since
488 an epoch---a well-defined point of time. On GNU and
489 POSIX systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
490 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
491 00:00:01 @sc{utc}, and so forth. GNU and most other
492 POSIX-compliant systems support such times as an extension
493 to POSIX, using negative counts, so that @samp{@@-1}
494 represents 1969-12-31 23:59:59 @sc{utc}.
496 Traditional Unix systems count seconds with 32-bit two's-complement
497 integers and can represent times from 1901-12-13 20:45:52 through
498 2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
499 of seconds with nanosecond subcounts, and can represent all the times
500 in the known lifetime of the universe to a resolution of 1 nanosecond.
503 On most hosts, these counts ignore the presence of leap seconds.
504 For example, on most hosts @samp{@@915148799} represents 1998-12-31
505 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
506 @sc{utc}, and there is no way to represent the intervening leap second
507 1998-12-31 23:59:60 @sc{utc}.
509 @node Specifying time zone rules
510 @section Specifying time zone rules
513 Normally, dates are interpreted using the rules of the current time
514 zone, which in turn are specified by the @env{TZ} environment
515 variable, or by a system default if @env{TZ} is not set. To specify a
516 different set of default time zone rules that apply just to one date,
517 start the date with a string of the form @samp{TZ="@var{rule}"}. The
518 two quote characters (@samp{"}) must be present in the date, and any
519 quotes or backslashes within @var{rule} must be escaped by a
522 For example, with the GNU @command{date} command you can
523 answer the question ``What time is it in New York when a Paris clock
524 shows 6:30am on October 31, 2004?'' by using a date beginning with
525 @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
528 $ export TZ="America/New_York"
529 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
530 Sun Oct 31 01:30:00 EDT 2004
533 In this example, the @option{--date} operand begins with its own
534 @env{TZ} setting, so the rest of that operand is processed according
535 to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
536 06:30} as if it were in Paris. However, since the output of the
537 @command{date} command is processed according to the overall time zone
538 rules, it uses New York time. (Paris was normally six hours ahead of
539 New York in 2004, but this example refers to a brief Halloween period
540 when the gap was five hours.)
542 A @env{TZ} value is a rule that typically names a location in the
543 @uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
544 A recent catalog of location names appears in the
545 @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
546 Gateway}. A few non-GNU hosts require a colon before a
547 location name in a @env{TZ} setting, e.g.,
548 @samp{TZ=":America/New_York"}.
550 The @samp{tz} database includes a wide variety of locations ranging
551 from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
552 if you are at sea and have your own private time zone, or if you are
553 using a non-GNU host that does not support the @samp{tz}
554 database, you may need to use a POSIX rule instead. Simple
555 POSIX rules like @samp{UTC0} specify a time zone without
556 daylight saving time; other rules can specify simple daylight saving
557 regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
558 libc, The GNU C Library}.
560 @node Authors of parse_datetime
561 @section Authors of @code{parse_datetime}
562 @c the anchor keeps the old node name, to try to avoid breaking links
563 @anchor{Authors of get_date}
565 @cindex authors of @code{parse_datetime}
567 @cindex Bellovin, Steven M.
570 @cindex MacKenzie, David
571 @cindex Meyering, Jim
573 @code{parse_datetime} started life as @code{getdate}, as originally
574 implemented by Steven M. Bellovin
575 (@email{smb@@research.att.com}) while at the University of North Carolina
576 at Chapel Hill. The code was later tweaked by a couple of people on
577 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
578 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
579 revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
580 Paul Eggert and others, including renaming it to @code{get_date} to
581 avoid a conflict with the alternative Posix function @code{getdate},
582 and a later rename to @code{parse_datetime}. The Posix function
583 @code{getdate} can parse more locale-specific dates using
584 @code{strptime}, but relies on an environment variable and external
585 file, and lacks the thread-safety of @code{parse_datetime}.
589 This chapter was originally produced by Fran@,{c}ois Pinard
590 (@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
591 and then edited by K. Berry (@email{kb@@cs.umb.edu}).