summaryrefslogtreecommitdiffstats
path: root/contrib/tzdata/theory.html
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/tzdata/theory.html')
-rw-r--r--contrib/tzdata/theory.html1793
1 files changed, 992 insertions, 801 deletions
diff --git a/contrib/tzdata/theory.html b/contrib/tzdata/theory.html
index ff85f53..4d8726d 100644
--- a/contrib/tzdata/theory.html
+++ b/contrib/tzdata/theory.html
@@ -1,26 +1,20 @@
-<!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,20 +22,27 @@
</ul>
</nav>
-
- <section>
- <h2 id="scope">Scope of the tz database</h2>
+<section>
+ <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,193 +60,218 @@ necessarily follow database guidelines.
</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>
-
- <section>
- <h2 id="naming">Names of time zone rules</h2>
+<section>
+ <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.
- This is essential for the intended use: static clocks keeping local
- civil time.
+ Uniquely identify every region where clocks have agreed since 1970.
+ This is essential for the intended use: static clocks keeping local
+ civil time.
</li>
<li>
- Indicate to experts where that region is.
+ 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.
+ Be portable to a wide variety of implementations.
</li>
<li>
- Use a consistent naming conventions over the entire world.
+ 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.
+ 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>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>'.
+ 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>'.
+ 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>'.
</li>
<li>
- Uninhabited regions like the North Pole and Bouvet Island
- do not need locations, since local time is not defined there.
+ 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 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,
- don't bother to include more than one location
- even if subregions' clocks disagreed before 1970.
- Otherwise these tables would become annoyingly large.
+ If all the clocks in a region have agreed since 1970,
+ 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>Costa_Rica</code>' to '<code>San_Jose</code>' and '<code>Guyana</code>' to '<code>Georgetown</code>'.
+ 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>'.
</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>Guatemala_City</code>', but prefer
- '<code>Mexico_City</code>' to '<code>Mexico</code>'
- because the country
- of Mexico has several time zones.
+ 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>Guatemala_City</code>', but prefer
+ '<code>Mexico_City</code>' to '<code>Mexico</code>'
+ 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.
+ 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
- '<code>backward</code>' file.
- This means old spellings will continue to work.
+ If a name is changed, put its old spelling in the
+ '<code>backward</code>' file.
+ This means old spellings will continue to work.
</li>
</ul>
<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,843 +280,1008 @@ and these older names are still supported.
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>
- <section>
- <h2 id="abbreviations">Time zone abbreviations</h2>
+<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>'
- 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.
-
- 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.
- </li>
- <li>
- Use abbreviations that are in common use among English-speakers,
- 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'.
+ 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><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 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><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>
- 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>
+ 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>
+ </li>
+ <li>
+ Use abbreviations that are in common use among English-speakers,
+ 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 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>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>A few abbreviations also follow the pattern that
-GMT/BST established for time in the UK. They are:
+ <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>
-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>
+ <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>
</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.
+ 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.
</li>
<li>
- Use current abbreviations for older timestamps to avoid confusion.
- 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.
+ Use current abbreviations for older timestamps to avoid confusion.
+ 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.
</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>
- <section>
- <h2 id="accuracy">Accuracy of the tz database</h2>
+<section>
+ <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
- 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
- daylight saving rules, software can mess up after the rule change
- if it blithely relies on conversions made before the change.
- </li>
- <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
- "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
- 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>
- <li>
- Most of the pre-1970 data entries come from unreliable sources, often
- astrology books that lack citations and whose compilers evidently
- invented entries when the true facts were unknown, without
- reporting which entries were known and which were invented.
- These books often contradict each other or give implausible entries,
- and on the rare occasions when they are checked they are
- typically found to be incorrect.
- </li>
- <li>
- 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 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 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 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 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 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 tz
- database were often spread out over hours, days, or even decades.
- </li>
- <li>
- Even if the time is specified by law, locations sometimes
- deliberately flout the law.
- </li>
- <li>
- Early timekeeping practices, even assuming perfect clocks, were
- often not specified to the accuracy that the tz 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.
- </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
- way to specify Easter, these exceptional years are entered as
- separate tz Rule 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
- non-hour-based system at night.
- </li>
- <li>
- Early clocks were less reliable, and data entries do not represent
- 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.
- </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>.
- <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
- 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.
- 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.
+ 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
+ daylight saving rules, software can mess up after the rule change
+ if it blithely relies on conversions made before the change.
+ </li>
+ <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
+ "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
+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>
+ <li>
+ Most of the pre-1970 data entries come from unreliable sources, often
+ astrology books that lack citations and whose compilers evidently
+ invented entries when the true facts were unknown, without
+ reporting which entries were known and which were invented.
+ These books often contradict each other or give implausible entries,
+ and on the rare occasions when they are checked they are
+ 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
+ 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.
+ </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.
+ </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
+ 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.
+ </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.
+ </li>
+ <li>
+ 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>
+ Even if the time is specified by law, locations sometimes
+ deliberately flout the law.
+ </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.
+ </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.
+ </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
+ 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.
+ </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
+ non-hour-based system at night.
+ </li>
+ <li>
+ Early clocks were less reliable, and data entries do not represent
+ 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.
+ </li>
+ <li>
+ Civil time was not based on atomic time before 1972, and we don't
+ 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, <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 <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.
</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.
-</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.
+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>
-POSIX has the following properties and limitations.
+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>
+
+<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.
+ 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 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>]]]
+ <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:
+ 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.
+ 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.
</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.
+ 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.
</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
- '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
- and defaults to 02:00.
- This is the same format as the offset, except that a
- leading '<code>+</code>' or '<code>-</code>' is not allowed.
+ takes the form
+ '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
+ and defaults to 02:00.
+ This is the same format as the offset, except that a
+ leading '<code>+</code>' or '<code>-</code>' is not allowed.
</dd>
<dt><var>date</var></dt><dd>
- takes one of the following forms:
+ takes one of the following forms:
<dl>
<dt>J<var>n</var> (1&le;<var>n</var>&le;365)</dt><dd>
- origin-1 day number not counting February 29
- </dd>
+ origin-1 day number not counting February 29
+ </dd>
<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.
+ 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.
</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:
+ </dl>
+ </dd>
+ </dl>
- <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
+ <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
+ "<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.
+ </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.
+ </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
+ <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 <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 <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 <code><abbr>tz</abbr></code> code both
+ require <code>time_t</code> to be an integer type.
+ </li>
+</ul>
- <pre><code>TZ='Pacific/Auckland'</code></pre>
+<h3 id="POSIX-extensions">Extensions to POSIX in the
+<code><abbr>tz</abbr></code> code</h3>
+<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
+ 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).
+ </p>
</li>
<li>
- POSIX does not define the exact meaning of TZ 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.
+ 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 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 supports platforms with a time zone abbreviation member in
+ <code>struct tm</code>, e.g., <code>tm_zone</code>.
</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.)
+ 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>.
</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.
+ 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>
- POSIX requires that systems ignore leap seconds.
+ Negative <code>time_t</code> values are supported, on systems
+ where <code>time_t</code> is signed.
</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.
- 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.
+ These functions can account for leap seconds, thanks to Bradley White.
</li>
</ul>
+
+<h3 id="vestigial">POSIX features no longer needed</h3>
<p>
-These are the extensions that have been made to the POSIX functions:
+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>
- <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
- 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).
- </p>
-</li>
-<li>
- 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 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 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
- where <code>time_t</code> is signed.
-</li>
-<li>
- These functions can account for leap seconds, thanks to Bradley White.
-</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.
+ </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>
-<p>
-Points of interest to folks with other systems:
-</p>
+
+<h3 id="other-portability">Other portability notes</h3>
<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>.
- </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>
- (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.
- </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.
- </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.
- This package takes care to do these conversions correctly.
- A comment in the source code tells how to get compatibly wrong
- results.
+ 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.
+ </li>
+ <li>
+ 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 <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>
+ <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
+ 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>
-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
-standardization proposals.
-</p>
+</section>
+<section>
+ <h2 id="stability">Interface stability</h2>
<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.
+The <code><abbr>tz</abbr></code> code and data supply the following interfaces:
</p>
- </section>
-
- <section>
- <h2 id="stability">Interface stability</h2>
-<p>
-The tz 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
- functions</a>" above.
+ Library functions described in "<a href="#functions">Time and date
+ functions</a>" above.
</li>
<li>
- The programs <code>tzselect</code>, <code>zdump</code>,
- and <code>zic</code>, documented in their man pages.
+ The programs <code>tzselect</code>, <code>zdump</code>,
+ and <code>zic</code>, documented in their man pages.
</li>
<li>
- The format of <code>zic</code> input files, documented in
- the <code>zic</code> man page.
+ The format of <code>zic</code> input files, documented in
+ the <code>zic</code> man page.
</li>
<li>
- The format of <code>zic</code> output files, documented in
- the <code>tzfile</code> man page.
+ The format of <code>zic</code> output files, documented in
+ the <code>tzfile</code> man page.
</li>
<li>
- The format of zone table files, documented in <code>zone1970.tab</code>.
+ The format of zone table files, documented in <code>zone1970.tab</code>.
</li>
<li>
- The format of the country code file, documented in <code>iso3166.tab</code>.
+ The format of the country code file, documented in <code>iso3166.tab</code>.
</li>
<li>
- The version number of the code and data, as the first line of
- the text file '<code>version</code>' in each release.
+ The version number of the code and data, as the first line of
+ 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>
-
- <section>
- <h2 id="calendar">Calendrical issues</h2>
+<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>
- <section>
- <h2 id="planets">Time and time zones on other planets</h2>
+<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,
-"<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).
+ 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).
</li>
<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
-(2004-01-14), pp A1, A20-A21.
+ 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-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)
+ 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)
</li>
<li>
-Matt Williams,
-"<a href="https://www.universetoday.com/37481/days-of-the-planets/">How
-long is a day on the other planets of the solar system?</a>"
-(2017-04-27).
+ Matt Williams,
+ "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How
+ long is a day on the other planets of the solar system?</a>"
+ (2017-04-27).
</li>
</ul>
- </section>
+</section>
- <footer>
- <hr>
-This file is in the public domain, so clarified as of 2009-05-17 by
-Arthur David Olson.
- </footer>
+<footer>
+ <hr>
+ This file is in the public domain, so clarified as of 2009-05-17 by
+ Arthur David Olson.
+</footer>
</body>
</html>
OpenPOWER on IntegriCloud