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 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.1 or 8@c any later version published by the Free Software Foundation; with no 9@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 10@c Texts. A copy of the license is included in the ``GNU Free 11@c Documentation License'' file as part of this distribution. 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 147 148@node Calendar date items 149@section Calendar date items 150 151@cindex calendar date item 152 153A @dfn{calendar date item} specifies a day of the year. It is 154specified differently, depending on whether the month is specified 155numerically or literally. All these strings specify the same calendar date: 156 157@example 1581972-09-24 # @sc{iso} 8601. 15972-9-24 # Assume 19xx for 69 through 99, 160 # 20xx for 00 through 68. 16172-09-24 # Leading zeros are ignored. 1629/24/72 # Common U.S. writing. 16324 September 1972 16424 Sept 72 # September has a special abbreviation. 16524 Sep 72 # Three-letter abbreviations always allowed. 166Sep 24, 1972 16724-sep-72 16824sep72 169@end example 170 171The year can also be omitted. In this case, the last specified year is 172used, or the current year if none. For example: 173 174@example 1759/24 176sep 24 177@end example 178 179Here are the rules. 180 181@cindex @sc{iso} 8601 date format 182@cindex date format, @sc{iso} 8601 183For numeric months, the @sc{iso} 8601 format 184@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is 185any positive number, @var{month} is a number between 01 and 12, and 186@var{day} is a number between 01 and 31. A leading zero must be present 187if a number is less than ten. If @var{year} is 68 or smaller, then 2000 188is added to it; otherwise, if @var{year} is less than 100, 189then 1900 is added to it. The construct 190@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, 191is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. 192 193@cindex month names in date strings 194@cindex abbreviations for months 195Literal months may be spelled out in full: @samp{January}, 196@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June}, 197@samp{July}, @samp{August}, @samp{September}, @samp{October}, 198@samp{November} or @samp{December}. Literal months may be abbreviated 199to their first three letters, possibly followed by an abbreviating dot. 200It is also permitted to write @samp{Sept} instead of @samp{September}. 201 202When months are written literally, the calendar date may be given as any 203of the following: 204 205@example 206@var{day} @var{month} @var{year} 207@var{day} @var{month} 208@var{month} @var{day} @var{year} 209@var{day}-@var{month}-@var{year} 210@end example 211 212Or, omitting the year: 213 214@example 215@var{month} @var{day} 216@end example 217 218 219@node Time of day items 220@section Time of day items 221 222@cindex time of day item 223 224A @dfn{time of day item} in date strings specifies the time on a given 225day. Here are some examples, all of which represent the same time: 226 227@example 22820:02:00.000000 22920:02 2308:02pm 23120:02-0500 # In @sc{est} (U.S. Eastern Standard Time). 232@end example 233 234More generally, the time of day may be given as 235@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is 236a number between 0 and 23, @var{minute} is a number between 0 and 23759, and @var{second} is a number between 0 and 59 possibly followed by 238@samp{.} or @samp{,} and a fraction containing one or more digits. 239Alternatively, 240@samp{:@var{second}} can be omitted, in which case it is taken to 241be zero. 242 243@findex am @r{in date strings} 244@findex pm @r{in date strings} 245@findex midnight @r{in date strings} 246@findex noon @r{in date strings} 247If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.} 248or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and 249@samp{:@var{minute}} may be omitted (taken to be zero). @samp{am} 250indicates the first half of the day, @samp{pm} indicates the second 251half of the day. In this notation, 12 is the predecessor of 1: 252midnight is @samp{12am} while noon is @samp{12pm}. 253(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm}, 254as opposed to the old tradition derived from Latin 255which uses @samp{12m} for noon and @samp{12pm} for midnight.) 256 257@cindex time zone correction 258@cindex minutes, time zone correction by 259The time may alternatively be followed by a time zone correction, 260expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+} 261or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number 262of zone minutes. You can also separate @var{hh} from @var{mm} with a colon. 263When a time zone correction is given this way, it 264forces interpretation of the time relative to 265Coordinated Universal Time (@sc{utc}), overriding any previous 266specification for the time zone or the local time zone. For example, 267@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours 268ahead of @sc{utc} (e.g., India). The @var{minute} 269part of the time of day may not be elided when a time zone correction 270is used. This is the best way to specify a time zone correction by 271fractional parts of an hour. 272 273Either @samp{am}/@samp{pm} or a time zone correction may be specified, 274but not both. 275 276 277@node Time zone items 278@section Time zone items 279 280@cindex time zone item 281 282A @dfn{time zone item} specifies an international time zone, indicated 283by a small set of letters, e.g., @samp{UTC} or @samp{Z} 284for Coordinated Universal 285Time. Any included periods are ignored. By following a 286non-daylight-saving time zone by the string @samp{DST} in a separate 287word (that is, separated by some white space), the corresponding 288daylight saving time zone may be specified. 289Alternatively, a non-daylight-saving time zone can be followed by a 290time zone correction, to add the two values. This is normally done 291only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to 292@samp{+05:30}. 293 294Time zone items other than @samp{UTC} and @samp{Z} 295are obsolescent and are not recommended, because they 296are ambiguous; for example, @samp{EST} has a different meaning in 297Australia than in the United States. Instead, it's better to use 298unambiguous numeric time zone corrections like @samp{-0500}, as 299described in the previous section. 300 301If neither a time zone item nor a time zone correction is supplied, 302time stamps are interpreted using the rules of the default time zone 303(@pxref{Specifying time zone rules}). 304 305 306@node Day of week items 307@section Day of week items 308 309@cindex day of week item 310 311The explicit mention of a day of the week will forward the date 312(only if necessary) to reach that day of the week in the future. 313 314Days of the week may be spelled out in full: @samp{Sunday}, 315@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday}, 316@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their 317first three letters, optionally followed by a period. The special 318abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for 319@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are 320also allowed. 321 322@findex next @var{day} 323@findex last @var{day} 324A number may precede a day of the week item to move forward 325supplementary weeks. It is best used in expression like @samp{third 326monday}. In this context, @samp{last @var{day}} or @samp{next 327@var{day}} is also acceptable; they move one week before or after 328the day that @var{day} by itself would represent. 329 330A comma following a day of the week item is ignored. 331 332 333@node Relative items in date strings 334@section Relative items in date strings 335 336@cindex relative items in date strings 337@cindex displacement of dates 338 339@dfn{Relative items} adjust a date (or the current date if none) forward 340or backward. The effects of relative items accumulate. Here are some 341examples: 342 343@example 3441 year 3451 year ago 3463 years 3472 days 348@end example 349 350@findex year @r{in date strings} 351@findex month @r{in date strings} 352@findex fortnight @r{in date strings} 353@findex week @r{in date strings} 354@findex day @r{in date strings} 355@findex hour @r{in date strings} 356@findex minute @r{in date strings} 357The unit of time displacement may be selected by the string @samp{year} 358or @samp{month} for moving by whole years or months. These are fuzzy 359units, as years and months are not all of equal duration. More precise 360units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 361days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes, 362@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or 363@samp{sec} worth one second. An @samp{s} suffix on these units is 364accepted and ignored. 365 366@findex ago @r{in date strings} 367The unit of time may be preceded by a multiplier, given as an optionally 368signed number. Unsigned numbers are taken as positively signed. No 369number at all implies 1 for a multiplier. Following a relative item by 370the string @samp{ago} is equivalent to preceding the unit by a 371multiplier with value @math{-1}. 372 373@findex day @r{in date strings} 374@findex tomorrow @r{in date strings} 375@findex yesterday @r{in date strings} 376The string @samp{tomorrow} is worth one day in the future (equivalent 377to @samp{day}), the string @samp{yesterday} is worth 378one day in the past (equivalent to @samp{day ago}). 379 380@findex now @r{in date strings} 381@findex today @r{in date strings} 382@findex this @r{in date strings} 383The strings @samp{now} or @samp{today} are relative items corresponding 384to zero-valued time displacement, these strings come from the fact 385a zero-valued time displacement represents the current time when not 386otherwise changed by previous items. They may be used to stress other 387items, like in @samp{12:00 today}. The string @samp{this} also has 388the meaning of a zero-valued time displacement, but is preferred in 389date strings like @samp{this thursday}. 390 391When a relative item causes the resulting date to cross a boundary 392where the clocks were adjusted, typically for daylight saving time, 393the resulting date and time are adjusted accordingly. 394 395The fuzz in units can cause problems with relative items. For 396example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01, 397because 2003-06-31 is an invalid date. To determine the previous 398month more reliably, you can ask for the month before the 15th of the 399current month. For example: 400 401@example 402$ date -R 403Thu, 31 Jul 2003 13:02:39 -0700 404$ date --date='-1 month' +'Last month was %B?' 405Last month was July? 406$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' 407Last month was June! 408@end example 409 410Also, take care when manipulating dates around clock changes such as 411daylight saving leaps. In a few cases these have added or subtracted 412as much as 24 hours from the clock, so it is often wise to adopt 413universal time by setting the @env{TZ} environment variable to 414@samp{UTC0} before embarking on calendrical calculations. 415 416@node Pure numbers in date strings 417@section Pure numbers in date strings 418 419@cindex pure numbers in date strings 420 421The precise interpretation of a pure decimal number depends 422on the context in the date string. 423 424If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no 425other calendar date item (@pxref{Calendar date items}) appears before it 426in the date string, then @var{yyyy} is read as the year, @var{mm} as the 427month number and @var{dd} as the day of the month, for the specified 428calendar date. 429 430If the decimal number is of the form @var{hh}@var{mm} and no other time 431of day item appears before it in the date string, then @var{hh} is read 432as the hour of the day and @var{mm} as the minute of the hour, for the 433specified time of day. @var{mm} can also be omitted. 434 435If both a calendar date and a time of day appear to the left of a number 436in the date string, but no relative item, then the number overrides the 437year. 438 439 440@node Seconds since the Epoch 441@section Seconds since the Epoch 442 443If you precede a number with @samp{@@}, it represents an internal time 444stamp as a count of seconds. The number can contain an internal 445decimal point (either @samp{.} or @samp{,}); any excess precision not 446supported by the internal representation is truncated toward minus 447infinity. Such a number cannot be combined with any other date 448item, as it specifies a complete time stamp. 449 450@cindex beginning of time, for @acronym{POSIX} 451@cindex epoch, for @acronym{POSIX} 452Internally, computer times are represented as a count of seconds since 453an epoch---a well-defined point of time. On @acronym{GNU} and 454@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so 455@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01 45600:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other 457@acronym{POSIX}-compliant systems support such times as an extension 458to @acronym{POSIX}, using negative counts, so that @samp{@@-1} 459represents 1969-12-31 23:59:59 @sc{utc}. 460 461Traditional Unix systems count seconds with 32-bit two's-complement 462integers and can represent times from 1901-12-13 20:45:52 through 4632038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts 464of seconds with nanosecond subcounts, and can represent all the times 465in the known lifetime of the universe to a resolution of 1 nanosecond. 466 467On most systems, these counts ignore the presence of leap seconds. 468For example, on most systems @samp{@@915148799} represents 1998-12-31 46923:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00 470@sc{utc}, and there is no way to represent the intervening leap second 4711998-12-31 23:59:60 @sc{utc}. 472 473@node Specifying time zone rules 474@section Specifying time zone rules 475 476@vindex TZ 477Normally, dates are interpreted using the rules of the current time 478zone, which in turn are specified by the @env{TZ} environment 479variable, or by a system default if @env{TZ} is not set. To specify a 480different set of default time zone rules that apply just to one date, 481start the date with a string of the form @samp{TZ="@var{rule}"}. The 482two quote characters (@samp{"}) must be present in the date, and any 483quotes or backslashes within @var{rule} must be escaped by a 484backslash. 485 486For example, with the @acronym{GNU} @command{date} command you can 487answer the question ``What time is it in New York when a Paris clock 488shows 6:30am on October 31, 2004?'' by using a date beginning with 489@samp{TZ="Europe/Paris"} as shown in the following shell transcript: 490 491@example 492$ export TZ="America/New_York" 493$ date --date='TZ="Europe/Paris" 2004-10-31 06:30' 494Sun Oct 31 01:30:00 EDT 2004 495@end example 496 497In this example, the @option{--date} operand begins with its own 498@env{TZ} setting, so the rest of that operand is processed according 499to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31 50006:30} as if it were in Paris. However, since the output of the 501@command{date} command is processed according to the overall time zone 502rules, it uses New York time. (Paris was normally six hours ahead of 503New York in 2004, but this example refers to a brief Halloween period 504when the gap was five hours.) 505 506A @env{TZ} value is a rule that typically names a location in the 507@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}. 508A recent catalog of location names appears in the 509@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time 510Gateway}. A few non-@acronym{GNU} hosts require a colon before a 511location name in a @env{TZ} setting, e.g., 512@samp{TZ=":America/New_York"}. 513 514The @samp{tz} database includes a wide variety of locations ranging 515from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but 516if you are at sea and have your own private time zone, or if you are 517using a non-@acronym{GNU} host that does not support the @samp{tz} 518database, you may need to use a @acronym{POSIX} rule instead. Simple 519@acronym{POSIX} rules like @samp{UTC0} specify a time zone without 520daylight saving time; other rules can specify simple daylight saving 521regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ}, 522libc, The GNU C Library}. 523 524@node Authors of get_date 525@section Authors of @code{get_date} 526 527@cindex authors of @code{get_date} 528 529@cindex Bellovin, Steven M. 530@cindex Salz, Rich 531@cindex Berets, Jim 532@cindex MacKenzie, David 533@cindex Meyering, Jim 534@cindex Eggert, Paul 535@code{get_date} was originally implemented by Steven M. Bellovin 536(@email{smb@@research.att.com}) while at the University of North Carolina 537at Chapel Hill. The code was later tweaked by a couple of people on 538Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) 539and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various 540revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering, 541Paul Eggert and others. 542 543@cindex Pinard, F. 544@cindex Berry, K. 545This chapter was originally produced by Fran@,{c}ois Pinard 546(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code, 547and then edited by K.@: Berry (@email{kb@@cs.umb.edu}). 548