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