1@c GNU date syntax documentation 2 3@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 4@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc. 5 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.2 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. 12 13@node Date input formats 14@chapter Date input formats 15 16@cindex date input formats 17@findex get_date 18 19First, a quote: 20 21@quotation 22Our units of temporal measurement, from seconds on up to months, are so 23complicated, asymmetrical and disjunctive so as to make coherent mental 24reckoning in time all but impossible. Indeed, had some tyrannical god 25contrived to enslave our minds to time, to make it all but impossible 26for us to escape subjection to sodden routines and unpleasant surprises, 27he could hardly have done better than handing down our present system. 28It is like a set of trapezoidal building blocks, with no vertical or 29horizontal surfaces, like a language in which the simplest thought 30demands ornate constructions, useless particles and lengthy 31circumlocutions. Unlike the more successful patterns of language and 32science, which enable us to face experience boldly or at least 33level-headedly, our system of temporal calculation silently and 34persistently encourages our terror of time. 35 36@dots{} It is as though architects had to measure length in feet, width 37in meters and height in ells; as though basic instruction manuals 38demanded a knowledge of five different languages. It is no wonder then 39that we often look into our own immediate past or future, last Tuesday 40or a week from Sunday, with feelings of helpless confusion. @dots{} 41 42--- Robert Grudin, @cite{Time and the Art of Living}. 43@end quotation 44 45This section describes the textual date representations that @sc{gnu} 46programs accept. These are the strings you, as a user, can supply as 47arguments to the various programs. The C interface (via the 48@code{get_date} function) is not described here. 49 50@menu 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. 61@end menu 62 63 64@node General date syntax 65@section General date syntax 66 67@cindex general date syntax 68 69@cindex items in date strings 70A @dfn{date} is a string, possibly empty, containing many items 71separated by whitespace. The whitespace may be omitted when no 72ambiguity arises. The empty string means the beginning of today (i.e., 73midnight). Order of the items is immaterial. A date string may contain 74many flavors of items: 75 76@itemize @bullet 77@item calendar date items 78@item time of day items 79@item time zone items 80@item day of the week items 81@item relative items 82@item pure numbers. 83@end itemize 84 85@noindent We describe each of these item types in turn, below. 86 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} 92A few ordinal numbers may be written out in words in some contexts. This is 93most useful for specifying day of the week items or relative items (see 94below). 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 98ordinal 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. 103 104@cindex months, written-out 105When a month is written this way, it is still considered to be written 106numerically, instead of being ``spelled in full''; this changes the 107allowed strings. 108 109@cindex language, in dates 110In the current implementation, only English is supported for words and 111abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first}, 112@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}. 113 114@cindex language, in dates 115@cindex time zone item 116The output of the @command{date} command 117is not always acceptable as a date string, 118not only because of the language problem, but also because there is no 119standard meaning for time zone items like @samp{IST}. When using 120@command{date} to generate a date string intended to be parsed later, 121specify a date format that is independent of language and that does not 122use time zone items other than @samp{UTC} and @samp{Z}. Here are some 123ways to do this: 124 125@example 126$ LC_ALL=C TZ=UTC0 date 127Mon Mar 1 00:21:42 UTC 2004 128$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 1292004-03-01 00:21:42Z 130$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. 1312004-02-29 16:21:42,692722128-0800 132$ date --rfc-2822 # a GNU extension 133Sun, 29 Feb 2004 16:21:42 -0800 134$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 1352004-02-29 16:21:42 -0800 136$ date +'@@%s.%N' # %s and %N are GNU extensions. 137@@1078100502.692722128 138@end example 139 140@cindex case, ignored in dates 141@cindex comments, in dates 142Alphabetic case is completely ignored in dates. Comments may be introduced 143between round parentheses, as long as included parentheses are properly 144nested. Hyphens not followed by a digit are currently ignored. Leading 145zeros on numbers are ignored. 146 147Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are 148rejected. In the typical case of a host that does not support leap 149seconds, a time like @samp{23:59:60} is rejected even if it 150corresponds to a valid leap second. 151 152 153@node Calendar date items 154@section Calendar date items 155 156@cindex calendar date item 157 158A @dfn{calendar date item} specifies a day of the year. It is 159specified differently, depending on whether the month is specified 160numerically or literally. All these strings specify the same calendar date: 161 162@example 1631972-09-24 # @sc{iso} 8601. 16472-9-24 # Assume 19xx for 69 through 99, 165 # 20xx for 00 through 68. 16672-09-24 # Leading zeros are ignored. 1679/24/72 # Common U.S. writing. 16824 September 1972 16924 Sept 72 # September has a special abbreviation. 17024 Sep 72 # Three-letter abbreviations always allowed. 171Sep 24, 1972 17224-sep-72 17324sep72 174@end example 175 176The year can also be omitted. In this case, the last specified year is 177used, or the current year if none. For example: 178 179@example 1809/24 181sep 24 182@end example 183 184Here are the rules. 185 186@cindex @sc{iso} 8601 date format 187@cindex date format, @sc{iso} 8601 188For numeric months, the @sc{iso} 8601 format 189@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is 190any 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 192if a number is less than ten. If @var{year} is 68 or smaller, then 2000 193is added to it; otherwise, if @var{year} is less than 100, 194then 1900 is added to it. The construct 195@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, 196is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. 197 198@cindex month names in date strings 199@cindex abbreviations for months 200Literal 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 204to their first three letters, possibly followed by an abbreviating dot. 205It is also permitted to write @samp{Sept} instead of @samp{September}. 206 207When months are written literally, the calendar date may be given as any 208of the following: 209 210@example 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} 215@end example 216 217Or, omitting the year: 218 219@example 220@var{month} @var{day} 221@end example 222 223 224@node Time of day items 225@section Time of day items 226 227@cindex time of day item 228 229A @dfn{time of day item} in date strings specifies the time on a given 230day. Here are some examples, all of which represent the same time: 231 232@example 23320:02:00.000000 23420:02 2358:02pm 23620:02-0500 # In @sc{est} (U.S. Eastern Standard Time). 237@end example 238 239More generally, the time of day may be given as 240@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is 241a number between 0 and 23, @var{minute} is a number between 0 and 24259, 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. 244Alternatively, 245@samp{:@var{second}} can be omitted, in which case it is taken to 246be zero. On the rare hosts that support leap seconds, @var{second} 247may be 60. 248 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} 253If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.} 254or @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} 256indicates the first half of the day, @samp{pm} indicates the second 257half of the day. In this notation, 12 is the predecessor of 1: 258midnight is @samp{12am} while noon is @samp{12pm}. 259(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm}, 260as opposed to the old tradition derived from Latin 261which uses @samp{12m} for noon and @samp{12pm} for midnight.) 262 263@cindex time zone correction 264@cindex minutes, time zone correction by 265The time may alternatively be followed by a time zone correction, 266expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+} 267or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number 268of zone minutes. You can also separate @var{hh} from @var{mm} with a colon. 269When a time zone correction is given this way, it 270forces interpretation of the time relative to 271Coordinated Universal Time (@sc{utc}), overriding any previous 272specification for the time zone or the local time zone. For example, 273@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours 274ahead of @sc{utc} (e.g., India). The @var{minute} 275part of the time of day may not be elided when a time zone correction 276is used. This is the best way to specify a time zone correction by 277fractional parts of an hour. 278 279Either @samp{am}/@samp{pm} or a time zone correction may be specified, 280but not both. 281 282 283@node Time zone items 284@section Time zone items 285 286@cindex time zone item 287 288A @dfn{time zone item} specifies an international time zone, indicated 289by a small set of letters, e.g., @samp{UTC} or @samp{Z} 290for Coordinated Universal 291Time. Any included periods are ignored. By following a 292non-daylight-saving time zone by the string @samp{DST} in a separate 293word (that is, separated by some white space), the corresponding 294daylight saving time zone may be specified. 295Alternatively, a non-daylight-saving time zone can be followed by a 296time zone correction, to add the two values. This is normally done 297only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to 298@samp{+05:30}. 299 300Time zone items other than @samp{UTC} and @samp{Z} 301are obsolescent and are not recommended, because they 302are ambiguous; for example, @samp{EST} has a different meaning in 303Australia than in the United States. Instead, it's better to use 304unambiguous numeric time zone corrections like @samp{-0500}, as 305described in the previous section. 306 307If neither a time zone item nor a time zone correction is supplied, 308time stamps are interpreted using the rules of the default time zone 309(@pxref{Specifying time zone rules}). 310 311 312@node Day of week items 313@section Day of week items 314 315@cindex day of week item 316 317The explicit mention of a day of the week will forward the date 318(only if necessary) to reach that day of the week in the future. 319 320Days of the week may be spelled out in full: @samp{Sunday}, 321@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday}, 322@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their 323first three letters, optionally followed by a period. The special 324abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for 325@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are 326also allowed. 327 328@findex next @var{day} 329@findex last @var{day} 330A number may precede a day of the week item to move forward 331supplementary weeks. It is best used in expression like @samp{third 332monday}. In this context, @samp{last @var{day}} or @samp{next 333@var{day}} is also acceptable; they move one week before or after 334the day that @var{day} by itself would represent. 335 336A comma following a day of the week item is ignored. 337 338 339@node Relative items in date strings 340@section Relative items in date strings 341 342@cindex relative items in date strings 343@cindex displacement of dates 344 345@dfn{Relative items} adjust a date (or the current date if none) forward 346or backward. The effects of relative items accumulate. Here are some 347examples: 348 349@example 3501 year 3511 year ago 3523 years 3532 days 354@end example 355 356@findex year @r{in date strings} 357@findex month @r{in date strings} 358@findex fortnight @r{in date strings} 359@findex week @r{in date strings} 360@findex day @r{in date strings} 361@findex hour @r{in date strings} 362@findex minute @r{in date strings} 363The unit of time displacement may be selected by the string @samp{year} 364or @samp{month} for moving by whole years or months. These are fuzzy 365units, as years and months are not all of equal duration. More precise 366units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 367days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes, 368@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or 369@samp{sec} worth one second. An @samp{s} suffix on these units is 370accepted and ignored. 371 372@findex ago @r{in date strings} 373The unit of time may be preceded by a multiplier, given as an optionally 374signed number. Unsigned numbers are taken as positively signed. No 375number at all implies 1 for a multiplier. Following a relative item by 376the string @samp{ago} is equivalent to preceding the unit by a 377multiplier with value @math{-1}. 378 379@findex day @r{in date strings} 380@findex tomorrow @r{in date strings} 381@findex yesterday @r{in date strings} 382The string @samp{tomorrow} is worth one day in the future (equivalent 383to @samp{day}), the string @samp{yesterday} is worth 384one day in the past (equivalent to @samp{day ago}). 385 386@findex now @r{in date strings} 387@findex today @r{in date strings} 388@findex this @r{in date strings} 389The strings @samp{now} or @samp{today} are relative items corresponding 390to zero-valued time displacement, these strings come from the fact 391a zero-valued time displacement represents the current time when not 392otherwise changed by previous items. They may be used to stress other 393items, like in @samp{12:00 today}. The string @samp{this} also has 394the meaning of a zero-valued time displacement, but is preferred in 395date strings like @samp{this thursday}. 396 397When a relative item causes the resulting date to cross a boundary 398where the clocks were adjusted, typically for daylight saving time, 399the resulting date and time are adjusted accordingly. 400 401The fuzz in units can cause problems with relative items. For 402example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01, 403because 2003-06-31 is an invalid date. To determine the previous 404month more reliably, you can ask for the month before the 15th of the 405current month. For example: 406 407@example 408$ date -R 409Thu, 31 Jul 2003 13:02:39 -0700 410$ date --date='-1 month' +'Last month was %B?' 411Last month was July? 412$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' 413Last month was June! 414@end example 415 416Also, take care when manipulating dates around clock changes such as 417daylight saving leaps. In a few cases these have added or subtracted 418as much as 24 hours from the clock, so it is often wise to adopt 419universal time by setting the @env{TZ} environment variable to 420@samp{UTC0} before embarking on calendrical calculations. 421 422@node Pure numbers in date strings 423@section Pure numbers in date strings 424 425@cindex pure numbers in date strings 426 427The precise interpretation of a pure decimal number depends 428on the context in the date string. 429 430If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no 431other calendar date item (@pxref{Calendar date items}) appears before it 432in the date string, then @var{yyyy} is read as the year, @var{mm} as the 433month number and @var{dd} as the day of the month, for the specified 434calendar date. 435 436If the decimal number is of the form @var{hh}@var{mm} and no other time 437of day item appears before it in the date string, then @var{hh} is read 438as the hour of the day and @var{mm} as the minute of the hour, for the 439specified time of day. @var{mm} can also be omitted. 440 441If both a calendar date and a time of day appear to the left of a number 442in the date string, but no relative item, then the number overrides the 443year. 444 445 446@node Seconds since the Epoch 447@section Seconds since the Epoch 448 449If you precede a number with @samp{@@}, it represents an internal time 450stamp as a count of seconds. The number can contain an internal 451decimal point (either @samp{.} or @samp{,}); any excess precision not 452supported by the internal representation is truncated toward minus 453infinity. Such a number cannot be combined with any other date 454item, as it specifies a complete time stamp. 455 456@cindex beginning of time, for @acronym{POSIX} 457@cindex epoch, for @acronym{POSIX} 458Internally, computer times are represented as a count of seconds since 459an epoch---a well-defined point of time. On @acronym{GNU} and 460@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so 461@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01 46200:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other 463@acronym{POSIX}-compliant systems support such times as an extension 464to @acronym{POSIX}, using negative counts, so that @samp{@@-1} 465represents 1969-12-31 23:59:59 @sc{utc}. 466 467Traditional Unix systems count seconds with 32-bit two's-complement 468integers and can represent times from 1901-12-13 20:45:52 through 4692038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts 470of seconds with nanosecond subcounts, and can represent all the times 471in the known lifetime of the universe to a resolution of 1 nanosecond. 472 473On most hosts, these counts ignore the presence of leap seconds. 474For example, on most hosts @samp{@@915148799} represents 1998-12-31 47523:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00 476@sc{utc}, and there is no way to represent the intervening leap second 4771998-12-31 23:59:60 @sc{utc}. 478 479@node Specifying time zone rules 480@section Specifying time zone rules 481 482@vindex TZ 483Normally, dates are interpreted using the rules of the current time 484zone, which in turn are specified by the @env{TZ} environment 485variable, or by a system default if @env{TZ} is not set. To specify a 486different set of default time zone rules that apply just to one date, 487start the date with a string of the form @samp{TZ="@var{rule}"}. The 488two quote characters (@samp{"}) must be present in the date, and any 489quotes or backslashes within @var{rule} must be escaped by a 490backslash. 491 492For example, with the @acronym{GNU} @command{date} command you can 493answer the question ``What time is it in New York when a Paris clock 494shows 6:30am on October 31, 2004?'' by using a date beginning with 495@samp{TZ="Europe/Paris"} as shown in the following shell transcript: 496 497@example 498$ export TZ="America/New_York" 499$ date --date='TZ="Europe/Paris" 2004-10-31 06:30' 500Sun Oct 31 01:30:00 EDT 2004 501@end example 502 503In this example, the @option{--date} operand begins with its own 504@env{TZ} setting, so the rest of that operand is processed according 505to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31 50606:30} as if it were in Paris. However, since the output of the 507@command{date} command is processed according to the overall time zone 508rules, it uses New York time. (Paris was normally six hours ahead of 509New York in 2004, but this example refers to a brief Halloween period 510when the gap was five hours.) 511 512A @env{TZ} value is a rule that typically names a location in the 513@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}. 514A recent catalog of location names appears in the 515@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time 516Gateway}. A few non-@acronym{GNU} hosts require a colon before a 517location name in a @env{TZ} setting, e.g., 518@samp{TZ=":America/New_York"}. 519 520The @samp{tz} database includes a wide variety of locations ranging 521from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but 522if you are at sea and have your own private time zone, or if you are 523using a non-@acronym{GNU} host that does not support the @samp{tz} 524database, you may need to use a @acronym{POSIX} rule instead. Simple 525@acronym{POSIX} rules like @samp{UTC0} specify a time zone without 526daylight saving time; other rules can specify simple daylight saving 527regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ}, 528libc, The GNU C Library}. 529 530@node Authors of get_date 531@section Authors of @code{get_date} 532 533@cindex authors of @code{get_date} 534 535@cindex Bellovin, Steven M. 536@cindex Salz, Rich 537@cindex Berets, Jim 538@cindex MacKenzie, David 539@cindex Meyering, Jim 540@cindex Eggert, Paul 541@code{get_date} was originally implemented by Steven M. Bellovin 542(@email{smb@@research.att.com}) while at the University of North Carolina 543at Chapel Hill. The code was later tweaked by a couple of people on 544Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) 545and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various 546revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering, 547Paul Eggert and others. 548 549@cindex Pinard, F. 550@cindex Berry, K. 551This chapter was originally produced by Fran@,{c}ois Pinard 552(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code, 553and then edited by K.@: Berry (@email{kb@@cs.umb.edu}). 554