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