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