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