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