1@c GNU date syntax documentation 2 3@c Copyright (C) 1994--2006, 2009--2021 Free Software Foundation, Inc. 4 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, no Front-Cover Texts, and no Back-Cover Texts. A 9@c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>. 10 11@node Date input formats 12@chapter Date input formats 13 14@cindex date input formats 15@findex parse_datetime 16 17First, a quote: 18 19@quotation 20Our units of temporal measurement, from seconds on up to months, are so 21complicated, asymmetrical and disjunctive so as to make coherent mental 22reckoning in time all but impossible. Indeed, had some tyrannical god 23contrived to enslave our minds to time, to make it all but impossible 24for us to escape subjection to sodden routines and unpleasant surprises, 25he could hardly have done better than handing down our present system. 26It is like a set of trapezoidal building blocks, with no vertical or 27horizontal surfaces, like a language in which the simplest thought 28demands ornate constructions, useless particles and lengthy 29circumlocutions. Unlike the more successful patterns of language and 30science, which enable us to face experience boldly or at least 31level-headedly, our system of temporal calculation silently and 32persistently encourages our terror of time. 33 34@dots{} It is as though architects had to measure length in feet, width 35in meters and height in ells; as though basic instruction manuals 36demanded a knowledge of five different languages. It is no wonder then 37that we often look into our own immediate past or future, last Tuesday 38or a week from Sunday, with feelings of helpless confusion. @dots{} 39 40---Robert Grudin, @cite{Time and the Art of Living}. 41@end quotation 42 43This section describes the textual date representations that GNU 44programs accept. These are the strings you, as a user, can supply as 45arguments to the various programs. The C interface (via the 46@code{parse_datetime} function) is not described here. 47 48@menu 49* General date syntax:: Common rules 50* Calendar date items:: 21 Jul 2020 51* Time of day items:: 9:20pm 52* Time zone items:: UTC, -0700, +0900, @dots{} 53* Combined date and time of day items:: 2020-07-21T20:02:00,000000-0400 54* Day of week items:: Monday and others 55* Relative items in date strings:: next tuesday, 2 years ago 56* Pure numbers in date strings:: 20200721, 1440 57* Seconds since the Epoch:: @@1595289600 58* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0" 59* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. 60@end menu 61 62 63@node General date syntax 64@section General date syntax 65 66@cindex general date syntax 67 68@cindex items in date strings 69A @dfn{date} is a string, possibly empty, containing many items 70separated by whitespace. The whitespace may be omitted when no 71ambiguity arises. The empty string means the beginning of today (i.e., 72midnight). Order of the items is immaterial. A date string may contain 73many flavors of items: 74 75@itemize @bullet 76@item calendar date items 77@item time of day items 78@item time zone items 79@item combined date and time of day 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 127Tue Jul 21 23:00:37 UTC 2020 128$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 1292020-07-21 23:00:37Z 130$ date --rfc-3339=ns # --rfc-3339 is a GNU extension. 1312020-07-21 19:00:37.692722128-04:00 132$ date --rfc-2822 # a GNU extension 133Tue, 21 Jul 2020 19:00:37 -0400 134$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 1352020-07-21 19:00:37 -0400 136$ date +'@@%s.%N' # %s and %N are GNU extensions. 137@@1595372437.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@cindex leap seconds 148Invalid dates like @samp{2019-02-29} or times like @samp{24:00} are 149rejected. In the typical case of a host that does not support leap 150seconds, a time like @samp{23:59:60} is rejected even if it 151corresponds to a valid leap second. 152 153 154@node Calendar date items 155@section Calendar date items 156 157@cindex calendar date item 158 159A @dfn{calendar date item} specifies a day of the year. It is 160specified differently, depending on whether the month is specified 161numerically or literally. All these strings specify the same calendar date: 162 163@example 1642020-07-20 # ISO 8601. 16520-7-20 # Assume 19xx for 69 through 99, 166 # 20xx for 00 through 68 (not recommended). 1677/20/2020 # Common U.S. writing. 16820 July 2020 16920 Jul 2020 # Three-letter abbreviations always allowed. 170Jul 20, 2020 17120-jul-2020 17220jul2020 173@end example 174 175The year can also be omitted. In this case, the last specified year is 176used, or the current year if none. For example: 177 178@example 1797/20 180jul 20 181@end example 182 183Here are the rules. 184 185@cindex ISO 8601 date format 186@cindex date format, ISO 8601 187For numeric months, the ISO 8601 format 188@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is 189any positive number, @var{month} is a number between 01 and 12, and 190@var{day} is a number between 01 and 31. A leading zero must be present 191if a number is less than ten. If @var{year} is 68 or smaller, then 2000 192is added to it; otherwise, if @var{year} is less than 100, 193then 1900 is added to it. The construct 194@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, 195is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. 196 197@cindex month names in date strings 198@cindex abbreviations for months 199Literal months may be spelled out in full: @samp{January}, 200@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June}, 201@samp{July}, @samp{August}, @samp{September}, @samp{October}, 202@samp{November} or @samp{December}. Literal months may be abbreviated 203to their first three letters, possibly followed by an abbreviating dot. 204It is also permitted to write @samp{Sept} instead of @samp{September}. 205 206When months are written literally, the calendar date may be given as any 207of the following: 208 209@example 210@var{day} @var{month} @var{year} 211@var{day} @var{month} 212@var{month} @var{day} @var{year} 213@var{day}-@var{month}-@var{year} 214@end example 215 216Or, omitting the year: 217 218@example 219@var{month} @var{day} 220@end example 221 222 223@node Time of day items 224@section Time of day items 225 226@cindex time of day item 227 228A @dfn{time of day item} in date strings specifies the time on a given 229day. Here are some examples, all of which represent the same time: 230 231@example 23220:02:00.000000 23320:02 2348:02pm 23520:02-0500 # In EST (U.S. Eastern Standard Time). 236@end example 237 238@cindex leap seconds 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. 269The zone minutes term, @var{mm}, may be omitted, in which case 270the one- or two-digit correction is interpreted as a number of hours. 271You can also separate @var{hh} from @var{mm} with a colon. 272When a time zone correction is given this way, it 273forces interpretation of the time relative to 274Coordinated Universal Time (UTC), overriding any previous 275specification for the time zone or the local time zone. For example, 276@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours 277ahead of UTC (e.g., India). 278This is the best way to 279specify a time zone correction by fractional parts of an hour. 280The maximum zone correction is 24 hours. 281 282Either @samp{am}/@samp{pm} or a time zone correction may be specified, 283but not both. 284 285 286@node Time zone items 287@section Time zone items 288 289@cindex time zone item 290 291A @dfn{time zone item} specifies an international time zone, indicated 292by a small set of letters, e.g., @samp{UTC} or @samp{Z} 293for Coordinated Universal 294Time. Any included periods are ignored. By following a 295non-daylight-saving time zone by the string @samp{DST} in a separate 296word (that is, separated by some white space), the corresponding 297daylight saving time zone may be specified. 298Alternatively, a non-daylight-saving time zone can be followed by a 299time zone correction, to add the two values. This is normally done 300only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to 301@samp{+05:30}. 302 303Time zone items other than @samp{UTC} and @samp{Z} 304are obsolescent and are not recommended, because they 305are ambiguous; for example, @samp{EST} has a different meaning in 306Australia than in the United States, and @samp{A} has different 307meaning as a military time zone than as an obsolescent 308RFC 822 time zone. Instead, it's better to use 309unambiguous numeric time zone corrections like @samp{-0500}, as 310described in the previous section. 311 312If neither a time zone item nor a time zone correction is supplied, 313timestamps are interpreted using the rules of the default time zone 314(@pxref{Specifying time zone rules}). 315 316 317@node Combined date and time of day items 318@section Combined date and time of day items 319 320@cindex combined date and time of day item 321@cindex ISO 8601 date and time of day format 322@cindex date and time of day format, ISO 8601 323 324The ISO 8601 date and time of day extended format consists of an ISO 3258601 date, a @samp{T} character separator, and an ISO 8601 time of 326day. This format is also recognized if the @samp{T} is replaced by a 327space. 328 329In this format, the time of day should use 24-hour notation. 330Fractional seconds are allowed, with either comma or period preceding 331the fraction. ISO 8601 fractional minutes and hours are not 332supported. Typically, hosts support nanosecond timestamp resolution; 333excess precision is silently discarded. 334 335Here are some examples: 336 337@example 3382012-09-24T20:02:00.052-05:00 3392012-12-31T23:59:59,999999999+11:00 3401970-01-01 00:00Z 341@end example 342 343@node Day of week items 344@section Day of week items 345 346@cindex day of week item 347 348The explicit mention of a day of the week will forward the date 349(only if necessary) to reach that day of the week in the future. 350 351Days of the week may be spelled out in full: @samp{Sunday}, 352@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday}, 353@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their 354first three letters, optionally followed by a period. The special 355abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for 356@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are 357also allowed. 358 359@findex next @var{day} 360@findex last @var{day} 361A number may precede a day of the week item to move forward 362supplementary weeks. It is best used in expression like @samp{third 363monday}. In this context, @samp{last @var{day}} or @samp{next 364@var{day}} is also acceptable; they move one week before or after 365the day that @var{day} by itself would represent. 366 367A comma following a day of the week item is ignored. 368 369 370@node Relative items in date strings 371@section Relative items in date strings 372 373@cindex relative items in date strings 374@cindex displacement of dates 375 376@dfn{Relative items} adjust a date (or the current date if none) forward 377or backward. The effects of relative items accumulate. Here are some 378examples: 379 380@example 3811 year 3821 year ago 3833 years 3842 days 385@end example 386 387@findex year @r{in date strings} 388@findex month @r{in date strings} 389@findex fortnight @r{in date strings} 390@findex week @r{in date strings} 391@findex day @r{in date strings} 392@findex hour @r{in date strings} 393@findex minute @r{in date strings} 394The unit of time displacement may be selected by the string @samp{year} 395or @samp{month} for moving by whole years or months. These are fuzzy 396units, as years and months are not all of equal duration. More precise 397units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 398days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes, 399@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or 400@samp{sec} worth one second. An @samp{s} suffix on these units is 401accepted and ignored. 402 403@findex ago @r{in date strings} 404The unit of time may be preceded by a multiplier, given as an optionally 405signed number. Unsigned numbers are taken as positively signed. No 406number at all implies 1 for a multiplier. Following a relative item by 407the string @samp{ago} is equivalent to preceding the unit by a 408multiplier with value @math{-1}. 409 410@findex day @r{in date strings} 411@findex tomorrow @r{in date strings} 412@findex yesterday @r{in date strings} 413The string @samp{tomorrow} is worth one day in the future (equivalent 414to @samp{day}), the string @samp{yesterday} is worth 415one day in the past (equivalent to @samp{day ago}). 416 417@findex now @r{in date strings} 418@findex today @r{in date strings} 419@findex this @r{in date strings} 420The strings @samp{now} or @samp{today} are relative items corresponding 421to zero-valued time displacement, these strings come from the fact 422a zero-valued time displacement represents the current time when not 423otherwise changed by previous items. They may be used to stress other 424items, like in @samp{12:00 today}. The string @samp{this} also has 425the meaning of a zero-valued time displacement, but is preferred in 426date strings like @samp{this thursday}. 427 428When a relative item causes the resulting date to cross a boundary 429where the clocks were adjusted, typically for daylight saving time, 430the resulting date and time are adjusted accordingly. 431 432The fuzz in units can cause problems with relative items. For 433example, @samp{2020-07-31 -1 month} might evaluate to 2020-07-01, 434because 2020-06-31 is an invalid date. To determine the previous 435month more reliably, you can ask for the month before the 15th of the 436current month. For example: 437 438@example 439$ date -R 440Thu, 31 Jul 2020 13:02:39 -0400 441$ date --date='-1 month' +'Last month was %B?' 442Last month was July? 443$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' 444Last month was June! 445@end example 446 447Also, take care when manipulating dates around clock changes such as 448daylight saving leaps. In a few cases these have added or subtracted 449as much as 24 hours from the clock, so it is often wise to adopt 450universal time by setting the @env{TZ} environment variable to 451@samp{UTC0} before embarking on calendrical calculations. 452 453@node Pure numbers in date strings 454@section Pure numbers in date strings 455 456@cindex pure numbers in date strings 457 458The precise interpretation of a pure decimal number depends 459on the context in the date string. 460 461If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no 462other calendar date item (@pxref{Calendar date items}) appears before it 463in the date string, then @var{yyyy} is read as the year, @var{mm} as the 464month number and @var{dd} as the day of the month, for the specified 465calendar date. 466 467If the decimal number is of the form @var{hh}@var{mm} and no other time 468of day item appears before it in the date string, then @var{hh} is read 469as the hour of the day and @var{mm} as the minute of the hour, for the 470specified time of day. @var{mm} can also be omitted. 471 472If both a calendar date and a time of day appear to the left of a number 473in the date string, but no relative item, then the number overrides the 474year. 475 476 477@node Seconds since the Epoch 478@section Seconds since the Epoch 479 480If you precede a number with @samp{@@}, it represents an internal 481timestamp as a count of seconds. The number can contain an internal 482decimal point (either @samp{.} or @samp{,}); any excess precision not 483supported by the internal representation is truncated toward minus 484infinity. Such a number cannot be combined with any other date 485item, as it specifies a complete timestamp. 486 487@cindex beginning of time, for POSIX 488@cindex Epoch, for POSIX 489Internally, computer times are represented as a count of seconds since 490an Epoch---a well-defined point of time. On GNU and 491POSIX systems, the Epoch is 1970-01-01 00:00:00 UTC, so 492@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01 49300:00:01 UTC, and so forth. GNU and most other 494POSIX-compliant systems support such times as an extension 495to POSIX, using negative counts, so that @samp{@@-1} 496represents 1969-12-31 23:59:59 UTC. 497 498Most modern systems count seconds with 64-bit two's-complement integers 499of seconds with nanosecond subcounts, which is a range that includes 500the known lifetime of the universe with nanosecond resolution. 501Some obsolescent systems count seconds with 32-bit two's-complement 502integers and can represent times from 1901-12-13 20:45:52 through 5032038-01-19 03:14:07 UTC@. A few systems sport other time ranges. 504 505@cindex leap seconds 506On most hosts, these counts ignore the presence of leap seconds. 507For example, on most hosts @samp{@@1483228799} represents 2016-12-31 50823:59:59 UTC, @samp{@@1483228800} represents 2017-01-01 00:00:00 509UTC, and there is no way to represent the intervening leap second 5102016-12-31 23:59:60 UTC. 511 512@node Specifying time zone rules 513@section Specifying time zone rules 514 515@vindex TZ 516Normally, dates are interpreted using the rules of the current time 517zone, which in turn are specified by the @env{TZ} environment 518variable, or by a system default if @env{TZ} is not set. To specify a 519different set of default time zone rules that apply just to one date, 520start the date with a string of the form @samp{TZ="@var{rule}"}. The 521two quote characters (@samp{"}) must be present in the date, and any 522quotes or backslashes within @var{rule} must be escaped by a 523backslash. 524 525For example, with the GNU @command{date} command you can 526answer the question ``What time is it in New York when a Paris clock 527shows 6:30am on October 31, 2019?'' by using a date beginning with 528@samp{TZ="Europe/Paris"} as shown in the following shell transcript: 529 530@example 531$ export TZ="America/New_York" 532$ date --date='TZ="Europe/Paris" 2019-10-31 06:30' 533Sun Oct 31 01:30:00 EDT 2019 534@end example 535 536In this example, the @option{--date} operand begins with its own 537@env{TZ} setting, so the rest of that operand is processed according 538to @samp{Europe/Paris} rules, treating the string @samp{2019-10-31 53906:30} as if it were in Paris. However, since the output of the 540@command{date} command is processed according to the overall time zone 541rules, it uses New York time. (Paris was normally six hours ahead of 542New York in 2019, but this example refers to a brief Halloween period 543when the gap was five hours.) 544 545A @env{TZ} value is a rule that typically names a location in the 546@uref{https://www.iana.org/time-zones, @samp{tz} database}. 547A recent catalog of location names appears in the 548@uref{https://twiki.org/cgi-bin/xtra/tzdatepick.html, TWiki Date and Time 549Gateway}. A few non-GNU hosts require a colon before a 550location name in a @env{TZ} setting, e.g., 551@samp{TZ=":America/New_York"}. 552 553The @samp{tz} database includes a wide variety of locations ranging 554from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but 555if you are at sea and have your own private time zone, or if you are 556using a non-GNU host that does not support the @samp{tz} 557database, you may need to use a POSIX rule instead. Simple 558POSIX rules like @samp{UTC0} specify a time zone without 559daylight saving time; other rules can specify simple daylight saving 560regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ}, 561libc, The GNU C Library}. 562 563@node Authors of parse_datetime 564@section Authors of @code{parse_datetime} 565@c the anchor keeps the old node name, to try to avoid breaking links 566@anchor{Authors of get_date} 567 568@cindex authors of @code{parse_datetime} 569 570@cindex Bellovin, Steven M. 571@cindex Salz, Rich 572@cindex Berets, Jim 573@cindex MacKenzie, David 574@cindex Meyering, Jim 575@cindex Eggert, Paul 576@code{parse_datetime} started life as @code{getdate}, as originally 577implemented by Steven M. Bellovin 578(@email{smb@@research.att.com}) while at the University of North Carolina 579at Chapel Hill. The code was later tweaked by a couple of people on 580Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) 581and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various 582revisions for the GNU system were made by David MacKenzie, Jim Meyering, 583Paul Eggert and others, including renaming it to @code{get_date} to 584avoid a conflict with the alternative Posix function @code{getdate}, 585and a later rename to @code{parse_datetime}. The Posix function 586@code{getdate} can parse more locale-specific dates using 587@code{strptime}, but relies on an environment variable and external 588file, and lacks the thread-safety of @code{parse_datetime}. 589 590@cindex Pinard, F. 591@cindex Berry, K. 592This chapter was originally produced by Fran@,{c}ois Pinard 593(@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code, 594and then edited by K. Berry (@email{kb@@cs.umb.edu}). 595