contrib/tzdata/theory.html

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