1b2b04f7eSchristos<!DOCTYPE html> 25f2f4c60Schristos<html lang="en"> 35f2f4c60Schristos<head> 45f2f4c60Schristos <title>Theory and pragmatics of the tz code and data</title> 55f2f4c60Schristos <meta charset="UTF-8"> 6b2b04f7eSchristos <style> 7b2b04f7eSchristos pre {margin-left: 2em; white-space: pre-wrap;} 8b2b04f7eSchristos </style> 95f2f4c60Schristos</head> 105f2f4c60Schristos 115f2f4c60Schristos<body> 12cfc8dcb4Schristos<h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1> 135f2f4c60Schristos <h3>Outline</h3> 145f2f4c60Schristos <nav> 155f2f4c60Schristos <ul> 16cfc8dcb4Schristos <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code> 17cfc8dcb4Schristos database</a></li> 1891e14238Schristos <li><a href="#naming">Timezone identifiers</a></li> 195f2f4c60Schristos <li><a href="#abbreviations">Time zone abbreviations</a></li> 20cfc8dcb4Schristos <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code> 21cfc8dcb4Schristos database</a></li> 225f2f4c60Schristos <li><a href="#functions">Time and date functions</a></li> 235f2f4c60Schristos <li><a href="#stability">Interface stability</a></li> 2414c787bcSchristos <li><a href="#leapsec">Leap seconds</a></li> 255f2f4c60Schristos <li><a href="#calendar">Calendrical issues</a></li> 2689098d20Schristos <li><a href="#planets">Time and time zones off earth</a></li> 275f2f4c60Schristos </ul> 285f2f4c60Schristos </nav> 295f2f4c60Schristos 305f2f4c60Schristos<section> 31cfc8dcb4Schristos <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2> 325f2f4c60Schristos<p> 33cfc8dcb4SchristosThe <a 34cfc8dcb4Schristoshref="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code> 35cfc8dcb4Schristosdatabase</a> attempts to record the history and predicted future of 367328cbb4Schristoscivil time scales. 37cfc8dcb4SchristosIt organizes <a href="tz-link.html">time zone and daylight saving time 38cfc8dcb4Schristosdata</a> by partitioning the world into <a 39b2b04f7eSchristoshref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a> 40cfc8dcb4Schristoswhose clocks all agree about timestamps that occur after the <a 41cfc8dcb4Schristoshref="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a> 42cfc8dcb4Schristos(1970-01-01 00:00:00 <a 43cfc8dcb4Schristoshref="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr 44cfc8dcb4Schristostitle="Coordinated Universal Time">UTC</abbr></a>). 45cfc8dcb4SchristosAlthough 1970 is a somewhat-arbitrary cutoff, there are significant 46cfc8dcb4Schristoschallenges to moving the cutoff earlier even by a decade or two, due 47cfc8dcb4Schristosto the wide variety of local practices before computer timekeeping 48cfc8dcb4Schristosbecame prevalent. 491b584801SchristosMost timezones correspond to a notable location and the database 501b584801Schristosrecords all known clock transitions for that location; 511b584801Schristossome timezones correspond instead to a fixed <abbr>UTC</abbr> offset. 525f2f4c60Schristos</p> 535f2f4c60Schristos 545f2f4c60Schristos<p> 55b2b04f7eSchristosEach timezone typically corresponds to a geographical region that is 56b2b04f7eSchristossmaller than a traditional time zone, because clocks in a timezone 57b2b04f7eSchristosall agree after 1970 whereas a traditional time zone merely 58b2b04f7eSchristosspecifies current standard time. For example, applications that deal 59b2b04f7eSchristoswith current and future timestamps in the traditional North 60b2b04f7eSchristosAmerican mountain time zone can choose from the timezones 61b2b04f7eSchristos<code>America/Denver</code> which observes US-style daylight saving 621b584801Schristostime (<abbr>DST</abbr>), 631b584801Schristosand <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>. 64b2b04f7eSchristosApplications that also deal with past timestamps in the mountain time 65b2b04f7eSchristoszone can choose from over a dozen timezones, such as 66b2b04f7eSchristos<code>America/Boise</code>, <code>America/Edmonton</code>, and 67b2b04f7eSchristos<code>America/Hermosillo</code>, each of which currently uses mountain 68b2b04f7eSchristostime but differs from other timezones for some timestamps after 1970. 69b2b04f7eSchristos</p> 70b2b04f7eSchristos 71b2b04f7eSchristos<p> 721b584801SchristosClock transitions before 1970 are recorded for location-based timezones, 735f2f4c60Schristosbecause most systems support timestamps before 1970 and could 745f2f4c60Schristosmisbehave if data entries were omitted for pre-1970 transitions. 755f2f4c60SchristosHowever, the database is not designed for and does not suffice for 765f2f4c60Schristosapplications requiring accurate handling of all past times everywhere, 775f2f4c60Schristosas it would take far too much effort and guesswork to record all 785f2f4c60Schristosdetails of pre-1970 civil timekeeping. 79cfc8dcb4SchristosAlthough some information outside the scope of the database is 80cf471610Schristoscollected in a file <code>backzone</code> that is distributed along 81cf471610Schristoswith the database proper, this file is less reliable and does not 82cf471610Schristosnecessarily follow database guidelines. 835f2f4c60Schristos</p> 845f2f4c60Schristos 855f2f4c60Schristos<p> 86cfc8dcb4SchristosAs described below, reference source code for using the 87cfc8dcb4Schristos<code><abbr>tz</abbr></code> database is also available. 88cfc8dcb4SchristosThe <code><abbr>tz</abbr></code> code is upwards compatible with <a 89cfc8dcb4Schristoshref="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international 90cfc8dcb4Schristosstandard for <a 91cfc8dcb4Schristoshref="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems. 927d1a89a3SchristosAs of this writing, the current edition of POSIX is POSIX.1-2024, 937d1a89a3Schristoswhich has been published but not yet in HTML form. 947d1a89a3SchristosUnlike its predecessor POSIX.1-2017 (<a 957005738dSchristoshref="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open 96cfc8dcb4SchristosGroup Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018 977d1a89a3SchristosEdition), POSIX.1-2024 requires support for the 987d1a89a3Schristos<code><abbr>tz</abbr></code> database, which has a 997d1a89a3Schristosmodel for describing civil time that is more complex than the 1007d1a89a3Schristosstandard and daylight saving times required by POSIX.1-2017. 101b2b04f7eSchristosA <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can 102cfc8dcb4Schristoshave more than two changes per year, these changes need not merely 103cfc8dcb4Schristosflip back and forth between two alternatives, and the rules themselves 104cfc8dcb4Schristoscan change at times. 10514c787bcSchristosWhether and when a timezone changes its clock, 10614c787bcSchristosand even the timezone's notional base offset from <abbr>UTC</abbr>, 10714c787bcSchristosare variable. 108b2b04f7eSchristosIt does not always make sense to talk about a timezone's 109b2b04f7eSchristos"base offset", which is not necessarily a single number. 1105f2f4c60Schristos</p> 111cfc8dcb4Schristos 1125f2f4c60Schristos</section> 1135f2f4c60Schristos 1145f2f4c60Schristos<section> 11591e14238Schristos <h2 id="naming">Timezone identifiers</h2> 1165f2f4c60Schristos<p> 11791e14238SchristosEach timezone has a name that uniquely identifies the timezone. 1185f2f4c60SchristosInexperienced users are not expected to select these names unaided. 1195f2f4c60SchristosDistributors should provide documentation and/or a simple selection 120b2b04f7eSchristosinterface that explains each name via a map or via descriptive text like 1217328cbb4Schristos"Czech Republic" instead of the timezone name "<code>Europe/Prague</code>". 122b2b04f7eSchristosIf geolocation information is available, a selection interface can 123b2b04f7eSchristoslocate the user on a timezone map or prioritize names that are 124b2b04f7eSchristosgeographically close. For an example selection interface, see the 125cfc8dcb4Schristos<code>tzselect</code> program in the <code><abbr>tz</abbr></code> code. 126*18b32cd1SchristosUnicode's <a href="https://cldr.unicode.org">Common Locale Data 127*18b32cd1SchristosRepository (<abbr>CLDR</abbr>)</a> 128*18b32cd1Schristoscontains data that may be useful for other selection 1297328cbb4Schristosinterfaces; it maps timezone names like <code>Europe/Prague</code> to 1307328cbb4Schristoslocale-dependent strings like "Prague", "Praha", "Прага", and "布拉格". 1315f2f4c60Schristos</p> 1325f2f4c60Schristos 1335f2f4c60Schristos<p> 134cfc8dcb4SchristosThe naming conventions attempt to strike a balance 1355f2f4c60Schristosamong the following goals: 1365f2f4c60Schristos</p> 137cfc8dcb4Schristos 1385f2f4c60Schristos<ul> 1395f2f4c60Schristos <li> 140b2b04f7eSchristos Uniquely identify every timezone where clocks have agreed since 1970. 1415f2f4c60Schristos This is essential for the intended use: static clocks keeping local 1425f2f4c60Schristos civil time. 1435f2f4c60Schristos </li> 1445f2f4c60Schristos <li> 145b2b04f7eSchristos Indicate to experts where the timezone's clocks typically are. 1465f2f4c60Schristos </li> 1475f2f4c60Schristos <li> 148cfc8dcb4Schristos Be robust in the presence of political changes. 14991e14238Schristos For example, names are typically not tied to countries, to avoid 150cfc8dcb4Schristos incompatibilities when countries change their name (e.g., 15191e14238Schristos Swaziland→Eswatini) or when locations change countries (e.g., Hong 152cfc8dcb4Schristos Kong from UK colony to China). 15391e14238Schristos There is no requirement that every country or national 15491e14238Schristos capital must have a timezone name. 1555f2f4c60Schristos </li> 1565f2f4c60Schristos <li> 1575f2f4c60Schristos Be portable to a wide variety of implementations. 1585f2f4c60Schristos </li> 1595f2f4c60Schristos <li> 1605f2f4c60Schristos Use a consistent naming conventions over the entire world. 1615f2f4c60Schristos </li> 1625f2f4c60Schristos</ul> 163cfc8dcb4Schristos 1645f2f4c60Schristos<p> 1657d1a89a3SchristosNames normally have the format 166cfc8dcb4Schristos<var>AREA</var><code>/</code><var>LOCATION</var>, where 167b2b04f7eSchristos<var>AREA</var> is a continent or ocean, and 168b2b04f7eSchristos<var>LOCATION</var> is a specific location within the area. 169cfc8dcb4SchristosNorth and South America share the same area, '<code>America</code>'. 170cfc8dcb4SchristosTypical names are '<code>Africa/Cairo</code>', 171cfc8dcb4Schristos'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'. 172cfc8dcb4SchristosSome names are further qualified to help avoid confusion; for example, 173cfc8dcb4Schristos'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg, 174cfc8dcb4SchristosIndiana from other Petersburgs in America. 1755f2f4c60Schristos</p> 1765f2f4c60Schristos 1775f2f4c60Schristos<p> 178cfc8dcb4SchristosHere are the general guidelines used for 179b2b04f7eSchristoschoosing timezone names, 1805f2f4c60Schristosin decreasing order of importance: 1815f2f4c60Schristos</p> 182cfc8dcb4Schristos 1835f2f4c60Schristos<ul> 1845f2f4c60Schristos <li> 1855f2f4c60Schristos Use only valid POSIX file name components (i.e., the parts of 186cfc8dcb4Schristos names other than '<code>/</code>'). 187cfc8dcb4Schristos Do not use the file name components '<code>.</code>' and 188cfc8dcb4Schristos '<code>..</code>'. 189cfc8dcb4Schristos Within a file name component, use only <a 190cfc8dcb4Schristos href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters, 191cfc8dcb4Schristos '<code>.</code>', '<code>-</code>' and '<code>_</code>'. 192cfc8dcb4Schristos Do not use digits, as that might create an ambiguity with <a 1937d1a89a3Schristos href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX's proleptic 194cfc8dcb4Schristos <code>TZ</code> strings</a>. 195cfc8dcb4Schristos A file name component must not exceed 14 characters or start with 196cfc8dcb4Schristos '<code>-</code>'. 1971b584801Schristos E.g., prefer <code>America/Noronha</code> to 1981b584801Schristos <code>America/Fernando_de_Noronha</code>. 199cfc8dcb4Schristos Exceptions: see the discussion of legacy names below. 2005f2f4c60Schristos </li> 2015f2f4c60Schristos <li> 2025f2f4c60Schristos A name must not be empty, or contain '<code>//</code>', or 2035f2f4c60Schristos start or end with '<code>/</code>'. 204*18b32cd1Schristos Also, a name must not be '<code>Etc/Unknown</code>', as 205*18b32cd1Schristos <abbr>CLDR</abbr> uses that string for an unknown or invalid timezone. 2065f2f4c60Schristos </li> 2075f2f4c60Schristos <li> 208cfc8dcb4Schristos Do not use names that differ only in case. 209cfc8dcb4Schristos Although the reference implementation is case-sensitive, some 210cfc8dcb4Schristos other implementations are not, and they would mishandle names 211cfc8dcb4Schristos differing only in case. 2125f2f4c60Schristos </li> 2135f2f4c60Schristos <li> 2145f2f4c60Schristos If one name <var>A</var> is an initial prefix of another 215cfc8dcb4Schristos name <var>AB</var> (ignoring case), then <var>B</var> must not 216cfc8dcb4Schristos start with '<code>/</code>', as a regular file cannot have the 217cfc8dcb4Schristos same name as a directory in POSIX. 218cfc8dcb4Schristos For example, <code>America/New_York</code> precludes 219cfc8dcb4Schristos <code>America/New_York/Bronx</code>. 2205f2f4c60Schristos </li> 2215f2f4c60Schristos <li> 2225f2f4c60Schristos Uninhabited regions like the North Pole and Bouvet Island 2235f2f4c60Schristos do not need locations, since local time is not defined there. 2245f2f4c60Schristos </li> 2255f2f4c60Schristos <li> 226*18b32cd1Schristos If all clocks in a region have agreed since 1970, 227*18b32cd1Schristos give them just one name even if some of the clocks disagreed before 1970, 228*18b32cd1Schristos or reside in different countries or in notable or faraway locations. 2295f2f4c60Schristos Otherwise these tables would become annoyingly large. 230*18b32cd1Schristos For example, do not create a name <code>Indian/Crozet</code> 231*18b32cd1Schristos as a near-duplicate or alias of <code>Asia/Dubai</code> 232*18b32cd1Schristos merely because they are different countries or territories, 233*18b32cd1Schristos or their clocks disagreed before 1970, or the 234*18b32cd1Schristos <a href="https://en.wikipedia.org/wiki/Crozet_Islands">Crozet Islands</a> 235*18b32cd1Schristos are notable in their own right, 236*18b32cd1Schristos or the Crozet Islands are not adjacent to other locations 237*18b32cd1Schristos that use <code>Asia/Dubai</code>. 2385f2f4c60Schristos </li> 2395f2f4c60Schristos <li> 24091e14238Schristos If boundaries between regions are fluid, such as during a war or 24191e14238Schristos insurrection, do not bother to create a new timezone merely 24291e14238Schristos because of yet another boundary change. This helps prevent table 24391e14238Schristos bloat and simplifies maintenance. 24491e14238Schristos </li> 24591e14238Schristos <li> 2465f2f4c60Schristos If a name is ambiguous, use a less ambiguous alternative; 247cfc8dcb4Schristos e.g., many cities are named San José and Georgetown, so 248cfc8dcb4Schristos prefer <code>America/Costa_Rica</code> to 249cfc8dcb4Schristos <code>America/San_Jose</code> and <code>America/Guyana</code> 250cfc8dcb4Schristos to <code>America/Georgetown</code>. 2515f2f4c60Schristos </li> 2525f2f4c60Schristos <li> 253cfc8dcb4Schristos Keep locations compact. 254cfc8dcb4Schristos Use cities or small islands, not countries or regions, so that any 255cfc8dcb4Schristos future changes do not split individual locations into different 256b2b04f7eSchristos timezones. 257cfc8dcb4Schristos E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>, 258cfc8dcb4Schristos since 259cfc8dcb4Schristos <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France 260cfc8dcb4Schristos has had multiple time zones</a>. 2615f2f4c60Schristos </li> 2625f2f4c60Schristos <li> 263cfc8dcb4Schristos Use mainstream English spelling, e.g., prefer 264b2b04f7eSchristos <code>Europe/Rome</code> to <code>Europa/Roma</code>, and 265cfc8dcb4Schristos prefer <code>Europe/Athens</code> to the Greek 266b2b04f7eSchristos <code>Ευρώπη/Αθήνα</code> or the Romanized 267b2b04f7eSchristos <code>Evrópi/Athína</code>. 268cfc8dcb4Schristos The POSIX file name restrictions encourage this guideline. 2695f2f4c60Schristos </li> 2705f2f4c60Schristos <li> 271cfc8dcb4Schristos Use the most populous among locations in a region, 272cfc8dcb4Schristos e.g., prefer <code>Asia/Shanghai</code> to 273cfc8dcb4Schristos <code>Asia/Beijing</code>. 274cfc8dcb4Schristos Among locations with similar populations, pick the best-known 275cfc8dcb4Schristos location, e.g., prefer <code>Europe/Rome</code> to 276cfc8dcb4Schristos <code>Europe/Milan</code>. 2775f2f4c60Schristos </li> 2785f2f4c60Schristos <li> 279cfc8dcb4Schristos Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to 280cfc8dcb4Schristos <code>Atlantic/Canaries</code>. 2815f2f4c60Schristos </li> 2825f2f4c60Schristos <li> 2835f2f4c60Schristos Omit common suffixes like '<code>_Islands</code>' and 284cfc8dcb4Schristos '<code>_City</code>', unless that would lead to ambiguity. 285cfc8dcb4Schristos E.g., prefer <code>America/Cayman</code> to 286cfc8dcb4Schristos <code>America/Cayman_Islands</code> and 287cfc8dcb4Schristos <code>America/Guatemala</code> to 288cfc8dcb4Schristos <code>America/Guatemala_City</code>, but prefer 289cfc8dcb4Schristos <code>America/Mexico_City</code> to 290cfc8dcb4Schristos <code>America/Mexico</code> 291cfc8dcb4Schristos because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the 292cfc8dcb4Schristos country of Mexico has several time zones</a>. 2935f2f4c60Schristos </li> 2945f2f4c60Schristos <li> 2955f2f4c60Schristos Use '<code>_</code>' to represent a space. 2965f2f4c60Schristos </li> 2975f2f4c60Schristos <li> 298cfc8dcb4Schristos Omit '<code>.</code>' from abbreviations in names. 299cfc8dcb4Schristos E.g., prefer <code>Atlantic/St_Helena</code> to 300cfc8dcb4Schristos <code>Atlantic/St._Helena</code>. 3015f2f4c60Schristos </li> 3025f2f4c60Schristos <li> 303cfc8dcb4Schristos Do not change established names if they only marginally violate 304cfc8dcb4Schristos the above guidelines. 305cfc8dcb4Schristos For example, do not change the existing name <code>Europe/Rome</code> to 306cfc8dcb4Schristos <code>Europe/Milan</code> merely because Milan's population has grown 307cfc8dcb4Schristos to be somewhat greater than Rome's. 3085f2f4c60Schristos </li> 3095f2f4c60Schristos <li> 3105f2f4c60Schristos If a name is changed, put its old spelling in the 311e1e57937Schristos '<code>backward</code>' file as a link to the new spelling. 3125f2f4c60Schristos This means old spellings will continue to work. 31314c787bcSchristos Ordinarily a name change should occur only in the rare case when 31414c787bcSchristos a location's consensus English-language spelling changes; for example, 31514c787bcSchristos in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code> 31614c787bcSchristos due to long-time widespread use of the new city name instead of the old. 3175f2f4c60Schristos </li> 3185f2f4c60Schristos</ul> 3195f2f4c60Schristos 3205f2f4c60Schristos<p> 32191e14238SchristosGuidelines have evolved with time, and names following old versions of 3227005738dSchristosthese guidelines might not follow the current version. When guidelines 32391e14238Schristoshave changed, old names continue to be supported. Guideline changes 32491e14238Schristoshave included the following: 3255f2f4c60Schristos</p> 3265f2f4c60Schristos 32791e14238Schristos<ul> 32891e14238Schristos<li> 32991e14238SchristosOlder versions of this package used a different naming scheme. 3305f2f4c60SchristosSee the file '<code>backward</code>' for most of these older names 3315f2f4c60Schristos(e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>'). 3325f2f4c60SchristosThe other old-fashioned names still supported are 333cfc8dcb4Schristos'<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and 334cfc8dcb4Schristos'<code>EET</code>' (see the file '<code>europe</code>'). 33591e14238Schristos</li> 3365f2f4c60Schristos 33791e14238Schristos<li> 3385f2f4c60SchristosOlder versions of this package defined legacy names that are 339cfc8dcb4Schristosincompatible with the first guideline of location names, but which are 340cfc8dcb4Schristosstill supported. 341cfc8dcb4SchristosThese legacy names are mostly defined in the file 342cfc8dcb4Schristos'<code>etcetera</code>'. 343cfc8dcb4SchristosAlso, the file '<code>backward</code>' defines the legacy names 3441e7378f8Schristos'<code>Etc/GMT0</code>', '<code>Etc/GMT-0</code>', '<code>Etc/GMT+0</code>', 345cfc8dcb4Schristos'<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', 346cfc8dcb4Schristosand the file '<code>northamerica</code>' defines the legacy names 347cfc8dcb4Schristos'<code>EST5EDT</code>', '<code>CST6CDT</code>', 348cfc8dcb4Schristos'<code>MST7MDT</code>', and '<code>PST8PDT</code>'. 34991e14238Schristos</li> 35091e14238Schristos 35191e14238Schristos<li> 3527005738dSchristosOlder versions of these guidelines said that 35391e14238Schristosthere should typically be at least one name for each <a 35491e14238Schristoshref="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr 35591e14238Schristostitle="International Organization for Standardization">ISO</abbr> 35691e14238Schristos3166-1</a> officially assigned two-letter code for an inhabited 35791e14238Schristoscountry or territory. 35891e14238SchristosThis old guideline has been dropped, as it was not needed to handle 35991e14238Schristostimestamps correctly and it increased maintenance burden. 36091e14238Schristos</li> 36191e14238Schristos</ul> 36291e14238Schristos 36391e14238Schristos<p> 364e1e57937SchristosThe file <code>zone1970.tab</code> lists geographical locations used 36591e14238Schristosto name timezones. 36691e14238SchristosIt is intended to be an exhaustive list of names for geographic 36791e14238Schristosregions as described above; this is a subset of the timezones in the data. 368e1e57937SchristosAlthough a <code>zone1970.tab</code> location's 36991e14238Schristos<a href="https://en.wikipedia.org/wiki/Longitude">longitude</a> 37091e14238Schristoscorresponds to 37191e14238Schristosits <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean 37291e14238Schristostime (<abbr>LMT</abbr>)</a> offset with one hour for every 15° 37391e14238Schristoseast longitude, this relationship is not exact. 374e1e57937SchristosThe backward-compatibility file <code>zone.tab</code> is similar 375e1e57937Schristosbut conforms to the older-version guidelines related to <abbr>ISO</abbr> 3166-1; 376e1e57937Schristosit lists only one country code per entry and unlike <code>zone1970.tab</code> 377e1e57937Schristosit can list names defined in <code>backward</code>. 378f22d6113SchristosApplications that process only timestamps from now on can instead use the file 379f22d6113Schristos<code>zonenow.tab</code>, which partitions the world more coarsely, 380f22d6113Schristosinto regions where clocks agree now and in the predicted future; 381f22d6113Schristosthis file is smaller and simpler than <code>zone1970.tab</code> 382f22d6113Schristosand <code>zone.tab</code>. 3835f2f4c60Schristos</p> 3845f2f4c60Schristos 3855f2f4c60Schristos<p> 386e1e57937SchristosThe database defines each timezone name to be a zone, or a link to a zone. 387e1e57937SchristosThe source file <code>backward</code> defines links for backward 388e1e57937Schristoscompatibility; it does not define zones. 389e1e57937SchristosAlthough <code>backward</code> was originally designed to be optional, 390e1e57937Schristosnowadays distributions typically use it 391e1e57937Schristosand no great weight should be attached to whether a link 392e1e57937Schristosis defined in <code>backward</code> or in some other file. 393e1e57937SchristosThe source file <code>etcetera</code> defines names that may be useful 3947d1a89a3Schristoson platforms that do not support proleptic <code>TZ</code> strings 3957d1a89a3Schristoslike <code><+08>-8</code>; 396e1e57937Schristosno other source file other than <code>backward</code> 397e1e57937Schristoscontains links to its zones. 3980129e5c6SchristosOne of <code>etcetera</code>'s names is <code>Etc/UTC</code>, 399e1e57937Schristosused by functions like <code>gmtime</code> to obtain leap 400e1e57937Schristossecond information on platforms that support leap seconds. 4010129e5c6SchristosAnother <code>etcetera</code> name, <code>GMT</code>, 4020129e5c6Schristosis used by older code releases. 4035f2f4c60Schristos</p> 4045f2f4c60Schristos</section> 405cfc8dcb4Schristos 4065f2f4c60Schristos<section> 4075f2f4c60Schristos <h2 id="abbreviations">Time zone abbreviations</h2> 4085f2f4c60Schristos<p> 4095f2f4c60SchristosWhen this package is installed, it generates time zone abbreviations 4105f2f4c60Schristoslike '<code>EST</code>' to be compatible with human tradition and POSIX. 411cfc8dcb4SchristosHere are the general guidelines used for choosing time zone abbreviations, 4125f2f4c60Schristosin decreasing order of importance: 413cfc8dcb4Schristos</p> 414cfc8dcb4Schristos 4155f2f4c60Schristos<ul> 4165f2f4c60Schristos <li> 417cf471610Schristos Use three to six characters that are ASCII alphanumerics or 4185f2f4c60Schristos '<code>+</code>' or '<code>-</code>'. 4195f2f4c60Schristos Previous editions of this database also used characters like 420cfc8dcb4Schristos space and '<code>?</code>', but these characters have a 421cfc8dcb4Schristos special meaning to the 422cfc8dcb4Schristos <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a> 423cfc8dcb4Schristos and cause commands like 4247005738dSchristos '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a> 4257005738dSchristos `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>' 4265f2f4c60Schristos to have unexpected effects. 427cfc8dcb4Schristos Previous editions of this guideline required upper-case letters, but the 428cfc8dcb4Schristos Congressman who introduced 429cfc8dcb4Schristos <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro 430cfc8dcb4Schristos Standard Time</a> preferred "ChST", so lower-case letters are now 431cfc8dcb4Schristos allowed. 432cfc8dcb4Schristos Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>', 433cfc8dcb4Schristos '<code>+</code>', and alphanumeric characters from the portable 434cfc8dcb4Schristos character set in the current locale. 435cfc8dcb4Schristos In practice ASCII alphanumerics and '<code>+</code>' and 436cfc8dcb4Schristos '<code>-</code>' are safe in all locales. 4375f2f4c60Schristos 438cfc8dcb4Schristos <p> 4395f2f4c60Schristos In other words, in the C locale the POSIX extended regular 440cfc8dcb4Schristos expression <code>[-+[:alnum:]]{3,6}</code> should match the 441cfc8dcb4Schristos abbreviation. 4427d1a89a3Schristos This guarantees that all abbreviations could have been specified 4437d1a89a3Schristos explicitly by a POSIX proleptic <code>TZ</code> string. 444cfc8dcb4Schristos </p> 4455f2f4c60Schristos </li> 4465f2f4c60Schristos <li> 4475f2f4c60Schristos Use abbreviations that are in common use among English-speakers, 448cfc8dcb4Schristos e.g., 'EST' for Eastern Standard Time in North America. 4495f2f4c60Schristos We assume that applications translate them to other languages 4505f2f4c60Schristos as part of the normal localization process; for example, 4515f2f4c60Schristos a French application might translate 'EST' to 'HNE'. 452cf471610Schristos 453cfc8dcb4Schristos <p> 454cfc8dcb4Schristos <small>These abbreviations (for standard/daylight/etc. time) are: 455cf471610Schristos ACST/ACDT Australian Central, 456cf471610Schristos AST/ADT/APT/AWT/ADDT Atlantic, 457cf471610Schristos AEST/AEDT Australian Eastern, 458cf471610Schristos AHST/AHDT Alaska-Hawaii, 459cf471610Schristos AKST/AKDT Alaska, 460cf471610Schristos AWST/AWDT Australian Western, 461cf471610Schristos BST/BDT Bering, 462cf471610Schristos CAT/CAST Central Africa, 463cf471610Schristos CET/CEST/CEMT Central European, 464cf471610Schristos ChST Chamorro, 46589098d20Schristos CST/CDT/CWT/CPT Central [North America], 466cf471610Schristos CST/CDT China, 467cf471610Schristos GMT/BST/IST/BDST Greenwich, 468cf471610Schristos EAT East Africa, 46989098d20Schristos EST/EDT/EWT/EPT Eastern [North America], 470cf471610Schristos EET/EEST Eastern European, 47176c76726Schristos GST/GDT Guam, 472273e6379Schristos HST/HDT/HWT/HPT Hawaii, 47314c787bcSchristos HKT/HKST/HKWT Hong Kong, 474cf471610Schristos IST India, 475cf471610Schristos IST/GMT Irish, 476cf471610Schristos IST/IDT/IDDT Israel, 477cf471610Schristos JST/JDT Japan, 478cf471610Schristos KST/KDT Korea, 479cfc8dcb4Schristos MET/MEST Middle European (a backward-compatibility alias for 480cfc8dcb4Schristos Central European), 481cf471610Schristos MSK/MSD Moscow, 48289098d20Schristos MST/MDT/MWT/MPT Mountain, 483cf471610Schristos NST/NDT/NWT/NPT/NDDT Newfoundland, 484cf471610Schristos NST/NDT/NWT/NPT Nome, 485cf471610Schristos NZMT/NZST New Zealand through 1945, 486cf471610Schristos NZST/NZDT New Zealand 1946–present, 487cf471610Schristos PKT/PKST Pakistan, 48889098d20Schristos PST/PDT/PWT/PPT Pacific, 489b2b04f7eSchristos PST/PDT Philippine, 490cf471610Schristos SAST South Africa, 491cf471610Schristos SST Samoa, 4920129e5c6Schristos UTC Universal, 493cf471610Schristos WAT/WAST West Africa, 494cf471610Schristos WET/WEST/WEMT Western European, 495cf471610Schristos WIB Waktu Indonesia Barat, 496cf471610Schristos WIT Waktu Indonesia Timur, 497cf471610Schristos WITA Waktu Indonesia Tengah, 498cfc8dcb4Schristos YST/YDT/YWT/YPT/YDDT Yukon</small>. 499cfc8dcb4Schristos </p> 5005f2f4c60Schristos </li> 5015f2f4c60Schristos <li> 502cfc8dcb4Schristos <p> 503cfc8dcb4Schristos For times taken from a city's longitude, use the 504cfc8dcb4Schristos traditional <var>x</var>MT notation. 505cfc8dcb4Schristos The only abbreviation like this in current use is '<abbr>GMT</abbr>'. 506cfc8dcb4Schristos The others are for timestamps before 1960, 507cfc8dcb4Schristos except that Monrovia Mean Time persisted until 1972. 508cfc8dcb4Schristos Typically, numeric abbreviations (e.g., '<code>-</code>004430' for 509cfc8dcb4Schristos MMT) would cause trouble here, as the numeric strings would exceed 510cfc8dcb4Schristos the POSIX length limit. 511cfc8dcb4Schristos </p> 512cf471610Schristos 513cfc8dcb4Schristos <p> 514cfc8dcb4Schristos <small>These abbreviations are: 5151b584801Schristos AMT Asunción, Athens; 51689098d20Schristos BMT Baghdad, Bangkok, Batavia, Bermuda, Bern, Bogotá, 517234ed2b2Schristos Brussels, Bucharest; 5181b584801Schristos CMT Calamarca, Caracas, Chisinau, Colón, Córdoba; 519cf471610Schristos DMT Dublin/Dunsink; 520cf471610Schristos EMT Easter; 521cf471610Schristos FFMT Fort-de-France; 522cf471610Schristos FMT Funchal; 523cf471610Schristos GMT Greenwich; 524cf471610Schristos HMT Havana, Helsinki, Horta, Howrah; 525cf471610Schristos IMT Irkutsk, Istanbul; 526cf471610Schristos JMT Jerusalem; 5270129e5c6Schristos KMT Kaunas, Kyiv, Kingston; 52889098d20Schristos LMT Lima, Lisbon, local; 529cfc8dcb4Schristos MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo, 530cfc8dcb4Schristos Moratuwa, Moscow; 531cf471610Schristos PLMT Phù Liễn; 532cf471610Schristos PMT Paramaribo, Paris, Perm, Pontianak, Prague; 533cf471610Schristos PMMT Port Moresby; 53489098d20Schristos PPMT Port-au-Prince; 535cf471610Schristos QMT Quito; 536cf471610Schristos RMT Rangoon, Riga, Rome; 537cf471610Schristos SDMT Santo Domingo; 538cf471610Schristos SJMT San José; 539cf471610Schristos SMT Santiago, Simferopol, Singapore, Stanley; 540cf471610Schristos TBMT Tbilisi; 541cf471610Schristos TMT Tallinn, Tehran; 54289098d20Schristos WMT Warsaw.</small> 543cfc8dcb4Schristos </p> 544cf471610Schristos 545cfc8dcb4Schristos <p> 546cfc8dcb4Schristos <small>A few abbreviations also follow the pattern that 547b2b04f7eSchristos <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK. 548cfc8dcb4Schristos They are: 549234ed2b2Schristos BMT/BST for Bermuda 1890–1930, 550cf471610Schristos CMT/BST for Calamarca Mean Time and Bolivian Summer Time 551cfc8dcb4Schristos 1890–1932, 552cfc8dcb4Schristos DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time 553cfc8dcb4Schristos 1880–1916, 554cfc8dcb4Schristos MMT/MST/MDST for Moscow 1880–1919, and 555cfc8dcb4Schristos RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926. 5561b584801Schristos </small> 557cfc8dcb4Schristos </p> 5585f2f4c60Schristos </li> 5595f2f4c60Schristos <li> 560cfc8dcb4Schristos Use '<abbr>LMT</abbr>' for local mean time of locations before the 561cfc8dcb4Schristos introduction of standard time; see "<a href="#scope">Scope of the 562cfc8dcb4Schristos <code><abbr>tz</abbr></code> database</a>". 5635f2f4c60Schristos </li> 5645f2f4c60Schristos <li> 5655f2f4c60Schristos If there is no common English abbreviation, use numeric offsets like 566b2b04f7eSchristos <code>-</code>05 and <code>+</code>0530 that are generated 567cfc8dcb4Schristos by <code>zic</code>'s <code>%z</code> notation. 5685f2f4c60Schristos </li> 5695f2f4c60Schristos <li> 5705f2f4c60Schristos Use current abbreviations for older timestamps to avoid confusion. 571cfc8dcb4Schristos For example, in 1910 a common English abbreviation for time 5725f2f4c60Schristos in central Europe was 'MEZ' (short for both "Middle European 573cfc8dcb4Schristos Zone" and for "Mitteleuropäische Zeit" in German). 574cfc8dcb4Schristos Nowadays 'CET' ("Central European Time") is more common in 575cfc8dcb4Schristos English, and the database uses 'CET' even for circa-1910 576cfc8dcb4Schristos timestamps as this is less confusing for modern users and avoids 577cfc8dcb4Schristos the need for determining when 'CET' supplanted 'MEZ' in common 578cfc8dcb4Schristos usage. 5795f2f4c60Schristos </li> 5805f2f4c60Schristos <li> 581b2b04f7eSchristos Use a consistent style in a timezone's history. 582b2b04f7eSchristos For example, if a history tends to use numeric 583cfc8dcb4Schristos abbreviations and a particular entry could go either way, use a 584cfc8dcb4Schristos numeric abbreviation. 5855f2f4c60Schristos </li> 5865f2f4c60Schristos <li> 587cfc8dcb4Schristos Use 588cfc8dcb4Schristos <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a> 589cfc8dcb4Schristos (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for 590cfc8dcb4Schristos locations while uninhabited. 591cfc8dcb4Schristos The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in 592cfc8dcb4Schristos some sense undefined; this notation is derived 593*18b32cd1Schristos from <a href="https://www.rfc-editor.org/rfc/rfc3339">Internet 594b2b04f7eSchristos <abbr title="Request For Comments">RFC</abbr> 3339</a>. 5957d1a89a3Schristos (The abbreviation 'Z' that 596*18b32cd1Schristos <a href="https://www.rfc-editor.org/rfc/rfc9557">Internet 5977d1a89a3Schristos <abbr>RFC</abbr> 9557</a> uses for this concept 5987d1a89a3Schristos would violate the POSIX requirement 5997d1a89a3Schristos of at least three characters in an abbreviation.) 6005f2f4c60Schristos </li> 6015f2f4c60Schristos</ul> 602cfc8dcb4Schristos 6035f2f4c60Schristos<p> 6045f2f4c60SchristosApplication writers should note that these abbreviations are ambiguous 605cf471610Schristosin practice: e.g., 'CST' means one thing in China and something else 606cf471610Schristosin North America, and 'IST' can refer to time in India, Ireland or 607cfc8dcb4SchristosIsrael. 608cfc8dcb4SchristosTo avoid ambiguity, use numeric <abbr>UT</abbr> offsets like 609cf471610Schristos'<code>-</code>0600' instead of time zone abbreviations like 'CST'. 6105f2f4c60Schristos</p> 6115f2f4c60Schristos</section> 6125f2f4c60Schristos 6135f2f4c60Schristos<section> 614cfc8dcb4Schristos <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2> 6155f2f4c60Schristos<p> 616cfc8dcb4SchristosThe <code><abbr>tz</abbr></code> database is not authoritative, and it 617cfc8dcb4Schristossurely has errors. 618cf471610SchristosCorrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. 6195f2f4c60SchristosUsers requiring authoritative data should consult national standards 6205f2f4c60Schristosbodies and the references cited in the database's comments. 6215f2f4c60Schristos</p> 6225f2f4c60Schristos 6235f2f4c60Schristos<p> 624cfc8dcb4SchristosErrors in the <code><abbr>tz</abbr></code> database arise from many sources: 6255f2f4c60Schristos</p> 626cfc8dcb4Schristos 6275f2f4c60Schristos<ul> 6285f2f4c60Schristos <li> 629cfc8dcb4Schristos The <code><abbr>tz</abbr></code> database predicts future 630cfc8dcb4Schristos timestamps, and current predictions 6315f2f4c60Schristos will be incorrect after future governments change the rules. 6325f2f4c60Schristos For example, if today someone schedules a meeting for 13:00 next 6335f2f4c60Schristos October 1, Casablanca time, and tomorrow Morocco changes its 6345f2f4c60Schristos daylight saving rules, software can mess up after the rule change 6355f2f4c60Schristos if it blithely relies on conversions made before the change. 6365f2f4c60Schristos </li> 6375f2f4c60Schristos <li> 6385f2f4c60Schristos The pre-1970 entries in this database cover only a tiny sliver of how 6395f2f4c60Schristos clocks actually behaved; the vast majority of the necessary 640cfc8dcb4Schristos information was lost or never recorded. 641b2b04f7eSchristos Thousands more timezones would be needed if 642cfc8dcb4Schristos the <code><abbr>tz</abbr></code> database's scope were extended to 643cfc8dcb4Schristos cover even just the known or guessed history of standard time; for 644cfc8dcb4Schristos example, the current single entry for France would need to split 645cfc8dcb4Schristos into dozens of entries, perhaps hundreds. 646cfc8dcb4Schristos And in most of the world even this approach would be misleading 647cfc8dcb4Schristos due to widespread disagreement or indifference about what times 648cfc8dcb4Schristos should be observed. 649cfc8dcb4Schristos In her 2015 book 650cfc8dcb4Schristos <cite><a 6518c24072aSchristos href="https://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The 652cfc8dcb4Schristos Global Transformation of Time, 1870–1950</a></cite>, 653cfc8dcb4Schristos Vanessa Ogle writes 6545f2f4c60Schristos "Outside of Europe and North America there was no system of time 6555f2f4c60Schristos zones at all, often not even a stable landscape of mean times, 656cfc8dcb4Schristos prior to the middle decades of the twentieth century". 657cfc8dcb4Schristos See: Timothy Shenk, <a 6585f2f4c60Schristoshref="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked: 6595f2f4c60Schristos A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. 6605f2f4c60Schristos </li> 6615f2f4c60Schristos <li> 6625f2f4c60Schristos Most of the pre-1970 data entries come from unreliable sources, often 6635f2f4c60Schristos astrology books that lack citations and whose compilers evidently 6645f2f4c60Schristos invented entries when the true facts were unknown, without 6655f2f4c60Schristos reporting which entries were known and which were invented. 6665f2f4c60Schristos These books often contradict each other or give implausible entries, 6675f2f4c60Schristos and on the rare occasions when they are checked they are 6685f2f4c60Schristos typically found to be incorrect. 6695f2f4c60Schristos </li> 6705f2f4c60Schristos <li> 671cfc8dcb4Schristos For the UK the <code><abbr>tz</abbr></code> database relies on 672cfc8dcb4Schristos years of first-class work done by 6735f2f4c60Schristos Joseph Myers and others; see 6745f2f4c60Schristos "<a href="https://www.polyomino.org.uk/british-time/">History of 6755f2f4c60Schristos legal time in Britain</a>". 6765f2f4c60Schristos Other countries are not done nearly as well. 6775f2f4c60Schristos </li> 6785f2f4c60Schristos <li> 679cfc8dcb4Schristos Sometimes, different people in the same city maintain clocks 680cfc8dcb4Schristos that differ significantly. 681cfc8dcb4Schristos Historically, railway time was used by railroad companies (which 682cfc8dcb4Schristos did not always 683cfc8dcb4Schristos agree with each other), church-clock time was used for birth 684cfc8dcb4Schristos certificates, etc. 685cfc8dcb4Schristos More recently, competing political groups might disagree about 686cfc8dcb4Schristos clock settings. Often this is merely common practice, but 687cfc8dcb4Schristos sometimes it is set by law. 688cfc8dcb4Schristos For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France 689cfc8dcb4Schristos was legally <abbr>UT</abbr> +00:09:21 outside train stations and 690cfc8dcb4Schristos <abbr>UT</abbr> +00:04:21 inside. Other examples include 691cfc8dcb4Schristos Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and 692cfc8dcb4Schristos Ürümqi to this day. 6935f2f4c60Schristos </li> 6945f2f4c60Schristos <li> 695cfc8dcb4Schristos Although a named location in the <code><abbr>tz</abbr></code> 696cfc8dcb4Schristos database stands for the containing region, its pre-1970 data 697cfc8dcb4Schristos entries are often accurate for only a small subset of that region. 698cfc8dcb4Schristos For example, <code>Europe/London</code> stands for the United 699cfc8dcb4Schristos Kingdom, but its pre-1847 times are valid only for locations that 700cfc8dcb4Schristos have London's exact meridian, and its 1847 transition 701cfc8dcb4Schristos to <abbr>GMT</abbr> is known to be valid only for the L&NW and 702cfc8dcb4Schristos the Caledonian railways. 7035f2f4c60Schristos </li> 7045f2f4c60Schristos <li> 705cfc8dcb4Schristos The <code><abbr>tz</abbr></code> database does not record the 706b2b04f7eSchristos earliest time for which a timezone's 7075f2f4c60Schristos data entries are thereafter valid for every location in the region. 708cfc8dcb4Schristos For example, <code>Europe/London</code> is valid for all locations 709cfc8dcb4Schristos in its region after <abbr>GMT</abbr> was made the standard time, 710cfc8dcb4Schristos but the date of standardization (1880-08-02) is not in the 711cfc8dcb4Schristos <code><abbr>tz</abbr></code> database, other than in commentary. 712b2b04f7eSchristos For many timezones the earliest time of 713cfc8dcb4Schristos validity is unknown. 7145f2f4c60Schristos </li> 7155f2f4c60Schristos <li> 716cfc8dcb4Schristos The <code><abbr>tz</abbr></code> database does not record a 717cfc8dcb4Schristos region's boundaries, and in many cases the boundaries are not known. 718b2b04f7eSchristos For example, the timezone 719cfc8dcb4Schristos <code>America/Kentucky/Louisville</code> represents a region 720cfc8dcb4Schristos around the city of Louisville, the boundaries of which are 721cfc8dcb4Schristos unclear. 7225f2f4c60Schristos </li> 7235f2f4c60Schristos <li> 724cfc8dcb4Schristos Changes that are modeled as instantaneous transitions in the 725cfc8dcb4Schristos <code><abbr>tz</abbr></code> 7265f2f4c60Schristos database were often spread out over hours, days, or even decades. 7275f2f4c60Schristos </li> 7285f2f4c60Schristos <li> 7295f2f4c60Schristos Even if the time is specified by law, locations sometimes 7305f2f4c60Schristos deliberately flout the law. 7315f2f4c60Schristos </li> 7325f2f4c60Schristos <li> 7335f2f4c60Schristos Early timekeeping practices, even assuming perfect clocks, were 734cfc8dcb4Schristos often not specified to the accuracy that the 735cfc8dcb4Schristos <code><abbr>tz</abbr></code> database requires. 7365f2f4c60Schristos </li> 7375f2f4c60Schristos <li> 7387328cbb4Schristos The <code><abbr>tz</abbr></code> database cannot represent stopped clocks. 7397328cbb4Schristos However, on 1911-03-11 at 00:00, some public-facing French clocks 7407328cbb4Schristos were changed by stopping them for a few minutes to effect a transition. 7417328cbb4Schristos The <code><abbr>tz</abbr></code> database models this via a 7427328cbb4Schristos backward transition; the relevant French legislation does not 7437328cbb4Schristos specify exactly how the transition was to occur. 7447328cbb4Schristos </li> 7457328cbb4Schristos <li> 7465f2f4c60Schristos Sometimes historical timekeeping was specified more precisely 747cfc8dcb4Schristos than what the <code><abbr>tz</abbr></code> code can handle. 7481b584801Schristos For example, from 1880 to 1916 clocks in Ireland observed Dublin Mean 749cfc8dcb4Schristos Time (estimated to be <abbr>UT</abbr> 7500129e5c6Schristos −00:25:21.1); although the <code><abbr>tz</abbr></code> 7510129e5c6Schristos source data can represent the .1 second, TZif files and the code cannot. 752cfc8dcb4Schristos In practice these old specifications were rarely if ever 753cfc8dcb4Schristos implemented to subsecond precision. 7545f2f4c60Schristos </li> 7555f2f4c60Schristos <li> 756cfc8dcb4Schristos Even when all the timestamp transitions recorded by the 757cfc8dcb4Schristos <code><abbr>tz</abbr></code> database are correct, the 758cfc8dcb4Schristos <code><abbr>tz</abbr></code> rules that generate them may not 759cfc8dcb4Schristos faithfully reflect the historical rules. 760cfc8dcb4Schristos For example, from 1922 until World War II the UK moved clocks 761cfc8dcb4Schristos forward the day following the third Saturday in April unless that 762cfc8dcb4Schristos was Easter, in which case it moved clocks forward the previous 763cfc8dcb4Schristos Sunday. 764cfc8dcb4Schristos Because the <code><abbr>tz</abbr></code> database has no 7655f2f4c60Schristos way to specify Easter, these exceptional years are entered as 766cfc8dcb4Schristos separate <code><abbr>tz</abbr> Rule</code> lines, even though the 767cfc8dcb4Schristos legal rules did not change. 768b2b04f7eSchristos When transitions are known but the historical rules behind them are not, 769b2b04f7eSchristos the database contains <code>Zone</code> and <code>Rule</code> 770b2b04f7eSchristos entries that are intended to represent only the generated 771b2b04f7eSchristos transitions, not any underlying historical rules; however, this 772b2b04f7eSchristos intent is recorded at best only in commentary. 7735f2f4c60Schristos </li> 7745f2f4c60Schristos <li> 775b2b04f7eSchristos The <code><abbr>tz</abbr></code> database models time 776cfc8dcb4Schristos using the <a 777cfc8dcb4Schristos href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic 778b2b04f7eSchristos Gregorian calendar</a> with days containing 24 equal-length hours 779b2b04f7eSchristos numbered 00 through 23, except when clock transitions occur. 780b2b04f7eSchristos Pre-standard time is modeled as local mean time. 781b2b04f7eSchristos However, historically many people used other calendars and other timescales. 782cfc8dcb4Schristos For example, the Roman Empire used 783cfc8dcb4Schristos the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian 784cfc8dcb4Schristos calendar</a>, 785cfc8dcb4Schristos and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman 786cfc8dcb4Schristos timekeeping</a> had twelve varying-length daytime hours with a 7875f2f4c60Schristos non-hour-based system at night. 788b2b04f7eSchristos And even today, some local practices diverge from the Gregorian 789b2b04f7eSchristos calendar with 24-hour days. These divergences range from 790b2b04f7eSchristos relatively minor, such as Japanese bars giving times like "24:30" for the 791b2b04f7eSchristos wee hours of the morning, to more-significant differences such as <a 792f22d6113Schristos href="https://theworld.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the 793b2b04f7eSchristos east African practice of starting the day at dawn</a>, renumbering 794b2b04f7eSchristos the Western 06:00 to be 12:00. These practices are largely outside 795b2b04f7eSchristos the scope of the <code><abbr>tz</abbr></code> code and data, which 796b2b04f7eSchristos provide only limited support for date and time localization 7977d1a89a3Schristos such as that required by POSIX. 7981b584801Schristos If <abbr>DST</abbr> is not used a different time zone 799b2b04f7eSchristos can often do the trick; for example, in Kenya a <code>TZ</code> setting 800b2b04f7eSchristos like <code><-03>3</code> or <code>America/Cayenne</code> starts 801b2b04f7eSchristos the day six hours later than <code>Africa/Nairobi</code> does. 8025f2f4c60Schristos </li> 8035f2f4c60Schristos <li> 8045f2f4c60Schristos Early clocks were less reliable, and data entries do not represent 8055f2f4c60Schristos clock error. 8065f2f4c60Schristos </li> 8075f2f4c60Schristos <li> 808cfc8dcb4Schristos The <code><abbr>tz</abbr></code> database assumes Universal Time 809cfc8dcb4Schristos (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not 810cfc8dcb4Schristos standardized for older timestamps. 811cfc8dcb4Schristos In the <code><abbr>tz</abbr></code> database commentary, 812cfc8dcb4Schristos <abbr>UT</abbr> denotes a family of time standards that includes 813cfc8dcb4Schristos Coordinated Universal Time (<abbr>UTC</abbr>) along with other 814cfc8dcb4Schristos variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>, 815cfc8dcb4Schristos with days starting at midnight. 816cfc8dcb4Schristos Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern 817cfc8dcb4Schristos timestamps, <abbr>UTC</abbr> was not defined until 1960, so 81889098d20Schristos commentary uses the more general abbreviation <abbr>UT</abbr> for 819cfc8dcb4Schristos timestamps that might predate 1960. 820cfc8dcb4Schristos Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly, 821cfc8dcb4Schristos and since pre-1972 <abbr>UTC</abbr> seconds varied in length, 822cfc8dcb4Schristos interpretation of older timestamps can be problematic when 823cfc8dcb4Schristos subsecond accuracy is needed. 8245f2f4c60Schristos </li> 8255f2f4c60Schristos <li> 826cfc8dcb4Schristos Civil time was not based on atomic time before 1972, and we do not 827cfc8dcb4Schristos know the history of 828cfc8dcb4Schristos <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's 829cfc8dcb4Schristos rotation</a> accurately enough to map <a 830cfc8dcb4Schristos href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr 831cfc8dcb4Schristos title="International System of Units">SI</abbr></a> seconds to 832cfc8dcb4Schristos historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a> 833cfc8dcb4Schristos to more than about one-hour accuracy. 834cfc8dcb4Schristos See: Stephenson FR, Morrison LV, Hohenkerk CY. 835b2b04f7eSchristos <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of 836cfc8dcb4Schristos the Earth's rotation: 720 BC to AD 2015</a>. 8378c24072aSchristos <cite>Proc Royal Soc A</cite>. 2016;472:20160404. 8385f2f4c60Schristos Also see: Espenak F. <a 8395f2f4c60Schristos href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty 8405f2f4c60Schristos in Delta T (ΔT)</a>. 8415f2f4c60Schristos </li> 8425f2f4c60Schristos <li> 843cfc8dcb4Schristos The relationship between POSIX time (that is, <abbr>UTC</abbr> but 844cfc8dcb4Schristos ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap 84589098d20Schristos seconds</a>) and <abbr>UTC</abbr> is not agreed upon. 84689098d20Schristos This affects time stamps during the leap second era (1972–2035). 847cfc8dcb4Schristos Although the POSIX 8485f2f4c60Schristos clock officially stops during an inserted leap second, at least one 8495f2f4c60Schristos proposed standard has it jumping back a second instead; and in 8505f2f4c60Schristos practice POSIX clocks more typically either progress glacially during 8515f2f4c60Schristos a leap second, or are slightly slowed while near a leap second. 8525f2f4c60Schristos </li> 8535f2f4c60Schristos <li> 854cfc8dcb4Schristos The <code><abbr>tz</abbr></code> database does not represent how 855cfc8dcb4Schristos uncertain its information is. 8565f2f4c60Schristos Ideally it would contain information about when data entries are 857cfc8dcb4Schristos incomplete or dicey. 858cfc8dcb4Schristos Partial temporal knowledge is a field of active research, though, 859cfc8dcb4Schristos and it is not clear how to apply it here. 8605f2f4c60Schristos </li> 8615f2f4c60Schristos</ul> 862cfc8dcb4Schristos 8635f2f4c60Schristos<p> 864cfc8dcb4SchristosIn short, many, perhaps most, of the <code><abbr>tz</abbr></code> 865cfc8dcb4Schristosdatabase's pre-1970 and future timestamps are either wrong or 866cfc8dcb4Schristosmisleading. 867cfc8dcb4SchristosAny attempt to pass the 868cfc8dcb4Schristos<code><abbr>tz</abbr></code> database off as the definition of time 869cfc8dcb4Schristosshould be unacceptable to anybody who cares about the facts. 870cfc8dcb4SchristosIn particular, the <code><abbr>tz</abbr></code> database's 871cfc8dcb4Schristos<abbr>LMT</abbr> offsets should not be considered meaningful, and 872b2b04f7eSchristosshould not prompt creation of timezones 873cfc8dcb4Schristosmerely because two locations 874cfc8dcb4Schristosdiffer in <abbr>LMT</abbr> or transitioned to standard time at 875cfc8dcb4Schristosdifferent dates. 8765f2f4c60Schristos</p> 8775f2f4c60Schristos</section> 8785f2f4c60Schristos 8795f2f4c60Schristos<section> 8805f2f4c60Schristos <h2 id="functions">Time and date functions</h2> 8815f2f4c60Schristos<p> 882cfc8dcb4SchristosThe <code><abbr>tz</abbr></code> code contains time and date functions 883cfc8dcb4Schristosthat are upwards compatible with those of POSIX. 884cfc8dcb4SchristosCode compatible with this package is already 885cfc8dcb4Schristos<a href="tz-link.html#tzdb">part of many platforms</a>, where the 886cfc8dcb4Schristosprimary use of this package is to update obsolete time-related files. 887cfc8dcb4SchristosTo do this, you may need to compile the time zone compiler 8887d1a89a3Schristos<code>zic</code> supplied with this package instead of using the 8897d1a89a3Schristossystem <code>zic</code>, since the format of <code>zic</code>'s 890cfc8dcb4Schristosinput is occasionally extended, and a platform may still be shipping 891cfc8dcb4Schristosan older <code>zic</code>. 8925f2f4c60Schristos</p> 8935f2f4c60Schristos 8947d1a89a3Schristos<p> 8957d1a89a3SchristosIn POSIX, time display in a process is controlled by the 8967d1a89a3Schristosenvironment variable <code>TZ</code>, which can have two forms: 8977d1a89a3Schristos</p> 8985f2f4c60Schristos<ul> 8995f2f4c60Schristos <li> 9007d1a89a3Schristos A <dfn>proleptic <code>TZ</code></dfn> value 9017d1a89a3Schristos like <code>CET-1CEST,M3.5.0,M10.5.0/3</code> uses a complex 9027d1a89a3Schristos notation that specifies a single standard time along with daylight 9037d1a89a3Schristos saving rules that apply to all years past, present, and future. 9047d1a89a3Schristos </li> 9057d1a89a3Schristos <li> 9067d1a89a3Schristos A <dfn>geographical <code>TZ</code></dfn> value 9077d1a89a3Schristos like <code>Europe/Berlin</code> names a location that stands for 9087d1a89a3Schristos civil time near that location, which can have more than 9097d1a89a3Schristos one standard time and more than one set of daylight saving rules, 9107d1a89a3Schristos to record timekeeping practice more accurately. 9117d1a89a3Schristos These names are defined by the <code><abbr>tz</abbr></code> database. 9127d1a89a3Schristos </li> 9137d1a89a3Schristos</ul> 9147d1a89a3Schristos 9157d1a89a3Schristos<h3 id="POSIX.1-2017">POSIX.1-2017 properties and limitations</h3> 9165f2f4c60Schristos<p> 9177d1a89a3SchristosSome platforms support only the features required by POSIX.1-2017, 9187d1a89a3Schristosand have not yet upgraded to POSIX.1-2024. 9197d1a89a3SchristosCode intended to be portable to these platforms must deal 9207d1a89a3Schristoswith problems that were fixed in later POSIX editions. 9217d1a89a3Schristos</p> 9227d1a89a3Schristos 9237d1a89a3Schristos<ul> 9247d1a89a3Schristos <li> 9257d1a89a3Schristos POSIX.1-2017 does not require support for geographical <code>TZ</code>, 9267d1a89a3Schristos and there is no convenient and efficient way to determine 9277d1a89a3Schristos the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary 9287d1a89a3Schristos timestamps, particularly for timezones 9297d1a89a3Schristos that do not fit into the POSIX model. 9307d1a89a3Schristos </li> 9317d1a89a3Schristos <li> 9327d1a89a3Schristos <p> 9337d1a89a3Schristos The proleptic <code>TZ</code> string, 9347d1a89a3Schristos which is all that POSIX.1-2017 requires, 9357d1a89a3Schristos has a format that is hard to describe and is error-prone in practice. 9367d1a89a3Schristos Also, proleptic <code>TZ</code> strings cannot deal with daylight 937cfc8dcb4Schristos saving time rules not based on the Gregorian calendar (as in 93889098d20Schristos Morocco), or with situations where more than two time zone 939cfc8dcb4Schristos abbreviations or <abbr>UT</abbr> offsets are used in an area. 9405f2f4c60Schristos </p> 941cfc8dcb4Schristos 9425f2f4c60Schristos <p> 9437d1a89a3Schristos A proleptic <code>TZ</code> string has the following format: 9445f2f4c60Schristos </p> 945cfc8dcb4Schristos 9465f2f4c60Schristos <p> 9475f2f4c60Schristos <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>]]] 9485f2f4c60Schristos </p> 949cfc8dcb4Schristos 9505f2f4c60Schristos <p> 9515f2f4c60Schristos where: 952cfc8dcb4Schristos </p> 953cfc8dcb4Schristos 9545f2f4c60Schristos <dl> 9555f2f4c60Schristos <dt><var>std</var> and <var>dst</var></dt><dd> 9565f2f4c60Schristos are 3 or more characters specifying the standard 957b2b04f7eSchristos and daylight saving time (<abbr>DST</abbr>) zone abbreviations. 958cfc8dcb4Schristos Starting with POSIX.1-2001, <var>std</var> and <var>dst</var> 959cfc8dcb4Schristos may also be in a quoted form like '<code><+09></code>'; 960cfc8dcb4Schristos this allows "<code>+</code>" and "<code>-</code>" in the names. 9615f2f4c60Schristos </dd> 9625f2f4c60Schristos <dt><var>offset</var></dt><dd> 9635f2f4c60Schristos is of the form 9645f2f4c60Schristos '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' 965cfc8dcb4Schristos and specifies the offset west of <abbr>UT</abbr>. 966cfc8dcb4Schristos '<var>hh</var>' may be a single digit; 967cfc8dcb4Schristos 0≤<var>hh</var>≤24. 968cfc8dcb4Schristos The default <abbr>DST</abbr> offset is one hour ahead of 969cfc8dcb4Schristos standard time. 9705f2f4c60Schristos </dd> 9715f2f4c60Schristos <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> 972cfc8dcb4Schristos specifies the beginning and end of <abbr>DST</abbr>. 973cfc8dcb4Schristos If this is absent, the system supplies its own ruleset 97489098d20Schristos for <abbr>DST</abbr>, typically current <abbr>US</abbr> 97589098d20Schristos <abbr>DST</abbr> rules. 9765f2f4c60Schristos </dd> 9775f2f4c60Schristos <dt><var>time</var></dt><dd> 9785f2f4c60Schristos takes the form 9795f2f4c60Schristos '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]' 9805f2f4c60Schristos and defaults to 02:00. 9815f2f4c60Schristos This is the same format as the offset, except that a 9825f2f4c60Schristos leading '<code>+</code>' or '<code>-</code>' is not allowed. 9835f2f4c60Schristos </dd> 9845f2f4c60Schristos <dt><var>date</var></dt><dd> 9855f2f4c60Schristos takes one of the following forms: 9865f2f4c60Schristos <dl> 9875f2f4c60Schristos <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> 9885f2f4c60Schristos origin-1 day number not counting February 29 9895f2f4c60Schristos </dd> 9905f2f4c60Schristos <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> 9915f2f4c60Schristos origin-0 day number counting February 29 if present 9925f2f4c60Schristos </dd> 993cfc8dcb4Schristos <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> 994cfc8dcb4Schristos (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, 995cfc8dcb4Schristos 1≤<var>m</var>≤12)</dt><dd> 996cfc8dcb4Schristos for the <var>d</var>th day of week <var>n</var> of 997cfc8dcb4Schristos month <var>m</var> of the year, where week 1 is the first 998cfc8dcb4Schristos week in which day <var>d</var> appears, and 999cfc8dcb4Schristos '<code>5</code>' stands for the last week in which 1000cfc8dcb4Schristos day <var>d</var> appears (which may be either the 4th or 1001cfc8dcb4Schristos 5th week). 1002cfc8dcb4Schristos Typically, this is the only useful form; the <var>n</var> 1003cfc8dcb4Schristos and <code>J</code><var>n</var> forms are rarely used. 10045f2f4c60Schristos </dd> 10055f2f4c60Schristos </dl> 10065f2f4c60Schristos </dd> 10075f2f4c60Schristos </dl> 1008cfc8dcb4Schristos 1009cfc8dcb4Schristos <p> 10107d1a89a3Schristos Here is an example proleptic <code>TZ</code> string for New 1011cfc8dcb4Schristos Zealand after 2007. 1012cfc8dcb4Schristos It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead 1013cfc8dcb4Schristos of <abbr>UT</abbr>, and that daylight saving time 1014cfc8dcb4Schristos (<abbr>NZDT</abbr>) is observed from September's last Sunday at 1015cfc8dcb4Schristos 02:00 until April's first Sunday at 03:00: 1016cfc8dcb4Schristos </p> 10175f2f4c60Schristos 10185f2f4c60Schristos <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> 10195f2f4c60Schristos 1020cfc8dcb4Schristos <p> 10217d1a89a3Schristos This proleptic <code>TZ</code> string is hard to remember, and 1022cfc8dcb4Schristos mishandles some timestamps before 2008. 10237d1a89a3Schristos With this package you can use a geographical <code>TZ</code> instead: 1024cfc8dcb4Schristos </p> 10255f2f4c60Schristos 10265f2f4c60Schristos <pre><code>TZ='Pacific/Auckland'</code></pre> 10275f2f4c60Schristos </li> 10287d1a89a3Schristos</ul> 10297d1a89a3Schristos 10307d1a89a3Schristos<p> 10317d1a89a3SchristosPOSIX.1-2017 also has the limitations of POSIX.1-2024, 10327d1a89a3Schristosdiscussed in the next section. 10337d1a89a3Schristos</p> 10347d1a89a3Schristos 10357d1a89a3Schristos<h3 id="POSIX.1-2024">POSIX.1-2024 properties and limitations</h3> 10367d1a89a3Schristos<p> 10377d1a89a3SchristosPOSIX.1-2024 extends POSIX.1-2017 in the following significant ways: 10387d1a89a3Schristos</p> 10397d1a89a3Schristos<ul> 10405f2f4c60Schristos <li> 10417d1a89a3Schristos POSIX.1-2024 requires support for geographical <code>TZ</code>. 10427d1a89a3Schristos Earlier POSIX editions require support only for proleptic <code>TZ</code>. 10435f2f4c60Schristos </li> 10445f2f4c60Schristos <li> 10457d1a89a3Schristos POSIX.1-2024 requires <code>struct tm</code> 10467d1a89a3Schristos to have a <abbr>UT</abbr> offset member <code>tm_gmtoff</code> 10477d1a89a3Schristos and a time zone abbreviation member <code>tm_zone</code>. 10487d1a89a3Schristos Earlier POSIX editions lack this requirement. 10497d1a89a3Schristos </li> 10507d1a89a3Schristos <li> 10517d1a89a3Schristos DST transition times can range from −167:59:59 10527d1a89a3Schristos to 167:59:59 instead of merely from 00:00:00 to 24:59:59. 10537d1a89a3Schristos This allows for proleptic TZ strings 10547d1a89a3Schristos like <code>"<-02>2<-01>,M3.5.0/-1,M10.5.0/0"</code> 10557d1a89a3Schristos where the transition time −1:00 means 23:00 the previous day. 10567d1a89a3Schristos </li> 10577d1a89a3Schristos</ul> 10587d1a89a3Schristos<p> 10597d1a89a3SchristosHowever POSIX.1-2024, like earlier POSIX editions, has some limitations: 10607d1a89a3Schristos<ul> 10617d1a89a3Schristos <li> 1062cfc8dcb4Schristos The <code>TZ</code> environment variable is process-global, which 1063cfc8dcb4Schristos makes it hard to write efficient, thread-safe applications that 1064b2b04f7eSchristos need access to multiple timezones. 10655f2f4c60Schristos </li> 10665f2f4c60Schristos <li> 1067cfc8dcb4Schristos In POSIX, there is no tamper-proof way for a process to learn the 10687005738dSchristos system's best idea of local (wall clock) time. 1069b2b04f7eSchristos This is important for applications that an administrator wants 1070cfc8dcb4Schristos used only at certain times – without regard to whether the 1071cfc8dcb4Schristos user has fiddled the 1072cfc8dcb4Schristos <code>TZ</code> environment variable. 1073cfc8dcb4Schristos While an administrator can "do everything in <abbr>UT</abbr>" to 1074cfc8dcb4Schristos get around the problem, doing so is inconvenient and precludes 1075b2b04f7eSchristos handling daylight saving time shifts – as might be required to 1076b2b04f7eSchristos limit phone calls to off-peak hours. 10775f2f4c60Schristos </li> 10785f2f4c60Schristos <li> 107914c787bcSchristos POSIX requires that <code>time_t</code> clock counts exclude leap 108014c787bcSchristos seconds. 10815f2f4c60Schristos </li> 10825f2f4c60Schristos <li> 10837d1a89a3Schristos POSIX does not define the <abbr>DST</abbr> transitions 10847d1a89a3Schristos for <code>TZ</code> values like 10857d1a89a3Schristos "<code>EST5EDT</code>". 10867d1a89a3Schristos Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules 10877d1a89a3Schristos were used to interpret such values, but this meant that the 10887d1a89a3Schristos <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each 10897d1a89a3Schristos time conversion package, and when 10907d1a89a3Schristos <abbr>US</abbr> time conversion rules changed (as in the United 10917d1a89a3Schristos States in 1987 and again in 2007), all packages that 10927d1a89a3Schristos interpreted <code>TZ</code> values had to be updated 10937d1a89a3Schristos to ensure proper results. 10947d1a89a3Schristos </li> 10957d1a89a3Schristos</ul> 10967d1a89a3Schristos 10977d1a89a3Schristos<h3 id="POSIX-extensions">Extensions to POSIX in the 10987d1a89a3Schristos<code><abbr>tz</abbr></code> code</h3> 10997d1a89a3Schristos<p> 11007d1a89a3Schristos The <code><abbr>tz</abbr></code> code defines some properties 11017d1a89a3Schristos left unspecified by POSIX, and attempts to support some 11027d1a89a3Schristos extensions to POSIX. 11037d1a89a3Schristos</p> 11047d1a89a3Schristos 11057d1a89a3Schristos<ul> 11067d1a89a3Schristos <li> 1107cfc8dcb4Schristos The <code><abbr>tz</abbr></code> code attempts to support all the 1108cfc8dcb4Schristos <code>time_t</code> implementations allowed by POSIX. 1109cfc8dcb4Schristos The <code>time_t</code> type represents a nonnegative count of seconds 1110cfc8dcb4Schristos since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds. 1111cfc8dcb4Schristos In practice, <code>time_t</code> is usually a signed 64- or 32-bit 1112cfc8dcb4Schristos integer; 32-bit signed <code>time_t</code> values stop working after 1113cfc8dcb4Schristos 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these 1114cfc8dcb4Schristos days typically use a signed 64-bit integer. 1115cfc8dcb4Schristos Unsigned 32-bit integers are used on one or two platforms, and 36-bit 1116cfc8dcb4Schristos and 40-bit integers are also used occasionally. 11175f2f4c60Schristos Although earlier POSIX versions allowed <code>time_t</code> to be a 1118b2b04f7eSchristos floating-point type, this was not supported by any practical system, 11197d1a89a3Schristos and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both 1120cfc8dcb4Schristos require <code>time_t</code> to be an integer type. 11215f2f4c60Schristos </li> 11225f2f4c60Schristos <li> 11235f2f4c60Schristos <p> 11247d1a89a3Schristos If the <code>TZ</code> environment variable uses the geographical format, 11257d1a89a3Schristos it is used in generating 11267d1a89a3Schristos the name of a file from which time-related information is read. 1127b2b04f7eSchristos The file's format is <dfn><abbr>TZif</abbr></dfn>, 112891e14238Schristos a timezone information format that contains binary data; see 1129*18b32cd1Schristos <a href="https://www.rfc-editor.org/rfc/9636">Internet 1130*18b32cd1Schristos <abbr>RFC</abbr> 9636</a>. 1131cfc8dcb4Schristos The daylight saving time rules to be used for a 1132b2b04f7eSchristos particular timezone are encoded in the 1133b2b04f7eSchristos <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>, 1134b2b04f7eSchristos Australian, and other rules to be encoded, and 1135cfc8dcb4Schristos allows for situations where more than two time zone 11365f2f4c60Schristos abbreviations are used. 11375f2f4c60Schristos </p> 11385f2f4c60Schristos <p> 11397d1a89a3Schristos When the <code><abbr>tz</abbr></code> code was developed in the 1980s, 11407d1a89a3Schristos it was recognized that allowing the <code>TZ</code> environment 1141cfc8dcb4Schristos variable to take on values such as '<code>America/New_York</code>' 1142cfc8dcb4Schristos might cause "old" programs (that expect <code>TZ</code> to have a 11437d1a89a3Schristos certain format) to operate incorrectly; consideration was given to using 1144cfc8dcb4Schristos some other environment variable (for example, <code>TIMEZONE</code>) 1145b2b04f7eSchristos to hold the string used to generate the <abbr>TZif</abbr> file's name. 1146cfc8dcb4Schristos In the end, however, it was decided to continue using 1147cfc8dcb4Schristos <code>TZ</code>: it is widely used for time zone purposes; 1148cfc8dcb4Schristos separately maintaining both <code>TZ</code> 1149cfc8dcb4Schristos and <code>TIMEZONE</code> seemed a nuisance; and systems where 1150cfc8dcb4Schristos "new" forms of <code>TZ</code> might cause problems can simply 1151b2b04f7eSchristos use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which 1152b2b04f7eSchristos can be used by "new" programs as well as by "old" programs that 1153b2b04f7eSchristos assume pre-POSIX <code>TZ</code> values. 11545f2f4c60Schristos </p> 11555f2f4c60Schristos </li> 11565f2f4c60Schristos <li> 11575f2f4c60Schristos Functions <code>tzalloc</code>, <code>tzfree</code>, 11585f2f4c60Schristos <code>localtime_rz</code>, and <code>mktime_z</code> for 1159cfc8dcb4Schristos more-efficient thread-safe applications that need to use multiple 1160b2b04f7eSchristos timezones. 1161cfc8dcb4Schristos The <code>tzalloc</code> and <code>tzfree</code> functions 1162cfc8dcb4Schristos allocate and free objects of type <code>timezone_t</code>, 1163cfc8dcb4Schristos and <code>localtime_rz</code> and <code>mktime_z</code> are 1164cfc8dcb4Schristos like <code>localtime_r</code> and <code>mktime</code> with an 1165cfc8dcb4Schristos extra <code>timezone_t</code> argument. 11667d1a89a3Schristos The functions were inspired by <a href="https://netbsd.org">NetBSD</a>. 11675f2f4c60Schristos </li> 11685f2f4c60Schristos <li> 11695f2f4c60Schristos Negative <code>time_t</code> values are supported, on systems 11705f2f4c60Schristos where <code>time_t</code> is signed. 11715f2f4c60Schristos </li> 11725f2f4c60Schristos <li> 117314c787bcSchristos These functions can account for leap seconds; 117414c787bcSchristos see <a href="#leapsec">Leap seconds</a> below. 11755f2f4c60Schristos </li> 11765f2f4c60Schristos</ul> 1177cfc8dcb4Schristos 1178cfc8dcb4Schristos<h3 id="vestigial">POSIX features no longer needed</h3> 11795f2f4c60Schristos<p> 1180cfc8dcb4SchristosPOSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a> 1181cfc8dcb4Schristosdefine some <a href="https://en.wikipedia.org/wiki/API"><abbr 1182cfc8dcb4Schristostitle="application programming interface">API</abbr>s</a> that are vestigial: 1183cfc8dcb4Schristosthey are not needed, and are relics of a too-simple model that does 1184cfc8dcb4Schristosnot suffice to handle many real-world timestamps. 1185cfc8dcb4SchristosAlthough the <code><abbr>tz</abbr></code> code supports these 1186cfc8dcb4Schristosvestigial <abbr>API</abbr>s for backwards compatibility, they should 1187cfc8dcb4Schristosbe avoided in portable applications. 1188cfc8dcb4SchristosThe vestigial <abbr>API</abbr>s are: 11895f2f4c60Schristos</p> 11905f2f4c60Schristos<ul> 11915f2f4c60Schristos <li> 1192cfc8dcb4Schristos The POSIX <code>tzname</code> variable does not suffice and is no 1193cfc8dcb4Schristos longer needed. 11947d1a89a3Schristos It is planned to be removed in a future edition of POSIX. 1195cfc8dcb4Schristos To get a timestamp's time zone abbreviation, consult 1196cfc8dcb4Schristos the <code>tm_zone</code> member if available; otherwise, 1197cfc8dcb4Schristos use <code>strftime</code>'s <code>"%Z"</code> conversion 1198cfc8dcb4Schristos specification. 11995f2f4c60Schristos </li> 12005f2f4c60Schristos <li> 1201cfc8dcb4Schristos The POSIX <code>daylight</code> and <code>timezone</code> 1202cfc8dcb4Schristos variables do not suffice and are no longer needed. 12037d1a89a3Schristos They are planned to be removed in a future edition of POSIX. 1204cfc8dcb4Schristos To get a timestamp's <abbr>UT</abbr> offset, consult 1205cfc8dcb4Schristos the <code>tm_gmtoff</code> member if available; otherwise, 1206cfc8dcb4Schristos subtract values returned by <code>localtime</code> 1207cfc8dcb4Schristos and <code>gmtime</code> using the rules of the Gregorian calendar, 1208cfc8dcb4Schristos or use <code>strftime</code>'s <code>"%z"</code> conversion 1209cfc8dcb4Schristos specification if a string like <code>"+0900"</code> suffices. 1210cfc8dcb4Schristos </li> 1211cfc8dcb4Schristos <li> 1212cfc8dcb4Schristos The <code>tm_isdst</code> member is almost never needed and most of 1213cfc8dcb4Schristos its uses should be discouraged in favor of the abovementioned 1214cfc8dcb4Schristos <abbr>API</abbr>s. 1215*18b32cd1Schristos It was intended as an index into the <code>tzname</code> variable, 1216*18b32cd1Schristos but as mentioned previously that usage is obsolete. 1217cfc8dcb4Schristos Although it can still be used in arguments to 1218cfc8dcb4Schristos <code>mktime</code> to disambiguate timestamps near 12198c24072aSchristos a <abbr>DST</abbr> transition when the clock jumps back on 12208c24072aSchristos platforms lacking <code>tm_gmtoff</code>, this 1221*18b32cd1Schristos disambiguation works only for proleptic <code>TZ</code> strings; 1222*18b32cd1Schristos it does not work in general for geographical timezones, 1223*18b32cd1Schristos such as when a location changes to a time zone with a 1224cfc8dcb4Schristos lesser <abbr>UT</abbr> offset. 1225cfc8dcb4Schristos </li> 1226cfc8dcb4Schristos</ul> 1227cfc8dcb4Schristos 1228cfc8dcb4Schristos<h3 id="other-portability">Other portability notes</h3> 1229cfc8dcb4Schristos<ul> 1230cfc8dcb4Schristos <li> 1231cfc8dcb4Schristos The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition 1232cfc8dcb4Schristos UNIX</a> <code>timezone</code> function is not present in this 1233cfc8dcb4Schristos package; it is impossible to reliably map <code>timezone</code>'s 1234cfc8dcb4Schristos arguments (a "minutes west of <abbr>GMT</abbr>" value and a 1235cfc8dcb4Schristos "daylight saving time in effect" flag) to a time zone 1236cfc8dcb4Schristos abbreviation, and we refuse to guess. 1237cfc8dcb4Schristos Programs that in the past used the <code>timezone</code> function 1238cfc8dcb4Schristos may now examine <code>localtime(&clock)->tm_zone</code> 12395f2f4c60Schristos (if <code>TM_ZONE</code> is defined) or 1240*18b32cd1Schristos use <code>strftime</code> with a <code>%Z</code> conversion specification 1241*18b32cd1Schristos to learn the correct time 1242cfc8dcb4Schristos zone abbreviation to use. 12435f2f4c60Schristos </li> 12445f2f4c60Schristos <li> 1245cfc8dcb4Schristos The <a 1246cfc8dcb4Schristos href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a> 1247cfc8dcb4Schristos <code>gettimeofday</code> function is not 1248cfc8dcb4Schristos used in this package. 1249cfc8dcb4Schristos This formerly let users obtain the current <abbr>UTC</abbr> offset 1250cfc8dcb4Schristos and <abbr>DST</abbr> flag, but this functionality was removed in 1251cfc8dcb4Schristos later versions of <abbr>BSD</abbr>. 12525f2f4c60Schristos </li> 12535f2f4c60Schristos <li> 1254cfc8dcb4Schristos In <abbr>SVR2</abbr>, time conversion fails for near-minimum or 1255cfc8dcb4Schristos near-maximum <code>time_t</code> values when doing conversions 1256cfc8dcb4Schristos for places that do not use <abbr>UT</abbr>. 12575f2f4c60Schristos This package takes care to do these conversions correctly. 12585f2f4c60Schristos A comment in the source code tells how to get compatibly wrong 12595f2f4c60Schristos results. 12605f2f4c60Schristos </li> 1261cfc8dcb4Schristos <li> 12625f2f4c60Schristos The functions that are conditionally compiled 126389098d20Schristos if <code>STD_INSPIRED</code> is nonzero should, at this point, be 1264cfc8dcb4Schristos looked on primarily as food for thought. 1265cfc8dcb4Schristos They are not in any sense "standard compatible" – some are 1266cfc8dcb4Schristos not, in fact, specified in <em>any</em> standard. 1267cfc8dcb4Schristos They do, however, represent responses of various authors to 12685f2f4c60Schristos standardization proposals. 1269cfc8dcb4Schristos </li> 1270cfc8dcb4Schristos <li> 1271b2b04f7eSchristos Other time conversion proposals, in particular those supported by the 1272b2b04f7eSchristos <a href="https://howardhinnant.github.io/date/tz.html">Time Zone 1273b2b04f7eSchristos Database Parser</a>, offer a wider selection of functions 1274cfc8dcb4Schristos that provide capabilities beyond those provided here. 1275cfc8dcb4Schristos The absence of such functions from this package is not meant to 1276cfc8dcb4Schristos discourage the development, standardization, or use of such 1277cfc8dcb4Schristos functions. 1278cfc8dcb4Schristos Rather, their absence reflects the decision to make this package 1279cfc8dcb4Schristos contain valid extensions to POSIX, to ensure its broad 1280cfc8dcb4Schristos acceptability. 1281cfc8dcb4Schristos If more powerful time conversion functions can be standardized, so 1282cfc8dcb4Schristos much the better. 1283cfc8dcb4Schristos </li> 1284cfc8dcb4Schristos</ul> 12855f2f4c60Schristos</section> 12865f2f4c60Schristos 12875f2f4c60Schristos<section> 12885f2f4c60Schristos <h2 id="stability">Interface stability</h2> 12895f2f4c60Schristos<p> 1290cfc8dcb4SchristosThe <code><abbr>tz</abbr></code> code and data supply the following interfaces: 12915f2f4c60Schristos</p> 1292cfc8dcb4Schristos 12935f2f4c60Schristos<ul> 12945f2f4c60Schristos <li> 1295b2b04f7eSchristos A set of timezone names as per 129691e14238Schristos "<a href="#naming">Timezone identifiers</a>" above. 12975f2f4c60Schristos </li> 12985f2f4c60Schristos <li> 12995f2f4c60Schristos Library functions described in "<a href="#functions">Time and date 13005f2f4c60Schristos functions</a>" above. 13015f2f4c60Schristos </li> 13025f2f4c60Schristos <li> 13035f2f4c60Schristos The programs <code>tzselect</code>, <code>zdump</code>, 13045f2f4c60Schristos and <code>zic</code>, documented in their man pages. 13055f2f4c60Schristos </li> 13065f2f4c60Schristos <li> 13075f2f4c60Schristos The format of <code>zic</code> input files, documented in 13085f2f4c60Schristos the <code>zic</code> man page. 13095f2f4c60Schristos </li> 13105f2f4c60Schristos <li> 13115f2f4c60Schristos The format of <code>zic</code> output files, documented in 13125f2f4c60Schristos the <code>tzfile</code> man page. 13135f2f4c60Schristos </li> 13145f2f4c60Schristos <li> 13155f2f4c60Schristos The format of zone table files, documented in <code>zone1970.tab</code>. 13165f2f4c60Schristos </li> 13175f2f4c60Schristos <li> 13185f2f4c60Schristos The format of the country code file, documented in <code>iso3166.tab</code>. 13195f2f4c60Schristos </li> 13205f2f4c60Schristos <li> 13215f2f4c60Schristos The version number of the code and data, as the first line of 13225f2f4c60Schristos the text file '<code>version</code>' in each release. 13235f2f4c60Schristos </li> 13245f2f4c60Schristos</ul> 1325cfc8dcb4Schristos 13265f2f4c60Schristos<p> 13275f2f4c60SchristosInterface changes in a release attempt to preserve compatibility with 1328cfc8dcb4Schristosrecent releases. 1329cfc8dcb4SchristosFor example, <code><abbr>tz</abbr></code> data files typically do not 133089098d20Schristosrely on recently added <code>zic</code> features, so that users can 1331cfc8dcb4Schristosrun older <code>zic</code> versions to process newer data files. 1332cfc8dcb4Schristos<a href="tz-link.html#download">Downloading 1333cfc8dcb4Schristosthe <code><abbr>tz</abbr></code> database</a> describes how releases 1334cfc8dcb4Schristosare tagged and distributed. 13355f2f4c60Schristos</p> 13365f2f4c60Schristos 13375f2f4c60Schristos<p> 1338cfc8dcb4SchristosInterfaces not listed above are less stable. 1339cfc8dcb4SchristosFor example, users should not rely on particular <abbr>UT</abbr> 1340cfc8dcb4Schristosoffsets or abbreviations for timestamps, as data entries are often 1341cfc8dcb4Schristosbased on guesswork and these guesses may be corrected or improved. 13425f2f4c60Schristos</p> 134391e14238Schristos 134491e14238Schristos<p> 134591e14238SchristosTimezone boundaries are not part of the stable interface. 134691e14238SchristosFor example, even though the <samp>Asia/Bangkok</samp> timezone 134791e14238Schristoscurrently includes Chang Mai, Hanoi, and Phnom Penh, this is not part 134891e14238Schristosof the stable interface and the timezone can split at any time. 134991e14238SchristosIf a calendar application records a future event in some location other 135091e14238Schristosthan Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record, 135191e14238Schristosthe application should be robust in the presence of timezone splits 135291e14238Schristosbetween now and the future time. 135391e14238Schristos</p> 13545f2f4c60Schristos</section> 13555f2f4c60Schristos 13565f2f4c60Schristos<section> 135714c787bcSchristos <h2 id="leapsec">Leap seconds</h2> 135814c787bcSchristos<p> 135989098d20SchristosLeap seconds were introduced in 1972 to accommodate the 136089098d20Schristosdifference between atomic time and the less regular rotation of the earth. 13617d1a89a3SchristosUnfortunately they have caused so many problems with civil 13627d1a89a3Schristostimekeeping that there are 13637d1a89a3Schristos<a href="https://www.bipm.org/en/cgpm-2022/resolution-4">plans 13647d1a89a3Schristosto discontinue them by 2035</a>. 13657d1a89a3SchristosEven if these plans come to fruition, a record of leap seconds will still be 13667d1a89a3Schristosneeded to resolve timestamps from 1972 through 2035, 13677d1a89a3Schristosand there may also be a need to record whatever mechanism replaces them. 136889098d20Schristos</p> 136989098d20Schristos 137089098d20Schristos<p> 137114c787bcSchristosThe <code><abbr>tz</abbr></code> code and data can account for leap seconds, 137214c787bcSchristosthanks to code contributed by Bradley White. 137314c787bcSchristosHowever, the leap second support of this package is rarely used directly 137414c787bcSchristosbecause POSIX requires leap seconds to be excluded and many 137514c787bcSchristossoftware packages would mishandle leap seconds if they were present. 137614c787bcSchristosInstead, leap seconds are more commonly handled by occasionally adjusting 137714c787bcSchristosthe operating system kernel clock as described in 137814c787bcSchristos<a href="tz-link.html#precision">Precision timekeeping</a>, 137914c787bcSchristosand this package by default installs a <samp>leapseconds</samp> file 138014c787bcSchristoscommonly used by 13818c24072aSchristos<a href="https://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a> 138214c787bcSchristossoftware that adjusts the kernel clock. 138314c787bcSchristosHowever, kernel-clock twiddling approximates UTC only roughly, 138489098d20Schristosand systems needing more precise UTC can use this package's leap 138514c787bcSchristossecond support directly. 138614c787bcSchristos</p> 138714c787bcSchristos 138814c787bcSchristos<p> 138989098d20SchristosThe directly supported mechanism assumes that <code>time_t</code> 139014c787bcSchristoscounts of seconds since the POSIX epoch normally include leap seconds, 139114c787bcSchristosas opposed to POSIX <code>time_t</code> counts which exclude leap seconds. 139214c787bcSchristosThis modified timescale is converted to <abbr>UTC</abbr> 13931b584801Schristosat the same point that time zone and <abbr>DST</abbr> 13941b584801Schristosadjustments are applied – 139514c787bcSchristosnamely, at calls to <code>localtime</code> and analogous functions – 139614c787bcSchristosand the process is driven by leap second information 139714c787bcSchristosstored in alternate versions of the <abbr>TZif</abbr> files. 139814c787bcSchristosBecause a leap second adjustment may be needed even 139914c787bcSchristosif no time zone correction is desired, 140014c787bcSchristoscalls to <code>gmtime</code>-like functions 140114c787bcSchristosalso need to consult a <abbr>TZif</abbr> file, 14020129e5c6Schristosconventionally named <samp><abbr>Etc/UTC</abbr></samp> 14030129e5c6Schristos(<samp><abbr>GMT</abbr></samp> in previous versions), 140414c787bcSchristosto see whether leap second corrections are needed. 140514c787bcSchristosTo convert an application's <code>time_t</code> timestamps to or from 140614c787bcSchristosPOSIX <code>time_t</code> timestamps (for use when, say, 140714c787bcSchristosembedding or interpreting timestamps in portable 140814c787bcSchristos<a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a> 140914c787bcSchristosfiles), 141014c787bcSchristosthe application can call the utility functions 141114c787bcSchristos<code>time2posix</code> and <code>posix2time</code> 141214c787bcSchristosincluded with this package. 141314c787bcSchristos</p> 141414c787bcSchristos 141514c787bcSchristos<p> 141614c787bcSchristosIf the POSIX-compatible <abbr>TZif</abbr> file set is installed 141714c787bcSchristosin a directory whose basename is <samp>zoneinfo</samp>, the 141814c787bcSchristosleap-second-aware file set is by default installed in a separate 141914c787bcSchristosdirectory <samp>zoneinfo-leaps</samp>. 142014c787bcSchristosAlthough each process can have its own time zone by setting 142114c787bcSchristosits <code>TZ</code> environment variable, there is no support for some 142214c787bcSchristosprocesses being leap-second aware while other processes are 142314c787bcSchristosPOSIX-compatible; the leap-second choice is system-wide. 142414c787bcSchristosSo if you configure your kernel to count leap seconds, you should also 142514c787bcSchristosdiscard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp> 142614c787bcSchristosto <samp>zoneinfo</samp>. 142714c787bcSchristosAlternatively, you can install just one set of <abbr>TZif</abbr> files 142814c787bcSchristosin the first place; see the <code>REDO</code> variable in this package's 142914c787bcSchristos<a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>. 143014c787bcSchristos</p> 143114c787bcSchristos</section> 143214c787bcSchristos 143314c787bcSchristos<section> 14345f2f4c60Schristos <h2 id="calendar">Calendrical issues</h2> 14355f2f4c60Schristos<p> 14365f2f4c60SchristosCalendrical issues are a bit out of scope for a time zone database, 14375f2f4c60Schristosbut they indicate the sort of problems that we would run into if we 1438cfc8dcb4Schristosextended the time zone database further into the past. 1439cfc8dcb4SchristosAn excellent resource in this area is Edward M. Reingold 1440cfc8dcb4Schristosand Nachum Dershowitz, <cite><a 1441cfc8dcb4Schristoshref="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical 1442cfc8dcb4SchristosCalculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018). 1443cfc8dcb4SchristosOther information and sources are given in the file '<code>calendars</code>' 1444cfc8dcb4Schristosin the <code><abbr>tz</abbr></code> distribution. 1445cfc8dcb4SchristosThey sometimes disagree. 14465f2f4c60Schristos</p> 14475f2f4c60Schristos</section> 14485f2f4c60Schristos 14495f2f4c60Schristos<section> 145089098d20Schristos <h2 id="planets">Time and time zones off Earth</h2> 145189098d20Schristos<p> 145289098d20SchristosThe European Space Agency is <a 145389098d20Schristoshref='https://www.esa.int/Applications/Navigation/Telling_time_on_the_Moon'>considering</a> 145489098d20Schristosthe establishment of a reference timescale for the Moon, which has 145589098d20Schristosdays roughly equivalent to 29.5 Earth days, and where relativistic 145689098d20Schristoseffects cause clocks to tick slightly faster than on Earth. 14577d1a89a3SchristosAlso, <abbr title="National Aeronautics and Space Administration">NASA</abbr> 14587d1a89a3Schristoshas been <a 14597d1a89a3Schristoshref='https://www.whitehouse.gov/wp-content/uploads/2024/04/Celestial-Time-Standardization-Policy.pdf'>ordered</a> 14607d1a89a3Schristosto consider the establishment of Coordinated Lunar Time (<abbr>LTC</abbr>). 14617d1a89a3SchristosIt is not yet known whether the US and European efforts will result in 14627d1a89a3Schristosmultiple timescales on the Moon. 146389098d20Schristos</p> 146489098d20Schristos 14655f2f4c60Schristos<p> 14667328cbb4SchristosSome people's work schedules have used 14677328cbb4Schristos<a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>. 1468cfc8dcb4SchristosJet Propulsion Laboratory (JPL) coordinators kept Mars time on 1469cfc8dcb4Schristosand off during the 147076c76726Schristos<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars 14717328cbb4SchristosPathfinder</a> mission (1997). 1472cfc8dcb4SchristosSome of their family members also adapted to Mars time. 1473cfc8dcb4SchristosDozens of special Mars watches were built for JPL workers who kept 14747328cbb4SchristosMars time during the 14757328cbb4Schristos<a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars 14767328cbb4SchristosExploration Rovers (MER)</a> mission (2004–2018). 14777328cbb4SchristosThese timepieces looked like normal Seikos and Citizens but were adjusted 14787328cbb4Schristosto use Mars seconds rather than terrestrial seconds, although 14797328cbb4Schristosunfortunately the adjusted watches were unreliable and appear to have 14807328cbb4Schristoshad only limited use. 14815f2f4c60Schristos</p> 14825f2f4c60Schristos 14835f2f4c60Schristos<p> 14845f2f4c60SchristosA Mars solar day is called a "sol" and has a mean period equal to 1485cfc8dcb4Schristosabout 24 hours 39 minutes 35.244 seconds in terrestrial time. 1486cfc8dcb4SchristosIt is divided into a conventional 24-hour clock, so each Mars second 1487cfc8dcb4Schristosequals about 1.02749125 terrestrial seconds. 14887328cbb4Schristos(One MER worker noted, "If I am working Mars hours, and Mars hours are 14897328cbb4Schristos2.5% more than Earth hours, shouldn't I get an extra 2.5% pay raise?") 14905f2f4c60Schristos</p> 14915f2f4c60Schristos 14925f2f4c60Schristos<p> 1493cfc8dcb4SchristosThe <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime 1494cfc8dcb4Schristosmeridian</a> of Mars goes through the center of the crater 1495cfc8dcb4Schristos<a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in 1496cfc8dcb4Schristoshonor of the British astronomer who built the Greenwich telescope that 1497cfc8dcb4Schristosdefines Earth's prime meridian. 1498cfc8dcb4SchristosMean solar time on the Mars prime meridian is 149976c76726Schristoscalled Mars Coordinated Time (<abbr>MTC</abbr>). 15005f2f4c60Schristos</p> 15015f2f4c60Schristos 15025f2f4c60Schristos<p> 15035f2f4c60SchristosEach landed mission on Mars has adopted a different reference for 15045f2f4c60Schristossolar timekeeping, so there is no real standard for Mars time zones. 15057328cbb4SchristosFor example, the MER mission defined two time zones "Local 1506cfc8dcb4SchristosSolar Time A" and "Local Solar Time B" for its two missions, each zone 1507cfc8dcb4Schristosdesigned so that its time equals local true solar time at 1508cfc8dcb4Schristosapproximately the middle of the nominal mission. 15097328cbb4SchristosThe A and B zones differ enough so that an MER worker assigned to 15107328cbb4Schristosthe A zone might suffer "Mars lag" when switching to work in the B zone. 1511cfc8dcb4SchristosSuch a "time zone" is not particularly suited for any application 1512cfc8dcb4Schristosother than the mission itself. 15135f2f4c60Schristos</p> 15145f2f4c60Schristos 15155f2f4c60Schristos<p> 15165f2f4c60SchristosMany calendars have been proposed for Mars, but none have achieved 1517cfc8dcb4Schristoswide acceptance. 1518cfc8dcb4SchristosAstronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a 15195f2f4c60Schristossequential count of Mars solar days elapsed since about 1873-12-29 1520cfc8dcb4Schristos12:00 <abbr>GMT</abbr>. 15215f2f4c60Schristos</p> 15225f2f4c60Schristos 15235f2f4c60Schristos<p> 15245f2f4c60SchristosIn our solar system, Mars is the planet with time and calendar most 1525cfc8dcb4Schristoslike Earth's. 1526cfc8dcb4SchristosOn other planets, Sun-based time and calendars would work quite 1527cfc8dcb4Schristosdifferently. 1528cfc8dcb4SchristosFor example, although Mercury's 1529cfc8dcb4Schristos<a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal 1530cfc8dcb4Schristosrotation period</a> is 58.646 Earth days, Mercury revolves around the 1531cfc8dcb4SchristosSun so rapidly that an observer on Mercury's equator would see a 1532cfc8dcb4Schristossunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a 1533cfc8dcb4SchristosMercury day. 1534cfc8dcb4SchristosVenus is more complicated, partly because its rotation is slightly 1535cfc8dcb4Schristos<a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>: 1536cfc8dcb4Schristosits year is 1.92 of its days. 1537cfc8dcb4SchristosGas giants like Jupiter are trickier still, as their polar and 1538cfc8dcb4Schristosequatorial regions rotate at different rates, so that the length of a 1539cfc8dcb4Schristosday depends on latitude. 1540cfc8dcb4SchristosThis effect is most pronounced on Neptune, where the day is about 12 1541cfc8dcb4Schristoshours at the poles and 18 hours at the equator. 15425f2f4c60Schristos</p> 15435f2f4c60Schristos 15445f2f4c60Schristos<p> 1545cfc8dcb4SchristosAlthough the <code><abbr>tz</abbr></code> database does not support 1546cfc8dcb4Schristostime on other planets, it is documented here in the hopes that support 1547cfc8dcb4Schristoswill be added eventually. 15485f2f4c60Schristos</p> 15495f2f4c60Schristos 15505f2f4c60Schristos<p> 1551cfc8dcb4SchristosSources for time on other planets: 15525f2f4c60Schristos</p> 1553cfc8dcb4Schristos 15545f2f4c60Schristos<ul> 15555f2f4c60Schristos <li> 15565f2f4c60Schristos Michael Allison and Robert Schmunk, 15575f2f4c60Schristos "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical 15585f2f4c60Schristos Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" 15597328cbb4Schristos (2020-03-08). 15607328cbb4Schristos </li> 15617328cbb4Schristos <li> 15627328cbb4Schristos Zara Mirmalek, 15637328cbb4Schristos <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making 15647328cbb4Schristos Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854. 15655f2f4c60Schristos </li> 15665f2f4c60Schristos <li> 15675f2f4c60Schristos Jia-Rui Chong, 15687005738dSchristos "<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays 1569cfc8dcb4Schristos Fit for a Martian</a>", <cite>Los Angeles Times</cite> 1570cfc8dcb4Schristos (2004-01-14), pp A1, A20–A21. 15715f2f4c60Schristos </li> 15725f2f4c60Schristos <li> 15735f2f4c60Schristos Tom Chmielewski, 15745f2f4c60Schristos "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet 1575cfc8dcb4Schristos Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26) 15765f2f4c60Schristos </li> 15775f2f4c60Schristos <li> 15785f2f4c60Schristos Matt Williams, 15795f2f4c60Schristos "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How 15805f2f4c60Schristos long is a day on the other planets of the solar system?</a>" 1581b2b04f7eSchristos (2016-01-20). 15825f2f4c60Schristos </li> 15835f2f4c60Schristos</ul> 15845f2f4c60Schristos</section> 15855f2f4c60Schristos 15865f2f4c60Schristos<footer> 15875f2f4c60Schristos <hr> 15885f2f4c60Schristos This file is in the public domain, so clarified as of 2009-05-17 by 15895f2f4c60Schristos Arthur David Olson. 15905f2f4c60Schristos</footer> 15915f2f4c60Schristos</body> 15925f2f4c60Schristos</html> 1593