contrib/tzdata/theory.html

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4   <title>Theory and pragmatics of the tz code and data</title>
   5   <meta charset="UTF-8">
   6   <style>
   7     pre {margin-left: 2em; white-space: pre-wrap;}
   8   </style>
   9 </head>
  10
  11 <body>
  12 <h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>
  13   <h3>Outline</h3>
  14   <nav>
  15     <ul>
  16       <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>
  17           database</a></li>
  18       <li><a href="#naming">Timezone identifiers</a></li>
  19       <li><a href="#abbreviations">Time zone abbreviations</a></li>
  20       <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code>
  21           database</a></li>
  22       <li><a href="#functions">Time and date functions</a></li>
  23       <li><a href="#stability">Interface stability</a></li>
  24       <li><a href="#leapsec">Leap seconds</a></li>
  25       <li><a href="#calendar">Calendrical issues</a></li>
  26       <li><a href="#planets">Time and time zones off earth</a></li>
  27     </ul>
  28   </nav>
  29
  30 <section>
  31   <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>
  32 <p>
  33 The <a
  34 href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code>
  35 database</a> attempts to record the history and predicted future of
  36 civil time scales.
  37 It organizes <a href="tz-link.html">time zone and daylight saving time
  38 data</a> by partitioning the world into <a
  39 href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a>
  40 whose clocks all agree about timestamps that occur after the <a
  41 href="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a>
  42 (1970-01-01 00:00:00 <a
  43 href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr
  44 title="Coordinated Universal Time">UTC</abbr></a>).
  45 Although 1970 is a somewhat-arbitrary cutoff, there are significant
  46 challenges to moving the cutoff earlier even by a decade or two, due
  47 to the wide variety of local practices before computer timekeeping
  48 became prevalent.
  49 Most timezones correspond to a notable location and the database
  50 records all known clock transitions for that location;
  51 some timezones correspond instead to a fixed <abbr>UTC</abbr> offset.
  52 </p>
  53
  54 <p>
  55 Each timezone typically corresponds to a geographical region that is
  56 smaller than a traditional time zone, because clocks in a timezone
  57 all agree after 1970 whereas a traditional time zone merely
  58 specifies current standard time. For example, applications that deal
  59 with current and future timestamps in the traditional North
  60 American mountain time zone can choose from the timezones
  61 <code>America/Denver</code> which observes US-style daylight saving
  62 time (<abbr>DST</abbr>),
  63 and <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>.
  64 Applications that also deal with past timestamps in the mountain time
  65 zone can choose from over a dozen timezones, such as
  66 <code>America/Boise</code>, <code>America/Edmonton</code>, and
  67 <code>America/Hermosillo</code>, each of which currently uses mountain
  68 time but differs from other timezones for some timestamps after 1970.
  69 </p>
  70
  71 <p>
  72 Clock transitions before 1970 are recorded for location-based timezones,
  73 because most systems support timestamps before 1970 and could
  74 misbehave if data entries were omitted for pre-1970 transitions.
  75 However, the database is not designed for and does not suffice for
  76 applications requiring accurate handling of all past times everywhere,
  77 as it would take far too much effort and guesswork to record all
  78 details of pre-1970 civil timekeeping.
  79 Although some information outside the scope of the database is
  80 collected in a file <code>backzone</code> that is distributed along
  81 with the database proper, this file is less reliable and does not
  82 necessarily follow database guidelines.
  83 </p>
  84
  85 <p>
  86 As described below, reference source code for using the
  87 <code><abbr>tz</abbr></code> database is also available.
  88 The <code><abbr>tz</abbr></code> code is upwards compatible with <a
  89 href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international
  90 standard for <a
  91 href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems.
  92 As of this writing, the current edition of POSIX is: <a
  93 href="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open
  94 Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018
  95 Edition.
  96 Because the database's scope encompasses real-world changes to civil
  97 timekeeping, its model for describing time is more complex than the
  98 standard and daylight saving times supported by POSIX.1-2017.
  99 A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
 100 have more than two changes per year, these changes need not merely
 101 flip back and forth between two alternatives, and the rules themselves
 102 can change at times.
 103 Whether and when a timezone changes its clock,
 104 and even the timezone's notional base offset from <abbr>UTC</abbr>,
 105 are variable.
 106 It does not always make sense to talk about a timezone's
 107 "base offset", which is not necessarily a single number.
 108 </p>
 109
 110 </section>
 111
 112 <section>
 113   <h2 id="naming">Timezone identifiers</h2>
 114 <p>
 115 Each timezone has a name that uniquely identifies the timezone.
 116 Inexperienced users are not expected to select these names unaided.
 117 Distributors should provide documentation and/or a simple selection
 118 interface that explains each name via a map or via descriptive text like
 119 "Czech Republic" instead of the timezone name "<code>Europe/Prague</code>".
 120 If geolocation information is available, a selection interface can
 121 locate the user on a timezone map or prioritize names that are
 122 geographically close. For an example selection interface, see the
 123 <code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.
 124 The <a href="https://cldr.unicode.org">Unicode Common Locale Data
 125 Repository</a> contains data that may be useful for other selection
 126 interfaces; it maps timezone names like <code>Europe/Prague</code> to
 127 locale-dependent strings like "Prague", "Praha", "Прага", and "布拉格".
 128 </p>
 129
 130 <p>
 131 The naming conventions attempt to strike a balance
 132 among the following goals:
 133 </p>
 134
 135 <ul>
 136   <li>
 137     Uniquely identify every timezone where clocks have agreed since 1970.
 138     This is essential for the intended use: static clocks keeping local
 139     civil time.
 140   </li>
 141   <li>
 142     Indicate to experts where the timezone's clocks typically are.
 143   </li>
 144   <li>
 145     Be robust in the presence of political changes.
 146     For example, names are typically not tied to countries, to avoid
 147     incompatibilities when countries change their name (e.g.,
 148     Swaziland&rarr;Eswatini) or when locations change countries (e.g., Hong
 149     Kong from UK colony to China).
 150     There is no requirement that every country or national
 151     capital must have a timezone name.
 152   </li>
 153   <li>
 154     Be portable to a wide variety of implementations.
 155   </li>
 156   <li>
 157     Use a consistent naming conventions over the entire world.
 158   </li>
 159 </ul>
 160
 161 <p>
 162 Names normally have the form
 163 <var>AREA</var><code>/</code><var>LOCATION</var>, where
 164 <var>AREA</var> is a continent or ocean, and
 165 <var>LOCATION</var> is a specific location within the area.
 166 North and South America share the same area, '<code>America</code>'.
 167 Typical names are '<code>Africa/Cairo</code>',
 168 '<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
 169 Some names are further qualified to help avoid confusion; for example,
 170 '<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
 171 Indiana from other Petersburgs in America.
 172 </p>
 173
 174 <p>
 175 Here are the general guidelines used for
 176 choosing timezone names,
 177 in decreasing order of importance:
 178 </p>
 179
 180 <ul>
 181   <li>
 182     Use only valid POSIX file name components (i.e., the parts of
 183     names other than '<code>/</code>').
 184     Do not use the file name components '<code>.</code>' and
 185     '<code>..</code>'.
 186     Within a file name component, use only <a
 187     href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters,
 188     '<code>.</code>', '<code>-</code>' and '<code>_</code>'.
 189     Do not use digits, as that might create an ambiguity with <a
 190     href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX.1-2017
 191     <code>TZ</code> strings</a>.
 192     A file name component must not exceed 14 characters or start with
 193     '<code>-</code>'.
 194     E.g., prefer <code>America/Noronha</code> to
 195     <code>America/Fernando_de_Noronha</code>.
 196     Exceptions: see the discussion of legacy names below.
 197   </li>
 198   <li>
 199     A name must not be empty, or contain '<code>//</code>', or
 200     start or end with '<code>/</code>'.
 201   </li>
 202   <li>
 203     Do not use names that differ only in case.
 204     Although the reference implementation is case-sensitive, some
 205     other implementations are not, and they would mishandle names
 206     differing only in case.
 207   </li>
 208   <li>
 209     If one name <var>A</var> is an initial prefix of another
 210     name <var>AB</var> (ignoring case), then <var>B</var> must not
 211     start with '<code>/</code>', as a regular file cannot have the
 212     same name as a directory in POSIX.
 213     For example, <code>America/New_York</code> precludes
 214     <code>America/New_York/Bronx</code>.
 215   </li>
 216   <li>
 217     Uninhabited regions like the North Pole and Bouvet Island
 218     do not need locations, since local time is not defined there.
 219   </li>
 220   <li>
 221     If all the clocks in a timezone have agreed since 1970,
 222     do not bother to include more than one timezone
 223     even if some of the clocks disagreed before 1970.
 224     Otherwise these tables would become annoyingly large.
 225   </li>
 226   <li>
 227     If boundaries between regions are fluid, such as during a war or
 228     insurrection, do not bother to create a new timezone merely
 229     because of yet another boundary change. This helps prevent table
 230     bloat and simplifies maintenance.
 231   </li>
 232   <li>
 233     If a name is ambiguous, use a less ambiguous alternative;
 234     e.g., many cities are named San José and Georgetown, so
 235     prefer <code>America/Costa_Rica</code> to
 236     <code>America/San_Jose</code> and <code>America/Guyana</code>
 237     to <code>America/Georgetown</code>.
 238   </li>
 239   <li>
 240     Keep locations compact.
 241     Use cities or small islands, not countries or regions, so that any
 242     future changes do not split individual locations into different
 243     timezones.
 244     E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
 245     since
 246     <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France
 247     has had multiple time zones</a>.
 248   </li>
 249   <li>
 250     Use mainstream English spelling, e.g., prefer
 251     <code>Europe/Rome</code> to <code>Europa/Roma</code>, and
 252     prefer <code>Europe/Athens</code> to the Greek
 253     <code>Ευρώπη/Αθήνα</code> or the Romanized
 254     <code>Evrópi/Athína</code>.
 255     The POSIX file name restrictions encourage this guideline.
 256   </li>
 257   <li>
 258     Use the most populous among locations in a region,
 259     e.g., prefer <code>Asia/Shanghai</code> to
 260     <code>Asia/Beijing</code>.
 261     Among locations with similar populations, pick the best-known
 262     location, e.g., prefer <code>Europe/Rome</code> to
 263     <code>Europe/Milan</code>.
 264   </li>
 265   <li>
 266     Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
 267     <code>Atlantic/Canaries</code>.
 268   </li>
 269   <li>
 270     Omit common suffixes like '<code>_Islands</code>' and
 271     '<code>_City</code>', unless that would lead to ambiguity.
 272     E.g., prefer <code>America/Cayman</code> to
 273     <code>America/Cayman_Islands</code> and
 274     <code>America/Guatemala</code> to
 275     <code>America/Guatemala_City</code>, but prefer
 276     <code>America/Mexico_City</code> to
 277     <code>America/Mexico</code>
 278     because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the
 279     country of Mexico has several time zones</a>.
 280   </li>
 281   <li>
 282     Use '<code>_</code>' to represent a space.
 283   </li>
 284   <li>
 285     Omit '<code>.</code>' from abbreviations in names.
 286     E.g., prefer <code>Atlantic/St_Helena</code> to
 287     <code>Atlantic/St._Helena</code>.
 288   </li>
 289   <li>
 290     Do not change established names if they only marginally violate
 291     the above guidelines.
 292     For example, do not change the existing name <code>Europe/Rome</code> to
 293     <code>Europe/Milan</code> merely because Milan's population has grown
 294     to be somewhat greater than Rome's.
 295   </li>
 296   <li>
 297     If a name is changed, put its old spelling in the
 298     '<code>backward</code>' file as a link to the new spelling.
 299     This means old spellings will continue to work.
 300     Ordinarily a name change should occur only in the rare case when
 301     a location's consensus English-language spelling changes; for example,
 302     in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code>
 303     due to long-time widespread use of the new city name instead of the old.
 304   </li>
 305 </ul>
 306
 307 <p>
 308 Guidelines have evolved with time, and names following old versions of
 309 these guidelines might not follow the current version. When guidelines
 310 have changed, old names continue to be supported. Guideline changes
 311 have included the following:
 312 </p>
 313
 314 <ul>
 315 <li>
 316 Older versions of this package used a different naming scheme.
 317 See the file '<code>backward</code>' for most of these older names
 318 (e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>').
 319 The other old-fashioned names still supported are
 320 '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and
 321 '<code>EET</code>' (see the file '<code>europe</code>').
 322 </li>
 323
 324 <li>
 325 Older versions of this package defined legacy names that are
 326 incompatible with the first guideline of location names, but which are
 327 still supported.
 328 These legacy names are mostly defined in the file
 329 '<code>etcetera</code>'.
 330 Also, the file '<code>backward</code>' defines the legacy names
 331 '<code>Etc/GMT0</code>', '<code>Etc/GMT-0</code>', '<code>Etc/GMT+0</code>',
 332 '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>',
 333 and the file '<code>northamerica</code>' defines the legacy names
 334 '<code>EST5EDT</code>', '<code>CST6CDT</code>',
 335 '<code>MST7MDT</code>', and '<code>PST8PDT</code>'.
 336 </li>
 337
 338 <li>
 339 Older versions of these guidelines said that
 340 there should typically be at least one name for each <a
 341 href="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr
 342 title="International Organization for Standardization">ISO</abbr>
 343 3166-1</a> officially assigned two-letter code for an inhabited
 344 country or territory.
 345 This old guideline has been dropped, as it was not needed to handle
 346 timestamps correctly and it increased maintenance burden.
 347 </li>
 348 </ul>
 349
 350 <p>
 351 The file <code>zone1970.tab</code> lists geographical locations used
 352 to name timezones.
 353 It is intended to be an exhaustive list of names for geographic
 354 regions as described above; this is a subset of the timezones in the data.
 355 Although a <code>zone1970.tab</code> location's
 356 <a href="https://en.wikipedia.org/wiki/Longitude">longitude</a>
 357 corresponds to
 358 its <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean
 359 time (<abbr>LMT</abbr>)</a> offset with one hour for every 15&deg;
 360 east longitude, this relationship is not exact.
 361 The backward-compatibility file <code>zone.tab</code> is similar
 362 but conforms to the older-version guidelines related to <abbr>ISO</abbr> 3166-1;
 363 it lists only one country code per entry and unlike <code>zone1970.tab</code>
 364 it can list names defined in <code>backward</code>.
 365 Applications that process only timestamps from now on can instead use the file
 366 <code>zonenow.tab</code>, which partitions the world more coarsely,
 367 into regions where clocks agree now and in the predicted future;
 368 this file is smaller and simpler than <code>zone1970.tab</code>
 369 and <code>zone.tab</code>.
 370 </p>
 371
 372 <p>
 373 The database defines each timezone name to be a zone, or a link to a zone.
 374 The source file <code>backward</code> defines links for backward
 375 compatibility; it does not define zones.
 376 Although <code>backward</code> was originally designed to be optional,
 377 nowadays distributions typically use it
 378 and no great weight should be attached to whether a link
 379 is defined in <code>backward</code> or in some other file.
 380 The source file <code>etcetera</code> defines names that may be useful
 381 on platforms that do not support POSIX.1-2017-style <code>TZ</code> strings;
 382 no other source file other than <code>backward</code>
 383 contains links to its zones.
 384 One of <code>etcetera</code>'s names is <code>Etc/UTC</code>,
 385 used by functions like <code>gmtime</code> to obtain leap
 386 second information on platforms that support leap seconds.
 387 Another <code>etcetera</code> name, <code>GMT</code>,
 388 is used by older code releases.
 389 </p>
 390 </section>
 391
 392 <section>
 393   <h2 id="abbreviations">Time zone abbreviations</h2>
 394 <p>
 395 When this package is installed, it generates time zone abbreviations
 396 like '<code>EST</code>' to be compatible with human tradition and POSIX.
 397 Here are the general guidelines used for choosing time zone abbreviations,
 398 in decreasing order of importance:
 399 </p>
 400
 401 <ul>
 402   <li>
 403     Use three to six characters that are ASCII alphanumerics or
 404     '<code>+</code>' or '<code>-</code>'.
 405     Previous editions of this database also used characters like
 406     space and '<code>?</code>', but these characters have a
 407     special meaning to the
 408     <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a>
 409     and cause commands like
 410     '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a>
 411     `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>'
 412     to have unexpected effects.
 413     Previous editions of this guideline required upper-case letters, but the
 414     Congressman who introduced
 415     <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro
 416     Standard Time</a> preferred "ChST", so lower-case letters are now
 417     allowed.
 418     Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>',
 419     '<code>+</code>', and alphanumeric characters from the portable
 420     character set in the current locale.
 421     In practice ASCII alphanumerics and '<code>+</code>' and
 422     '<code>-</code>' are safe in all locales.
 423
 424     <p>
 425     In other words, in the C locale the POSIX extended regular
 426     expression <code>[-+[:alnum:]]{3,6}</code> should match the
 427     abbreviation.
 428     This guarantees that all abbreviations could have been specified by a
 429     POSIX.1-2017 <code>TZ</code> string.
 430     </p>
 431   </li>
 432   <li>
 433     Use abbreviations that are in common use among English-speakers,
 434     e.g., 'EST' for Eastern Standard Time in North America.
 435     We assume that applications translate them to other languages
 436     as part of the normal localization process; for example,
 437     a French application might translate 'EST' to 'HNE'.
 438
 439     <p>
 440     <small>These abbreviations (for standard/daylight/etc. time) are:
 441       ACST/ACDT Australian Central,
 442       AST/ADT/APT/AWT/ADDT Atlantic,
 443       AEST/AEDT Australian Eastern,
 444       AHST/AHDT Alaska-Hawaii,
 445       AKST/AKDT Alaska,
 446       AWST/AWDT Australian Western,
 447       BST/BDT Bering,
 448       CAT/CAST Central Africa,
 449       CET/CEST/CEMT Central European,
 450       ChST Chamorro,
 451       CST/CDT/CWT/CPT Central [North America],
 452       CST/CDT China,
 453       GMT/BST/IST/BDST Greenwich,
 454       EAT East Africa,
 455       EST/EDT/EWT/EPT Eastern [North America],
 456       EET/EEST Eastern European,
 457       GST/GDT Guam,
 458       HST/HDT/HWT/HPT Hawaii,
 459       HKT/HKST/HKWT Hong Kong,
 460       IST India,
 461       IST/GMT Irish,
 462       IST/IDT/IDDT Israel,
 463       JST/JDT Japan,
 464       KST/KDT Korea,
 465       MET/MEST Middle European (a backward-compatibility alias for
 466         Central European),
 467       MSK/MSD Moscow,
 468       MST/MDT/MWT/MPT Mountain,
 469       NST/NDT/NWT/NPT/NDDT Newfoundland,
 470       NST/NDT/NWT/NPT Nome,
 471       NZMT/NZST New Zealand through 1945,
 472       NZST/NZDT New Zealand 1946&ndash;present,
 473       PKT/PKST Pakistan,
 474       PST/PDT/PWT/PPT Pacific,
 475       PST/PDT Philippine,
 476       SAST South Africa,
 477       SST Samoa,
 478       UTC Universal,
 479       WAT/WAST West Africa,
 480       WET/WEST/WEMT Western European,
 481       WIB Waktu Indonesia Barat,
 482       WIT Waktu Indonesia Timur,
 483       WITA Waktu Indonesia Tengah,
 484       YST/YDT/YWT/YPT/YDDT Yukon</small>.
 485     </p>
 486   </li>
 487   <li>
 488     <p>
 489     For times taken from a city's longitude, use the
 490     traditional <var>x</var>MT notation.
 491     The only abbreviation like this in current use is '<abbr>GMT</abbr>'.
 492     The others are for timestamps before 1960,
 493     except that Monrovia Mean Time persisted until 1972.
 494     Typically, numeric abbreviations (e.g., '<code>-</code>004430' for
 495     MMT) would cause trouble here, as the numeric strings would exceed
 496     the POSIX length limit.
 497     </p>
 498
 499     <p>
 500     <small>These abbreviations are:
 501       AMT Asunción, Athens;
 502       BMT Baghdad, Bangkok, Batavia, Bermuda, Bern, Bogotá,
 503         Brussels, Bucharest;
 504       CMT Calamarca, Caracas, Chisinau, Colón, Córdoba;
 505       DMT Dublin/Dunsink;
 506       EMT Easter;
 507       FFMT Fort-de-France;
 508       FMT Funchal;
 509       GMT Greenwich;
 510       HMT Havana, Helsinki, Horta, Howrah;
 511       IMT Irkutsk, Istanbul;
 512       JMT Jerusalem;
 513       KMT Kaunas, Kyiv, Kingston;
 514       LMT Lima, Lisbon, local;
 515       MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo,
 516         Moratuwa, Moscow;
 517       PLMT Phù Liễn;
 518       PMT Paramaribo, Paris, Perm, Pontianak, Prague;
 519       PMMT Port Moresby;
 520       PPMT Port-au-Prince;
 521       QMT Quito;
 522       RMT Rangoon, Riga, Rome;
 523       SDMT Santo Domingo;
 524       SJMT San José;
 525       SMT Santiago, Simferopol, Singapore, Stanley;
 526       TBMT Tbilisi;
 527       TMT Tallinn, Tehran;
 528       WMT Warsaw.</small>
 529     </p>
 530
 531     <p>
 532     <small>A few abbreviations also follow the pattern that
 533     <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK.
 534     They are:
 535       BMT/BST for Bermuda 1890&ndash;1930,
 536       CMT/BST for Calamarca Mean Time and Bolivian Summer Time
 537         1890&ndash;1932,
 538       DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time
 539         1880&ndash;1916,
 540       MMT/MST/MDST for Moscow 1880&ndash;1919, and
 541       RMT/LST for Riga Mean Time and Latvian Summer time 1880&ndash;1926.
 542     </small>
 543     </p>
 544   </li>
 545   <li>
 546     Use '<abbr>LMT</abbr>' for local mean time of locations before the
 547     introduction of standard time; see "<a href="#scope">Scope of the
 548     <code><abbr>tz</abbr></code> database</a>".
 549   </li>
 550   <li>
 551     If there is no common English abbreviation, use numeric offsets like
 552     <code>-</code>05 and <code>+</code>0530 that are generated
 553     by <code>zic</code>'s <code>%z</code> notation.
 554   </li>
 555   <li>
 556     Use current abbreviations for older timestamps to avoid confusion.
 557     For example, in 1910 a common English abbreviation for time
 558     in central Europe was 'MEZ' (short for both "Middle European
 559     Zone" and for "Mitteleuropäische Zeit" in German).
 560     Nowadays 'CET' ("Central European Time") is more common in
 561     English, and the database uses 'CET' even for circa-1910
 562     timestamps as this is less confusing for modern users and avoids
 563     the need for determining when 'CET' supplanted 'MEZ' in common
 564     usage.
 565   </li>
 566   <li>
 567     Use a consistent style in a timezone's history.
 568     For example, if a history tends to use numeric
 569     abbreviations and a particular entry could go either way, use a
 570     numeric abbreviation.
 571   </li>
 572   <li>
 573     Use
 574     <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a>
 575     (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
 576     locations while uninhabited.
 577     The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
 578     some sense undefined; this notation is derived
 579     from <a href="https://datatracker.ietf.org/doc/html/rfc3339">Internet
 580     <abbr title="Request For Comments">RFC</abbr> 3339</a>.
 581   </li>
 582 </ul>
 583
 584 <p>
 585 Application writers should note that these abbreviations are ambiguous
 586 in practice: e.g., 'CST' means one thing in China and something else
 587 in North America, and 'IST' can refer to time in India, Ireland or
 588 Israel.
 589 To avoid ambiguity, use numeric <abbr>UT</abbr> offsets like
 590 '<code>-</code>0600' instead of time zone abbreviations like 'CST'.
 591 </p>
 592 </section>
 593
 594 <section>
 595   <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
 596 <p>
 597 The <code><abbr>tz</abbr></code> database is not authoritative, and it
 598 surely has errors.
 599 Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
 600 Users requiring authoritative data should consult national standards
 601 bodies and the references cited in the database's comments.
 602 </p>
 603
 604 <p>
 605 Errors in the <code><abbr>tz</abbr></code> database arise from many sources:
 606 </p>
 607
 608 <ul>
 609   <li>
 610     The <code><abbr>tz</abbr></code> database predicts future
 611     timestamps, and current predictions
 612     will be incorrect after future governments change the rules.
 613     For example, if today someone schedules a meeting for 13:00 next
 614     October 1, Casablanca time, and tomorrow Morocco changes its
 615     daylight saving rules, software can mess up after the rule change
 616     if it blithely relies on conversions made before the change.
 617   </li>
 618   <li>
 619     The pre-1970 entries in this database cover only a tiny sliver of how
 620     clocks actually behaved; the vast majority of the necessary
 621     information was lost or never recorded.
 622     Thousands more timezones would be needed if
 623     the <code><abbr>tz</abbr></code> database's scope were extended to
 624     cover even just the known or guessed history of standard time; for
 625     example, the current single entry for France would need to split
 626     into dozens of entries, perhaps hundreds.
 627     And in most of the world even this approach would be misleading
 628     due to widespread disagreement or indifference about what times
 629     should be observed.
 630     In her 2015 book
 631     <cite><a
 632     href="https://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The
 633     Global Transformation of Time, 1870&ndash;1950</a></cite>,
 634     Vanessa Ogle writes
 635     "Outside of Europe and North America there was no system of time
 636     zones at all, often not even a stable landscape of mean times,
 637     prior to the middle decades of the twentieth century".
 638     See: Timothy Shenk, <a
 639 href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked:
 640       A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17.
 641   </li>
 642   <li>
 643     Most of the pre-1970 data entries come from unreliable sources, often
 644     astrology books that lack citations and whose compilers evidently
 645     invented entries when the true facts were unknown, without
 646     reporting which entries were known and which were invented.
 647     These books often contradict each other or give implausible entries,
 648     and on the rare occasions when they are checked they are
 649     typically found to be incorrect.
 650   </li>
 651   <li>
 652     For the UK the <code><abbr>tz</abbr></code> database relies on
 653     years of first-class work done by
 654     Joseph Myers and others; see
 655     "<a href="https://www.polyomino.org.uk/british-time/">History of
 656     legal time in Britain</a>".
 657     Other countries are not done nearly as well.
 658   </li>
 659   <li>
 660     Sometimes, different people in the same city maintain clocks
 661     that differ significantly.
 662     Historically, railway time was used by railroad companies (which
 663     did not always
 664     agree with each other), church-clock time was used for birth
 665     certificates, etc.
 666     More recently, competing political groups might disagree about
 667     clock settings. Often this is merely common practice, but
 668     sometimes it is set by law.
 669     For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France
 670     was legally <abbr>UT</abbr> +00:09:21 outside train stations and
 671     <abbr>UT</abbr> +00:04:21 inside. Other examples include
 672     Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and
 673     Ürümqi to this day.
 674   </li>
 675   <li>
 676     Although a named location in the <code><abbr>tz</abbr></code>
 677     database stands for the containing region, its pre-1970 data
 678     entries are often accurate for only a small subset of that region.
 679     For example, <code>Europe/London</code> stands for the United
 680     Kingdom, but its pre-1847 times are valid only for locations that
 681     have London's exact meridian, and its 1847 transition
 682     to <abbr>GMT</abbr> is known to be valid only for the L&amp;NW and
 683     the Caledonian railways.
 684   </li>
 685   <li>
 686     The <code><abbr>tz</abbr></code> database does not record the
 687     earliest time for which a timezone's
 688     data entries are thereafter valid for every location in the region.
 689     For example, <code>Europe/London</code> is valid for all locations
 690     in its region after <abbr>GMT</abbr> was made the standard time,
 691     but the date of standardization (1880-08-02) is not in the
 692     <code><abbr>tz</abbr></code> database, other than in commentary.
 693     For many timezones the earliest time of
 694     validity is unknown.
 695   </li>
 696   <li>
 697     The <code><abbr>tz</abbr></code> database does not record a
 698     region's boundaries, and in many cases the boundaries are not known.
 699     For example, the timezone
 700     <code>America/Kentucky/Louisville</code> represents a region
 701     around the city of Louisville, the boundaries of which are
 702     unclear.
 703   </li>
 704   <li>
 705     Changes that are modeled as instantaneous transitions in the
 706     <code><abbr>tz</abbr></code>
 707     database were often spread out over hours, days, or even decades.
 708   </li>
 709   <li>
 710     Even if the time is specified by law, locations sometimes
 711     deliberately flout the law.
 712   </li>
 713   <li>
 714     Early timekeeping practices, even assuming perfect clocks, were
 715     often not specified to the accuracy that the
 716     <code><abbr>tz</abbr></code> database requires.
 717   </li>
 718   <li>
 719     The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
 720     However, on 1911-03-11 at 00:00, some public-facing French clocks
 721     were changed by stopping them for a few minutes to effect a transition.
 722     The <code><abbr>tz</abbr></code> database models this via a
 723     backward transition; the relevant French legislation does not
 724     specify exactly how the transition was to occur.
 725   </li>
 726   <li>
 727     Sometimes historical timekeeping was specified more precisely
 728     than what the <code><abbr>tz</abbr></code> code can handle.
 729     For example, from 1880 to 1916 clocks in Ireland observed Dublin Mean
 730     Time (estimated to be <abbr>UT</abbr>
 731     &minus;00:25:21.1); although the <code><abbr>tz</abbr></code>
 732     source data can represent the .1 second, TZif files and the code cannot.
 733     In practice these old specifications were rarely if ever
 734     implemented to subsecond precision.
 735   </li>
 736   <li>
 737     Even when all the timestamp transitions recorded by the
 738     <code><abbr>tz</abbr></code> database are correct, the
 739     <code><abbr>tz</abbr></code> rules that generate them may not
 740     faithfully reflect the historical rules.
 741     For example, from 1922 until World War II the UK moved clocks
 742     forward the day following the third Saturday in April unless that
 743     was Easter, in which case it moved clocks forward the previous
 744     Sunday.
 745     Because the <code><abbr>tz</abbr></code> database has no
 746     way to specify Easter, these exceptional years are entered as
 747     separate <code><abbr>tz</abbr> Rule</code> lines, even though the
 748     legal rules did not change.
 749     When transitions are known but the historical rules behind them are not,
 750     the database contains <code>Zone</code> and <code>Rule</code>
 751     entries that are intended to represent only the generated
 752     transitions, not any underlying historical rules; however, this
 753     intent is recorded at best only in commentary.
 754   </li>
 755   <li>
 756     The <code><abbr>tz</abbr></code> database models time
 757     using the <a
 758     href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic
 759     Gregorian calendar</a> with days containing 24 equal-length hours
 760     numbered 00 through 23, except when clock transitions occur.
 761     Pre-standard time is modeled as local mean time.
 762     However, historically many people used other calendars and other timescales.
 763     For example, the Roman Empire used
 764     the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian
 765     calendar</a>,
 766     and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman
 767     timekeeping</a> had twelve varying-length daytime hours with a
 768     non-hour-based system at night.
 769     And even today, some local practices diverge from the Gregorian
 770     calendar with 24-hour days. These divergences range from
 771     relatively minor, such as Japanese bars giving times like "24:30" for the
 772     wee hours of the morning, to more-significant differences such as <a
 773     href="https://theworld.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the
 774     east African practice of starting the day at dawn</a>, renumbering
 775     the Western 06:00 to be 12:00. These practices are largely outside
 776     the scope of the <code><abbr>tz</abbr></code> code and data, which
 777     provide only limited support for date and time localization
 778     such as that required by POSIX.1-2017.
 779     If <abbr>DST</abbr> is not used a different time zone
 780     can often do the trick; for example, in Kenya a <code>TZ</code> setting
 781     like <code>&lt;-03&gt;3</code> or <code>America/Cayenne</code> starts
 782     the day six hours later than <code>Africa/Nairobi</code> does.
 783   </li>
 784   <li>
 785     Early clocks were less reliable, and data entries do not represent
 786     clock error.
 787   </li>
 788   <li>
 789     The <code><abbr>tz</abbr></code> database assumes Universal Time
 790     (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not
 791     standardized for older timestamps.
 792     In the <code><abbr>tz</abbr></code> database commentary,
 793     <abbr>UT</abbr> denotes a family of time standards that includes
 794     Coordinated Universal Time (<abbr>UTC</abbr>) along with other
 795     variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>,
 796     with days starting at midnight.
 797     Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern
 798     timestamps, <abbr>UTC</abbr> was not defined until 1960, so
 799     commentary uses the more general abbreviation <abbr>UT</abbr> for
 800     timestamps that might predate 1960.
 801     Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly,
 802     and since pre-1972 <abbr>UTC</abbr> seconds varied in length,
 803     interpretation of older timestamps can be problematic when
 804     subsecond accuracy is needed.
 805   </li>
 806   <li>
 807     Civil time was not based on atomic time before 1972, and we do not
 808     know the history of
 809     <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's
 810     rotation</a> accurately enough to map <a
 811     href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr
 812     title="International System of Units">SI</abbr></a> seconds to
 813     historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a>
 814     to more than about one-hour accuracy.
 815     See: Stephenson FR, Morrison LV, Hohenkerk CY.
 816     <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of
 817     the Earth's rotation: 720 BC to AD 2015</a>.
 818     <cite>Proc Royal Soc A</cite>. 2016;472:20160404.
 819     Also see: Espenak F. <a
 820     href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty
 821     in Delta T (ΔT)</a>.
 822   </li>
 823   <li>
 824     The relationship between POSIX time (that is, <abbr>UTC</abbr> but
 825     ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap
 826     seconds</a>) and <abbr>UTC</abbr> is not agreed upon.
 827     This affects time stamps during the leap second era (1972&ndash;2035).
 828     Although the POSIX
 829     clock officially stops during an inserted leap second, at least one
 830     proposed standard has it jumping back a second instead; and in
 831     practice POSIX clocks more typically either progress glacially during
 832     a leap second, or are slightly slowed while near a leap second.
 833   </li>
 834   <li>
 835     The <code><abbr>tz</abbr></code> database does not represent how
 836     uncertain its information is.
 837     Ideally it would contain information about when data entries are
 838     incomplete or dicey.
 839     Partial temporal knowledge is a field of active research, though,
 840     and it is not clear how to apply it here.
 841   </li>
 842 </ul>
 843
 844 <p>
 845 In short, many, perhaps most, of the <code><abbr>tz</abbr></code>
 846 database's pre-1970 and future timestamps are either wrong or
 847 misleading.
 848 Any attempt to pass the
 849 <code><abbr>tz</abbr></code> database off as the definition of time
 850 should be unacceptable to anybody who cares about the facts.
 851 In particular, the <code><abbr>tz</abbr></code> database's
 852 <abbr>LMT</abbr> offsets should not be considered meaningful, and
 853 should not prompt creation of timezones
 854 merely because two locations
 855 differ in <abbr>LMT</abbr> or transitioned to standard time at
 856 different dates.
 857 </p>
 858 </section>
 859
 860 <section>
 861   <h2 id="functions">Time and date functions</h2>
 862 <p>
 863 The <code><abbr>tz</abbr></code> code contains time and date functions
 864 that are upwards compatible with those of POSIX.
 865 Code compatible with this package is already
 866 <a href="tz-link.html#tzdb">part of many platforms</a>, where the
 867 primary use of this package is to update obsolete time-related files.
 868 To do this, you may need to compile the time zone compiler
 869 '<code>zic</code>' supplied with this package instead of using the
 870 system '<code>zic</code>', since the format of <code>zic</code>'s
 871 input is occasionally extended, and a platform may still be shipping
 872 an older <code>zic</code>.
 873 </p>
 874
 875 <h3 id="POSIX">POSIX.1-2017 properties and limitations</h3>
 876 <ul>
 877   <li>
 878     <p>
 879     In POSIX.1-2017, time display in a process is controlled by the
 880     environment variable <code>TZ</code>.
 881     Unfortunately, the POSIX.1-2017
 882     <code>TZ</code> string takes a form that is hard to describe and
 883     is error-prone in practice.
 884     Also, POSIX.1-2017 <code>TZ</code> strings cannot deal with daylight
 885     saving time rules not based on the Gregorian calendar (as in
 886     Morocco), or with situations where more than two time zone
 887     abbreviations or <abbr>UT</abbr> offsets are used in an area.
 888     </p>
 889
 890     <p>
 891     The POSIX.1-2017 <code>TZ</code> string takes the following form:
 892     </p>
 893
 894     <p>
 895     <var>stdoffset</var>[<var>dst</var>[<var>offset</var>][<code>,</code><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]]]
 896     </p>
 897
 898     <p>
 899     where:
 900     </p>
 901
 902     <dl>
 903       <dt><var>std</var> and <var>dst</var></dt><dd>
 904         are 3 or more characters specifying the standard
 905         and daylight saving time (<abbr>DST</abbr>) zone abbreviations.
 906         Starting with POSIX.1-2001, <var>std</var> and <var>dst</var>
 907         may also be in a quoted form like '<code>&lt;+09&gt;</code>';
 908         this allows "<code>+</code>" and "<code>-</code>" in the names.
 909       </dd>
 910       <dt><var>offset</var></dt><dd>
 911         is of the form
 912         '<code>[&plusmn;]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>'
 913         and specifies the offset west of <abbr>UT</abbr>.
 914         '<var>hh</var>' may be a single digit;
 915         0&le;<var>hh</var>&le;24.
 916         The default <abbr>DST</abbr> offset is one hour ahead of
 917         standard time.
 918       </dd>
 919       <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
 920         specifies the beginning and end of <abbr>DST</abbr>.
 921         If this is absent, the system supplies its own ruleset
 922         for <abbr>DST</abbr>, typically current <abbr>US</abbr>
 923         <abbr>DST</abbr> rules.
 924       </dd>
 925       <dt><var>time</var></dt><dd>
 926         takes the form
 927         '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
 928         and defaults to 02:00.
 929         This is the same format as the offset, except that a
 930         leading '<code>+</code>' or '<code>-</code>' is not allowed.
 931       </dd>
 932       <dt><var>date</var></dt><dd>
 933         takes one of the following forms:
 934         <dl>
 935           <dt>J<var>n</var> (1&le;<var>n</var>&le;365)</dt><dd>
 936             origin-1 day number not counting February 29
 937           </dd>
 938           <dt><var>n</var> (0&le;<var>n</var>&le;365)</dt><dd>
 939             origin-0 day number counting February 29 if present
 940           </dd>
 941           <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
 942             (0[Sunday]&le;<var>d</var>&le;6[Saturday], 1&le;<var>n</var>&le;5,
 943             1&le;<var>m</var>&le;12)</dt><dd>
 944             for the <var>d</var>th day of week <var>n</var> of
 945             month <var>m</var> of the year, where week 1 is the first
 946             week in which day <var>d</var> appears, and
 947             '<code>5</code>' stands for the last week in which
 948             day <var>d</var> appears (which may be either the 4th or
 949             5th week).
 950             Typically, this is the only useful form; the <var>n</var>
 951             and <code>J</code><var>n</var> forms are rarely used.
 952           </dd>
 953         </dl>
 954       </dd>
 955     </dl>
 956
 957     <p>
 958     Here is an example POSIX.1-2017 <code>TZ</code> string for New
 959     Zealand after 2007.
 960     It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead
 961     of <abbr>UT</abbr>, and that daylight saving time
 962     (<abbr>NZDT</abbr>) is observed from September's last Sunday at
 963     02:00 until April's first Sunday at 03:00:
 964     </p>
 965
 966     <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
 967
 968     <p>
 969     This POSIX.1-2017 <code>TZ</code> string is hard to remember, and
 970     mishandles some timestamps before 2008.
 971     With this package you can use this instead:
 972     </p>
 973
 974     <pre><code>TZ='Pacific/Auckland'</code></pre>
 975   </li>
 976   <li>
 977     POSIX does not define the <abbr>DST</abbr> transitions
 978     for <code>TZ</code> values like
 979     "<code>EST5EDT</code>".
 980     Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
 981     were used to interpret such values, but this meant that the
 982     <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
 983     time conversion package, and when
 984     <abbr>US</abbr> time conversion rules changed (as in the United
 985     States in 1987 and again in 2007), all packages that
 986     interpreted <code>TZ</code> values had to be updated
 987     to ensure proper results.
 988   </li>
 989   <li>
 990     The <code>TZ</code> environment variable is process-global, which
 991     makes it hard to write efficient, thread-safe applications that
 992     need access to multiple timezones.
 993   </li>
 994   <li>
 995     In POSIX, there is no tamper-proof way for a process to learn the
 996     system's best idea of local (wall clock) time.
 997     This is important for applications that an administrator wants
 998     used only at certain times &ndash; without regard to whether the
 999     user has fiddled the
1000     <code>TZ</code> environment variable.
1001     While an administrator can "do everything in <abbr>UT</abbr>" to
1002     get around the problem, doing so is inconvenient and precludes
1003     handling daylight saving time shifts &ndash; as might be required to
1004     limit phone calls to off-peak hours.
1005   </li>
1006   <li>
1007     POSIX.1-2017 provides no convenient and efficient way to determine
1008     the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary
1009     timestamps, particularly for timezones
1010     that do not fit into the POSIX model.
1011   </li>
1012   <li>
1013     POSIX requires that <code>time_t</code> clock counts exclude leap
1014     seconds.
1015   </li>
1016   <li>
1017     The <code><abbr>tz</abbr></code> code attempts to support all the
1018     <code>time_t</code> implementations allowed by POSIX.
1019     The <code>time_t</code> type represents a nonnegative count of seconds
1020     since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds.
1021     In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1022     integer; 32-bit signed <code>time_t</code> values stop working after
1023     2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these
1024     days typically use a signed 64-bit integer.
1025     Unsigned 32-bit integers are used on one or two platforms, and 36-bit
1026     and 40-bit integers are also used occasionally.
1027     Although earlier POSIX versions allowed <code>time_t</code> to be a
1028     floating-point type, this was not supported by any practical system,
1029     and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both
1030     require <code>time_t</code> to be an integer type.
1031   </li>
1032 </ul>
1033
1034 <h3 id="POSIX-extensions">Extensions to POSIX.1-2017 in the
1035 <code><abbr>tz</abbr></code> code</h3>
1036 <ul>
1037   <li>
1038     <p>
1039     The <code>TZ</code> environment variable is used in generating
1040     the name of a file from which time-related information is read
1041     (or is interpreted à la POSIX.1-2017); <code>TZ</code> is no longer
1042     constrained to be a string containing abbreviations
1043     and numeric data as described <a href="#POSIX">above</a>.
1044     The file's format is <dfn><abbr>TZif</abbr></dfn>,
1045     a timezone information format that contains binary data; see
1046     <a href="https://datatracker.ietf.org/doc/html/8536">Internet
1047     <abbr>RFC</abbr> 8536</a>.
1048     The daylight saving time rules to be used for a
1049     particular timezone are encoded in the
1050     <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
1051     Australian, and other rules to be encoded, and
1052     allows for situations where more than two time zone
1053     abbreviations are used.
1054     </p>
1055     <p>
1056     It was recognized that allowing the <code>TZ</code> environment
1057     variable to take on values such as '<code>America/New_York</code>'
1058     might cause "old" programs (that expect <code>TZ</code> to have a
1059     certain form) to operate incorrectly; consideration was given to using
1060     some other environment variable (for example, <code>TIMEZONE</code>)
1061     to hold the string used to generate the <abbr>TZif</abbr> file's name.
1062     In the end, however, it was decided to continue using
1063     <code>TZ</code>: it is widely used for time zone purposes;
1064     separately maintaining both <code>TZ</code>
1065     and <code>TIMEZONE</code> seemed a nuisance; and systems where
1066     "new" forms of <code>TZ</code> might cause problems can simply
1067     use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1068     can be used by "new" programs as well as by "old" programs that
1069     assume pre-POSIX <code>TZ</code> values.
1070     </p>
1071   </li>
1072   <li>
1073     The code supports platforms with a <abbr>UT</abbr> offset member
1074     in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>,
1075     or with a time zone abbreviation member in
1076     <code>struct tm</code>, e.g., <code>tm_zone</code>. As noted
1077     in <a href="https://austingroupbugs.net/view.php?id=1533">Austin
1078     Group defect 1533</a>, a future version of POSIX is planned to
1079     require <code>tm_gmtoff</code> and <code>tm_zone</code>.
1080   </li>
1081   <li>
1082     Functions <code>tzalloc</code>, <code>tzfree</code>,
1083     <code>localtime_rz</code>, and <code>mktime_z</code> for
1084     more-efficient thread-safe applications that need to use multiple
1085     timezones.
1086     The <code>tzalloc</code> and <code>tzfree</code> functions
1087     allocate and free objects of type <code>timezone_t</code>,
1088     and <code>localtime_rz</code> and <code>mktime_z</code> are
1089     like <code>localtime_r</code> and <code>mktime</code> with an
1090     extra <code>timezone_t</code> argument.
1091     The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>.
1092   </li>
1093   <li>
1094     Negative <code>time_t</code> values are supported, on systems
1095     where <code>time_t</code> is signed.
1096   </li>
1097   <li>
1098     These functions can account for leap seconds;
1099     see <a href="#leapsec">Leap seconds</a> below.
1100   </li>
1101 </ul>
1102
1103 <h3 id="vestigial">POSIX features no longer needed</h3>
1104 <p>
1105 POSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a>
1106 define some <a href="https://en.wikipedia.org/wiki/API"><abbr
1107 title="application programming interface">API</abbr>s</a> that are vestigial:
1108 they are not needed, and are relics of a too-simple model that does
1109 not suffice to handle many real-world timestamps.
1110 Although the <code><abbr>tz</abbr></code> code supports these
1111 vestigial <abbr>API</abbr>s for backwards compatibility, they should
1112 be avoided in portable applications.
1113 The vestigial <abbr>API</abbr>s are:
1114 </p>
1115 <ul>
1116   <li>
1117     The POSIX <code>tzname</code> variable does not suffice and is no
1118     longer needed.
1119     To get a timestamp's time zone abbreviation, consult
1120     the <code>tm_zone</code> member if available; otherwise,
1121     use <code>strftime</code>'s <code>"%Z"</code> conversion
1122     specification.
1123   </li>
1124   <li>
1125     The POSIX <code>daylight</code> and <code>timezone</code>
1126     variables do not suffice and are no longer needed.
1127     To get a timestamp's <abbr>UT</abbr> offset, consult
1128     the <code>tm_gmtoff</code> member if available; otherwise,
1129     subtract values returned by <code>localtime</code>
1130     and <code>gmtime</code> using the rules of the Gregorian calendar,
1131     or use <code>strftime</code>'s <code>"%z"</code> conversion
1132     specification if a string like <code>"+0900"</code> suffices.
1133   </li>
1134   <li>
1135     The <code>tm_isdst</code> member is almost never needed and most of
1136     its uses should be discouraged in favor of the abovementioned
1137     <abbr>API</abbr>s.
1138     Although it can still be used in arguments to
1139     <code>mktime</code> to disambiguate timestamps near
1140     a <abbr>DST</abbr> transition when the clock jumps back on
1141     platforms lacking <code>tm_gmtoff</code>, this
1142     disambiguation does not work when standard time itself jumps back,
1143     which can occur when a location changes to a time zone with a
1144     lesser <abbr>UT</abbr> offset.
1145   </li>
1146 </ul>
1147
1148 <h3 id="other-portability">Other portability notes</h3>
1149 <ul>
1150   <li>
1151     The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition
1152     UNIX</a> <code>timezone</code> function is not present in this
1153     package; it is impossible to reliably map <code>timezone</code>'s
1154     arguments (a "minutes west of <abbr>GMT</abbr>" value and a
1155     "daylight saving time in effect" flag) to a time zone
1156     abbreviation, and we refuse to guess.
1157     Programs that in the past used the <code>timezone</code> function
1158     may now examine <code>localtime(&amp;clock)-&gt;tm_zone</code>
1159     (if <code>TM_ZONE</code> is defined) or
1160     <code>tzname[localtime(&amp;clock)-&gt;tm_isdst]</code>
1161     (if <code>HAVE_TZNAME</code> is nonzero) to learn the correct time
1162     zone abbreviation to use.
1163   </li>
1164   <li>
1165     The <a
1166     href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a>
1167     <code>gettimeofday</code> function is not
1168     used in this package.
1169     This formerly let users obtain the current <abbr>UTC</abbr> offset
1170     and <abbr>DST</abbr> flag, but this functionality was removed in
1171     later versions of <abbr>BSD</abbr>.
1172   </li>
1173   <li>
1174     In <abbr>SVR2</abbr>, time conversion fails for near-minimum or
1175     near-maximum <code>time_t</code> values when doing conversions
1176     for places that do not use <abbr>UT</abbr>.
1177     This package takes care to do these conversions correctly.
1178     A comment in the source code tells how to get compatibly wrong
1179     results.
1180   </li>
1181   <li>
1182     The functions that are conditionally compiled
1183     if <code>STD_INSPIRED</code> is nonzero should, at this point, be
1184     looked on primarily as food for thought.
1185     They are not in any sense "standard compatible" &ndash; some are
1186     not, in fact, specified in <em>any</em> standard.
1187     They do, however, represent responses of various authors to
1188     standardization proposals.
1189   </li>
1190   <li>
1191     Other time conversion proposals, in particular those supported by the
1192     <a href="https://howardhinnant.github.io/date/tz.html">Time Zone
1193     Database Parser</a>, offer a wider selection of functions
1194     that provide capabilities beyond those provided here.
1195     The absence of such functions from this package is not meant to
1196     discourage the development, standardization, or use of such
1197     functions.
1198     Rather, their absence reflects the decision to make this package
1199     contain valid extensions to POSIX, to ensure its broad
1200     acceptability.
1201     If more powerful time conversion functions can be standardized, so
1202     much the better.
1203   </li>
1204 </ul>
1205 </section>
1206
1207 <section>
1208   <h2 id="stability">Interface stability</h2>
1209 <p>
1210 The <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1211 </p>
1212
1213 <ul>
1214   <li>
1215     A set of timezone names as per
1216       "<a href="#naming">Timezone identifiers</a>" above.
1217   </li>
1218   <li>
1219     Library functions described in "<a href="#functions">Time and date
1220       functions</a>" above.
1221   </li>
1222   <li>
1223     The programs <code>tzselect</code>, <code>zdump</code>,
1224     and <code>zic</code>, documented in their man pages.
1225   </li>
1226   <li>
1227     The format of <code>zic</code> input files, documented in
1228     the <code>zic</code> man page.
1229   </li>
1230   <li>
1231     The format of <code>zic</code> output files, documented in
1232     the <code>tzfile</code> man page.
1233   </li>
1234   <li>
1235     The format of zone table files, documented in <code>zone1970.tab</code>.
1236   </li>
1237   <li>
1238     The format of the country code file, documented in <code>iso3166.tab</code>.
1239   </li>
1240   <li>
1241     The version number of the code and data, as the first line of
1242     the text file '<code>version</code>' in each release.
1243   </li>
1244 </ul>
1245
1246 <p>
1247 Interface changes in a release attempt to preserve compatibility with
1248 recent releases.
1249 For example, <code><abbr>tz</abbr></code> data files typically do not
1250 rely on recently added <code>zic</code> features, so that users can
1251 run older <code>zic</code> versions to process newer data files.
1252 <a href="tz-link.html#download">Downloading
1253 the <code><abbr>tz</abbr></code> database</a> describes how releases
1254 are tagged and distributed.
1255 </p>
1256
1257 <p>
1258 Interfaces not listed above are less stable.
1259 For example, users should not rely on particular <abbr>UT</abbr>
1260 offsets or abbreviations for timestamps, as data entries are often
1261 based on guesswork and these guesses may be corrected or improved.
1262 </p>
1263
1264 <p>
1265 Timezone boundaries are not part of the stable interface.
1266 For example, even though the <samp>Asia/Bangkok</samp> timezone
1267 currently includes Chang Mai, Hanoi, and Phnom Penh, this is not part
1268 of the stable interface and the timezone can split at any time.
1269 If a calendar application records a future event in some location other
1270 than Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record,
1271 the application should be robust in the presence of timezone splits
1272 between now and the future time.
1273 </p>
1274 </section>
1275
1276 <section>
1277   <h2 id="leapsec">Leap seconds</h2>
1278 <p>
1279 Leap seconds were introduced in 1972 to accommodate the
1280 difference between atomic time and the less regular rotation of the earth.
1281 Unfortunately they caused so many problems with civil
1282 timekeeping that they
1283 are <a href="https://www.bipm.org/en/cgpm-2022/resolution-4">planned
1284 to be discontinued by 2035</a>, with some as-yet-undetermined
1285 mechanism replacing them, perhaps after the year 2135.
1286 Despite their impending obsolescence, a record of leap seconds is still
1287 needed to resolve timestamps from 1972 through 2035.
1288 </p>
1289
1290 <p>
1291 The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1292 thanks to code contributed by Bradley White.
1293 However, the leap second support of this package is rarely used directly
1294 because POSIX requires leap seconds to be excluded and many
1295 software packages would mishandle leap seconds if they were present.
1296 Instead, leap seconds are more commonly handled by occasionally adjusting
1297 the operating system kernel clock as described in
1298 <a href="tz-link.html#precision">Precision timekeeping</a>,
1299 and this package by default installs a <samp>leapseconds</samp> file
1300 commonly used by
1301 <a href="https://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a>
1302 software that adjusts the kernel clock.
1303 However, kernel-clock twiddling approximates UTC only roughly,
1304 and systems needing more precise UTC can use this package's leap
1305 second support directly.
1306 </p>
1307
1308 <p>
1309 The directly supported mechanism assumes that <code>time_t</code>
1310 counts of seconds since the POSIX epoch normally include leap seconds,
1311 as opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1312 This modified timescale is converted to <abbr>UTC</abbr>
1313 at the same point that time zone and <abbr>DST</abbr>
1314 adjustments are applied &ndash;
1315 namely, at calls to <code>localtime</code> and analogous functions &ndash;
1316 and the process is driven by leap second information
1317 stored in alternate versions of the <abbr>TZif</abbr> files.
1318 Because a leap second adjustment may be needed even
1319 if no time zone correction is desired,
1320 calls to <code>gmtime</code>-like functions
1321 also need to consult a <abbr>TZif</abbr> file,
1322 conventionally named <samp><abbr>Etc/UTC</abbr></samp>
1323 (<samp><abbr>GMT</abbr></samp> in previous versions),
1324 to see whether leap second corrections are needed.
1325 To convert an application's <code>time_t</code> timestamps to or from
1326 POSIX <code>time_t</code> timestamps (for use when, say,
1327 embedding or interpreting timestamps in portable
1328 <a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1329 files),
1330 the application can call the utility functions
1331 <code>time2posix</code> and <code>posix2time</code>
1332 included with this package.
1333 </p>
1334
1335 <p>
1336 If the POSIX-compatible <abbr>TZif</abbr> file set is installed
1337 in a directory whose basename is <samp>zoneinfo</samp>, the
1338 leap-second-aware file set is by default installed in a separate
1339 directory <samp>zoneinfo-leaps</samp>.
1340 Although each process can have its own time zone by setting
1341 its <code>TZ</code> environment variable, there is no support for some
1342 processes being leap-second aware while other processes are
1343 POSIX-compatible; the leap-second choice is system-wide.
1344 So if you configure your kernel to count leap seconds, you should also
1345 discard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp>
1346 to <samp>zoneinfo</samp>.
1347 Alternatively, you can install just one set of <abbr>TZif</abbr> files
1348 in the first place; see the <code>REDO</code> variable in this package's
1349 <a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>.
1350 </p>
1351 </section>
1352
1353 <section>
1354   <h2 id="calendar">Calendrical issues</h2>
1355 <p>
1356 Calendrical issues are a bit out of scope for a time zone database,
1357 but they indicate the sort of problems that we would run into if we
1358 extended the time zone database further into the past.
1359 An excellent resource in this area is Edward M. Reingold
1360 and Nachum Dershowitz, <cite><a
1361 href="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical
1362 Calculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018).
1363 Other information and sources are given in the file '<code>calendars</code>'
1364 in the <code><abbr>tz</abbr></code> distribution.
1365 They sometimes disagree.
1366 </p>
1367 </section>
1368
1369 <section>
1370   <h2 id="planets">Time and time zones off Earth</h2>
1371 <p>
1372 The European Space Agency is <a
1373 href='https://www.esa.int/Applications/Navigation/Telling_time_on_the_Moon'>considering</a>
1374 the establishment of a reference timescale for the Moon, which has
1375 days roughly equivalent to 29.5 Earth days, and where relativistic
1376 effects cause clocks to tick slightly faster than on Earth.
1377 </p>
1378
1379 <p>
1380 Some people's work schedules have used
1381 <a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>.
1382 Jet Propulsion Laboratory (JPL) coordinators kept Mars time on
1383 and off during the
1384 <a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars
1385 Pathfinder</a> mission (1997).
1386 Some of their family members also adapted to Mars time.
1387 Dozens of special Mars watches were built for JPL workers who kept
1388 Mars time during the
1389 <a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars
1390 Exploration Rovers (MER)</a> mission (2004&ndash;2018).
1391 These timepieces looked like normal Seikos and Citizens but were adjusted
1392 to use Mars seconds rather than terrestrial seconds, although
1393 unfortunately the adjusted watches were unreliable and appear to have
1394 had only limited use.
1395 </p>
1396
1397 <p>
1398 A Mars solar day is called a "sol" and has a mean period equal to
1399 about 24 hours 39 minutes 35.244 seconds in terrestrial time.
1400 It is divided into a conventional 24-hour clock, so each Mars second
1401 equals about 1.02749125 terrestrial seconds.
1402 (One MER worker noted, "If I am working Mars hours, and Mars hours are
1403 2.5% more than Earth hours, shouldn't I get an extra 2.5% pay raise?")
1404 </p>
1405
1406 <p>
1407 The <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime
1408 meridian</a> of Mars goes through the center of the crater
1409 <a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in
1410 honor of the British astronomer who built the Greenwich telescope that
1411 defines Earth's prime meridian.
1412 Mean solar time on the Mars prime meridian is
1413 called Mars Coordinated Time (<abbr>MTC</abbr>).
1414 </p>
1415
1416 <p>
1417 Each landed mission on Mars has adopted a different reference for
1418 solar timekeeping, so there is no real standard for Mars time zones.
1419 For example, the MER mission defined two time zones "Local
1420 Solar Time A" and "Local Solar Time B" for its two missions, each zone
1421 designed so that its time equals local true solar time at
1422 approximately the middle of the nominal mission.
1423 The A and B zones differ enough so that an MER worker assigned to
1424 the A zone might suffer "Mars lag" when switching to work in the B zone.
1425 Such a "time zone" is not particularly suited for any application
1426 other than the mission itself.
1427 </p>
1428
1429 <p>
1430 Many calendars have been proposed for Mars, but none have achieved
1431 wide acceptance.
1432 Astronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a
1433 sequential count of Mars solar days elapsed since about 1873-12-29
1434 12:00 <abbr>GMT</abbr>.
1435 </p>
1436
1437 <p>
1438 In our solar system, Mars is the planet with time and calendar most
1439 like Earth's.
1440 On other planets, Sun-based time and calendars would work quite
1441 differently.
1442 For example, although Mercury's
1443 <a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal
1444 rotation period</a> is 58.646 Earth days, Mercury revolves around the
1445 Sun so rapidly that an observer on Mercury's equator would see a
1446 sunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a
1447 Mercury day.
1448 Venus is more complicated, partly because its rotation is slightly
1449 <a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>:
1450 its year is 1.92 of its days.
1451 Gas giants like Jupiter are trickier still, as their polar and
1452 equatorial regions rotate at different rates, so that the length of a
1453 day depends on latitude.
1454 This effect is most pronounced on Neptune, where the day is about 12
1455 hours at the poles and 18 hours at the equator.
1456 </p>
1457
1458 <p>
1459 Although the <code><abbr>tz</abbr></code> database does not support
1460 time on other planets, it is documented here in the hopes that support
1461 will be added eventually.
1462 </p>
1463
1464 <p>
1465 Sources for time on other planets:
1466 </p>
1467
1468 <ul>
1469   <li>
1470     Michael Allison and Robert Schmunk,
1471     "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical
1472       Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>"
1473     (2020-03-08).
1474   </li>
1475   <li>
1476     Zara Mirmalek,
1477     <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making
1478         Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854.
1479   </li>
1480   <li>
1481     Jia-Rui Chong,
1482     "<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays
1483     Fit for a Martian</a>", <cite>Los Angeles Times</cite>
1484     (2004-01-14), pp A1, A20&ndash;A21.
1485   </li>
1486   <li>
1487     Tom Chmielewski,
1488     "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet
1489     Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26)
1490   </li>
1491   <li>
1492     Matt Williams,
1493     "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How
1494     long is a day on the other planets of the solar system?</a>"
1495     (2016-01-20).
1496   </li>
1497 </ul>
1498 </section>
1499
1500 <footer>
1501   <hr>
1502   This file is in the public domain, so clarified as of 2009-05-17 by
1503   Arthur David Olson.
1504 </footer>
1505 </body>
1506 </html>