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, Bern, Bogotá, Bridgetown, Brussels,
 478         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       CMT/BST for Calamarca Mean Time and Bolivian Summer Time
 510         1890&ndash;1932,
 511       DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time
 512         1880&ndash;1916,
 513       MMT/MST/MDST for Moscow 1880&ndash;1919, and
 514       RMT/LST for Riga Mean Time and Latvian Summer time 1880&ndash;1926.
 515     An extra-special case is SET for Swedish Time (<em>svensk
 516     normaltid</em>) 1879&ndash;1899, 3&deg; west of the Stockholm
 517     Observatory.</small>
 518     </p>
 519   </li>
 520   <li>
 521     Use '<abbr>LMT</abbr>' for local mean time of locations before the
 522     introduction of standard time; see "<a href="#scope">Scope of the
 523     <code><abbr>tz</abbr></code> database</a>".
 524   </li>
 525   <li>
 526     If there is no common English abbreviation, use numeric offsets like
 527     <code>-</code>05 and <code>+</code>0530 that are generated
 528     by <code>zic</code>'s <code>%z</code> notation.
 529   </li>
 530   <li>
 531     Use current abbreviations for older timestamps to avoid confusion.
 532     For example, in 1910 a common English abbreviation for time
 533     in central Europe was 'MEZ' (short for both "Middle European
 534     Zone" and for "Mitteleuropäische Zeit" in German).
 535     Nowadays 'CET' ("Central European Time") is more common in
 536     English, and the database uses 'CET' even for circa-1910
 537     timestamps as this is less confusing for modern users and avoids
 538     the need for determining when 'CET' supplanted 'MEZ' in common
 539     usage.
 540   </li>
 541   <li>
 542     Use a consistent style in a timezone's history.
 543     For example, if a history tends to use numeric
 544     abbreviations and a particular entry could go either way, use a
 545     numeric abbreviation.
 546   </li>
 547   <li>
 548     Use
 549     <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a>
 550     (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
 551     locations while uninhabited.
 552     The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
 553     some sense undefined; this notation is derived
 554     from <a href="https://tools.ietf.org/html/rfc3339">Internet
 555     <abbr title="Request For Comments">RFC</abbr> 3339</a>.
 556   </li>
 557 </ul>
 558
 559 <p>
 560 Application writers should note that these abbreviations are ambiguous
 561 in practice: e.g., 'CST' means one thing in China and something else
 562 in North America, and 'IST' can refer to time in India, Ireland or
 563 Israel.
 564 To avoid ambiguity, use numeric <abbr>UT</abbr> offsets like
 565 '<code>-</code>0600' instead of time zone abbreviations like 'CST'.
 566 </p>
 567 </section>
 568
 569 <section>
 570   <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
 571 <p>
 572 The <code><abbr>tz</abbr></code> database is not authoritative, and it
 573 surely has errors.
 574 Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
 575 Users requiring authoritative data should consult national standards
 576 bodies and the references cited in the database's comments.
 577 </p>
 578
 579 <p>
 580 Errors in the <code><abbr>tz</abbr></code> database arise from many sources:
 581 </p>
 582
 583 <ul>
 584   <li>
 585     The <code><abbr>tz</abbr></code> database predicts future
 586     timestamps, and current predictions
 587     will be incorrect after future governments change the rules.
 588     For example, if today someone schedules a meeting for 13:00 next
 589     October 1, Casablanca time, and tomorrow Morocco changes its
 590     daylight saving rules, software can mess up after the rule change
 591     if it blithely relies on conversions made before the change.
 592   </li>
 593   <li>
 594     The pre-1970 entries in this database cover only a tiny sliver of how
 595     clocks actually behaved; the vast majority of the necessary
 596     information was lost or never recorded.
 597     Thousands more timezones would be needed if
 598     the <code><abbr>tz</abbr></code> database's scope were extended to
 599     cover even just the known or guessed history of standard time; for
 600     example, the current single entry for France would need to split
 601     into dozens of entries, perhaps hundreds.
 602     And in most of the world even this approach would be misleading
 603     due to widespread disagreement or indifference about what times
 604     should be observed.
 605     In her 2015 book
 606     <cite><a
 607     href="http://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The
 608     Global Transformation of Time, 1870&ndash;1950</a></cite>,
 609     Vanessa Ogle writes
 610     "Outside of Europe and North America there was no system of time
 611     zones at all, often not even a stable landscape of mean times,
 612     prior to the middle decades of the twentieth century".
 613     See: Timothy Shenk, <a
 614 href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked:
 615       A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17.
 616   </li>
 617   <li>
 618     Most of the pre-1970 data entries come from unreliable sources, often
 619     astrology books that lack citations and whose compilers evidently
 620     invented entries when the true facts were unknown, without
 621     reporting which entries were known and which were invented.
 622     These books often contradict each other or give implausible entries,
 623     and on the rare occasions when they are checked they are
 624     typically found to be incorrect.
 625   </li>
 626   <li>
 627     For the UK the <code><abbr>tz</abbr></code> database relies on
 628     years of first-class work done by
 629     Joseph Myers and others; see
 630     "<a href="https://www.polyomino.org.uk/british-time/">History of
 631     legal time in Britain</a>".
 632     Other countries are not done nearly as well.
 633   </li>
 634   <li>
 635     Sometimes, different people in the same city maintain clocks
 636     that differ significantly.
 637     Historically, railway time was used by railroad companies (which
 638     did not always
 639     agree with each other), church-clock time was used for birth
 640     certificates, etc.
 641     More recently, competing political groups might disagree about
 642     clock settings. Often this is merely common practice, but
 643     sometimes it is set by law.
 644     For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France
 645     was legally <abbr>UT</abbr> +00:09:21 outside train stations and
 646     <abbr>UT</abbr> +00:04:21 inside. Other examples include
 647     Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and
 648     Ürümqi to this day.
 649   </li>
 650   <li>
 651     Although a named location in the <code><abbr>tz</abbr></code>
 652     database stands for the containing region, its pre-1970 data
 653     entries are often accurate for only a small subset of that region.
 654     For example, <code>Europe/London</code> stands for the United
 655     Kingdom, but its pre-1847 times are valid only for locations that
 656     have London's exact meridian, and its 1847 transition
 657     to <abbr>GMT</abbr> is known to be valid only for the L&amp;NW and
 658     the Caledonian railways.
 659   </li>
 660   <li>
 661     The <code><abbr>tz</abbr></code> database does not record the
 662     earliest time for which a timezone's
 663     data entries are thereafter valid for every location in the region.
 664     For example, <code>Europe/London</code> is valid for all locations
 665     in its region after <abbr>GMT</abbr> was made the standard time,
 666     but the date of standardization (1880-08-02) is not in the
 667     <code><abbr>tz</abbr></code> database, other than in commentary.
 668     For many timezones the earliest time of
 669     validity is unknown.
 670   </li>
 671   <li>
 672     The <code><abbr>tz</abbr></code> database does not record a
 673     region's boundaries, and in many cases the boundaries are not known.
 674     For example, the timezone
 675     <code>America/Kentucky/Louisville</code> represents a region
 676     around the city of Louisville, the boundaries of which are
 677     unclear.
 678   </li>
 679   <li>
 680     Changes that are modeled as instantaneous transitions in the
 681     <code><abbr>tz</abbr></code>
 682     database were often spread out over hours, days, or even decades.
 683   </li>
 684   <li>
 685     Even if the time is specified by law, locations sometimes
 686     deliberately flout the law.
 687   </li>
 688   <li>
 689     Early timekeeping practices, even assuming perfect clocks, were
 690     often not specified to the accuracy that the
 691     <code><abbr>tz</abbr></code> database requires.
 692   </li>
 693   <li>
 694     The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
 695     However, on 1911-03-11 at 00:00, some public-facing French clocks
 696     were changed by stopping them for a few minutes to effect a transition.
 697     The <code><abbr>tz</abbr></code> database models this via a
 698     backward transition; the relevant French legislation does not
 699     specify exactly how the transition was to occur.
 700   </li>
 701   <li>
 702     Sometimes historical timekeeping was specified more precisely
 703     than what the <code><abbr>tz</abbr></code> code can handle.
 704     For example, from 1909 to 1937 <a
 705     href="https://www.staff.science.uu.nl/~gent0113/wettijd/wettijd.htm"
 706     hreflang="nl">Netherlands clocks</a> were legally Amsterdam Mean
 707     Time (estimated to be <abbr>UT</abbr>
 708     +00:19:32.13), but the <code><abbr>tz</abbr></code>
 709     code cannot represent the fractional second.
 710     In practice these old specifications were rarely if ever
 711     implemented to subsecond precision.
 712   </li>
 713   <li>
 714     Even when all the timestamp transitions recorded by the
 715     <code><abbr>tz</abbr></code> database are correct, the
 716     <code><abbr>tz</abbr></code> rules that generate them may not
 717     faithfully reflect the historical rules.
 718     For example, from 1922 until World War II the UK moved clocks
 719     forward the day following the third Saturday in April unless that
 720     was Easter, in which case it moved clocks forward the previous
 721     Sunday.
 722     Because the <code><abbr>tz</abbr></code> database has no
 723     way to specify Easter, these exceptional years are entered as
 724     separate <code><abbr>tz</abbr> Rule</code> lines, even though the
 725     legal rules did not change.
 726     When transitions are known but the historical rules behind them are not,
 727     the database contains <code>Zone</code> and <code>Rule</code>
 728     entries that are intended to represent only the generated
 729     transitions, not any underlying historical rules; however, this
 730     intent is recorded at best only in commentary.
 731   </li>
 732   <li>
 733     The <code><abbr>tz</abbr></code> database models time
 734     using the <a
 735     href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic
 736     Gregorian calendar</a> with days containing 24 equal-length hours
 737     numbered 00 through 23, except when clock transitions occur.
 738     Pre-standard time is modeled as local mean time.
 739     However, historically many people used other calendars and other timescales.
 740     For example, the Roman Empire used
 741     the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian
 742     calendar</a>,
 743     and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman
 744     timekeeping</a> had twelve varying-length daytime hours with a
 745     non-hour-based system at night.
 746     And even today, some local practices diverge from the Gregorian
 747     calendar with 24-hour days. These divergences range from
 748     relatively minor, such as Japanese bars giving times like "24:30" for the
 749     wee hours of the morning, to more-significant differences such as <a
 750     href="https://www.pri.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the
 751     east African practice of starting the day at dawn</a>, renumbering
 752     the Western 06:00 to be 12:00. These practices are largely outside
 753     the scope of the <code><abbr>tz</abbr></code> code and data, which
 754     provide only limited support for date and time localization
 755     such as that required by POSIX. If DST is not used a different time zone
 756     can often do the trick; for example, in Kenya a <code>TZ</code> setting
 757     like <code>&lt;-03&gt;3</code> or <code>America/Cayenne</code> starts
 758     the day six hours later than <code>Africa/Nairobi</code> does.
 759   </li>
 760   <li>
 761     Early clocks were less reliable, and data entries do not represent
 762     clock error.
 763   </li>
 764   <li>
 765     The <code><abbr>tz</abbr></code> database assumes Universal Time
 766     (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not
 767     standardized for older timestamps.
 768     In the <code><abbr>tz</abbr></code> database commentary,
 769     <abbr>UT</abbr> denotes a family of time standards that includes
 770     Coordinated Universal Time (<abbr>UTC</abbr>) along with other
 771     variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>,
 772     with days starting at midnight.
 773     Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern
 774     timestamps, <abbr>UTC</abbr> was not defined until 1960, so
 775     commentary uses the more-general abbreviation <abbr>UT</abbr> for
 776     timestamps that might predate 1960.
 777     Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly,
 778     and since pre-1972 <abbr>UTC</abbr> seconds varied in length,
 779     interpretation of older timestamps can be problematic when
 780     subsecond accuracy is needed.
 781   </li>
 782   <li>
 783     Civil time was not based on atomic time before 1972, and we do not
 784     know the history of
 785     <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's
 786     rotation</a> accurately enough to map <a
 787     href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr
 788     title="International System of Units">SI</abbr></a> seconds to
 789     historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a>
 790     to more than about one-hour accuracy.
 791     See: Stephenson FR, Morrison LV, Hohenkerk CY.
 792     <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of
 793     the Earth's rotation: 720 BC to AD 2015</a>.
 794     <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404.
 795     Also see: Espenak F. <a
 796     href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty
 797     in Delta T (ΔT)</a>.
 798   </li>
 799   <li>
 800     The relationship between POSIX time (that is, <abbr>UTC</abbr> but
 801     ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap
 802     seconds</a>) and <abbr>UTC</abbr> is not agreed upon after 1972.
 803     Although the POSIX
 804     clock officially stops during an inserted leap second, at least one
 805     proposed standard has it jumping back a second instead; and in
 806     practice POSIX clocks more typically either progress glacially during
 807     a leap second, or are slightly slowed while near a leap second.
 808   </li>
 809   <li>
 810     The <code><abbr>tz</abbr></code> database does not represent how
 811     uncertain its information is.
 812     Ideally it would contain information about when data entries are
 813     incomplete or dicey.
 814     Partial temporal knowledge is a field of active research, though,
 815     and it is not clear how to apply it here.
 816   </li>
 817 </ul>
 818
 819 <p>
 820 In short, many, perhaps most, of the <code><abbr>tz</abbr></code>
 821 database's pre-1970 and future timestamps are either wrong or
 822 misleading.
 823 Any attempt to pass the
 824 <code><abbr>tz</abbr></code> database off as the definition of time
 825 should be unacceptable to anybody who cares about the facts.
 826 In particular, the <code><abbr>tz</abbr></code> database's
 827 <abbr>LMT</abbr> offsets should not be considered meaningful, and
 828 should not prompt creation of timezones
 829 merely because two locations
 830 differ in <abbr>LMT</abbr> or transitioned to standard time at
 831 different dates.
 832 </p>
 833 </section>
 834
 835 <section>
 836   <h2 id="functions">Time and date functions</h2>
 837 <p>
 838 The <code><abbr>tz</abbr></code> code contains time and date functions
 839 that are upwards compatible with those of POSIX.
 840 Code compatible with this package is already
 841 <a href="tz-link.html#tzdb">part of many platforms</a>, where the
 842 primary use of this package is to update obsolete time-related files.
 843 To do this, you may need to compile the time zone compiler
 844 '<code>zic</code>' supplied with this package instead of using the
 845 system '<code>zic</code>', since the format of <code>zic</code>'s
 846 input is occasionally extended, and a platform may still be shipping
 847 an older <code>zic</code>.
 848 </p>
 849
 850 <h3 id="POSIX">POSIX properties and limitations</h3>
 851 <ul>
 852   <li>
 853     <p>
 854     In POSIX, time display in a process is controlled by the
 855     environment variable <code>TZ</code>.
 856     Unfortunately, the POSIX
 857     <code>TZ</code> string takes a form that is hard to describe and
 858     is error-prone in practice.
 859     Also, POSIX <code>TZ</code> strings cannot deal with daylight
 860     saving time rules not based on the Gregorian calendar (as in
 861     Iran), or with situations where more than two time zone
 862     abbreviations or <abbr>UT</abbr> offsets are used in an area.
 863     </p>
 864
 865     <p>
 866     The POSIX <code>TZ</code> string takes the following form:
 867     </p>
 868
 869     <p>
 870     <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>]]]
 871     </p>
 872
 873     <p>
 874     where:
 875     </p>
 876
 877     <dl>
 878       <dt><var>std</var> and <var>dst</var></dt><dd>
 879         are 3 or more characters specifying the standard
 880         and daylight saving time (<abbr>DST</abbr>) zone abbreviations.
 881         Starting with POSIX.1-2001, <var>std</var> and <var>dst</var>
 882         may also be in a quoted form like '<code>&lt;+09&gt;</code>';
 883         this allows "<code>+</code>" and "<code>-</code>" in the names.
 884       </dd>
 885       <dt><var>offset</var></dt><dd>
 886         is of the form
 887         '<code>[&plusmn;]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>'
 888         and specifies the offset west of <abbr>UT</abbr>.
 889         '<var>hh</var>' may be a single digit;
 890         0&le;<var>hh</var>&le;24.
 891         The default <abbr>DST</abbr> offset is one hour ahead of
 892         standard time.
 893       </dd>
 894       <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
 895         specifies the beginning and end of <abbr>DST</abbr>.
 896         If this is absent, the system supplies its own ruleset
 897         for <abbr>DST</abbr>, and its rules can differ from year to year;
 898         typically <abbr>US</abbr> <abbr>DST</abbr> rules are used.
 899       </dd>
 900       <dt><var>time</var></dt><dd>
 901         takes the form
 902         '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
 903         and defaults to 02:00.
 904         This is the same format as the offset, except that a
 905         leading '<code>+</code>' or '<code>-</code>' is not allowed.
 906       </dd>
 907       <dt><var>date</var></dt><dd>
 908         takes one of the following forms:
 909         <dl>
 910           <dt>J<var>n</var> (1&le;<var>n</var>&le;365)</dt><dd>
 911             origin-1 day number not counting February 29
 912           </dd>
 913           <dt><var>n</var> (0&le;<var>n</var>&le;365)</dt><dd>
 914             origin-0 day number counting February 29 if present
 915           </dd>
 916           <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
 917             (0[Sunday]&le;<var>d</var>&le;6[Saturday], 1&le;<var>n</var>&le;5,
 918             1&le;<var>m</var>&le;12)</dt><dd>
 919             for the <var>d</var>th day of week <var>n</var> of
 920             month <var>m</var> of the year, where week 1 is the first
 921             week in which day <var>d</var> appears, and
 922             '<code>5</code>' stands for the last week in which
 923             day <var>d</var> appears (which may be either the 4th or
 924             5th week).
 925             Typically, this is the only useful form; the <var>n</var>
 926             and <code>J</code><var>n</var> forms are rarely used.
 927           </dd>
 928         </dl>
 929       </dd>
 930     </dl>
 931
 932     <p>
 933     Here is an example POSIX <code>TZ</code> string for New
 934     Zealand after 2007.
 935     It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead
 936     of <abbr>UT</abbr>, and that daylight saving time
 937     (<abbr>NZDT</abbr>) is observed from September's last Sunday at
 938     02:00 until April's first Sunday at 03:00:
 939     </p>
 940
 941     <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
 942
 943     <p>
 944     This POSIX <code>TZ</code> string is hard to remember, and
 945     mishandles some timestamps before 2008.
 946     With this package you can use this instead:
 947     </p>
 948
 949     <pre><code>TZ='Pacific/Auckland'</code></pre>
 950   </li>
 951   <li>
 952     POSIX does not define the <abbr>DST</abbr> transitions
 953     for <code>TZ</code> values like
 954     "<code>EST5EDT</code>".
 955     Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
 956     were used to interpret such values, but this meant that the
 957     <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
 958     program that did time conversion. This meant that when
 959     <abbr>US</abbr> time conversion rules changed (as in the United
 960     States in 1987), all programs that did time conversion had to be
 961     recompiled to ensure proper results.
 962   </li>
 963   <li>
 964     The <code>TZ</code> environment variable is process-global, which
 965     makes it hard to write efficient, thread-safe applications that
 966     need access to multiple timezones.
 967   </li>
 968   <li>
 969     In POSIX, there is no tamper-proof way for a process to learn the
 970     system's best idea of local (wall clock) time.
 971     This is important for applications that an administrator wants
 972     used only at certain times &ndash; without regard to whether the
 973     user has fiddled the
 974     <code>TZ</code> environment variable.
 975     While an administrator can "do everything in <abbr>UT</abbr>" to
 976     get around the problem, doing so is inconvenient and precludes
 977     handling daylight saving time shifts &ndash; as might be required to
 978     limit phone calls to off-peak hours.
 979   </li>
 980   <li>
 981     POSIX provides no convenient and efficient way to determine
 982     the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary
 983     timestamps, particularly for timezones
 984     that do not fit into the POSIX model.
 985   </li>
 986   <li>
 987     POSIX requires that <code>time_t</code> clock counts exclude leap
 988     seconds.
 989   </li>
 990   <li>
 991     The <code><abbr>tz</abbr></code> code attempts to support all the
 992     <code>time_t</code> implementations allowed by POSIX.
 993     The <code>time_t</code> type represents a nonnegative count of seconds
 994     since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds.
 995     In practice, <code>time_t</code> is usually a signed 64- or 32-bit
 996     integer; 32-bit signed <code>time_t</code> values stop working after
 997     2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these
 998     days typically use a signed 64-bit integer.
 999     Unsigned 32-bit integers are used on one or two platforms, and 36-bit
