diff options
| author | gordon <gordon@FreeBSD.org> | 2018-04-04 05:40:48 +0000 |
|---|---|---|
| committer | gordon <gordon@FreeBSD.org> | 2018-04-04 05:40:48 +0000 |
| commit | 7b354623a7c28cdf0b77ccb43d3f6bfeeaa2f2ac (patch) | |
| tree | ba4af944768d1fbb4ca1ee28202b101c6200b867 /contrib/tzdata/theory.html | |
| parent | 0ce10b6784cbf4e1763f41eaadbf25a600ea4f89 (diff) | |
| download | FreeBSD-src-7b354623a7c28cdf0b77ccb43d3f6bfeeaa2f2ac.zip FreeBSD-src-7b354623a7c28cdf0b77ccb43d3f6bfeeaa2f2ac.tar.gz | |
Update timezone database information. [EN-18:03.tzdata]
Submitted by: philip
Approved by: so
Security: FreeBSD-EN-18:03.tzdata
Diffstat (limited to 'contrib/tzdata/theory.html')
| -rw-r--r-- | contrib/tzdata/theory.html | 1793 |
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→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→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° 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° +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–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–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–1932, DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time -1880–1916, MMT/MST/MDST for Moscow 1880–1919, and RMT/LST -for Riga Mean Time and Latvian Summer time 1880–1926. -An extra-special case is SET for Swedish Time (<em>svensk -normaltid</em>) 1879–1899, 3° 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–1932, + DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time + 1880–1916, + MMT/MST/MDST for Moscow 1880–1919, and + RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926. + An extra-special case is SET for Swedish Time (<em>svensk + normaltid</em>) 1879–1899, 3° 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&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–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&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><+09></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><+09></code>'; + this allows "<code>+</code>" and "<code>-</code>" in the names. </dd> <dt><var>offset</var></dt><dd> - is of the form - '<code>[±]<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≤<var>hh</var>≤24. - The default DST offset is one hour ahead of standard time. + is of the form + '<code>[±]<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≤<var>hh</var>≤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≤<var>n</var>≤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≤<var>n</var>≤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]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, 1≤<var>m</var>≤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]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, + 1≤<var>m</var>≤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 – 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 – - 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 – directly or + indirectly – 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 – directly or indirectly – - 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(&clock)->tm_zone</code> - (if <code>TM_ZONE</code> is defined) or - <code>tzname[localtime(&clock)->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(&clock)->tm_zone</code> + (if <code>TM_ZONE</code> is defined) or + <code>tzname[localtime(&clock)->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" – 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" – 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> |
