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