1000     and 40-bit integers are also used occasionally.
1001     Although earlier POSIX versions allowed <code>time_t</code> to be a
1002     floating-point type, this was not supported by any practical system,
1003     and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both
1004     require <code>time_t</code> to be an integer type.
1005   </li>
1006 </ul>
1007
1008 <h3 id="POSIX-extensions">Extensions to POSIX in the
1009 <code><abbr>tz</abbr></code> code</h3>
1010 <ul>
1011   <li>
1012     <p>
1013     The <code>TZ</code> environment variable is used in generating
1014     the name of a file from which time-related information is read
1015     (or is interpreted à la POSIX); <code>TZ</code> is no longer
1016     constrained to be a string containing abbreviations
1017     and numeric data as described <a href="#POSIX">above</a>.
1018     The file's format is <dfn><abbr>TZif</abbr></dfn>,
1019     a timezone information format that contains binary data; see
1020     <a href="https://tools.ietf.org/html/8536">Internet
1021     <abbr>RFC</abbr> 8536</a>.
1022     The daylight saving time rules to be used for a
1023     particular timezone are encoded in the
1024     <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
1025     Australian, and other rules to be encoded, and
1026     allows for situations where more than two time zone
1027     abbreviations are used.
1028     </p>
1029     <p>
1030     It was recognized that allowing the <code>TZ</code> environment
1031     variable to take on values such as '<code>America/New_York</code>'
1032     might cause "old" programs (that expect <code>TZ</code> to have a
1033     certain form) to operate incorrectly; consideration was given to using
1034     some other environment variable (for example, <code>TIMEZONE</code>)
1035     to hold the string used to generate the <abbr>TZif</abbr> file's name.
1036     In the end, however, it was decided to continue using
1037     <code>TZ</code>: it is widely used for time zone purposes;
1038     separately maintaining both <code>TZ</code>
1039     and <code>TIMEZONE</code> seemed a nuisance; and systems where
1040     "new" forms of <code>TZ</code> might cause problems can simply
1041     use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1042     can be used by "new" programs as well as by "old" programs that
1043     assume pre-POSIX <code>TZ</code> values.
1044     </p>
1045   </li>
1046   <li>
1047     The code supports platforms with a <abbr>UT</abbr> offset member
1048     in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>.
1049   </li>
1050   <li>
1051     The code supports platforms with a time zone abbreviation member in
1052     <code>struct tm</code>, e.g., <code>tm_zone</code>.
1053   </li>
1054   <li>
1055     Functions <code>tzalloc</code>, <code>tzfree</code>,
1056     <code>localtime_rz</code>, and <code>mktime_z</code> for
1057     more-efficient thread-safe applications that need to use multiple
1058     timezones.
1059     The <code>tzalloc</code> and <code>tzfree</code> functions
1060     allocate and free objects of type <code>timezone_t</code>,
1061     and <code>localtime_rz</code> and <code>mktime_z</code> are
1062     like <code>localtime_r</code> and <code>mktime</code> with an
1063     extra <code>timezone_t</code> argument.
1064     The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>.
1065   </li>
1066   <li>
1067     Negative <code>time_t</code> values are supported, on systems
1068     where <code>time_t</code> is signed.
1069   </li>
1070   <li>
1071     These functions can account for leap seconds;
1072     see <a href="#leapsec">Leap seconds</a> below.
1073   </li>
1074 </ul>
1075
1076 <h3 id="vestigial">POSIX features no longer needed</h3>
1077 <p>
1078 POSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a>
1079 define some <a href="https://en.wikipedia.org/wiki/API"><abbr
1080 title="application programming interface">API</abbr>s</a> that are vestigial:
1081 they are not needed, and are relics of a too-simple model that does
1082 not suffice to handle many real-world timestamps.
1083 Although the <code><abbr>tz</abbr></code> code supports these
1084 vestigial <abbr>API</abbr>s for backwards compatibility, they should
1085 be avoided in portable applications.
1086 The vestigial <abbr>API</abbr>s are:
1087 </p>
1088 <ul>
1089   <li>
1090     The POSIX <code>tzname</code> variable does not suffice and is no
1091     longer needed.
1092     To get a timestamp's time zone abbreviation, consult
1093     the <code>tm_zone</code> member if available; otherwise,
1094     use <code>strftime</code>'s <code>"%Z"</code> conversion
1095     specification.
1096   </li>
1097   <li>
1098     The POSIX <code>daylight</code> and <code>timezone</code>
1099     variables do not suffice and are no longer needed.
1100     To get a timestamp's <abbr>UT</abbr> offset, consult
1101     the <code>tm_gmtoff</code> member if available; otherwise,
1102     subtract values returned by <code>localtime</code>
1103     and <code>gmtime</code> using the rules of the Gregorian calendar,
1104     or use <code>strftime</code>'s <code>"%z"</code> conversion
1105     specification if a string like <code>"+0900"</code> suffices.
1106   </li>
1107   <li>
1108     The <code>tm_isdst</code> member is almost never needed and most of
1109     its uses should be discouraged in favor of the abovementioned
1110     <abbr>API</abbr>s.
1111     Although it can still be used in arguments to
1112     <code>mktime</code> to disambiguate timestamps near
1113     a <abbr>DST</abbr> transition when the clock jumps back, this
1114     disambiguation does not work when standard time itself jumps back,
1115     which can occur when a location changes to a time zone with a
1116     lesser <abbr>UT</abbr> offset.
1117   </li>
1118 </ul>
1119
1120 <h3 id="other-portability">Other portability notes</h3>
1121 <ul>
1122   <li>
1123     The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition
1124     UNIX</a> <code>timezone</code> function is not present in this
1125     package; it is impossible to reliably map <code>timezone</code>'s
1126     arguments (a "minutes west of <abbr>GMT</abbr>" value and a
1127     "daylight saving time in effect" flag) to a time zone
1128     abbreviation, and we refuse to guess.
1129     Programs that in the past used the <code>timezone</code> function
1130     may now examine <code>localtime(&amp;clock)-&gt;tm_zone</code>
1131     (if <code>TM_ZONE</code> is defined) or
1132     <code>tzname[localtime(&amp;clock)-&gt;tm_isdst]</code>
1133     (if <code>HAVE_TZNAME</code> is nonzero) to learn the correct time
1134     zone abbreviation to use.
1135   </li>
1136   <li>
1137     The <a
1138     href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a>
1139     <code>gettimeofday</code> function is not
1140     used in this package.
1141     This formerly let users obtain the current <abbr>UTC</abbr> offset
1142     and <abbr>DST</abbr> flag, but this functionality was removed in
1143     later versions of <abbr>BSD</abbr>.
1144   </li>
1145   <li>
1146     In <abbr>SVR2</abbr>, time conversion fails for near-minimum or
1147     near-maximum <code>time_t</code> values when doing conversions
1148     for places that do not use <abbr>UT</abbr>.
1149     This package takes care to do these conversions correctly.
1150     A comment in the source code tells how to get compatibly wrong
1151     results.
1152   </li>
1153   <li>
1154     The functions that are conditionally compiled
1155     if <code>STD_INSPIRED</code> is defined should, at this point, be
1156     looked on primarily as food for thought.
1157     They are not in any sense "standard compatible" &ndash; some are
1158     not, in fact, specified in <em>any</em> standard.
1159     They do, however, represent responses of various authors to
1160     standardization proposals.
1161   </li>
1162   <li>
1163     Other time conversion proposals, in particular those supported by the
1164     <a href="https://howardhinnant.github.io/date/tz.html">Time Zone
1165     Database Parser</a>, offer a wider selection of functions
1166     that provide capabilities beyond those provided here.
1167     The absence of such functions from this package is not meant to
1168     discourage the development, standardization, or use of such
1169     functions.
1170     Rather, their absence reflects the decision to make this package
1171     contain valid extensions to POSIX, to ensure its broad
1172     acceptability.
1173     If more powerful time conversion functions can be standardized, so
1174     much the better.
1175   </li>
1176 </ul>
1177 </section>
1178
1179 <section>
1180   <h2 id="stability">Interface stability</h2>
1181 <p>
1182 The <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1183 </p>
1184
1185 <ul>
1186   <li>
1187     A set of timezone names as per
1188       "<a href="#naming">Timezone identifiers</a>" above.
1189   </li>
1190   <li>
1191     Library functions described in "<a href="#functions">Time and date
1192       functions</a>" above.
1193   </li>
1194   <li>
1195     The programs <code>tzselect</code>, <code>zdump</code>,
1196     and <code>zic</code>, documented in their man pages.
1197   </li>
1198   <li>
1199     The format of <code>zic</code> input files, documented in
1200     the <code>zic</code> man page.
1201   </li>
1202   <li>
1203     The format of <code>zic</code> output files, documented in
1204     the <code>tzfile</code> man page.
1205   </li>
1206   <li>
1207     The format of zone table files, documented in <code>zone1970.tab</code>.
1208   </li>
1209   <li>
1210     The format of the country code file, documented in <code>iso3166.tab</code>.
1211   </li>
1212   <li>
1213     The version number of the code and data, as the first line of
1214     the text file '<code>version</code>' in each release.
1215   </li>
1216 </ul>
1217
1218 <p>
1219 Interface changes in a release attempt to preserve compatibility with
1220 recent releases.
1221 For example, <code><abbr>tz</abbr></code> data files typically do not
1222 rely on recently-added <code>zic</code> features, so that users can
1223 run older <code>zic</code> versions to process newer data files.
1224 <a href="tz-link.html#download">Downloading
1225 the <code><abbr>tz</abbr></code> database</a> describes how releases
1226 are tagged and distributed.
1227 </p>
1228
1229 <p>
1230 Interfaces not listed above are less stable.
1231 For example, users should not rely on particular <abbr>UT</abbr>
1232 offsets or abbreviations for timestamps, as data entries are often
1233 based on guesswork and these guesses may be corrected or improved.
1234 </p>
1235
1236 <p>
1237 Timezone boundaries are not part of the stable interface.
1238 For example, even though the <samp>Asia/Bangkok</samp> timezone
1239 currently includes Chang Mai, Hanoi, and Phnom Penh, this is not part
1240 of the stable interface and the timezone can split at any time.
1241 If a calendar application records a future event in some location other
1242 than Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record,
1243 the application should be robust in the presence of timezone splits
1244 between now and the future time.
1245 </p>
1246 </section>
1247
1248 <section>
1249   <h2 id="leapsec">Leap seconds</h2>
1250 <p>
1251 The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1252 thanks to code contributed by Bradley White.
1253 However, the leap second support of this package is rarely used directly
1254 because POSIX requires leap seconds to be excluded and many
1255 software packages would mishandle leap seconds if they were present.
1256 Instead, leap seconds are more commonly handled by occasionally adjusting
1257 the operating system kernel clock as described in
1258 <a href="tz-link.html#precision">Precision timekeeping</a>,
1259 and this package by default installs a <samp>leapseconds</samp> file
1260 commonly used by
1261 <a href="http://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a>
1262 software that adjusts the kernel clock.
1263 However, kernel-clock twiddling approximates UTC only roughly,
1264 and systems needing more-precise UTC can use this package's leap
1265 second support directly.
1266 </p>
1267
1268 <p>
1269 The directly-supported mechanism assumes that <code>time_t</code>
1270 counts of seconds since the POSIX epoch normally include leap seconds,
1271 as opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1272 This modified timescale is converted to <abbr>UTC</abbr>
1273 at the same point that time zone and DST adjustments are applied &ndash;
1274 namely, at calls to <code>localtime</code> and analogous functions &ndash;
1275 and the process is driven by leap second information
1276 stored in alternate versions of the <abbr>TZif</abbr> files.
1277 Because a leap second adjustment may be needed even
1278 if no time zone correction is desired,
1279 calls to <code>gmtime</code>-like functions
1280 also need to consult a <abbr>TZif</abbr> file,
1281 conventionally named <samp><abbr>GMT</abbr></samp>,
1282 to see whether leap second corrections are needed.
1283 To convert an application's <code>time_t</code> timestamps to or from
1284 POSIX <code>time_t</code> timestamps (for use when, say,
1285 embedding or interpreting timestamps in portable
1286 <a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1287 files),
1288 the application can call the utility functions
1289 <code>time2posix</code> and <code>posix2time</code>
1290 included with this package.
1291 </p>
1292
1293 <p>
1294 If the POSIX-compatible <abbr>TZif</abbr> file set is installed
1295 in a directory whose basename is <samp>zoneinfo</samp>, the
1296 leap-second-aware file set is by default installed in a separate
1297 directory <samp>zoneinfo-leaps</samp>.
1298 Although each process can have its own time zone by setting
1299 its <code>TZ</code> environment variable, there is no support for some
1300 processes being leap-second aware while other processes are
1301 POSIX-compatible; the leap-second choice is system-wide.
1302 So if you configure your kernel to count leap seconds, you should also
1303 discard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp>
1304 to <samp>zoneinfo</samp>.
1305 Alternatively, you can install just one set of <abbr>TZif</abbr> files
1306 in the first place; see the <code>REDO</code> variable in this package's
1307 <a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>.
1308 </p>
1309 </section>
1310
1311 <section>
1312   <h2 id="calendar">Calendrical issues</h2>
1313 <p>
1314 Calendrical issues are a bit out of scope for a time zone database,
1315 but they indicate the sort of problems that we would run into if we
1316 extended the time zone database further into the past.
1317 An excellent resource in this area is Edward M. Reingold
1318 and Nachum Dershowitz, <cite><a
1319 href="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical
1320 Calculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018).
1321 Other information and sources are given in the file '<code>calendars</code>'
1322 in the <code><abbr>tz</abbr></code> distribution.
1323 They sometimes disagree.
1324 </p>
1325 </section>
1326
1327 <section>
1328   <h2 id="planets">Time and time zones on other planets</h2>
1329 <p>
1330 Some people's work schedules have used
1331 <a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>.
1332 Jet Propulsion Laboratory (JPL) coordinators kept Mars time on
1333 and off during the
1334 <a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars
1335 Pathfinder</a> mission (1997).
1336 Some of their family members also adapted to Mars time.
1337 Dozens of special Mars watches were built for JPL workers who kept
1338 Mars time during the
1339 <a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars
1340 Exploration Rovers (MER)</a> mission (2004&ndash;2018).
1341 These timepieces looked like normal Seikos and Citizens but were adjusted
1342 to use Mars seconds rather than terrestrial seconds, although
1343 unfortunately the adjusted watches were unreliable and appear to have
1344 had only limited use.
1345 </p>
1346
1347 <p>
1348 A Mars solar day is called a "sol" and has a mean period equal to
1349 about 24 hours 39 minutes 35.244 seconds in terrestrial time.
1350 It is divided into a conventional 24-hour clock, so each Mars second
1351 equals about 1.02749125 terrestrial seconds.
1352 (One MER worker noted, "If I am working Mars hours, and Mars hours are
1353 2.5% more than Earth hours, shouldn't I get an extra 2.5% pay raise?")
1354 </p>
1355
1356 <p>
1357 The <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime
1358 meridian</a> of Mars goes through the center of the crater
1359 <a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in
1360 honor of the British astronomer who built the Greenwich telescope that
1361 defines Earth's prime meridian.
1362 Mean solar time on the Mars prime meridian is
1363 called Mars Coordinated Time (<abbr>MTC</abbr>).
1364 </p>
1365
1366 <p>
1367 Each landed mission on Mars has adopted a different reference for
1368 solar timekeeping, so there is no real standard for Mars time zones.
1369 For example, the MER mission defined two time zones "Local
1370 Solar Time A" and "Local Solar Time B" for its two missions, each zone
1371 designed so that its time equals local true solar time at
1372 approximately the middle of the nominal mission.
1373 The A and B zones differ enough so that an MER worker assigned to
1374 the A zone might suffer "Mars lag" when switching to work in the B zone.
1375 Such a "time zone" is not particularly suited for any application
1376 other than the mission itself.
1377 </p>
1378
1379 <p>
1380 Many calendars have been proposed for Mars, but none have achieved
1381 wide acceptance.
1382 Astronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a
1383 sequential count of Mars solar days elapsed since about 1873-12-29
1384 12:00 <abbr>GMT</abbr>.
1385 </p>
1386
1387 <p>
1388 In our solar system, Mars is the planet with time and calendar most
1389 like Earth's.
1390 On other planets, Sun-based time and calendars would work quite
1391 differently.
1392 For example, although Mercury's
1393 <a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal
1394 rotation period</a> is 58.646 Earth days, Mercury revolves around the
1395 Sun so rapidly that an observer on Mercury's equator would see a
1396 sunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a
1397 Mercury day.
1398 Venus is more complicated, partly because its rotation is slightly
1399 <a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>:
1400 its year is 1.92 of its days.
1401 Gas giants like Jupiter are trickier still, as their polar and
1402 equatorial regions rotate at different rates, so that the length of a
1403 day depends on latitude.
1404 This effect is most pronounced on Neptune, where the day is about 12
1405 hours at the poles and 18 hours at the equator.
1406 </p>
1407
1408 <p>
1409 Although the <code><abbr>tz</abbr></code> database does not support
1410 time on other planets, it is documented here in the hopes that support
1411 will be added eventually.
1412 </p>
1413
1414 <p>
1415 Sources for time on other planets:
1416 </p>
1417
1418 <ul>
1419   <li>
1420     Michael Allison and Robert Schmunk,
1421     "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical
1422       Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>"
1423     (2020-03-08).
1424   </li>
1425   <li>
1426     Zara Mirmalek,
1427     <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making
1428         Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854.
1429   </li>
1430   <li>
1431     Jia-Rui Chong,
1432     "<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays
1433     Fit for a Martian</a>", <cite>Los Angeles Times</cite>
1434     (2004-01-14), pp A1, A20&ndash;A21.
1435   </li>
1436   <li>
1437     Tom Chmielewski,
1438     "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet
1439     Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26)
1440   </li>
1441   <li>
1442     Matt Williams,
1443     "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How
1444     long is a day on the other planets of the solar system?</a>"
1445     (2016-01-20).
1446   </li>
1447 </ul>
1448 </section>
1449
1450 <footer>
1451   <hr>
1452   This file is in the public domain, so clarified as of 2009-05-17 by
1453   Arthur David Olson.
1454 </footer>
1455 </body>
1456 </html>