theory.html revision 1.2
11.1Schristos<!DOCTYPE html> 21.1Schristos<html lang="en"> 31.1Schristos<head> 41.1Schristos <title>Theory and pragmatics of the tz code and data</title> 51.1Schristos <meta charset="UTF-8"> 61.1Schristos</head> 71.1Schristos 81.1Schristos<!-- The somewhat-unusal indenting style in this file is intended to 91.1Schristos shrink the output of the shell command 'diff Theory Theory.html', 101.1Schristos where 'Theory' was the plain text file that this file is derived 111.1Schristos from. The 'Theory' file used leading white space to indent, and 121.1Schristos when possible that indentation is preserved here. Eventually we 131.1Schristos may stop doing this and remove this comment. --> 141.1Schristos 151.1Schristos<body> 161.1Schristos <h1>Theory and pragmatics of the tz code and data</h1> 171.1Schristos <h3>Outline</h3> 181.1Schristos <nav> 191.1Schristos <ul> 201.1Schristos <li><a href="#scope">Scope of the tz database</a></li> 211.1Schristos <li><a href="#naming">Names of time zone rules</a></li> 221.1Schristos <li><a href="#abbreviations">Time zone abbreviations</a></li> 231.1Schristos <li><a href="#accuracy">Accuracy of the tz database</a></li> 241.1Schristos <li><a href="#functions">Time and date functions</a></li> 251.1Schristos <li><a href="#stability">Interface stability</a></li> 261.1Schristos <li><a href="#calendar">Calendrical issues</a></li> 271.1Schristos <li><a href="#planets">Time and time zones on other planets</a></li> 281.1Schristos </ul> 291.1Schristos </nav> 301.1Schristos 311.1Schristos 321.1Schristos <section> 331.1Schristos <h2 id="scope">Scope of the tz database</h2> 341.1Schristos<p> 351.1SchristosThe tz database attempts to record the history and predicted future of 361.1Schristosall computer-based clocks that track civil time. To represent this 371.1Schristosdata, the world is partitioned into regions whose clocks all agree 381.1Schristosabout timestamps that occur after the somewhat-arbitrary cutoff point 391.1Schristosof the POSIX Epoch (1970-01-01 00:00:00 UTC). For each such region, 401.1Schristosthe database records all known clock transitions, and labels the region 411.1Schristoswith a notable location. Although 1970 is a somewhat-arbitrary 421.1Schristoscutoff, there are significant challenges to moving the cutoff earlier 431.1Schristoseven by a decade or two, due to the wide variety of local practices 441.1Schristosbefore computer timekeeping became prevalent. 451.1Schristos</p> 461.1Schristos 471.1Schristos<p> 481.1SchristosClock transitions before 1970 are recorded for each such location, 491.1Schristosbecause most systems support timestamps before 1970 and could 501.1Schristosmisbehave if data entries were omitted for pre-1970 transitions. 511.1SchristosHowever, the database is not designed for and does not suffice for 521.1Schristosapplications requiring accurate handling of all past times everywhere, 531.1Schristosas it would take far too much effort and guesswork to record all 541.1Schristosdetails of pre-1970 civil timekeeping. 551.2SchristosAthough some information outside the scope of the database is 561.2Schristoscollected in a file <code>backzone</code> that is distributed along 571.2Schristoswith the database proper, this file is less reliable and does not 581.2Schristosnecessarily follow database guidelines. 591.1Schristos</p> 601.1Schristos 611.1Schristos<p> 621.1SchristosAs described below, reference source code for using the tz database is 631.1Schristosalso available. The tz code is upwards compatible with POSIX, an 641.1Schristosinternational standard for UNIX-like systems. As of this writing, the 651.1Schristoscurrent edition of POSIX is: 661.1Schristos <a href="http://pubs.opengroup.org/onlinepubs/9699919799/"> 671.1Schristos The Open Group Base Specifications Issue 7</a>, 681.1Schristos IEEE Std 1003.1-2008, 2016 Edition. 691.1Schristos</p> 701.1Schristos </section> 711.1Schristos 721.1Schristos 731.1Schristos 741.1Schristos <section> 751.1Schristos <h2 id="naming">Names of time zone rules</h2> 761.1Schristos<p> 771.1SchristosEach of the database's time zone rules has a unique name. 781.1SchristosInexperienced users are not expected to select these names unaided. 791.1SchristosDistributors should provide documentation and/or a simple selection 801.1Schristosinterface that explains the names; for one example, see the 'tzselect' 811.1Schristosprogram in the tz code. The 821.1Schristos<a href="http://cldr.unicode.org/">Unicode Common Locale Data 831.1SchristosRepository</a> contains data that may be useful for other 841.1Schristosselection interfaces. 851.1Schristos</p> 861.1Schristos 871.1Schristos<p> 881.1SchristosThe time zone rule naming conventions attempt to strike a balance 891.1Schristosamong the following goals: 901.1Schristos</p> 911.1Schristos<ul> 921.1Schristos <li> 931.1Schristos Uniquely identify every region where clocks have agreed since 1970. 941.1Schristos This is essential for the intended use: static clocks keeping local 951.1Schristos civil time. 961.1Schristos </li> 971.1Schristos <li> 981.1Schristos Indicate to experts where that region is. 991.1Schristos </li> 1001.1Schristos <li> 1011.1Schristos Be robust in the presence of political changes. For example, names 1021.1Schristos of countries are ordinarily not used, to avoid incompatibilities 1031.1Schristos when countries change their name (e.g. Zaire→Congo) or when 1041.1Schristos locations change countries (e.g. Hong Kong from UK colony to 1051.1Schristos China). 1061.1Schristos </li> 1071.1Schristos <li> 1081.1Schristos Be portable to a wide variety of implementations. 1091.1Schristos </li> 1101.1Schristos <li> 1111.1Schristos Use a consistent naming conventions over the entire world. 1121.1Schristos </li> 1131.1Schristos</ul> 1141.1Schristos<p> 1151.1SchristosNames normally have the 1161.1Schristosform <var>AREA</var><code>/</code><var>LOCATION</var>, 1171.1Schristoswhere <var>AREA</var> is the name of a continent or ocean, 1181.1Schristosand <var>LOCATION</var> is the name of a specific 1191.1Schristoslocation within that region. North and South America share the same 1201.1Schristosarea, '<code>America</code>'. Typical names are 1211.1Schristos'<code>Africa/Cairo</code>', '<code>America/New_York</code>', and 1221.1Schristos'<code>Pacific/Honolulu</code>'. 1231.1Schristos</p> 1241.1Schristos 1251.1Schristos<p> 1261.1SchristosHere are the general rules used for choosing location names, 1271.1Schristosin decreasing order of importance: 1281.1Schristos</p> 1291.1Schristos<ul> 1301.1Schristos <li> 1311.1Schristos Use only valid POSIX file name components (i.e., the parts of 1321.1Schristos names other than '<code>/</code>'). Do not use the file name 1331.1Schristos components '<code>.</code>' and '<code>..</code>'. 1341.1Schristos Within a file name component, 1351.1Schristos use only ASCII letters, '<code>.</code>', 1361.1Schristos '<code>-</code>' and '<code>_</code>'. Do not use 1371.1Schristos digits, as that might create an ambiguity with POSIX 1381.1Schristos TZ strings. A file name component must not exceed 14 1391.1Schristos characters or start with '<code>-</code>'. E.g., 1401.1Schristos prefer '<code>Brunei</code>' to 1411.1Schristos '<code>Bandar_Seri_Begawan</code>'. Exceptions: see 1421.1Schristos the discussion 1431.1Schristos of legacy names below. 1441.1Schristos </li> 1451.1Schristos <li> 1461.1Schristos A name must not be empty, or contain '<code>//</code>', or 1471.1Schristos start or end with '<code>/</code>'. 1481.1Schristos </li> 1491.1Schristos <li> 1501.1Schristos Do not use names that differ only in case. Although the reference 1511.1Schristos implementation is case-sensitive, some other implementations 1521.1Schristos are not, and they would mishandle names differing only in case. 1531.1Schristos </li> 1541.1Schristos <li> 1551.1Schristos If one name <var>A</var> is an initial prefix of another 1561.1Schristos name <var>AB</var> (ignoring case), then <var>B</var> 1571.1Schristos must not start with '<code>/</code>', as a 1581.1Schristos regular file cannot have 1591.1Schristos the same name as a directory in POSIX. For example, 1601.1Schristos '<code>America/New_York</code>' precludes 1611.1Schristos '<code>America/New_York/Bronx</code>'. 1621.1Schristos </li> 1631.1Schristos <li> 1641.1Schristos Uninhabited regions like the North Pole and Bouvet Island 1651.1Schristos do not need locations, since local time is not defined there. 1661.1Schristos </li> 1671.1Schristos <li> 1681.1Schristos There should typically be at least one name for each ISO 3166-1 1691.1Schristos officially assigned two-letter code for an inhabited country 1701.1Schristos or territory. 1711.1Schristos </li> 1721.1Schristos <li> 1731.1Schristos If all the clocks in a region have agreed since 1970, 1741.1Schristos don't bother to include more than one location 1751.1Schristos even if subregions' clocks disagreed before 1970. 1761.1Schristos Otherwise these tables would become annoyingly large. 1771.1Schristos </li> 1781.1Schristos <li> 1791.1Schristos If a name is ambiguous, use a less ambiguous alternative; 1801.1Schristos e.g. many cities are named San José and Georgetown, so 1811.1Schristos prefer '<code>Costa_Rica</code>' to '<code>San_Jose</code>' and '<code>Guyana</code>' to '<code>Georgetown</code>'. 1821.1Schristos </li> 1831.1Schristos <li> 1841.1Schristos Keep locations compact. Use cities or small islands, not countries 1851.1Schristos or regions, so that any future time zone changes do not split 1861.1Schristos locations into different time zones. E.g. prefer 1871.1Schristos '<code>Paris</code>' to '<code>France</code>', since 1881.1Schristos France has had multiple time zones. 1891.1Schristos </li> 1901.1Schristos <li> 1911.1Schristos Use mainstream English spelling, e.g. prefer 1921.1Schristos '<code>Rome</code>' to '<code>Roma</code>', and prefer 1931.1Schristos '<code>Athens</code>' to the Greek 1941.1Schristos '<code>Αθήνα</code>' or the Romanized 1951.1Schristos '<code>Athína</code>'. 1961.1Schristos The POSIX file name restrictions encourage this rule. 1971.1Schristos </li> 1981.1Schristos <li> 1991.1Schristos Use the most populous among locations in a zone, 2001.1Schristos e.g. prefer '<code>Shanghai</code>' to 2011.1Schristos '<code>Beijing</code>'. Among locations with 2021.1Schristos similar populations, pick the best-known location, 2031.1Schristos e.g. prefer '<code>Rome</code>' to '<code>Milan</code>'. 2041.1Schristos </li> 2051.1Schristos <li> 2061.1Schristos Use the singular form, e.g. prefer '<code>Canary</code>' to '<code>Canaries</code>'. 2071.1Schristos </li> 2081.1Schristos <li> 2091.1Schristos Omit common suffixes like '<code>_Islands</code>' and 2101.1Schristos '<code>_City</code>', unless that would lead to 2111.1Schristos ambiguity. E.g. prefer '<code>Cayman</code>' to 2121.1Schristos '<code>Cayman_Islands</code>' and 2131.1Schristos '<code>Guatemala</code>' to 2141.1Schristos '<code>Guatemala_City</code>', but prefer 2151.1Schristos '<code>Mexico_City</code>' to '<code>Mexico</code>' 2161.1Schristos because the country 2171.1Schristos of Mexico has several time zones. 2181.1Schristos </li> 2191.1Schristos <li> 2201.1Schristos Use '<code>_</code>' to represent a space. 2211.1Schristos </li> 2221.1Schristos <li> 2231.1Schristos Omit '<code>.</code>' from abbreviations in names, e.g. prefer 2241.1Schristos '<code>St_Helena</code>' to '<code>St._Helena</code>'. 2251.1Schristos </li> 2261.1Schristos <li> 2271.1Schristos Do not change established names if they only marginally 2281.1Schristos violate the above rules. For example, don't change 2291.1Schristos the existing name '<code>Rome</code>' to 2301.1Schristos '<code>Milan</code>' merely because 2311.1Schristos Milan's population has grown to be somewhat greater 2321.1Schristos than Rome's. 2331.1Schristos </li> 2341.1Schristos <li> 2351.1Schristos If a name is changed, put its old spelling in the 2361.1Schristos '<code>backward</code>' file. 2371.1Schristos This means old spellings will continue to work. 2381.1Schristos </li> 2391.1Schristos</ul> 2401.1Schristos 2411.1Schristos<p> 2421.1SchristosThe file '<code>zone1970.tab</code>' lists geographical locations used 2431.1Schristosto name time 2441.1Schristoszone rules. It is intended to be an exhaustive list of names for 2451.1Schristosgeographic regions as described above; this is a subset of the names 2461.1Schristosin the data. Although a '<code>zone1970.tab</code>' location's longitude 2471.2Schristoscorresponds to its LMT offset with one hour for every 15° east 2481.1Schristoslongitude, this relationship is not exact. 2491.1Schristos</p> 2501.1Schristos 2511.1Schristos<p> 2521.1SchristosOlder versions of this package used a different naming scheme, 2531.1Schristosand these older names are still supported. 2541.1SchristosSee the file '<code>backward</code>' for most of these older names 2551.1Schristos(e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>'). 2561.1SchristosThe other old-fashioned names still supported are 2571.1Schristos'<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and '<code>EET</code>' (see the file '<code>europe</code>'). 2581.1Schristos</p> 2591.1Schristos 2601.1Schristos<p> 2611.1SchristosOlder versions of this package defined legacy names that are 2621.1Schristosincompatible with the first rule of location names, but which are 2631.1Schristosstill supported. These legacy names are mostly defined in the file 2641.1Schristos'<code>etcetera</code>'. Also, the file '<code>backward</code>' defines the legacy names 2651.1Schristos'<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', and the file '<code>northamerica</code>' defines the 2661.1Schristoslegacy names '<code>EST5EDT</code>', '<code>CST6CDT</code>', '<code>MST7MDT</code>', and '<code>PST8PDT</code>'. 2671.1Schristos</p> 2681.1Schristos 2691.1Schristos<p> 2701.1SchristosExcluding '<code>backward</code>' should not affect the other data. If 2711.1Schristos'<code>backward</code>' is excluded, excluding '<code>etcetera</code>' should not affect the 2721.1Schristosremaining data. 2731.1Schristos</p> 2741.1Schristos 2751.1Schristos 2761.1Schristos </section> 2771.1Schristos <section> 2781.1Schristos <h2 id="abbreviations">Time zone abbreviations</h2> 2791.1Schristos<p> 2801.1SchristosWhen this package is installed, it generates time zone abbreviations 2811.1Schristoslike '<code>EST</code>' to be compatible with human tradition and POSIX. 2821.1SchristosHere are the general rules used for choosing time zone abbreviations, 2831.1Schristosin decreasing order of importance: 2841.1Schristos<ul> 2851.1Schristos <li> 2861.2Schristos Use three to six characters that are ASCII alphanumerics or 2871.1Schristos '<code>+</code>' or '<code>-</code>'. 2881.1Schristos Previous editions of this database also used characters like 2891.1Schristos '<code> </code>' and '<code>?</code>', but these 2901.1Schristos characters have a special meaning to 2911.1Schristos the shell and cause commands like 2921.1Schristos '<code>set `date`</code>' 2931.1Schristos to have unexpected effects. 2941.1Schristos Previous editions of this rule required upper-case letters, 2951.1Schristos but the Congressman who introduced Chamorro Standard Time 2961.1Schristos preferred "ChST", so lower-case letters are now allowed. 2971.1Schristos Also, POSIX from 2001 on relaxed the rule to allow 2981.1Schristos '<code>-</code>', '<code>+</code>', 2991.1Schristos and alphanumeric characters from the portable character set 3001.1Schristos in the current locale. In practice ASCII alphanumerics and 3011.1Schristos '<code>+</code>' and '<code>-</code>' are safe in all locales. 3021.1Schristos 3031.1Schristos In other words, in the C locale the POSIX extended regular 3041.2Schristos expression <code>[-+[:alnum:]]{3,6}</code> should match 3051.1Schristos the abbreviation. 3061.1Schristos This guarantees that all abbreviations could have been 3071.1Schristos specified by a POSIX TZ string. 3081.1Schristos </li> 3091.1Schristos <li> 3101.1Schristos Use abbreviations that are in common use among English-speakers, 3111.1Schristos e.g. 'EST' for Eastern Standard Time in North America. 3121.1Schristos We assume that applications translate them to other languages 3131.1Schristos as part of the normal localization process; for example, 3141.1Schristos a French application might translate 'EST' to 'HNE'. 3151.2Schristos 3161.2Schristos<p><small>These abbreviations (for standard/daylight/etc. time) are: 3171.2SchristosACST/ACDT Australian Central, 3181.2SchristosAST/ADT/APT/AWT/ADDT Atlantic, 3191.2SchristosAEST/AEDT Australian Eastern, 3201.2SchristosAHST/AHDT Alaska-Hawaii, 3211.2SchristosAKST/AKDT Alaska, 3221.2SchristosAWST/AWDT Australian Western, 3231.2SchristosBST/BDT Bering, 3241.2SchristosCAT/CAST Central Africa, 3251.2SchristosCET/CEST/CEMT Central European, 3261.2SchristosChST Chamorro, 3271.2SchristosCST/CDT/CWT/CPT/CDDT Central [North America], 3281.2SchristosCST/CDT China, 3291.2SchristosGMT/BST/IST/BDST Greenwich, 3301.2SchristosEAT East Africa, 3311.2SchristosEST/EDT/EWT/EPT/EDDT Eastern [North America], 3321.2SchristosEET/EEST Eastern European, 3331.2SchristosGST Guam, 3341.2SchristosHST/HDT Hawaii, 3351.2SchristosHKT/HKST Hong Kong, 3361.2SchristosIST India, 3371.2SchristosIST/GMT Irish, 3381.2SchristosIST/IDT/IDDT Israel, 3391.2SchristosJST/JDT Japan, 3401.2SchristosKST/KDT Korea, 3411.2SchristosMET/MEST Middle European (a backward-compatibility alias for Central European), 3421.2SchristosMSK/MSD Moscow, 3431.2SchristosMST/MDT/MWT/MPT/MDDT Mountain, 3441.2SchristosNST/NDT/NWT/NPT/NDDT Newfoundland, 3451.2SchristosNST/NDT/NWT/NPT Nome, 3461.2SchristosNZMT/NZST New Zealand through 1945, 3471.2SchristosNZST/NZDT New Zealand 1946–present, 3481.2SchristosPKT/PKST Pakistan, 3491.2SchristosPST/PDT/PWT/PPT/PDDT Pacific, 3501.2SchristosSAST South Africa, 3511.2SchristosSST Samoa, 3521.2SchristosWAT/WAST West Africa, 3531.2SchristosWET/WEST/WEMT Western European, 3541.2SchristosWIB Waktu Indonesia Barat, 3551.2SchristosWIT Waktu Indonesia Timur, 3561.2SchristosWITA Waktu Indonesia Tengah, 3571.2SchristosYST/YDT/YWT/YPT/YDDT Yukon</small>.</p> 3581.1Schristos </li> 3591.1Schristos <li> 3601.1Schristos For zones whose times are taken from a city's longitude, use the 3611.2Schristostraditional <var>x</var>MT notation. The only abbreviation like this 3621.2Schristosin current use is 'GMT'. The others are for timestamps before 1960, 3631.2Schristosexcept that Monrovia Mean Time persisted until 1972. Typically, 3641.2Schristosnumeric abbreviations (e.g., '<code>-</code>004430' for MMT) would 3651.2Schristoscause trouble here, as the numeric strings would exceed the POSIX length limit. 3661.2Schristos 3671.2Schristos<p><small>These abbreviations are: 3681.2SchristosAMT Amsterdam, Asunción, Athens; 3691.2SchristosBMT Baghdad, Bangkok, Batavia, Bern, Bogotá, Bridgetown, Brussels, Bucharest; 3701.2SchristosCMT Calamarca, Caracas, Chisinau, Colón, Copenhagen, Córdoba; 3711.2SchristosDMT Dublin/Dunsink; 3721.2SchristosEMT Easter; 3731.2SchristosFFMT Fort-de-France; 3741.2SchristosFMT Funchal; 3751.2SchristosGMT Greenwich; 3761.2SchristosHMT Havana, Helsinki, Horta, Howrah; 3771.2SchristosIMT Irkutsk, Istanbul; 3781.2SchristosJMT Jerusalem; 3791.2SchristosKMT Kaunas, Kiev, Kingston; 3801.2SchristosLMT Lima, Lisbon, local, Luanda; 3811.2SchristosMMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo, Moratuwa, 3821.2Schristos Moscow; 3831.2SchristosPLMT Phù Liễn; 3841.2SchristosPMT Paramaribo, Paris, Perm, Pontianak, Prague; 3851.2SchristosPMMT Port Moresby; 3861.2SchristosQMT Quito; 3871.2SchristosRMT Rangoon, Riga, Rome; 3881.2SchristosSDMT Santo Domingo; 3891.2SchristosSJMT San José; 3901.2SchristosSMT Santiago, Simferopol, Singapore, Stanley; 3911.2SchristosTBMT Tbilisi; 3921.2SchristosTMT Tallinn, Tehran; 3931.2SchristosWMT Warsaw</small>.</p> 3941.2Schristos 3951.2Schristos<p><small>A few abbreviations also follow the pattern that 3961.2SchristosGMT/BST established for time in the UK. They are: 3971.2Schristos 3981.2SchristosCMT/BST for Calamarca Mean Time and Bolivian Summer Time 3991.2Schristos1890–1932, DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time 4001.2Schristos1880–1916, MMT/MST/MDST for Moscow 1880–1919, and RMT/LST 4011.2Schristosfor Riga Mean Time and Latvian Summer time 1880–1926. 4021.2SchristosAn extra-special case is SET for Swedish Time (<em>svensk 4031.2Schristosnormaltid</em>) 1879–1899, 3° west of the Stockholm 4041.2SchristosObservatory.</small></p> 4051.1Schristos </li> 4061.1Schristos <li> 4071.1Schristos Use 'LMT' for local mean time of locations before the introduction 4081.1Schristos of standard time; see "<a href="#scope">Scope of the 4091.1Schristos tz database</a>". 4101.1Schristos </li> 4111.1Schristos <li> 4121.1Schristos If there is no common English abbreviation, use numeric offsets like 4131.1Schristos <code>-</code>05 and <code>+</code>0830 that are 4141.1Schristos generated by zic's <code>%z</code> notation. 4151.1Schristos </li> 4161.1Schristos <li> 4171.1Schristos Use current abbreviations for older timestamps to avoid confusion. 4181.1Schristos For example, in 1910 a common English abbreviation for UT +01 4191.1Schristos in central Europe was 'MEZ' (short for both "Middle European 4201.1Schristos Zone" and for "Mitteleuropäische Zeit" in German). Nowadays 4211.1Schristos 'CET' ("Central European Time") is more common in English, and 4221.1Schristos the database uses 'CET' even for circa-1910 timestamps as this 4231.1Schristos is less confusing for modern users and avoids the need for 4241.1Schristos determining when 'CET' supplanted 'MEZ' in common usage. 4251.1Schristos </li> 4261.1Schristos <li> 4271.1Schristos Use a consistent style in a zone's history. For example, if a zone's 4281.1Schristos history tends to use numeric abbreviations and a particular 4291.1Schristos entry could go either way, use a numeric abbreviation. 4301.1Schristos </li> 4311.1Schristos <li> 4321.1Schristos Use UT (with time zone abbreviation '<code>-</code>00') for 4331.1Schristos locations while uninhabited. The leading 4341.1Schristos '<code>-</code>' is a flag that the time 4351.1Schristos zone is in some sense undefined; this notation is 4361.1Schristos derived from Internet RFC 3339. 4371.1Schristos </li> 4381.1Schristos</ul> 4391.1Schristos<p> 4401.1SchristosApplication writers should note that these abbreviations are ambiguous 4411.2Schristosin practice: e.g., 'CST' means one thing in China and something else 4421.2Schristosin North America, and 'IST' can refer to time in India, Ireland or 4431.2SchristosIsrael. To avoid ambiguity, use numeric UT offsets like 4441.2Schristos'<code>-</code>0600' instead of time zone abbreviations like 'CST'. 4451.1Schristos</p> 4461.1Schristos </section> 4471.1Schristos 4481.1Schristos 4491.1Schristos <section> 4501.1Schristos <h2 id="accuracy">Accuracy of the tz database</h2> 4511.1Schristos<p> 4521.1SchristosThe tz database is not authoritative, and it surely has errors. 4531.2SchristosCorrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. 4541.1SchristosUsers requiring authoritative data should consult national standards 4551.1Schristosbodies and the references cited in the database's comments. 4561.1Schristos</p> 4571.1Schristos 4581.1Schristos<p> 4591.1SchristosErrors in the tz database arise from many sources: 4601.1Schristos</p> 4611.1Schristos<ul> 4621.1Schristos <li> 4631.1Schristos The tz database predicts future timestamps, and current predictions 4641.1Schristos will be incorrect after future governments change the rules. 4651.1Schristos For example, if today someone schedules a meeting for 13:00 next 4661.1Schristos October 1, Casablanca time, and tomorrow Morocco changes its 4671.1Schristos daylight saving rules, software can mess up after the rule change 4681.1Schristos if it blithely relies on conversions made before the change. 4691.1Schristos </li> 4701.1Schristos <li> 4711.1Schristos The pre-1970 entries in this database cover only a tiny sliver of how 4721.1Schristos clocks actually behaved; the vast majority of the necessary 4731.1Schristos information was lost or never recorded. Thousands more zones would 4741.1Schristos be needed if the tz database's scope were extended to cover even 4751.1Schristos just the known or guessed history of standard time; for example, 4761.1Schristos the current single entry for France would need to split into dozens 4771.1Schristos of entries, perhaps hundreds. And in most of the world even this 4781.1Schristos approach would be misleading due to widespread disagreement or 4791.1Schristos indifference about what times should be observed. In her 2015 book 4801.1Schristos <cite>The Global Transformation of Time, 1870-1950</cite>, Vanessa Ogle writes 4811.1Schristos "Outside of Europe and North America there was no system of time 4821.1Schristos zones at all, often not even a stable landscape of mean times, 4831.1Schristos prior to the middle decades of the twentieth century". See: 4841.1Schristos Timothy Shenk, <a 4851.1Schristos href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked: 4861.1Schristos A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. 4871.1Schristos </li> 4881.1Schristos <li> 4891.1Schristos Most of the pre-1970 data entries come from unreliable sources, often 4901.1Schristos astrology books that lack citations and whose compilers evidently 4911.1Schristos invented entries when the true facts were unknown, without 4921.1Schristos reporting which entries were known and which were invented. 4931.1Schristos These books often contradict each other or give implausible entries, 4941.1Schristos and on the rare occasions when they are checked they are 4951.1Schristos typically found to be incorrect. 4961.1Schristos </li> 4971.1Schristos <li> 4981.1Schristos For the UK the tz database relies on years of first-class work done by 4991.1Schristos Joseph Myers and others; see 5001.1Schristos "<a href="https://www.polyomino.org.uk/british-time/">History of 5011.1Schristos legal time in Britain</a>". 5021.1Schristos Other countries are not done nearly as well. 5031.1Schristos </li> 5041.1Schristos <li> 5051.1Schristos Sometimes, different people in the same city would maintain clocks 5061.1Schristos that differed significantly. Railway time was used by railroad 5071.1Schristos companies (which did not always agree with each other), 5081.1Schristos church-clock time was used for birth certificates, etc. 5091.1Schristos Often this was merely common practice, but sometimes it was set by law. 5101.1Schristos For example, from 1891 to 1911 the UT offset in France was legally 5111.1Schristos 0:09:21 outside train stations and 0:04:21 inside. 5121.1Schristos </li> 5131.1Schristos <li> 5141.1Schristos Although a named location in the tz database stands for the 5151.1Schristos containing region, its pre-1970 data entries are often accurate for 5161.1Schristos only a small subset of that region. For example, <code>Europe/London</code> 5171.1Schristos stands for the United Kingdom, but its pre-1847 times are valid 5181.1Schristos only for locations that have London's exact meridian, and its 1847 5191.1Schristos transition to GMT is known to be valid only for the L&NW and the 5201.1Schristos Caledonian railways. 5211.1Schristos </li> 5221.1Schristos <li> 5231.1Schristos The tz database does not record the earliest time for which a zone's 5241.1Schristos data entries are thereafter valid for every location in the region. 5251.1Schristos For example, <code>Europe/London</code> is valid for all locations in its 5261.1Schristos region after GMT was made the standard time, but the date of 5271.1Schristos standardization (1880-08-02) is not in the tz database, other than 5281.1Schristos in commentary. For many zones the earliest time of validity is 5291.1Schristos unknown. 5301.1Schristos </li> 5311.1Schristos <li> 5321.1Schristos The tz database does not record a region's boundaries, and in many 5331.1Schristos cases the boundaries are not known. For example, the zone 5341.1Schristos <code>America/Kentucky/Louisville</code> represents a region around 5351.1Schristos the city of 5361.1Schristos Louisville, the boundaries of which are unclear. 5371.1Schristos </li> 5381.1Schristos <li> 5391.1Schristos Changes that are modeled as instantaneous transitions in the tz 5401.1Schristos database were often spread out over hours, days, or even decades. 5411.1Schristos </li> 5421.1Schristos <li> 5431.1Schristos Even if the time is specified by law, locations sometimes 5441.1Schristos deliberately flout the law. 5451.1Schristos </li> 5461.1Schristos <li> 5471.1Schristos Early timekeeping practices, even assuming perfect clocks, were 5481.1Schristos often not specified to the accuracy that the tz database requires. 5491.1Schristos </li> 5501.1Schristos <li> 5511.1Schristos Sometimes historical timekeeping was specified more precisely 5521.1Schristos than what the tz database can handle. For example, from 1909 to 5531.1Schristos 1937 Netherlands clocks were legally UT +00:19:32.13, but the tz 5541.1Schristos database cannot represent the fractional second. 5551.1Schristos </li> 5561.1Schristos <li> 5571.1Schristos Even when all the timestamp transitions recorded by the tz database 5581.1Schristos are correct, the tz rules that generate them may not faithfully 5591.1Schristos reflect the historical rules. For example, from 1922 until World 5601.1Schristos War II the UK moved clocks forward the day following the third 5611.1Schristos Saturday in April unless that was Easter, in which case it moved 5621.1Schristos clocks forward the previous Sunday. Because the tz database has no 5631.1Schristos way to specify Easter, these exceptional years are entered as 5641.1Schristos separate tz Rule lines, even though the legal rules did not change. 5651.1Schristos </li> 5661.1Schristos <li> 5671.1Schristos The tz database models pre-standard time using the proleptic Gregorian 5681.1Schristos calendar and local mean time (LMT), but many people used other 5691.1Schristos calendars and other timescales. For example, the Roman Empire used 5701.1Schristos the Julian calendar, and had 12 varying-length daytime hours with a 5711.1Schristos non-hour-based system at night. 5721.1Schristos </li> 5731.1Schristos <li> 5741.1Schristos Early clocks were less reliable, and data entries do not represent 5751.1Schristos clock error. 5761.1Schristos </li> 5771.1Schristos <li> 5781.1Schristos The tz database assumes Universal Time (UT) as an origin, even 5791.1Schristos though UT is not standardized for older timestamps. In the tz 5801.1Schristos database commentary, UT denotes a family of time standards that 5811.1Schristos includes Coordinated Universal Time (UTC) along with other variants 5821.1Schristos such as UT1 and GMT, with days starting at midnight. Although UT 5831.1Schristos equals UTC for modern timestamps, UTC was not defined until 1960, 5841.1Schristos so commentary uses the more-general abbreviation UT for timestamps 5851.1Schristos that might predate 1960. Since UT, UT1, etc. disagree slightly, 5861.1Schristos and since pre-1972 UTC seconds varied in length, interpretation of 5871.1Schristos older timestamps can be problematic when subsecond accuracy is 5881.1Schristos needed. 5891.1Schristos </li> 5901.1Schristos <li> 5911.1Schristos Civil time was not based on atomic time before 1972, and we don't 5921.1Schristos know the history of earth's rotation accurately enough to map SI 5931.1Schristos seconds to historical solar time to more than about one-hour 5941.1Schristos accuracy. See: Stephenson FR, Morrison LV, Hohenkerk CY. 5951.1Schristos <a href="http://dx.doi.org/10.1098/rspa.2016.0404">Measurement 5961.1Schristos of the Earth's rotation: 720 BC to AD 2015</a>. 5971.1Schristos <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404. 5981.1Schristos Also see: Espenak F. <a 5991.1Schristos href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty 6001.1Schristos in Delta T (ΔT)</a>. 6011.1Schristos </li> 6021.1Schristos <li> 6031.1Schristos The relationship between POSIX time (that is, UTC but ignoring leap 6041.1Schristos seconds) and UTC is not agreed upon after 1972. Although the POSIX 6051.1Schristos clock officially stops during an inserted leap second, at least one 6061.1Schristos proposed standard has it jumping back a second instead; and in 6071.1Schristos practice POSIX clocks more typically either progress glacially during 6081.1Schristos a leap second, or are slightly slowed while near a leap second. 6091.1Schristos </li> 6101.1Schristos <li> 6111.1Schristos The tz database does not represent how uncertain its information is. 6121.1Schristos Ideally it would contain information about when data entries are 6131.1Schristos incomplete or dicey. Partial temporal knowledge is a field of 6141.1Schristos active research, though, and it's not clear how to apply it here. 6151.1Schristos </li> 6161.1Schristos</ul> 6171.1Schristos<p> 6181.1SchristosIn short, many, perhaps most, of the tz database's pre-1970 and future 6191.1Schristostimestamps are either wrong or misleading. Any attempt to pass the 6201.1Schristostz database off as the definition of time should be unacceptable to 6211.1Schristosanybody who cares about the facts. In particular, the tz database's 6221.1SchristosLMT offsets should not be considered meaningful, and should not prompt 6231.1Schristoscreation of zones merely because two locations differ in LMT or 6241.1Schristostransitioned to standard time at different dates. 6251.1Schristos</p> 6261.1Schristos </section> 6271.1Schristos 6281.1Schristos 6291.1Schristos <section> 6301.1Schristos <h2 id="functions">Time and date functions</h2> 6311.1Schristos<p> 6321.1SchristosThe tz code contains time and date functions that are upwards 6331.1Schristoscompatible with those of POSIX. 6341.1Schristos</p> 6351.1Schristos 6361.1Schristos<p> 6371.1SchristosPOSIX has the following properties and limitations. 6381.1Schristos</p> 6391.1Schristos<ul> 6401.1Schristos <li> 6411.1Schristos <p> 6421.1Schristos In POSIX, time display in a process is controlled by the 6431.1Schristos environment variable TZ. Unfortunately, the POSIX TZ string takes 6441.1Schristos a form that is hard to describe and is error-prone in practice. 6451.1Schristos Also, POSIX TZ strings can't deal with other (for example, Israeli) 6461.1Schristos daylight saving time rules, or situations where more than two 6471.1Schristos time zone abbreviations are used in an area. 6481.1Schristos </p> 6491.1Schristos <p> 6501.1Schristos The POSIX TZ string takes the following form: 6511.1Schristos </p> 6521.1Schristos <p> 6531.1Schristos <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>]]] 6541.1Schristos </p> 6551.1Schristos <p> 6561.1Schristos where: 6571.1Schristos <dl> 6581.1Schristos <dt><var>std</var> and <var>dst</var></dt><dd> 6591.1Schristos are 3 or more characters specifying the standard 6601.1Schristos and daylight saving time (DST) zone names. 6611.1Schristos Starting with POSIX.1-2001, <var>std</var> 6621.1Schristos and <var>dst</var> may also be 6631.2Schristos in a quoted form like '<code><+09></code>'; this allows 6641.1Schristos "<code>+</code>" and "<code>-</code>" in the names. 6651.1Schristos </dd> 6661.1Schristos <dt><var>offset</var></dt><dd> 6671.1Schristos is of the form 6681.1Schristos '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' 6691.1Schristos and specifies the offset west of UT. '<var>hh</var>' 6701.1Schristos may be a single digit; 0≤<var>hh</var>≤24. 6711.1Schristos The default DST offset is one hour ahead of standard time. 6721.1Schristos </dd> 6731.1Schristos <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> 6741.1Schristos specifies the beginning and end of DST. If this is absent, 6751.1Schristos the system supplies its own rules for DST, and these can 6761.1Schristos differ from year to year; typically US DST rules are used. 6771.1Schristos </dd> 6781.1Schristos <dt><var>time</var></dt><dd> 6791.1Schristos takes the form 6801.1Schristos '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]' 6811.1Schristos and defaults to 02:00. 6821.1Schristos This is the same format as the offset, except that a 6831.1Schristos leading '<code>+</code>' or '<code>-</code>' is not allowed. 6841.1Schristos </dd> 6851.1Schristos <dt><var>date</var></dt><dd> 6861.1Schristos takes one of the following forms: 6871.1Schristos <dl> 6881.1Schristos <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> 6891.1Schristos origin-1 day number not counting February 29 6901.1Schristos </dd> 6911.1Schristos <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> 6921.1Schristos origin-0 day number counting February 29 if present 6931.1Schristos </dd> 6941.1Schristos <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> 6951.1Schristos for the <var>d</var>th day of 6961.1Schristos week <var>n</var> of month <var>m</var> of the 6971.1Schristos year, where week 1 is the first week in which 6981.1Schristos day <var>d</var> appears, and '<code>5</code>' 6991.1Schristos stands for the last week in which 7001.1Schristos day <var>d</var> appears 7011.1Schristos (which may be either the 4th or 5th week). 7021.1Schristos Typically, this is the only useful form; 7031.1Schristos the <var>n</var> 7041.1Schristos and <code>J</code><var>n</var> forms are 7051.1Schristos rarely used. 7061.1Schristos </dd> 7071.1Schristos</dl> 7081.1Schristos</dd> 7091.1Schristos</dl> 7101.1Schristos Here is an example POSIX TZ string for New Zealand after 2007. 7111.2Schristos It says that standard time (NZST) is 12 hours ahead of UT, 7121.1Schristos and that daylight saving time (NZDT) is observed from September's 7131.1Schristos last Sunday at 02:00 until April's first Sunday at 03:00: 7141.1Schristos 7151.1Schristos <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> 7161.1Schristos 7171.1Schristos This POSIX TZ string is hard to remember, and mishandles some 7181.1Schristos timestamps before 2008. With this package you can use this 7191.1Schristos instead: 7201.1Schristos 7211.1Schristos <pre><code>TZ='Pacific/Auckland'</code></pre> 7221.1Schristos </li> 7231.1Schristos <li> 7241.1Schristos POSIX does not define the exact meaning of TZ values like 7251.1Schristos "<code>EST5EDT</code>". 7261.1Schristos Typically the current US DST rules are used to interpret such values, 7271.1Schristos but this means that the US DST rules are compiled into each program 7281.1Schristos that does time conversion. This means that when US time conversion 7291.1Schristos rules change (as in the United States in 1987), all programs that 7301.1Schristos do time conversion must be recompiled to ensure proper results. 7311.1Schristos </li> 7321.1Schristos <li> 7331.1Schristos The TZ environment variable is process-global, which makes it hard 7341.1Schristos to write efficient, thread-safe applications that need access 7351.1Schristos to multiple time zones. 7361.1Schristos </li> 7371.1Schristos <li> 7381.1Schristos In POSIX, there's no tamper-proof way for a process to learn the 7391.1Schristos system's best idea of local wall clock. (This is important for 7401.1Schristos applications that an administrator wants used only at certain 7411.1Schristos times – 7421.1Schristos without regard to whether the user has fiddled the TZ environment 7431.2Schristos variable. While an administrator can "do everything in UT" to get 7441.1Schristos around the problem, doing so is inconvenient and precludes handling 7451.1Schristos daylight saving time shifts - as might be required to limit phone 7461.1Schristos calls to off-peak hours.) 7471.1Schristos </li> 7481.1Schristos <li> 7491.1Schristos POSIX provides no convenient and efficient way to determine the UT 7501.1Schristos offset and time zone abbreviation of arbitrary timestamps, 7511.1Schristos particularly for time zone settings that do not fit into the 7521.1Schristos POSIX model. 7531.1Schristos </li> 7541.1Schristos <li> 7551.1Schristos POSIX requires that systems ignore leap seconds. 7561.1Schristos </li> 7571.1Schristos <li> 7581.1Schristos The tz code attempts to support all the <code>time_t</code> 7591.1Schristos implementations allowed by POSIX. The <code>time_t</code> 7601.1Schristos type represents a nonnegative count of 7611.1Schristos seconds since 1970-01-01 00:00:00 UTC, ignoring leap seconds. 7621.1Schristos In practice, <code>time_t</code> is usually a signed 64- or 7631.1Schristos 32-bit integer; 32-bit signed <code>time_t</code> values stop 7641.1Schristos working after 2038-01-19 03:14:07 UTC, so 7651.1Schristos new implementations these days typically use a signed 64-bit integer. 7661.1Schristos Unsigned 32-bit integers are used on one or two platforms, 7671.1Schristos and 36-bit and 40-bit integers are also used occasionally. 7681.1Schristos Although earlier POSIX versions allowed <code>time_t</code> to be a 7691.1Schristos floating-point type, this was not supported by any practical 7701.1Schristos systems, and POSIX.1-2013 and the tz code both 7711.1Schristos require <code>time_t</code> 7721.1Schristos to be an integer type. 7731.1Schristos </li> 7741.1Schristos</ul> 7751.1Schristos<p> 7761.1SchristosThese are the extensions that have been made to the POSIX functions: 7771.1Schristos</p> 7781.1Schristos<ul> 7791.1Schristos <li> 7801.1Schristos <p> 7811.1Schristos The TZ environment variable is used in generating the name of a file 7821.1Schristos from which time zone information is read (or is interpreted a la 7831.1Schristos POSIX); TZ is no longer constrained to be a three-letter time zone 7841.1Schristos name followed by a number of hours and an optional three-letter 7851.1Schristos daylight time zone name. The daylight saving time rules to be used 7861.1Schristos for a particular time zone are encoded in the time zone file; 7871.1Schristos the format of the file allows U.S., Australian, and other rules to be 7881.1Schristos encoded, and allows for situations where more than two time zone 7891.1Schristos abbreviations are used. 7901.1Schristos </p> 7911.1Schristos <p> 7921.1Schristos It was recognized that allowing the TZ environment variable to 7931.1Schristos take on values such as '<code>America/New_York</code>' might 7941.1Schristos cause "old" programs 7951.1Schristos (that expect TZ to have a certain form) to operate incorrectly; 7961.1Schristos consideration was given to using some other environment variable 7971.1Schristos (for example, TIMEZONE) to hold the string used to generate the 7981.1Schristos time zone information file name. In the end, however, it was decided 7991.1Schristos to continue using TZ: it is widely used for time zone purposes; 8001.1Schristos separately maintaining both TZ and TIMEZONE seemed a nuisance; 8011.1Schristos and systems where "new" forms of TZ might cause problems can simply 8021.1Schristos use TZ values such as "<code>EST5EDT</code>" which can be used both by 8031.1Schristos "new" programs (a la POSIX) and "old" programs (as zone names and 8041.1Schristos offsets). 8051.1Schristos </p> 8061.1Schristos</li> 8071.1Schristos<li> 8081.1Schristos The code supports platforms with a UT offset member 8091.1Schristos in <code>struct tm</code>, 8101.1Schristos e.g., <code>tm_gmtoff</code>. 8111.1Schristos</li> 8121.1Schristos<li> 8131.1Schristos The code supports platforms with a time zone abbreviation member in 8141.1Schristos <code>struct tm</code>, e.g., <code>tm_zone</code>. 8151.1Schristos</li> 8161.1Schristos<li> 8171.1Schristos Since the TZ environment variable can now be used to control time 8181.1Schristos conversion, the <code>daylight</code> 8191.1Schristos and <code>timezone</code> variables are no longer needed. 8201.1Schristos (These variables are defined and set by <code>tzset</code>; 8211.1Schristos however, their values will not be used 8221.1Schristos by <code>localtime</code>.) 8231.1Schristos</li> 8241.1Schristos<li> 8251.1Schristos Functions <code>tzalloc</code>, <code>tzfree</code>, 8261.1Schristos <code>localtime_rz</code>, and <code>mktime_z</code> for 8271.1Schristos more-efficient thread-safe applications that need to use 8281.1Schristos multiple time zones. The <code>tzalloc</code> 8291.1Schristos and <code>tzfree</code> functions allocate and free objects of 8301.1Schristos type <code>timezone_t</code>, and <code>localtime_rz</code> 8311.1Schristos and <code>mktime_z</code> are like <code>localtime_r</code> 8321.1Schristos and <code>mktime</code> with an extra 8331.1Schristos <code>timezone_t</code> argument. The functions were inspired 8341.1Schristos by NetBSD. 8351.1Schristos</li> 8361.1Schristos<li> 8371.1Schristos A function <code>tzsetwall</code> has been added to arrange 8381.1Schristos for the system's 8391.1Schristos best approximation to local wall clock time to be delivered by 8401.1Schristos subsequent calls to <code>localtime</code>. Source code for portable 8411.1Schristos applications that "must" run on local wall clock time should call 8421.1Schristos <code>tzsetwall</code>; if such code is moved to "old" systems that don't 8431.1Schristos provide tzsetwall, you won't be able to generate an executable program. 8441.1Schristos (These time zone functions also arrange for local wall clock time to be 8451.1Schristos used if tzset is called – directly or indirectly – 8461.1Schristos and there's no TZ 8471.1Schristos environment variable; portable applications should not, however, rely 8481.1Schristos on this behavior since it's not the way SVR2 systems behave.) 8491.1Schristos</li> 8501.1Schristos<li> 8511.1Schristos Negative <code>time_t</code> values are supported, on systems 8521.1Schristos where <code>time_t</code> is signed. 8531.1Schristos</li> 8541.1Schristos<li> 8551.1Schristos These functions can account for leap seconds, thanks to Bradley White. 8561.1Schristos</li> 8571.1Schristos</ul> 8581.1Schristos<p> 8591.1SchristosPoints of interest to folks with other systems: 8601.1Schristos</p> 8611.1Schristos<ul> 8621.1Schristos <li> 8631.1Schristos Code compatible with this package is already part of many platforms, 8641.1Schristos including GNU/Linux, Android, the BSDs, Chromium OS, Cygwin, AIX, iOS, 8651.1Schristos BlackBery 10, macOS, Microsoft Windows, OpenVMS, and Solaris. 8661.1Schristos On such hosts, the primary use of this package 8671.1Schristos is to update obsolete time zone rule tables. 8681.1Schristos To do this, you may need to compile the time zone compiler 8691.1Schristos '<code>zic</code>' supplied with this package instead of using 8701.1Schristos the system '<code>zic</code>', since the format 8711.1Schristos of <code>zic</code>'s input is occasionally extended, and a 8721.1Schristos platform may still be shipping an older <code>zic</code>. 8731.1Schristos </li> 8741.1Schristos <li> 8751.1Schristos The UNIX Version 7 <code>timezone</code> function is not 8761.1Schristos present in this package; 8771.1Schristos it's impossible to reliably map timezone's arguments (a "minutes west 8781.1Schristos of GMT" value and a "daylight saving time in effect" flag) to a 8791.1Schristos time zone abbreviation, and we refuse to guess. 8801.1Schristos Programs that in the past used the timezone function may now examine 8811.1Schristos <code>localtime(&clock)->tm_zone</code> 8821.1Schristos (if <code>TM_ZONE</code> is defined) or 8831.1Schristos <code>tzname[localtime(&clock)->tm_isdst]</code> 8841.1Schristos (if <code>HAVE_TZNAME</code> is defined) 8851.1Schristos to learn the correct time zone abbreviation to use. 8861.1Schristos </li> 8871.1Schristos <li> 8881.1Schristos The 4.2BSD <code>gettimeofday</code> function is not used in 8891.1Schristos this package. 8901.1Schristos This formerly let users obtain the current UTC offset and DST flag, 8911.1Schristos but this functionality was removed in later versions of BSD. 8921.1Schristos </li> 8931.1Schristos <li> 8941.1Schristos In SVR2, time conversion fails for near-minimum or near-maximum 8951.1Schristos <code>time_t</code> values when doing conversions for places 8961.1Schristos that don't use UT. 8971.1Schristos This package takes care to do these conversions correctly. 8981.1Schristos A comment in the source code tells how to get compatibly wrong 8991.1Schristos results. 9001.1Schristos </li> 9011.1Schristos</ul> 9021.1Schristos<p> 9031.1SchristosThe functions that are conditionally compiled 9041.1Schristosif <code>STD_INSPIRED</code> is defined 9051.1Schristosshould, at this point, be looked on primarily as food for thought. They are 9061.1Schristosnot in any sense "standard compatible" – some are not, in fact, 9071.1Schristosspecified in <em>any</em> standard. They do, however, represent responses of 9081.1Schristosvarious authors to 9091.1Schristosstandardization proposals. 9101.1Schristos</p> 9111.1Schristos 9121.1Schristos<p> 9131.1SchristosOther time conversion proposals, in particular the one developed by folks at 9141.1SchristosHewlett Packard, offer a wider selection of functions that provide capabilities 9151.1Schristosbeyond those provided here. The absence of such functions from this package 9161.1Schristosis not meant to discourage the development, standardization, or use of such 9171.1Schristosfunctions. Rather, their absence reflects the decision to make this package 9181.1Schristoscontain valid extensions to POSIX, to ensure its broad acceptability. If 9191.1Schristosmore powerful time conversion functions can be standardized, so much the 9201.1Schristosbetter. 9211.1Schristos</p> 9221.1Schristos </section> 9231.1Schristos 9241.1Schristos 9251.1Schristos <section> 9261.1Schristos <h2 id="stability">Interface stability</h2> 9271.1Schristos<p> 9281.1SchristosThe tz code and data supply the following interfaces: 9291.1Schristos</p> 9301.1Schristos<ul> 9311.1Schristos <li> 9321.1Schristos A set of zone names as per "<a href="#naming">Names of time zone 9331.1Schristos rules</a>" above. 9341.1Schristos </li> 9351.1Schristos <li> 9361.1Schristos Library functions described in "<a href="#functions">Time and date 9371.1Schristos functions</a>" above. 9381.1Schristos </li> 9391.1Schristos <li> 9401.1Schristos The programs <code>tzselect</code>, <code>zdump</code>, 9411.1Schristos and <code>zic</code>, documented in their man pages. 9421.1Schristos </li> 9431.1Schristos <li> 9441.1Schristos The format of <code>zic</code> input files, documented in 9451.1Schristos the <code>zic</code> man page. 9461.1Schristos </li> 9471.1Schristos <li> 9481.1Schristos The format of <code>zic</code> output files, documented in 9491.1Schristos the <code>tzfile</code> man page. 9501.1Schristos </li> 9511.1Schristos <li> 9521.1Schristos The format of zone table files, documented in <code>zone1970.tab</code>. 9531.1Schristos </li> 9541.1Schristos <li> 9551.1Schristos The format of the country code file, documented in <code>iso3166.tab</code>. 9561.1Schristos </li> 9571.1Schristos <li> 9581.1Schristos The version number of the code and data, as the first line of 9591.1Schristos the text file '<code>version</code>' in each release. 9601.1Schristos </li> 9611.1Schristos</ul> 9621.1Schristos<p> 9631.1SchristosInterface changes in a release attempt to preserve compatibility with 9641.1Schristosrecent releases. For example, tz data files typically do not rely on 9651.1Schristosrecently-added <code>zic</code> features, so that users can run 9661.1Schristosolder <code>zic</code> versions to process newer data 9671.2Schristosfiles. <a href="tz-link.html">Sources for time zone and daylight 9681.1Schristossaving time data</a> describes how 9691.1Schristosreleases are tagged and distributed. 9701.1Schristos</p> 9711.1Schristos 9721.1Schristos<p> 9731.1SchristosInterfaces not listed above are less stable. For example, users 9741.1Schristosshould not rely on particular UT offsets or abbreviations for 9751.1Schristostimestamps, as data entries are often based on guesswork and these 9761.1Schristosguesses may be corrected or improved. 9771.1Schristos</p> 9781.1Schristos </section> 9791.1Schristos 9801.1Schristos 9811.1Schristos <section> 9821.1Schristos <h2 id="calendar">Calendrical issues</h2> 9831.1Schristos<p> 9841.1SchristosCalendrical issues are a bit out of scope for a time zone database, 9851.1Schristosbut they indicate the sort of problems that we would run into if we 9861.1Schristosextended the time zone database further into the past. An excellent 9871.1Schristosresource in this area is Nachum Dershowitz and Edward M. Reingold, 9881.1Schristos<cite><a href="https://www.cs.tau.ac.il/~nachum/calendar-book/third-edition/">Calendrical 9891.1SchristosCalculations: Third Edition</a></cite>, Cambridge University Press (2008). 9901.1SchristosOther information and sources are given in the file '<samp>calendars</samp>' 9911.1Schristosin the tz distribution. They sometimes disagree. 9921.1Schristos</p> 9931.1Schristos </section> 9941.1Schristos 9951.1Schristos 9961.1Schristos <section> 9971.1Schristos <h2 id="planets">Time and time zones on other planets</h2> 9981.1Schristos<p> 9991.1SchristosSome people's work schedules use Mars time. Jet Propulsion Laboratory 10001.1Schristos(JPL) coordinators have kept Mars time on and off at least since 1997 10011.1Schristosfor the Mars Pathfinder mission. Some of their family members have 10021.1Schristosalso adapted to Mars time. Dozens of special Mars watches were built 10031.1Schristosfor JPL workers who kept Mars time during the Mars Exploration 10041.1SchristosRovers mission (2004). These timepieces look like normal Seikos and 10051.1SchristosCitizens but use Mars seconds rather than terrestrial seconds. 10061.1Schristos</p> 10071.1Schristos 10081.1Schristos<p> 10091.1SchristosA Mars solar day is called a "sol" and has a mean period equal to 10101.1Schristosabout 24 hours 39 minutes 35.244 seconds in terrestrial time. It is 10111.1Schristosdivided into a conventional 24-hour clock, so each Mars second equals 10121.1Schristosabout 1.02749125 terrestrial seconds. 10131.1Schristos</p> 10141.1Schristos 10151.1Schristos<p> 10161.1SchristosThe prime meridian of Mars goes through the center of the crater 10171.1SchristosAiry-0, named in honor of the British astronomer who built the 10181.1SchristosGreenwich telescope that defines Earth's prime meridian. Mean solar 10191.1Schristostime on the Mars prime meridian is called Mars Coordinated Time (MTC). 10201.1Schristos</p> 10211.1Schristos 10221.1Schristos<p> 10231.1SchristosEach landed mission on Mars has adopted a different reference for 10241.1Schristossolar time keeping, so there is no real standard for Mars time zones. 10251.1SchristosFor example, the Mars Exploration Rover project (2004) defined two 10261.1Schristostime zones "Local Solar Time A" and "Local Solar Time B" for its two 10271.1Schristosmissions, each zone designed so that its time equals local true solar 10281.1Schristostime at approximately the middle of the nominal mission. Such a "time 10291.1Schristoszone" is not particularly suited for any application other than the 10301.1Schristosmission itself. 10311.1Schristos</p> 10321.1Schristos 10331.1Schristos<p> 10341.1SchristosMany calendars have been proposed for Mars, but none have achieved 10351.1Schristoswide acceptance. Astronomers often use Mars Sol Date (MSD) which is a 10361.1Schristossequential count of Mars solar days elapsed since about 1873-12-29 10371.1Schristos12:00 GMT. 10381.1Schristos</p> 10391.1Schristos 10401.1Schristos<p> 10411.1SchristosIn our solar system, Mars is the planet with time and calendar most 10421.1Schristoslike Earth's. On other planets, Sun-based time and calendars would 10431.1Schristoswork quite differently. For example, although Mercury's sidereal 10441.1Schristosrotation period is 58.646 Earth days, Mercury revolves around the Sun 10451.1Schristosso rapidly that an observer on Mercury's equator would see a sunrise 10461.1Schristosonly every 175.97 Earth days, i.e., a Mercury year is 0.5 of a Mercury 10471.1Schristosday. Venus is more complicated, partly because its rotation is 10481.1Schristosslightly retrograde: its year is 1.92 of its days. Gas giants like 10491.1SchristosJupiter are trickier still, as their polar and equatorial regions 10501.1Schristosrotate at different rates, so that the length of a day depends on 10511.1Schristoslatitude. This effect is most pronounced on Neptune, where the day is 10521.1Schristosabout 12 hours at the poles and 18 hours at the equator. 10531.1Schristos</p> 10541.1Schristos 10551.1Schristos<p> 10561.1SchristosAlthough the tz database does not support time on other planets, it is 10571.1Schristosdocumented here in the hopes that support will be added eventually. 10581.1Schristos</p> 10591.1Schristos 10601.1Schristos<p> 10611.1SchristosSources: 10621.1Schristos</p> 10631.1Schristos<ul> 10641.1Schristos <li> 10651.1SchristosMichael Allison and Robert Schmunk, 10661.1Schristos"<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical 10671.1SchristosNotes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" 10681.2Schristos(2015-06-30). 10691.1Schristos </li> 10701.1Schristos <li> 10711.1SchristosJia-Rui Chong, 10721.1Schristos"<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays 10731.1SchristosFit for a Martian</a>", Los Angeles Times 10741.1Schristos(2004-01-14), pp A1, A20-A21. 10751.1Schristos </li> 10761.1Schristos <li> 10771.1SchristosTom Chmielewski, 10781.1Schristos"<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet 10791.1SchristosLag Is Worse on Mars</a>", The Atlantic (2015-02-26) 10801.1Schristos </li> 10811.1Schristos <li> 10821.1SchristosMatt Williams, 10831.1Schristos"<a href="https://www.universetoday.com/37481/days-of-the-planets/">How 10841.1Schristoslong is a day on the other planets of the solar system?</a>" 10851.1Schristos(2017-04-27). 10861.1Schristos </li> 10871.1Schristos</ul> 10881.1Schristos </section> 10891.1Schristos 10901.1Schristos <footer> 10911.1Schristos <hr> 10921.1SchristosThis file is in the public domain, so clarified as of 2009-05-17 by 10931.1SchristosArthur David Olson. 10941.1Schristos </footer> 10951.1Schristos</body> 10961.1Schristos</html> 1097