Branch: Tag:

2018-09-05

2018-09-05 10:10:57 by Henrik Grubbström (Grubba) <grubba@grubba.org>

Cpp: Break circular references via "magic" macros.

1: + <!DOCTYPE html>   <html lang="en">   <head>    <title>Theory and pragmatics of the tz code and data</title>    <meta charset="UTF-8">   </head>    -  + <!-- The somewhat-unusal indenting style in this file is intended to +  shrink the output of the shell command 'diff Theory Theory.html', +  where 'Theory' was the plain text file that this file is derived +  from. The 'Theory' file used leading white space to indent, and +  when possible that indentation is preserved here. Eventually we +  may stop doing this and remove this comment. --> +    <body> - <h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1> +  <h1>Theory and pragmatics of the tz code and data</h1>    <h3>Outline</h3>    <nav>    <ul> -  <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code> -  database</a></li> -  <li><a href="#naming">Names of time zone rulesets</a></li> +  <li><a href="#scope">Scope of the tz database</a></li> +  <li><a href="#naming">Names of time zone rules</a></li>    <li><a href="#abbreviations">Time zone abbreviations</a></li> -  <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code> -  database</a></li> +  <li><a href="#accuracy">Accuracy of the tz database</a></li>    <li><a href="#functions">Time and date functions</a></li>    <li><a href="#stability">Interface stability</a></li>    <li><a href="#calendar">Calendrical issues</a></li>
22:    </ul>    </nav>    +     <section> -  <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2> +  <h2 id="scope">Scope of the tz database</h2>   <p> - The <a - href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code> - database</a> attempts to record the history and predicted future of - all computer-based clocks that track civil time. - It organizes <a href="tz-link.html">time zone and daylight saving time - data</a> by partitioning the world into <a - href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">regions</a> - whose clocks all agree about timestamps that occur after the <a - href="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a> - (1970-01-01 00:00:00 <a - href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr - title="Coordinated Universal Time">UTC</abbr></a>). - The database labels each such region with a notable location and - records all known clock transitions for that location. - Although 1970 is a somewhat-arbitrary cutoff, there are significant - challenges to moving the cutoff earlier even by a decade or two, due - to the wide variety of local practices before computer timekeeping - became prevalent. + The tz database attempts to record the history and predicted future of + all computer-based clocks that track civil time. To represent this + data, the world is partitioned into regions whose clocks all agree + about timestamps that occur after the somewhat-arbitrary cutoff point + of the POSIX Epoch (1970-01-01 00:00:00 UTC). For each such region, + the database records all known clock transitions, and labels the region + with a notable location. Although 1970 is a somewhat-arbitrary + cutoff, there are significant challenges to moving the cutoff earlier + even by a decade or two, due to the wide variety of local practices + before computer timekeeping became prevalent.   </p>      <p>
53:   applications requiring accurate handling of all past times everywhere,   as it would take far too much effort and guesswork to record all   details of pre-1970 civil timekeeping. - Although some information outside the scope of the database is - collected in a file <code>backzone</code> that is distributed along - with the database proper, this file is less reliable and does not - necessarily follow database guidelines. +    </p>      <p> - As described below, reference source code for using the - <code><abbr>tz</abbr></code> database is also available. - The <code><abbr>tz</abbr></code> code is upwards compatible with <a - href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international - standard for <a - href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems. - As of this writing, the current edition of POSIX is: <a - href="http://pubs.opengroup.org/onlinepubs/9699919799/"> The Open - Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018 - Edition. - Because the database's scope encompasses real-world changes to civil - timekeeping, its model for describing time is more complex than the - standard and daylight saving times supported by POSIX. - A <code><abbr>tz</abbr></code> region corresponds to a ruleset that can - have more than two changes per year, these changes need not merely - flip back and forth between two alternatives, and the rules themselves - can change at times. - Whether and when a <code><abbr>tz</abbr></code> region changes its - clock, and even the region's notional base offset from UTC, are variable. - It does not always make sense to talk about a region's - "base offset", since it is not necessarily a single number. + As described below, reference source code for using the tz database is + also available. The tz code is upwards compatible with POSIX, an + international standard for UNIX-like systems. As of this writing, the + current edition of POSIX is: +  <a href="http://pubs.opengroup.org/onlinepubs/9699919799/"> +  The Open Group Base Specifications Issue 7</a>, +  IEEE Std 1003.1-2008, 2016 Edition.   </p> -  +     </section>    -  +  +     <section> -  <h2 id="naming">Names of time zone rulesets</h2> +  <h2 id="naming">Names of time zone rules</h2>   <p> - Each <code><abbr>tz</abbr></code> region has a unique name that - corresponds to a set of time zone rules. + Each of the database's time zone rules has a unique name.   Inexperienced users are not expected to select these names unaided.   Distributors should provide documentation and/or a simple selection - interface that explains the names; for one example, see the - <code>tzselect</code> program in the <code><abbr>tz</abbr></code> code. - The <a href="http://cldr.unicode.org/">Unicode Common Locale Data - Repository</a> contains data that may be useful for other selection - interfaces. + interface that explains the names; for one example, see the 'tzselect' + program in the tz code. The + <a href="http://cldr.unicode.org/">Unicode Common Locale Data + Repository</a> contains data that may be useful for other + selection interfaces.   </p>      <p> - The naming conventions attempt to strike a balance + The time zone rule naming conventions attempt to strike a balance   among the following goals:   </p> -  +    <ul>    <li>    Uniquely identify every region where clocks have agreed since 1970.
114:    Indicate to experts where that region is.    </li>    <li> -  Be robust in the presence of political changes. -  For example, names of countries are ordinarily not used, to avoid -  incompatibilities when countries change their name (e.g., -  Zaire&rarr;Congo) or when locations change countries (e.g., Hong -  Kong from UK colony to China). +  Be robust in the presence of political changes. For example, names +  of countries are ordinarily not used, to avoid incompatibilities +  when countries change their name (e.g. Zaire&rarr;Congo) or when +  locations change countries (e.g. Hong Kong from UK colony to +  China).    </li>    <li>    Be portable to a wide variety of implementations.
127:    Use a consistent naming conventions over the entire world.    </li>   </ul> -  +    <p> - Names normally have the form - <var>AREA</var><code>/</code><var>LOCATION</var>, where - <var>AREA</var> is the name of a continent or ocean, and - <var>LOCATION</var> is the name of a specific location within that - region. - North and South America share the same area, '<code>America</code>'. - Typical names are '<code>Africa/Cairo</code>', - '<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'. - Some names are further qualified to help avoid confusion; for example, - '<code>America/Indiana/Petersburg</code>' distinguishes Petersburg, - Indiana from other Petersburgs in America. + Names normally have the + form <var>AREA</var><code>/</code><var>LOCATION</var>, + where <var>AREA</var> is the name of a continent or ocean, + and <var>LOCATION</var> is the name of a specific + location within that region. North and South America share the same + area, '<code>America</code>'. Typical names are + '<code>Africa/Cairo</code>', '<code>America/New_York</code>', and + '<code>Pacific/Honolulu</code>'.   </p>      <p> - Here are the general guidelines used for - choosing <code><abbr>tz</abbr></code> region names, + Here are the general rules used for choosing location names,   in decreasing order of importance:   </p> -  +    <ul>    <li>    Use only valid POSIX file name components (i.e., the parts of -  names other than '<code>/</code>'). -  Do not use the file name components '<code>.</code>' and -  '<code>..</code>'. -  Within a file name component, use only <a -  href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters, -  '<code>.</code>', '<code>-</code>' and '<code>_</code>'. -  Do not use digits, as that might create an ambiguity with <a -  href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX -  <code>TZ</code> strings</a>. -  A file name component must not exceed 14 characters or start with -  '<code>-</code>'. -  E.g., prefer <code>Asia/Brunei</code> to -  <code>Asia/Bandar_Seri_Begawan</code>. -  Exceptions: see the discussion of legacy names below. +  names other than '<code>/</code>'). Do not use the file name +  components '<code>.</code>' and '<code>..</code>'. +  Within a file name component, +  use only ASCII letters, '<code>.</code>', +  '<code>-</code>' and '<code>_</code>'. Do not use +  digits, as that might create an ambiguity with POSIX +  TZ strings. A file name component must not exceed 14 +  characters or start with '<code>-</code>'. E.g., +  prefer '<code>Brunei</code>' to +  '<code>Bandar_Seri_Begawan</code>'. Exceptions: see +  the discussion +  of legacy names below.    </li>    <li>    A name must not be empty, or contain '<code>//</code>', or    start or end with '<code>/</code>'.    </li>    <li> -  Do not use names that differ only in case. -  Although the reference implementation is case-sensitive, some -  other implementations are not, and they would mishandle names -  differing only in case. +  Do not use names that differ only in case. Although the reference +  implementation is case-sensitive, some other implementations +  are not, and they would mishandle names differing only in case.    </li>    <li>    If one name <var>A</var> is an initial prefix of another -  name <var>AB</var> (ignoring case), then <var>B</var> must not -  start with '<code>/</code>', as a regular file cannot have the -  same name as a directory in POSIX. -  For example, <code>America/New_York</code> precludes -  <code>America/New_York/Bronx</code>. +  name <var>AB</var> (ignoring case), then <var>B</var> +  must not start with '<code>/</code>', as a +  regular file cannot have +  the same name as a directory in POSIX. For example, +  '<code>America/New_York</code>' precludes +  '<code>America/New_York/Bronx</code>'.    </li>    <li>    Uninhabited regions like the North Pole and Bouvet Island    do not need locations, since local time is not defined there.    </li>    <li> -  There should typically be at least one name for each <a -  href="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr -  title="International Organization for Standardization">ISO</abbr> -  3166-1</a> officially assigned two-letter code for an inhabited -  country or territory. +  There should typically be at least one name for each ISO 3166-1 +  officially assigned two-letter code for an inhabited country +  or territory.    </li>    <li>    If all the clocks in a region have agreed since 1970, -  do not bother to include more than one location +  don't bother to include more than one location    even if subregions' clocks disagreed before 1970.    Otherwise these tables would become annoyingly large.    </li>    <li>    If a name is ambiguous, use a less ambiguous alternative; -  e.g., many cities are named San José and Georgetown, so -  prefer <code>America/Costa_Rica</code> to -  <code>America/San_Jose</code> and <code>America/Guyana</code> -  to <code>America/Georgetown</code>. +  e.g. many cities are named San José and Georgetown, so +  prefer '<code>Costa_Rica</code>' to '<code>San_Jose</code>' and '<code>Guyana</code>' to '<code>Georgetown</code>'.    </li>    <li> -  Keep locations compact. -  Use cities or small islands, not countries or regions, so that any -  future changes do not split individual locations into different -  <code><abbr>tz</abbr></code> regions. -  E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>, -  since -  <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France -  has had multiple time zones</a>. +  Keep locations compact. Use cities or small islands, not countries +  or regions, so that any future time zone changes do not split +  locations into different time zones. E.g. prefer +  '<code>Paris</code>' to '<code>France</code>', since +  France has had multiple time zones.    </li>    <li> -  Use mainstream English spelling, e.g., prefer -  <code>Europe/Rome</code> to <code>Europe/Roma</code>, and -  prefer <code>Europe/Athens</code> to the Greek -  <code>Europe/Αθήνα</code> or the Romanized -  <code>Europe/Athína</code>. -  The POSIX file name restrictions encourage this guideline. +  Use mainstream English spelling, e.g. prefer +  '<code>Rome</code>' to '<code>Roma</code>', and prefer +  '<code>Athens</code>' to the Greek +  '<code>Αθήνα</code>' or the Romanized +  '<code>Athína</code>'. +  The POSIX file name restrictions encourage this rule.    </li>    <li> -  Use the most populous among locations in a region, -  e.g., prefer <code>Asia/Shanghai</code> to -  <code>Asia/Beijing</code>. -  Among locations with similar populations, pick the best-known -  location, e.g., prefer <code>Europe/Rome</code> to -  <code>Europe/Milan</code>. +  Use the most populous among locations in a zone, +  e.g. prefer '<code>Shanghai</code>' to +  '<code>Beijing</code>'. Among locations with +  similar populations, pick the best-known location, +  e.g. prefer '<code>Rome</code>' to '<code>Milan</code>'.    </li>    <li> -  Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to -  <code>Atlantic/Canaries</code>. +  Use the singular form, e.g. prefer '<code>Canary</code>' to '<code>Canaries</code>'.    </li>    <li>    Omit common suffixes like '<code>_Islands</code>' and -  '<code>_City</code>', unless that would lead to ambiguity. -  E.g., prefer <code>America/Cayman</code> to -  <code>America/Cayman_Islands</code> and -  <code>America/Guatemala</code> to -  <code>America/Guatemala_City</code>, but prefer -  <code>America/Mexico_City</code> to -  <code>America/Mexico</code> -  because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the -  country of Mexico has several time zones</a>. +  '<code>_City</code>', unless that would lead to +  ambiguity. E.g. prefer '<code>Cayman</code>' to +  '<code>Cayman_Islands</code>' and +  '<code>Guatemala</code>' to +  '<code>Guatemala_City</code>', but prefer +  '<code>Mexico_City</code>' to '<code>Mexico</code>' +  because the country +  of Mexico has several time zones.    </li>    <li>    Use '<code>_</code>' to represent a space.    </li>    <li> -  Omit '<code>.</code>' from abbreviations in names. -  E.g., prefer <code>Atlantic/St_Helena</code> to -  <code>Atlantic/St._Helena</code>. +  Omit '<code>.</code>' from abbreviations in names, e.g. prefer +  '<code>St_Helena</code>' to '<code>St._Helena</code>'.    </li>    <li> -  Do not change established names if they only marginally violate -  the above guidelines. -  For example, do not change the existing name <code>Europe/Rome</code> to -  <code>Europe/Milan</code> merely because Milan's population has grown -  to be somewhat greater than Rome's. +  Do not change established names if they only marginally +  violate the above rules. For example, don't change +  the existing name '<code>Rome</code>' to +  '<code>Milan</code>' merely because +  Milan's population has grown to be somewhat greater +  than Rome's.    </li>    <li>    If a name is changed, put its old spelling in the
274:      <p>   The file '<code>zone1970.tab</code>' lists geographical locations used - to name <code><abbr>tz</abbr></code> regions. - It is intended to be an exhaustive list of names for geographic - regions as described above; this is a subset of the names in the data. - Although a '<code>zone1970.tab</code>' location's - <a href="https://en.wikipedia.org/wiki/Longitude">longitude</a> - corresponds to - its <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean - time (<abbr>LMT</abbr>)</a> offset with one hour for every 15&deg; - east longitude, this relationship is not exact. + to name time + zone rules. It is intended to be an exhaustive list of names for + geographic regions as described above; this is a subset of the names + in the data. Although a '<code>zone1970.tab</code>' location's longitude + corresponds to its LMT offset with one hour for every 15 degrees east + longitude, this relationship is not exact.   </p>      <p>
291:   See the file '<code>backward</code>' for most of these older names   (e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>').   The other old-fashioned names still supported are - '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and - '<code>EET</code>' (see the file '<code>europe</code>'). + '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and '<code>EET</code>' (see the file '<code>europe</code>').   </p>      <p>   Older versions of this package defined legacy names that are - incompatible with the first guideline of location names, but which are - still supported. - These legacy names are mostly defined in the file - '<code>etcetera</code>'. - Also, the file '<code>backward</code>' defines the legacy names - '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', - and the file '<code>northamerica</code>' defines the legacy names - '<code>EST5EDT</code>', '<code>CST6CDT</code>', - '<code>MST7MDT</code>', and '<code>PST8PDT</code>'. + incompatible with the first rule of location names, but which are + still supported. These legacy names are mostly defined in the file + '<code>etcetera</code>'. Also, the file '<code>backward</code>' defines the legacy names + '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', and the file '<code>northamerica</code>' defines the + legacy names '<code>EST5EDT</code>', '<code>CST6CDT</code>', '<code>MST7MDT</code>', and '<code>PST8PDT</code>'.   </p>      <p> - Excluding '<code>backward</code>' should not affect the other data. - If '<code>backward</code>' is excluded, excluding - '<code>etcetera</code>' should not affect the remaining data. + Excluding '<code>backward</code>' should not affect the other data. If + '<code>backward</code>' is excluded, excluding '<code>etcetera</code>' should not affect the + remaining data.   </p> - </section> +     -  +  +  </section>    <section>    <h2 id="abbreviations">Time zone abbreviations</h2>   <p>   When this package is installed, it generates time zone abbreviations   like '<code>EST</code>' to be compatible with human tradition and POSIX. - Here are the general guidelines used for choosing time zone abbreviations, + Here are the general rules used for choosing time zone abbreviations,   in decreasing order of importance: - </p> -  +    <ul>    <li> -  Use three to six characters that are ASCII alphanumerics or +  Use three or more characters that are ASCII alphanumerics or    '<code>+</code>' or '<code>-</code>'.    Previous editions of this database also used characters like -  space and '<code>?</code>', but these characters have a -  special meaning to the -  <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a> -  and cause commands like -  '<code><a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a> -  `<a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>' +  '<code> </code>' and '<code>?</code>', but these +  characters have a special meaning to +  the shell and cause commands like +  '<code>set `date`</code>'    to have unexpected effects. -  Previous editions of this guideline required upper-case letters, but the -  Congressman who introduced -  <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro -  Standard Time</a> preferred "ChST", so lower-case letters are now -  allowed. -  Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>', -  '<code>+</code>', and alphanumeric characters from the portable -  character set in the current locale. -  In practice ASCII alphanumerics and '<code>+</code>' and -  '<code>-</code>' are safe in all locales. +  Previous editions of this rule required upper-case letters, +  but the Congressman who introduced Chamorro Standard Time +  preferred "ChST", so lower-case letters are now allowed. +  Also, POSIX from 2001 on relaxed the rule to allow +  '<code>-</code>', '<code>+</code>', +  and alphanumeric characters from the portable character set +  in the current locale. In practice ASCII alphanumerics and +  '<code>+</code>' and '<code>-</code>' are safe in all locales.    -  <p> +     In other words, in the C locale the POSIX extended regular -  expression <code>[-+[:alnum:]]{3,6}</code> should match the -  abbreviation. -  This guarantees that all abbreviations could have been specified by a -  POSIX <code>TZ</code> string. -  </p> +  expression <code>[-+[:alnum:]]{3,}</code> should match +  the abbreviation. +  This guarantees that all abbreviations could have been +  specified by a POSIX TZ string.    </li>    <li>    Use abbreviations that are in common use among English-speakers, -  e.g., 'EST' for Eastern Standard Time in North America. +  e.g. 'EST' for Eastern Standard Time in North America.    We assume that applications translate them to other languages    as part of the normal localization process; for example,    a French application might translate 'EST' to 'HNE'. -  -  <p> -  <small>These abbreviations (for standard/daylight/etc. time) are: -  ACST/ACDT Australian Central, -  AST/ADT/APT/AWT/ADDT Atlantic, -  AEST/AEDT Australian Eastern, -  AHST/AHDT Alaska-Hawaii, -  AKST/AKDT Alaska, -  AWST/AWDT Australian Western, -  BST/BDT Bering, -  CAT/CAST Central Africa, -  CET/CEST/CEMT Central European, -  ChST Chamorro, -  CST/CDT/CWT/CPT/CDDT Central [North America], -  CST/CDT China, -  GMT/BST/IST/BDST Greenwich, -  EAT East Africa, -  EST/EDT/EWT/EPT/EDDT Eastern [North America], -  EET/EEST Eastern European, -  GST Guam, -  HST/HDT Hawaii, -  HKT/HKST Hong Kong, -  IST India, -  IST/GMT Irish, -  IST/IDT/IDDT Israel, -  JST/JDT Japan, -  KST/KDT Korea, -  MET/MEST Middle European (a backward-compatibility alias for -  Central European), -  MSK/MSD Moscow, -  MST/MDT/MWT/MPT/MDDT Mountain, -  NST/NDT/NWT/NPT/NDDT Newfoundland, -  NST/NDT/NWT/NPT Nome, -  NZMT/NZST New Zealand through 1945, -  NZST/NZDT New Zealand 1946&ndash;present, -  PKT/PKST Pakistan, -  PST/PDT/PWT/PPT/PDDT Pacific, -  SAST South Africa, -  SST Samoa, -  WAT/WAST West Africa, -  WET/WEST/WEMT Western European, -  WIB Waktu Indonesia Barat, -  WIT Waktu Indonesia Timur, -  WITA Waktu Indonesia Tengah, -  YST/YDT/YWT/YPT/YDDT Yukon</small>. -  </p> +     </li>    <li> -  <p> -  For times taken from a city's longitude, use the -  traditional <var>x</var>MT notation. -  The only abbreviation like this in current use is '<abbr>GMT</abbr>'. -  The others are for timestamps before 1960, -  except that Monrovia Mean Time persisted until 1972. -  Typically, numeric abbreviations (e.g., '<code>-</code>004430' for -  MMT) would cause trouble here, as the numeric strings would exceed -  the POSIX length limit. -  </p> -  -  <p> -  <small>These abbreviations are: -  AMT Amsterdam, Asunción, Athens; -  BMT Baghdad, Bangkok, Batavia, Bern, Bogotá, Bridgetown, Brussels, -  Bucharest; -  CMT Calamarca, Caracas, Chisinau, Colón, Copenhagen, Córdoba; -  DMT Dublin/Dunsink; -  EMT Easter; -  FFMT Fort-de-France; -  FMT Funchal; -  GMT Greenwich; -  HMT Havana, Helsinki, Horta, Howrah; -  IMT Irkutsk, Istanbul; -  JMT Jerusalem; -  KMT Kaunas, Kiev, Kingston; -  LMT Lima, Lisbon, local, Luanda; -  MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo, -  Moratuwa, Moscow; -  PLMT Phù Liễn; -  PMT Paramaribo, Paris, Perm, Pontianak, Prague; -  PMMT Port Moresby; -  QMT Quito; -  RMT Rangoon, Riga, Rome; -  SDMT Santo Domingo; -  SJMT San José; -  SMT Santiago, Simferopol, Singapore, Stanley; -  TBMT Tbilisi; -  TMT Tallinn, Tehran; -  WMT Warsaw</small>. -  </p> -  -  <p> -  <small>A few abbreviations also follow the pattern that -  <abbr>GMT<abbr>/<abbr>BST</abbr> established for time in the UK. -  They are: -  CMT/BST for Calamarca Mean Time and Bolivian Summer Time -  1890&ndash;1932, -  DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time -  1880&ndash;1916, -  MMT/MST/MDST for Moscow 1880&ndash;1919, and -  RMT/LST for Riga Mean Time and Latvian Summer time 1880&ndash;1926. -  An extra-special case is SET for Swedish Time (<em>svensk -  normaltid</em>) 1879&ndash;1899, 3&deg; west of the Stockholm -  Observatory.</small> -  </p> +  For zones whose times are taken from a city's longitude, use the +  traditional <var>x</var>MT notation, e.g. 'PMT' for +  Paris Mean Time. +  The only name like this in current use is 'GMT'.    </li>    <li> -  Use '<abbr>LMT</abbr>' for local mean time of locations before the -  introduction of standard time; see "<a href="#scope">Scope of the -  <code><abbr>tz</abbr></code> database</a>". +  Use 'LMT' for local mean time of locations before the introduction +  of standard time; see "<a href="#scope">Scope of the +  tz database</a>".    </li>    <li>    If there is no common English abbreviation, use numeric offsets like -  <code>-</code>05 and <code>+</code>0830 that are generated -  by <code>zic</code>'s <code>%z</code> notation. +  <code>-</code>05 and <code>+</code>0830 that are +  generated by zic's <code>%z</code> notation.    </li>    <li>    Use current abbreviations for older timestamps to avoid confusion. -  For example, in 1910 a common English abbreviation for time +  For example, in 1910 a common English abbreviation for UT +01    in central Europe was 'MEZ' (short for both "Middle European -  Zone" and for "Mitteleuropäische Zeit" in German). -  Nowadays 'CET' ("Central European Time") is more common in -  English, and the database uses 'CET' even for circa-1910 -  timestamps as this is less confusing for modern users and avoids -  the need for determining when 'CET' supplanted 'MEZ' in common -  usage. +  Zone" and for "Mitteleuropäische Zeit" in German). Nowadays +  'CET' ("Central European Time") is more common in English, and +  the database uses 'CET' even for circa-1910 timestamps as this +  is less confusing for modern users and avoids the need for +  determining when 'CET' supplanted 'MEZ' in common usage.    </li>    <li> -  Use a consistent style in a <code><abbr>tz</abbr></code> region's history. -  For example, if history tends to use numeric -  abbreviations and a particular entry could go either way, use a -  numeric abbreviation. +  Use a consistent style in a zone's history. For example, if a zone's +  history tends to use numeric abbreviations and a particular +  entry could go either way, use a numeric abbreviation.    </li> -  + </ul> +  [The remaining guidelines predate the introduction of <code>%z</code>. +  They are problematic as they mean tz data entries invent +  notation rather than record it. These guidelines are now +  deprecated and the plan is to gradually move to <code>%z</code> for +  inhabited locations and to "<code>-</code>00" for uninhabited locations.] + <ul>    <li> -  Use -  <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a> -  (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for -  locations while uninhabited. -  The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in -  some sense undefined; this notation is derived -  from <a href="https://tools.ietf.org/html/rfc3339">Internet -  <abbr title="Request For Comments">RFC 3339</a>. +  If there is no common English abbreviation, abbreviate the English +  translation of the usual phrase used by native speakers. +  If this is not available or is a phrase mentioning the country +  (e.g. "Cape Verde Time"), then: +  <ul> +  <li> +  When a country is identified with a single or principal zone, +  append 'T' to the country's ISO code, e.g. 'CVT' for +  Cape Verde Time. For summer time append 'ST'; +  for double summer time append 'DST'; etc.    </li> -  +  <li> +  Otherwise, take the first three letters of an English place +  name identifying each zone and append 'T', 'ST', etc. +  as before; e.g. 'CHAST' for CHAtham Summer Time. +  </li>    </ul> -  +  </li> +  <li> +  Use UT (with time zone abbreviation '<code>-</code>00') for +  locations while uninhabited. The leading +  '<code>-</code>' is a flag that the time +  zone is in some sense undefined; this notation is +  derived from Internet RFC 3339. +  </li> + </ul>   <p>   Application writers should note that these abbreviations are ambiguous - in practice: e.g., 'CST' means one thing in China and something else - in North America, and 'IST' can refer to time in India, Ireland or - Israel. - To avoid ambiguity, use numeric <abbr>UT</abbr> offsets like - '<code>-</code>0600' instead of time zone abbreviations like 'CST'. + in practice: e.g. 'CST' has a different meaning in China than + it does in the United States. In new applications, it's often better + to use numeric UT offsets like '<code>-</code>0600' instead of time zone + abbreviations like 'CST'; this avoids the ambiguity.   </p>    </section>    -  +     <section> -  <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2> +  <h2 id="accuracy">Accuracy of the tz database</h2>   <p> - The <code><abbr>tz</abbr></code> database is not authoritative, and it - surely has errors. - Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. + The tz database is not authoritative, and it surely has errors. + Corrections are welcome and encouraged; see the file CONTRIBUTING.   Users requiring authoritative data should consult national standards   bodies and the references cited in the database's comments.   </p>      <p> - Errors in the <code><abbr>tz</abbr></code> database arise from many sources: + Errors in the tz database arise from many sources:   </p> -  +    <ul>    <li> -  The <code><abbr>tz</abbr></code> database predicts future -  timestamps, and current predictions +  The tz database predicts future timestamps, and current predictions    will be incorrect after future governments change the rules.    For example, if today someone schedules a meeting for 13:00 next    October 1, Casablanca time, and tomorrow Morocco changes its
542:    <li>    The pre-1970 entries in this database cover only a tiny sliver of how    clocks actually behaved; the vast majority of the necessary -  information was lost or never recorded. -  Thousands more <code><abbr>tz</abbr></code> regions would be needed if -  the <code><abbr>tz</abbr></code> database's scope were extended to -  cover even just the known or guessed history of standard time; for -  example, the current single entry for France would need to split -  into dozens of entries, perhaps hundreds. -  And in most of the world even this approach would be misleading -  due to widespread disagreement or indifference about what times -  should be observed. -  In her 2015 book -  <cite><a -  href="http://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The -  Global Transformation of Time, 1870&ndash;1950</a></cite>, -  Vanessa Ogle writes +  information was lost or never recorded. Thousands more zones would +  be needed if the tz database's scope were extended to cover even +  just the known or guessed history of standard time; for example, +  the current single entry for France would need to split into dozens +  of entries, perhaps hundreds. And in most of the world even this +  approach would be misleading due to widespread disagreement or +  indifference about what times should be observed. In her 2015 book +  <cite>The Global Transformation of Time, 1870-1950</cite>, Vanessa Ogle writes    "Outside of Europe and North America there was no system of time    zones at all, often not even a stable landscape of mean times, -  prior to the middle decades of the twentieth century". -  See: Timothy Shenk, <a +  prior to the middle decades of the twentieth century". See: +  Timothy Shenk, <a   href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked:    A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17.    </li>
573:    typically found to be incorrect.    </li>    <li> -  For the UK the <code><abbr>tz</abbr></code> database relies on -  years of first-class work done by +  For the UK the tz database relies on years of first-class work done by    Joseph Myers and others; see    "<a href="https://www.polyomino.org.uk/british-time/">History of    legal time in Britain</a>".    Other countries are not done nearly as well.    </li>    <li> -  Sometimes, different people in the same city maintain clocks -  that differ significantly. -  Historically, railway time was used by railroad companies (which -  did not always -  agree with each other), church-clock time was used for birth -  certificates, etc. -  More recently, competing political groups might disagree about -  clock settings. Often this is merely common practice, but -  sometimes it is set by law. -  For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France -  was legally <abbr>UT</abbr> +00:09:21 outside train stations and -  <abbr>UT</abbr> +00:04:21 inside. Other examples include -  Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and -  Ürümqi to this day. +  Sometimes, different people in the same city would maintain clocks +  that differed significantly. Railway time was used by railroad +  companies (which did not always agree with each other), +  church-clock time was used for birth certificates, etc. +  Often this was merely common practice, but sometimes it was set by law. +  For example, from 1891 to 1911 the UT offset in France was legally +  0:09:21 outside train stations and 0:04:21 inside.    </li>    <li> -  Although a named location in the <code><abbr>tz</abbr></code> -  database stands for the containing region, its pre-1970 data -  entries are often accurate for only a small subset of that region. -  For example, <code>Europe/London</code> stands for the United -  Kingdom, but its pre-1847 times are valid only for locations that -  have London's exact meridian, and its 1847 transition -  to <abbr>GMT</abbr> is known to be valid only for the L&amp;NW and -  the Caledonian railways. +  Although a named location in the tz database stands for the +  containing region, its pre-1970 data entries are often accurate for +  only a small subset of that region. For example, <code>Europe/London</code> +  stands for the United Kingdom, but its pre-1847 times are valid +  only for locations that have London's exact meridian, and its 1847 +  transition to GMT is known to be valid only for the L&amp;NW and the +  Caledonian railways.    </li>    <li> -  The <code><abbr>tz</abbr></code> database does not record the -  earliest time for which a <code><abbr>tz</abbr></code> region's +  The tz database does not record the earliest time for which a zone's    data entries are thereafter valid for every location in the region. -  For example, <code>Europe/London</code> is valid for all locations -  in its region after <abbr>GMT</abbr> was made the standard time, -  but the date of standardization (1880-08-02) is not in the -  <code><abbr>tz</abbr></code> database, other than in commentary. -  For many <code><abbr>tz</abbr></code> regions the earliest time of -  validity is unknown. +  For example, <code>Europe/London</code> is valid for all locations in its +  region after GMT was made the standard time, but the date of +  standardization (1880-08-02) is not in the tz database, other than +  in commentary. For many zones the earliest time of validity is +  unknown.    </li>    <li> -  The <code><abbr>tz</abbr></code> database does not record a -  region's boundaries, and in many cases the boundaries are not known. -  For example, the <code><abbr>tz</abbr></code> region -  <code>America/Kentucky/Louisville</code> represents a region -  around the city of Louisville, the boundaries of which are -  unclear. +  The tz database does not record a region's boundaries, and in many +  cases the boundaries are not known. For example, the zone +  <code>America/Kentucky/Louisville</code> represents a region around +  the city of +  Louisville, the boundaries of which are unclear.    </li>    <li> -  Changes that are modeled as instantaneous transitions in the -  <code><abbr>tz</abbr></code> +  Changes that are modeled as instantaneous transitions in the tz    database were often spread out over hours, days, or even decades.    </li>    <li>
636:    </li>    <li>    Early timekeeping practices, even assuming perfect clocks, were -  often not specified to the accuracy that the -  <code><abbr>tz</abbr></code> database requires. +  often not specified to the accuracy that the tz database requires.    </li>    <li>    Sometimes historical timekeeping was specified more precisely -  than what the <code><abbr>tz</abbr></code> code can handle. -  For example, from 1909 to 1937 <a -  href="https://www.staff.science.uu.nl/~gent0113/wettijd/wettijd.htm" -  hreflang="nl">Netherlands clocks</a> were legally Amsterdam Mean -  Time (estimated to be <abbr>UT</abbr> -  +00:19:32.13), but the <code><abbr>tz</abbr></code> -  code cannot represent the fractional second. -  In practice these old specifications were rarely if ever -  implemented to subsecond precision. +  than what the tz database can handle. For example, from 1909 to +  1937 Netherlands clocks were legally UT +00:19:32.13, but the tz +  database cannot represent the fractional second.    </li>    <li> -  Even when all the timestamp transitions recorded by the -  <code><abbr>tz</abbr></code> database are correct, the -  <code><abbr>tz</abbr></code> rules that generate them may not -  faithfully reflect the historical rules. -  For example, from 1922 until World War II the UK moved clocks -  forward the day following the third Saturday in April unless that -  was Easter, in which case it moved clocks forward the previous -  Sunday. -  Because the <code><abbr>tz</abbr></code> database has no +  Even when all the timestamp transitions recorded by the tz database +  are correct, the tz rules that generate them may not faithfully +  reflect the historical rules. For example, from 1922 until World +  War II the UK moved clocks forward the day following the third +  Saturday in April unless that was Easter, in which case it moved +  clocks forward the previous Sunday. Because the tz database has no    way to specify Easter, these exceptional years are entered as -  separate <code><abbr>tz</abbr> Rule</code> lines, even though the -  legal rules did not change. +  separate tz Rule lines, even though the legal rules did not change.    </li>    <li> -  The <code><abbr>tz</abbr></code> database models pre-standard time -  using the <a -  href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic -  Gregorian calendar</a> and local mean time, but many people used -  other calendars and other timescales. -  For example, the Roman Empire used -  the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian -  calendar</a>, -  and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman -  timekeeping</a> had twelve varying-length daytime hours with a +  The tz database models pre-standard time using the proleptic Gregorian +  calendar and local mean time (LMT), but many people used other +  calendars and other timescales. For example, the Roman Empire used +  the Julian calendar, and had 12 varying-length daytime hours with a    non-hour-based system at night.    </li>    <li>
683:    clock error.    </li>    <li> -  The <code><abbr>tz</abbr></code> database assumes Universal Time -  (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not -  standardized for older timestamps. -  In the <code><abbr>tz</abbr></code> database commentary, -  <abbr>UT</abbr> denotes a family of time standards that includes -  Coordinated Universal Time (<abbr>UTC</abbr>) along with other -  variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>, -  with days starting at midnight. -  Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern -  timestamps, <abbr>UTC</abbr> was not defined until 1960, so -  commentary uses the more-general abbreviation <abbr>UT</abbr> for -  timestamps that might predate 1960. -  Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly, -  and since pre-1972 <abbr>UTC</abbr> seconds varied in length, -  interpretation of older timestamps can be problematic when -  subsecond accuracy is needed. +  The tz database assumes Universal Time (UT) as an origin, even +  though UT is not standardized for older timestamps. In the tz +  database commentary, UT denotes a family of time standards that +  includes Coordinated Universal Time (UTC) along with other variants +  such as UT1 and GMT, with days starting at midnight. Although UT +  equals UTC for modern timestamps, UTC was not defined until 1960, +  so commentary uses the more-general abbreviation UT for timestamps +  that might predate 1960. Since UT, UT1, etc. disagree slightly, +  and since pre-1972 UTC seconds varied in length, interpretation of +  older timestamps can be problematic when subsecond accuracy is +  needed.    </li>    <li> -  Civil time was not based on atomic time before 1972, and we do not -  know the history of -  <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's -  rotation</a> accurately enough to map <a -  href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr -  title="International System of Units">SI</abbr></a> seconds to -  historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a> -  to more than about one-hour accuracy. -  See: Stephenson FR, Morrison LV, Hohenkerk CY. -  <a href="http://dx.doi.org/10.1098/rspa.2016.0404">Measurement of -  the Earth's rotation: 720 BC to AD 2015</a>. +  Civil time was not based on atomic time before 1972, and we don't +  know the history of earth's rotation accurately enough to map SI +  seconds to historical solar time to more than about one-hour +  accuracy. See: Stephenson FR, Morrison LV, Hohenkerk CY. +  <a href="http://dx.doi.org/10.1098/rspa.2016.0404">Measurement +  of the Earth's rotation: 720 BC to AD 2015</a>.    <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404.    Also see: Espenak F. <a    href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty    in Delta T (ΔT)</a>.    </li>    <li> -  The relationship between POSIX time (that is, <abbr>UTC</abbr> but -  ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap -  seconds</a>) and <abbr>UTC</abbr> is not agreed upon after 1972. -  Although the POSIX +  The relationship between POSIX time (that is, UTC but ignoring leap +  seconds) and UTC is not agreed upon after 1972. Although the POSIX    clock officially stops during an inserted leap second, at least one    proposed standard has it jumping back a second instead; and in    practice POSIX clocks more typically either progress glacially during    a leap second, or are slightly slowed while near a leap second.    </li>    <li> -  The <code><abbr>tz</abbr></code> database does not represent how -  uncertain its information is. +  The tz database does not represent how uncertain its information is.    Ideally it would contain information about when data entries are -  incomplete or dicey. -  Partial temporal knowledge is a field of active research, though, -  and it is not clear how to apply it here. +  incomplete or dicey. Partial temporal knowledge is a field of +  active research, though, and it's not clear how to apply it here.    </li>   </ul> -  +    <p> - In short, many, perhaps most, of the <code><abbr>tz</abbr></code> - database's pre-1970 and future timestamps are either wrong or - misleading. - Any attempt to pass the - <code><abbr>tz</abbr></code> database off as the definition of time - should be unacceptable to anybody who cares about the facts. - In particular, the <code><abbr>tz</abbr></code> database's - <abbr>LMT</abbr> offsets should not be considered meaningful, and - should not prompt creation of <code><abbr>tz</abbr></code> regions - merely because two locations - differ in <abbr>LMT</abbr> or transitioned to standard time at - different dates. + In short, many, perhaps most, of the tz database's pre-1970 and future + timestamps are either wrong or misleading. Any attempt to pass the + tz database off as the definition of time should be unacceptable to + anybody who cares about the facts. In particular, the tz database's + LMT offsets should not be considered meaningful, and should not prompt + creation of zones merely because two locations differ in LMT or + transitioned to standard time at different dates.   </p>    </section>    -  +     <section>    <h2 id="functions">Time and date functions</h2>   <p> - The <code><abbr>tz</abbr></code> code contains time and date functions - that are upwards compatible with those of POSIX. - Code compatible with this package is already - <a href="tz-link.html#tzdb">part of many platforms</a>, where the - primary use of this package is to update obsolete time-related files. - To do this, you may need to compile the time zone compiler - '<code>zic</code>' supplied with this package instead of using the - system '<code>zic</code>', since the format of <code>zic</code>'s - input is occasionally extended, and a platform may still be shipping - an older <code>zic</code>. + The tz code contains time and date functions that are upwards + compatible with those of POSIX.   </p>    - <h3 id="POSIX">POSIX properties and limitations</h3> + <p> + POSIX has the following properties and limitations. + </p>   <ul>    <li>    <p>    In POSIX, time display in a process is controlled by the -  environment variable <code>TZ</code>. -  Unfortunately, the POSIX -  <code>TZ</code> string takes a form that is hard to describe and -  is error-prone in practice. -  Also, POSIX <code>TZ</code> strings cannot deal with daylight -  saving time rules not based on the Gregorian calendar (as in -  Iran), or with situations where more than two time zone -  abbreviations or <abbr>UT</abbr> offsets are used in an area. +  environment variable TZ. Unfortunately, the POSIX TZ string takes +  a form that is hard to describe and is error-prone in practice. +  Also, POSIX TZ strings can't deal with other (for example, Israeli) +  daylight saving time rules, or situations where more than two +  time zone abbreviations are used in an area.    </p> -  +     <p> -  The POSIX <code>TZ</code> string takes the following form: +  The POSIX TZ string takes the following form:    </p> -  +     <p>    <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>]]]    </p> -  +     <p>    where: -  </p> -  +     <dl>    <dt><var>std</var> and <var>dst</var></dt><dd>    are 3 or more characters specifying the standard -  and daylight saving time (<abbr>DST</abbr>) zone names. -  Starting with POSIX.1-2001, <var>std</var> and <var>dst</var> -  may also be in a quoted form like '<code>&lt;+09&gt;</code>'; -  this allows "<code>+</code>" and "<code>-</code>" in the names. +  and daylight saving time (DST) zone names. +  Starting with POSIX.1-2001, <var>std</var> +  and <var>dst</var> may also be +  in a quoted form like '<code>&lt;UTC+10&gt;</code>'; this allows +  "<code>+</code>" and "<code>-</code>" in the names.    </dd>    <dt><var>offset</var></dt><dd>    is of the form    '<code>[&plusmn;]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' -  and specifies the offset west of <abbr>UT</abbr>. -  '<var>hh</var>' may be a single digit; -  0&le;<var>hh</var>&le;24. -  The default <abbr>DST</abbr> offset is one hour ahead of -  standard time. +  and specifies the offset west of UT. '<var>hh</var>' +  may be a single digit; 0&le;<var>hh</var>&le;24. +  The default DST offset is one hour ahead of standard time.    </dd>    <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> -  specifies the beginning and end of <abbr>DST</abbr>. -  If this is absent, the system supplies its own ruleset -  for <abbr>DST</abbr>, and its rules can differ from year to year; -  typically <abbr>US</abbr> <abbr>DST</abbr> rules are used. +  specifies the beginning and end of DST. If this is absent, +  the system supplies its own rules for DST, and these can +  differ from year to year; typically US DST rules are used.    </dd>    <dt><var>time</var></dt><dd>    takes the form
834:    <dt><var>n</var> (0&le;<var>n</var>&le;365)</dt><dd>    origin-0 day number counting February 29 if present    </dd> -  <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> -  (0[Sunday]&le;<var>d</var>&le;6[Saturday], 1&le;<var>n</var>&le;5, -  1&le;<var>m</var>&le;12)</dt><dd> -  for the <var>d</var>th day of week <var>n</var> of -  month <var>m</var> of the year, where week 1 is the first -  week in which day <var>d</var> appears, and -  '<code>5</code>' stands for the last week in which -  day <var>d</var> appears (which may be either the 4th or -  5th week). -  Typically, this is the only useful form; the <var>n</var> -  and <code>J</code><var>n</var> forms are rarely used. +  <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> (0[Sunday]&le;<var>d</var>&le;6[Saturday], 1&le;<var>n</var>&le;5, 1&le;<var>m</var>&le;12)</dt><dd> +  for the <var>d</var>th day of +  week <var>n</var> of month <var>m</var> of the +  year, where week 1 is the first week in which +  day <var>d</var> appears, and '<code>5</code>' +  stands for the last week in which +  day <var>d</var> appears +  (which may be either the 4th or 5th week). +  Typically, this is the only useful form; +  the <var>n</var> +  and <code>J</code><var>n</var> forms are +  rarely used.    </dd>   </dl>   </dd>   </dl> -  +  Here is an example POSIX TZ string for New Zealand after 2007. +  It says that standard time (NZST) is 12 hours ahead of UTC, +  and that daylight saving time (NZDT) is observed from September's +  last Sunday at 02:00 until April's first Sunday at 03:00:    -  <p> -  Here is an example POSIX <code>TZ</code> string for New -  Zealand after 2007. -  It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead -  of <abbr>UT</abbr>, and that daylight saving time -  (<abbr>NZDT</abbr>) is observed from September's last Sunday at -  02:00 until April's first Sunday at 03:00: -  </p> -  +     <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>    -  <p> -  This POSIX <code>TZ</code> string is hard to remember, and -  mishandles some timestamps before 2008. -  With this package you can use this instead: -  </p> +  This POSIX TZ string is hard to remember, and mishandles some +  timestamps before 2008. With this package you can use this +  instead:       <pre><code>TZ='Pacific/Auckland'</code></pre>    </li>    <li> -  POSIX does not define the exact meaning of <code>TZ</code> values like +  POSIX does not define the exact meaning of TZ values like    "<code>EST5EDT</code>". -  Typically the current <abbr>US</abbr> <abbr>DST</abbr> rules -  are used to interpret such values, but this means that the -  <abbr>US</abbr> <abbr>DST</abbr> rules are compiled into each -  program that does time conversion. -  This means that when -  <abbr>US</abbr> time conversion rules change (as in the United -  States in 1987), all programs that do time conversion must be -  recompiled to ensure proper results. +  Typically the current US DST rules are used to interpret such values, +  but this means that the US DST rules are compiled into each program +  that does time conversion. This means that when US time conversion +  rules change (as in the United States in 1987), all programs that +  do time conversion must be recompiled to ensure proper results.    </li>    <li> -  The <code>TZ</code> environment variable is process-global, which -  makes it hard to write efficient, thread-safe applications that -  need access to multiple time zone rulesets. +  The TZ environment variable is process-global, which makes it hard +  to write efficient, thread-safe applications that need access +  to multiple time zones.    </li>    <li> -  In POSIX, there is no tamper-proof way for a process to learn the -  system's best idea of local wall clock. -  (This is important for applications that an administrator wants -  used only at certain times &ndash; without regard to whether the -  user has fiddled the -  <code>TZ</code> environment variable. -  While an administrator can "do everything in <abbr>UT</abbr>" to -  get around the problem, doing so is inconvenient and precludes -  handling daylight saving time shifts - as might be required to -  limit phone calls to off-peak hours.) +  In POSIX, there's no tamper-proof way for a process to learn the +  system's best idea of local wall clock. (This is important for +  applications that an administrator wants used only at certain +  times &ndash; +  without regard to whether the user has fiddled the TZ environment +  variable. While an administrator can "do everything in UTC" to get +  around the problem, doing so is inconvenient and precludes handling +  daylight saving time shifts - as might be required to limit phone +  calls to off-peak hours.)    </li>    <li> -  POSIX provides no convenient and efficient way to determine -  the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary -  timestamps, particularly for <code><abbr>tz</abbr></code> regions -  that do not fit into the POSIX model. +  POSIX provides no convenient and efficient way to determine the UT +  offset and time zone abbreviation of arbitrary timestamps, +  particularly for time zone settings that do not fit into the +  POSIX model.    </li>    <li>    POSIX requires that systems ignore leap seconds.    </li>    <li> -  The <code><abbr>tz</abbr></code> code attempts to support all the -  <code>time_t</code> implementations allowed by POSIX. -  The <code>time_t</code> type represents a nonnegative count of seconds -  since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds. -  In practice, <code>time_t</code> is usually a signed 64- or 32-bit -  integer; 32-bit signed <code>time_t</code> values stop working after -  2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these -  days typically use a signed 64-bit integer. -  Unsigned 32-bit integers are used on one or two platforms, and 36-bit -  and 40-bit integers are also used occasionally. +  The tz code attempts to support all the <code>time_t</code> +  implementations allowed by POSIX. The <code>time_t</code> +  type represents a nonnegative count of +  seconds since 1970-01-01 00:00:00 UTC, ignoring leap seconds. +  In practice, <code>time_t</code> is usually a signed 64- or +  32-bit integer; 32-bit signed <code>time_t</code> values stop +  working after 2038-01-19 03:14:07 UTC, so +  new implementations these days typically use a signed 64-bit integer. +  Unsigned 32-bit integers are used on one or two platforms, +  and 36-bit and 40-bit integers are also used occasionally.    Although earlier POSIX versions allowed <code>time_t</code> to be a -  floating-point type, this was not supported by any practical systems, -  and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both -  require <code>time_t</code> to be an integer type. +  floating-point type, this was not supported by any practical +  systems, and POSIX.1-2013 and the tz code both +  require <code>time_t</code> +  to be an integer type.    </li>   </ul> -  - <h3 id="POSIX-extensions">Extensions to POSIX in the - <code><abbr>tz</abbr></code> code</h3> + <p> + These are the extensions that have been made to the POSIX functions: + </p>   <ul>    <li>    <p> -  The <code>TZ</code> environment variable is used in generating -  the name of a binary file from which time-related information is read -  (or is interpreted à la POSIX); <code>TZ</code> is no longer -  constrained to be a three-letter time zone -  abbreviation followed by a number of hours and an optional three-letter -  daylight time zone abbreviation. -  The daylight saving time rules to be used for a -  particular <code><abbr>tz</abbr></code> region are encoded in the -  binary file; the format of the file -  allows U.S., Australian, and other rules to be encoded, and -  allows for situations where more than two time zone +  The TZ environment variable is used in generating the name of a file +  from which time zone information is read (or is interpreted a la +  POSIX); TZ is no longer constrained to be a three-letter time zone +  name followed by a number of hours and an optional three-letter +  daylight time zone name. The daylight saving time rules to be used +  for a particular time zone are encoded in the time zone file; +  the format of the file allows U.S., Australian, and other rules to be +  encoded, and allows for situations where more than two time zone    abbreviations are used.    </p>    <p> -  It was recognized that allowing the <code>TZ</code> environment -  variable to take on values such as '<code>America/New_York</code>' -  might cause "old" programs (that expect <code>TZ</code> to have a -  certain form) to operate incorrectly; consideration was given to using -  some other environment variable (for example, <code>TIMEZONE</code>) -  to hold the string used to generate the binary file's name. -  In the end, however, it was decided to continue using -  <code>TZ</code>: it is widely used for time zone purposes; -  separately maintaining both <code>TZ</code> -  and <code>TIMEZONE</code> seemed a nuisance; and systems where -  "new" forms of <code>TZ</code> might cause problems can simply -  use <code>TZ</code> values such as "<code>EST5EDT</code>" which -  can be used both by "new" programs (à la POSIX) and "old" -  programs (as zone names and offsets). +  It was recognized that allowing the TZ environment variable to +  take on values such as '<code>America/New_York</code>' might +  cause "old" programs +  (that expect TZ to have a certain form) to operate incorrectly; +  consideration was given to using some other environment variable +  (for example, TIMEZONE) to hold the string used to generate the +  time zone information file name. In the end, however, it was decided +  to continue using TZ: it is widely used for time zone purposes; +  separately maintaining both TZ and TIMEZONE seemed a nuisance; +  and systems where "new" forms of TZ might cause problems can simply +  use TZ values such as "<code>EST5EDT</code>" which can be used both by +  "new" programs (a la POSIX) and "old" programs (as zone names and +  offsets).    </p>   </li>   <li> -  The code supports platforms with a <abbr>UT</abbr> offset member -  in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>. +  The code supports platforms with a UT offset member +  in <code>struct tm</code>, +  e.g., <code>tm_gmtoff</code>.   </li>   <li>    The code supports platforms with a time zone abbreviation member in    <code>struct tm</code>, e.g., <code>tm_zone</code>.   </li>   <li> -  +  Since the TZ environment variable can now be used to control time +  conversion, the <code>daylight</code> +  and <code>timezone</code> variables are no longer needed. +  (These variables are defined and set by <code>tzset</code>; +  however, their values will not be used +  by <code>localtime</code>.) + </li> + <li>    Functions <code>tzalloc</code>, <code>tzfree</code>,    <code>localtime_rz</code>, and <code>mktime_z</code> for -  more-efficient thread-safe applications that need to use multiple -  time zone rulesets. -  The <code>tzalloc</code> and <code>tzfree</code> functions -  allocate and free objects of type <code>timezone_t</code>, -  and <code>localtime_rz</code> and <code>mktime_z</code> are -  like <code>localtime_r</code> and <code>mktime</code> with an -  extra <code>timezone_t</code> argument. -  The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>. +  more-efficient thread-safe applications that need to use +  multiple time zones. The <code>tzalloc</code> +  and <code>tzfree</code> functions allocate and free objects of +  type <code>timezone_t</code>, and <code>localtime_rz</code> +  and <code>mktime_z</code> are like <code>localtime_r</code> +  and <code>mktime</code> with an extra +  <code>timezone_t</code> argument. The functions were inspired +  by NetBSD.   </li>   <li> -  A function <code>tzsetwall</code> has been added to arrange for the -  system's best approximation to local wall clock time to be delivered -  by subsequent calls to <code>localtime</code>. -  Source code for portable applications that "must" run on local wall -  clock time should call <code>tzsetwall</code>; -  if such code is moved to "old" systems that do not -  provide <code>tzsetwall</code>, you will not be able to generate an -  executable program. -  (These functions also arrange for local wall clock time to -  be used if <code>tzset</code> is called &ndash; directly or -  indirectly &ndash; and there is no <code>TZ</code> environment -  variable; portable applications should not, however, rely on this -  behavior since it is not the way <a -  href="https://en.wikipedia.org/wiki/UNIX_System_V#SVR2"><abbr>SVR2</abbr></a> -  systems behave.) +  A function <code>tzsetwall</code> has been added to arrange +  for the system's +  best approximation to local wall clock time to be delivered by +  subsequent calls to <code>localtime</code>. Source code for portable +  applications that "must" run on local wall clock time should call +  <code>tzsetwall</code>; if such code is moved to "old" systems that don't +  provide tzsetwall, you won't be able to generate an executable program. +  (These time zone functions also arrange for local wall clock time to be +  used if tzset is called &ndash; directly or indirectly &ndash; +  and there's no TZ +  environment variable; portable applications should not, however, rely +  on this behavior since it's not the way SVR2 systems behave.)    </li>    <li>    Negative <code>time_t</code> values are supported, on systems
1005:    These functions can account for leap seconds, thanks to Bradley White.    </li>   </ul> -  - <h3 id="vestigial">POSIX features no longer needed</h3> +    <p> - POSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a> - define some <a href="https://en.wikipedia.org/wiki/API"><abbr - title="application programming interface">API</abbr>s</a> that are vestigial: - they are not needed, and are relics of a too-simple model that does - not suffice to handle many real-world timestamps. - Although the <code><abbr>tz</abbr></code> code supports these - vestigial <abbr>API</abbr>s for backwards compatibility, they should - be avoided in portable applications. - The vestigial <abbr>API</abbr>s are: + Points of interest to folks with other systems:   </p>   <ul>    <li> -  The POSIX <code>tzname</code> variable does not suffice and is no -  longer needed. -  To get a timestamp's time zone abbreviation, consult -  the <code>tm_zone</code> member if available; otherwise, -  use <code>strftime</code>'s <code>"%Z"</code> conversion -  specification. +  Code compatible with this package is already part of many platforms, +  including GNU/Linux, Android, the BSDs, Chromium OS, Cygwin, AIX, iOS, +  BlackBery 10, macOS, Microsoft Windows, OpenVMS, and Solaris. +  On such hosts, the primary use of this package +  is to update obsolete time zone rule tables. +  To do this, you may need to compile the time zone compiler +  '<code>zic</code>' supplied with this package instead of using +  the system '<code>zic</code>', since the format +  of <code>zic</code>'s input is occasionally extended, and a +  platform may still be shipping an older <code>zic</code>.    </li>    <li> -  The POSIX <code>daylight</code> and <code>timezone</code> -  variables do not suffice and are no longer needed. -  To get a timestamp's <abbr>UT</abbr> offset, consult -  the <code>tm_gmtoff</code> member if available; otherwise, -  subtract values returned by <code>localtime</code> -  and <code>gmtime</code> using the rules of the Gregorian calendar, -  or use <code>strftime</code>'s <code>"%z"</code> conversion -  specification if a string like <code>"+0900"</code> suffices. -  </li> -  <li> -  The <code>tm_isdst</code> member is almost never needed and most of -  its uses should be discouraged in favor of the abovementioned -  <abbr>API</abbr>s. -  Although it can still be used in arguments to -  <code>mktime</code> to disambiguate timestamps near -  a <abbr>DST</abbr> transition when the clock jumps back, this -  disambiguation does not work when standard time itself jumps back, -  which can occur when a location changes to a time zone with a -  lesser <abbr>UT</abbr> offset. -  </li> - </ul> -  - <h3 id="other-portability">Other portability notes</h3> - <ul> -  <li> -  The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition -  UNIX</a> <code>timezone</code> function is not present in this -  package; it is impossible to reliably map <code>timezone</code>'s -  arguments (a "minutes west of <abbr>GMT</abbr>" value and a -  "daylight saving time in effect" flag) to a time zone -  abbreviation, and we refuse to guess. -  Programs that in the past used the <code>timezone</code> function -  may now examine <code>localtime(&amp;clock)-&gt;tm_zone</code> +  The UNIX Version 7 <code>timezone</code> function is not +  present in this package; +  it's impossible to reliably map timezone's arguments (a "minutes west +  of GMT" value and a "daylight saving time in effect" flag) to a +  time zone abbreviation, and we refuse to guess. +  Programs that in the past used the timezone function may now examine +  <code>localtime(&amp;clock)-&gt;tm_zone</code>    (if <code>TM_ZONE</code> is defined) or    <code>tzname[localtime(&amp;clock)-&gt;tm_isdst]</code> -  (if <code>HAVE_TZNAME</code> is defined) to learn the correct time -  zone abbreviation to use. +  (if <code>HAVE_TZNAME</code> is defined) +  to learn the correct time zone abbreviation to use.    </li>    <li> -  The <a -  href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a> -  <code>gettimeofday</code> function is not -  used in this package. -  This formerly let users obtain the current <abbr>UTC</abbr> offset -  and <abbr>DST</abbr> flag, but this functionality was removed in -  later versions of <abbr>BSD</abbr>. +  The 4.2BSD <code>gettimeofday</code> function is not used in +  this package. +  This formerly let users obtain the current UTC offset and DST flag, +  but this functionality was removed in later versions of BSD.    </li>    <li> -  In <abbr>SVR2</abbr>, time conversion fails for near-minimum or -  near-maximum <code>time_t</code> values when doing conversions -  for places that do not use <abbr>UT</abbr>. +  In SVR2, time conversion fails for near-minimum or near-maximum +  <code>time_t</code> values when doing conversions for places +  that don't use UT.    This package takes care to do these conversions correctly.    A comment in the source code tells how to get compatibly wrong    results.    </li> -  <li> + </ul> + <p>   The functions that are conditionally compiled -  if <code>STD_INSPIRED</code> is defined should, at this point, be -  looked on primarily as food for thought. -  They are not in any sense "standard compatible" &ndash; some are -  not, in fact, specified in <em>any</em> standard. -  They do, however, represent responses of various authors to + if <code>STD_INSPIRED</code> is defined + should, at this point, be looked on primarily as food for thought. They are + not in any sense "standard compatible" &ndash; some are not, in fact, + specified in <em>any</em> standard. They do, however, represent responses of + various authors to   standardization proposals. -  </li> -  <li> -  Other time conversion proposals, in particular the one developed -  by folks at Hewlett Packard, offer a wider selection of functions -  that provide capabilities beyond those provided here. -  The absence of such functions from this package is not meant to -  discourage the development, standardization, or use of such -  functions. -  Rather, their absence reflects the decision to make this package -  contain valid extensions to POSIX, to ensure its broad -  acceptability. -  If more powerful time conversion functions can be standardized, so -  much the better. -  </li> - </ul> + </p> +  + <p> + Other time conversion proposals, in particular the one developed by folks at + Hewlett Packard, offer a wider selection of functions that provide capabilities + beyond those provided here. The absence of such functions from this package + is not meant to discourage the development, standardization, or use of such + functions. Rather, their absence reflects the decision to make this package + contain valid extensions to POSIX, to ensure its broad acceptability. If + more powerful time conversion functions can be standardized, so much the + better. + </p>    </section>    -  +     <section>    <h2 id="stability">Interface stability</h2>   <p> - The <code><abbr>tz</abbr></code> code and data supply the following interfaces: + The tz code and data supply the following interfaces:   </p> -  +    <ul>    <li> -  A set of <code><abbr>tz</abbr></code> region names as per -  "<a href="#naming">Names of time zone rulesets</a>" above. +  A set of zone names as per "<a href="#naming">Names of time zone +  rules</a>" above.    </li>    <li>    Library functions described in "<a href="#functions">Time and date
1146:    the text file '<code>version</code>' in each release.    </li>   </ul> -  +    <p>   Interface changes in a release attempt to preserve compatibility with - recent releases. - For example, <code><abbr>tz</abbr></code> data files typically do not - rely on recently-added <code>zic</code> features, so that users can - run older <code>zic</code> versions to process newer data files. - <a href="tz-link.html#download">Downloading - the <code><abbr>tz</abbr></code> database</a> describes how releases - are tagged and distributed. + recent releases. For example, tz data files typically do not rely on + recently-added <code>zic</code> features, so that users can run + older <code>zic</code> versions to process newer data + files. <a href="tz-link.htm">Sources for time zone and daylight + saving time data</a> describes how + releases are tagged and distributed.   </p>      <p> - Interfaces not listed above are less stable. - For example, users should not rely on particular <abbr>UT</abbr> - offsets or abbreviations for timestamps, as data entries are often - based on guesswork and these guesses may be corrected or improved. + Interfaces not listed above are less stable. For example, users + should not rely on particular UT offsets or abbreviations for + timestamps, as data entries are often based on guesswork and these + guesses may be corrected or improved.   </p>    </section>    -  +     <section>    <h2 id="calendar">Calendrical issues</h2>   <p>   Calendrical issues are a bit out of scope for a time zone database,   but they indicate the sort of problems that we would run into if we - extended the time zone database further into the past. - An excellent resource in this area is Edward M. Reingold - and Nachum Dershowitz, <cite><a - href="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical - Calculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018). - Other information and sources are given in the file '<code>calendars</code>' - in the <code><abbr>tz</abbr></code> distribution. - They sometimes disagree. + extended the time zone database further into the past. An excellent + resource in this area is Nachum Dershowitz and Edward M. Reingold, + <cite><a href="https://www.cs.tau.ac.il/~nachum/calendar-book/third-edition/">Calendrical + Calculations: Third Edition</a></cite>, Cambridge University Press (2008). + Other information and sources are given in the file '<samp>calendars</samp>' + in the tz distribution. They sometimes disagree.   </p>    </section>    -  +     <section>    <h2 id="planets">Time and time zones on other planets</h2>   <p> - Some people's work schedules - use <a href="https://en.wikipedia.org/wiki/Timekeeping on Mars">Mars time</a>. - Jet Propulsion Laboratory (JPL) coordinators kept Mars time on - and off during the - <a href="https://en.wikipedia.org/wiki/Mars_Pathfinder#End_of_mission">Mars - Pathfinder</a> mission. - Some of their family members also adapted to Mars time. - Dozens of special Mars watches were built for JPL workers who kept - Mars time during the Mars Exploration Rovers mission (2004). - These timepieces look like normal Seikos and Citizens but use Mars - seconds rather than terrestrial seconds. + Some people's work schedules use Mars time. Jet Propulsion Laboratory + (JPL) coordinators have kept Mars time on and off at least since 1997 + for the Mars Pathfinder mission. Some of their family members have + also adapted to Mars time. Dozens of special Mars watches were built + for JPL workers who kept Mars time during the Mars Exploration + Rovers mission (2004). These timepieces look like normal Seikos and + Citizens but use Mars seconds rather than terrestrial seconds.   </p>      <p>   A Mars solar day is called a "sol" and has a mean period equal to - about 24 hours 39 minutes 35.244 seconds in terrestrial time. - It is divided into a conventional 24-hour clock, so each Mars second - equals about 1.02749125 terrestrial seconds. + about 24 hours 39 minutes 35.244 seconds in terrestrial time. It is + divided into a conventional 24-hour clock, so each Mars second equals + about 1.02749125 terrestrial seconds.   </p>      <p> - The <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime - meridian</a> of Mars goes through the center of the crater - <a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in - honor of the British astronomer who built the Greenwich telescope that - defines Earth's prime meridian. - Mean solar time on the Mars prime meridian is - called <a href="https://en.wikipedia.org/wiki/Mars_Coordinated_Time">Mars - Coordinated Time (<abbr>MTC</abbr>)</a>. + The prime meridian of Mars goes through the center of the crater + Airy-0, named in honor of the British astronomer who built the + Greenwich telescope that defines Earth's prime meridian. Mean solar + time on the Mars prime meridian is called Mars Coordinated Time (MTC).   </p>      <p>   Each landed mission on Mars has adopted a different reference for   solar time keeping, so there is no real standard for Mars time zones. - For example, the - <a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars - Exploration Rover</a> project (2004) defined two time zones "Local - Solar Time A" and "Local Solar Time B" for its two missions, each zone - designed so that its time equals local true solar time at - approximately the middle of the nominal mission. - Such a "time zone" is not particularly suited for any application - other than the mission itself. + For example, the Mars Exploration Rover project (2004) defined two + time zones "Local Solar Time A" and "Local Solar Time B" for its two + missions, each zone designed so that its time equals local true solar + time at approximately the middle of the nominal mission. Such a "time + zone" is not particularly suited for any application other than the + mission itself.   </p>      <p>   Many calendars have been proposed for Mars, but none have achieved - wide acceptance. - Astronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a + wide acceptance. Astronomers often use Mars Sol Date (MSD) which is a   sequential count of Mars solar days elapsed since about 1873-12-29 - 12:00 <abbr>GMT</abbr>. + 12:00 GMT.   </p>      <p>   In our solar system, Mars is the planet with time and calendar most - like Earth's. - On other planets, Sun-based time and calendars would work quite - differently. - For example, although Mercury's - <a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal - rotation period</a> is 58.646 Earth days, Mercury revolves around the - Sun so rapidly that an observer on Mercury's equator would see a - sunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a - Mercury day. - Venus is more complicated, partly because its rotation is slightly - <a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>: - its year is 1.92 of its days. - Gas giants like Jupiter are trickier still, as their polar and - equatorial regions rotate at different rates, so that the length of a - day depends on latitude. - This effect is most pronounced on Neptune, where the day is about 12 - hours at the poles and 18 hours at the equator. + like Earth's. On other planets, Sun-based time and calendars would + work quite differently. For example, although Mercury's sidereal + rotation period is 58.646 Earth days, Mercury revolves around the Sun + so rapidly that an observer on Mercury's equator would see a sunrise + only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a Mercury + day. Venus is more complicated, partly because its rotation is + slightly retrograde: its year is 1.92 of its days. Gas giants like + Jupiter are trickier still, as their polar and equatorial regions + rotate at different rates, so that the length of a day depends on + latitude. This effect is most pronounced on Neptune, where the day is + about 12 hours at the poles and 18 hours at the equator.   </p>      <p> - Although the <code><abbr>tz</abbr></code> database does not support - time on other planets, it is documented here in the hopes that support - will be added eventually. + Although the tz database does not support time on other planets, it is + documented here in the hopes that support will be added eventually.   </p>      <p> - Sources for time on other planets: + Sources:   </p> -  +    <ul>    <li>   Michael Allison and Robert Schmunk,   "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical   Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" -  (2015-06-30). + (2012-08-08).    </li>    <li>   Jia-Rui Chong,   "<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays -  Fit for a Martian</a>", <cite>Los Angeles Times</cite> -  (2004-01-14), pp A1, A20&ndash;A21. + Fit for a Martian</a>", Los Angeles Times + (2004-01-14), pp A1, A20-A21.    </li>    <li>   Tom Chmielewski,   "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet -  Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26) + Lag Is Worse on Mars</a>", The Atlantic (2015-02-26)    </li>    <li>    Matt Williams,