Branch: Tag:

2018-04-14

2018-04-14 12:26:16 by Henrik Grubbström (Grubba) <grubba@grubba.org>

Updated to tzdata2018d.

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 tz code and data</h1> + <h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>    <h3>Outline</h3>    <nav>    <ul> -  <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="#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="#abbreviations">Time zone abbreviations</a></li> -  <li><a href="#accuracy">Accuracy of the tz database</a></li> +  <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code> +  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>
28:    </ul>    </nav>    -  +    <section> -  <h2 id="scope">Scope of the tz database</h2> +  <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>   <p> - 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. + 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 of 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.   </p>      <p>
59:   </p>      <p> - 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. + 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-2008, 2016 + 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 doesn't even really make sense to talk about a region's + "base offset", since it is not necessarily a single number.   </p> -  +    </section>    -  -  +    <section> -  <h2 id="naming">Names of time zone rules</h2> +  <h2 id="naming">Names of time zone rulesets</h2>   <p> - Each of the database's time zone rules has a unique name. + Each <code><abbr>tz</abbr></code> region has a unique name that + corresponds to a set of time zone rules.   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 '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. + 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.   </p>      <p> - The time zone rule naming conventions attempt to strike a balance + The naming conventions attempt to strike a balance   among the following goals:   </p> -  +    <ul>    <li>    Uniquely identify every region where clocks have agreed since 1970.
98:    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.
111:    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>'. + 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 rules used for choosing location names, + Here are the general guidelines used for + choosing <code><abbr>tz</abbr></code> region 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 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. +  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>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 +  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>
165:    do not need locations, since local time is not defined there.    </li>    <li> -  There should typically be at least one name for each ISO 3166-1 -  officially assigned two-letter code for an inhabited country -  or territory. +  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.    </li>    <li>    If all the clocks in a region have agreed since 1970,
177:    </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>Costa_Rica</code>' to '<code>San_Jose</code>' and '<code>Guyana</code>' to '<code>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 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. +  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>Paris</code>' to '<code>France</code>', since +  <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France +  has had multiple time zones</a>.    </li>    <li> -  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. +  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 guideline.    </li>    <li> -  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>'. +  Use the most populous among locations in a region, +  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>Canary</code>' to '<code>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>Cayman</code>' to -  '<code>Cayman_Islands</code>' and -  '<code>Guatemala</code>' to +  '<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. +  because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the +  country of Mexico has several time zones</a>.    </li>    <li>    Use '<code>_</code>' to represent a space.    </li>    <li> -  Omit '<code>.</code>' from abbreviations in names, e.g. prefer -  '<code>St_Helena</code>' to '<code>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 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. +  Do not change established names if they only marginally violate +  the above guidelines. +  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
240:      <p>   The file '<code>zone1970.tab</code>' lists geographical locations used - 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&deg; east - longitude, this relationship is not exact. + 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.   </p>      <p>
254:   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 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>'. + 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>'.   </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>    <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 rules used for choosing time zone abbreviations, + Here are the general guidelines used for choosing time zone abbreviations,   in decreasing order of importance: -  + </p> +    <ul>    <li>    Use three to six characters that are ASCII alphanumerics or    '<code>+</code>' or '<code>-</code>'.    Previous editions of this database also used characters like -  '<code> </code>' and '<code>?</code>', but these -  characters have a special meaning to -  the shell and cause commands like -  '<code>set `date`</code>' +  '<code> </code>' and '<code>?</code>', but these characters have a +  special meaning to the shell 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>'    to have unexpected effects. -  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. +  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.    -  +  <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 TZ string. +  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>    </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: +  <p> +  <small>These abbreviations (for standard/daylight/etc. time) are:   ACST/ACDT Australian Central,   AST/ADT/APT/AWT/ADDT Atlantic,   AEST/AEDT Australian Eastern,
338:   IST/IDT/IDDT Israel,   JST/JDT Japan,   KST/KDT Korea, - MET/MEST Middle European (a backward-compatibility alias for Central European), +  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,
354:   WIB Waktu Indonesia Barat,   WIT Waktu Indonesia Timur,   WITA Waktu Indonesia Tengah, - YST/YDT/YWT/YPT/YDDT Yukon</small>.</p> +  YST/YDT/YWT/YPT/YDDT Yukon</small>. +  </p>    </li>    <li> -  For zones whose times are taken from a city's longitude, use the - traditional <var>x</var>MT notation. The only abbreviation like this - in current use is 'GMT'. 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> +  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: +  <p> +  <small>These abbreviations are:    AMT Amsterdam, Asunción, Athens; - BMT Baghdad, Bangkok, Batavia, Bern, Bogotá, Bridgetown, Brussels, Bucharest; +  BMT Baghdad, Bangkok, Batavia, Bern, Bogotá, Bridgetown, Brussels, +  Bucharest;   CMT Calamarca, Caracas, Chisinau, Colón, Copenhagen, Córdoba;   DMT Dublin/Dunsink;   EMT Easter;
378:   JMT Jerusalem;   KMT Kaunas, Kiev, Kingston;   LMT Lima, Lisbon, local, Luanda; - MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo, Moratuwa, -  Moscow; +  MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo, +  Moratuwa, Moscow;   PLMT Phù Liễn;   PMT Paramaribo, Paris, Perm, Pontianak, Prague;   PMMT Port Moresby;
390:   SMT Santiago, Simferopol, Singapore, Stanley;   TBMT Tbilisi;   TMT Tallinn, Tehran; - WMT Warsaw</small>.</p> +  WMT Warsaw</small>. +  </p>    - <p><small>A few abbreviations also follow the pattern that - GMT/BST established for time in the UK. They are: -  +  <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. +  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> +  Observatory.</small> +  </p>    </li>    <li> -  Use 'LMT' for local mean time of locations before the introduction -  of standard time; see "<a href="#scope">Scope of the -  tz database</a>". +  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>".    </li>    <li>    If there is no common English abbreviation, use numeric offsets like -  <code>-</code>05 and <code>+</code>0830 that are -  generated by zic's <code>%z</code> notation. +  <code>-</code>05 and <code>+</code>0830 that are generated +  by <code>zic</code>'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 UT +01 +  For example, in 1910 a common English abbreviation for time    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 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. +  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.    </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. +  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>.    </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 UT offsets like + Israel. + To avoid ambiguity, use numeric <abbr>UT</abbr> offsets like   '<code>-</code>0600' instead of time zone abbreviations like 'CST'.   </p>   </section>    -  +    <section> -  <h2 id="accuracy">Accuracy of the tz database</h2> +  <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>   <p> - The tz database is not authoritative, and it surely has errors. + 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>.   Users requiring authoritative data should consult national standards   bodies and the references cited in the database's comments.   </p>      <p> - Errors in the tz database arise from many sources: + Errors in the <code><abbr>tz</abbr></code> database arise from many sources:   </p> -  +    <ul>    <li> -  The tz database predicts future timestamps, and current predictions +  The <code><abbr>tz</abbr></code> 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
470:    <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 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 +  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    "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>
495:    typically found to be incorrect.    </li>    <li> -  For the UK the tz database relies on years of first-class work done by +  For the UK the <code><abbr>tz</abbr></code> 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 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. +  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.    </li>    <li> -  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. +  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.    </li>    <li> -  The tz database does not record the earliest time for which a zone's +  The <code><abbr>tz</abbr></code> database does not record the +  earliest time for which a <code><abbr>tz</abbr></code> region'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 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. +  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.    </li>    <li> -  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. +  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.    </li>    <li> -  Changes that are modeled as instantaneous transitions in the tz +  Changes that are modeled as instantaneous transitions in the +  <code><abbr>tz</abbr></code>    database were often spread out over hours, days, or even decades.    </li>    <li>
545:    </li>    <li>    Early timekeeping practices, even assuming perfect clocks, were -  often not specified to the accuracy that the tz database requires. +  often not specified to the accuracy that the +  <code><abbr>tz</abbr></code> database requires.    </li>    <li>    Sometimes historical timekeeping was specified more precisely -  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. +  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.    </li>    <li> -  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 +  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    way to specify Easter, these exceptional years are entered as -  separate tz Rule lines, even though the legal rules did not change. +  separate <code><abbr>tz</abbr> Rule</code> lines, even though the +  legal rules did not change.    </li>    <li> -  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 +  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    non-hour-based system at night.    </li>    <li>
575:    clock error.    </li>    <li> -  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. +  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.    </li>    <li>    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>. +  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>.    <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, UTC but ignoring leap -  seconds) and UTC is not agreed upon after 1972. Although the POSIX +  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    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 tz database does not represent how uncertain its information is. +  The <code><abbr>tz</abbr></code> 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's 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 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. + 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.   </p>   </section>    -  +    <section>    <h2 id="functions">Time and date functions</h2>   <p> - The tz code contains time and date functions that are upwards - compatible with those of POSIX. + 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>.   </p>    - <p> - POSIX has the following properties and limitations. - </p> + <h3 id="POSIX">POSIX properties and limitations</h3>   <ul>    <li>    <p>    In POSIX, time display in a process is controlled by the -  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. +  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 can't 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.    </p> -  +     <p> -  The POSIX TZ string takes the following form: +  The POSIX <code>TZ</code> 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 (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;+09&gt;</code>'; this allows -  "<code>+</code>" and "<code>-</code>" in the names. +  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.    </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 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. +  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.    </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 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. +  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.    </dd>    <dt><var>time</var></dt><dd>    takes the form
691:    <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 UT, -  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>    -  This POSIX TZ string is hard to remember, and mishandles some -  timestamps before 2008. With this package you can use this -  instead: +  <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>       <pre><code>TZ='Pacific/Auckland'</code></pre>    </li>    <li> -  POSIX does not define the exact meaning of TZ values like +  POSIX does not define the exact meaning of <code>TZ</code> values like    "<code>EST5EDT</code>". -  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. +  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.    </li>    <li> -  The TZ environment variable is process-global, which makes it hard -  to write efficient, thread-safe applications that need access -  to multiple time zones. +  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.    </li>    <li>    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 UT" 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.) +  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.)    </li>    <li> -  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. +  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.    </li>    <li>    POSIX requires that systems ignore leap seconds.    </li>    <li> -  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. +  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.    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 tz 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 <code><abbr>tz</abbr></code> code both +  require <code>time_t</code> to be an integer type.    </li>   </ul> - <p> - These are the extensions that have been made to the POSIX functions: - </p> +  + <h3 id="POSIX-extensions">Extensions to POSIX in the + <code><abbr>tz</abbr></code> code</h3>   <ul>    <li>    <p> -  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 +  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    abbreviations are used.    </p>    <p> -  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). +  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).    </p>    </li>    <li> -  The code supports platforms with a UT offset member -  in <code>struct tm</code>, -  e.g., <code>tm_gmtoff</code>. +  The code supports platforms with a <abbr>UT</abbr> 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 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. +  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>.    </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 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.) +  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 <code>tzsetwall</code>, you won't 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's no <code>TZ</code> 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
855:    These functions can account for leap seconds, thanks to Bradley White.   </li>   </ul> +  + <h3 id="vestigial">POSIX features no longer needed</h3>   <p> - Points of interest to folks with other systems: + 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:   </p>   <ul>    <li> -  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>. +  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.    </li>    <li> -  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> +  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's 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>    (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 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. +  The <abbr>4.2BSD</abbr> <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>.    </li>    <li> -  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. +  In <abbr>SVR2</abbr>, time conversion fails for near-minimum or +  near-maximum <code>time_t</code> values when doing conversions +  for places that don't use <abbr>UT</abbr>.    This package takes care to do these conversions correctly.    A comment in the source code tells how to get compatibly wrong    results.    </li> - </ul> - <p> +  <li>    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. - </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> +  </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>   </section>    -  +    <section>    <h2 id="stability">Interface stability</h2>   <p> - The tz code and data supply the following interfaces: + The <code><abbr>tz</abbr></code> code and data supply the following interfaces:   </p> -  +    <ul>    <li> -  A set of zone names as per "<a href="#naming">Names of time zone -  rules</a>" above. +  A set of <code><abbr>tz</abbr></code> region names as per +  "<a href="#naming">Names of time zone rulesets</a>" above.    </li>    <li>    Library functions described in "<a href="#functions">Time and date
959:    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, 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.html">Sources for time zone and daylight - saving time data</a> describes how - releases are tagged and distributed. + 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.   </p>      <p> - 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. + 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.   </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 Nachum Dershowitz and Edward M. Reingold, - <cite><a href="https://www.cs.tau.ac.il/~nachum/calendar-book/third-edition/">Calendrical + 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. + Other information and sources are given in the file '<code>calendars</code>' + in the <code><abbr>tz</abbr></code> 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 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. + Some people's work schedules + use <a href="https://en.wikipedia.org/wiki/Timekeeping on Mars">Mars time</a>. + Jet Propulsion Laboratory (JPL) coordinators have kept Mars time on + and off at least since 1997 for the + <a href="https://en.wikipedia.org/wiki/Mars_Pathfinder#End_of_mission">Mars + Pathfinder</a> 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 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). + 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>.   </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 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. + 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.   </p>      <p>   Many calendars have been proposed for Mars, but none have achieved - wide acceptance. Astronomers often use Mars Sol Date (MSD) which is a + wide acceptance. + Astronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a   sequential count of Mars solar days elapsed since about 1873-12-29 - 12:00 GMT. + 12:00 <abbr>GMT</abbr>.   </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 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. + 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.   </p>      <p> - Although the tz database does not support time on other planets, it is - documented here in the hopes that support will be added eventually. + 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.   </p>      <p> - Sources: + Sources for time on other planets:   </p> -  +    <ul>    <li>   Michael Allison and Robert Schmunk,
1070:    <li>   Jia-Rui Chong,   "<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays - Fit for a Martian</a>", Los Angeles Times +  Fit for a Martian</a>", <cite>Los Angeles Times</cite>    (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>", The Atlantic (2015-02-26) +  Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26)    </li>    <li>   Matt Williams,