1bc421551SDag-Erling Smørgrav<!DOCTYPE html> 2bc421551SDag-Erling Smørgrav<html lang="en"> 3bc421551SDag-Erling Smørgrav<head> 4bc421551SDag-Erling Smørgrav <title>Theory and pragmatics of the tz code and data</title> 5bc421551SDag-Erling Smørgrav <meta charset="UTF-8"> 6ff2c98b3SDag-Erling Smørgrav <meta name="viewport" content="width=device-width, initial-scale=1"> 7bc421551SDag-Erling Smørgrav <style> 8ff2c98b3SDag-Erling Smørgrav dd {margin-left: 1.3rem;} 9ff2c98b3SDag-Erling Smørgrav pre {margin-left: 1.3rem; overflow: auto;} 10ff2c98b3SDag-Erling Smørgrav ul {padding-left: 1.3rem;} 11bc421551SDag-Erling Smørgrav </style> 12bc421551SDag-Erling Smørgrav</head> 13bc421551SDag-Erling Smørgrav 14bc421551SDag-Erling Smørgrav<body> 15212e3524SDag-Erling Smørgrav<main> 16bc421551SDag-Erling Smørgrav<h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1> 17bc421551SDag-Erling Smørgrav <nav> 18bc421551SDag-Erling Smørgrav <ul> 19bc421551SDag-Erling Smørgrav <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code> 20bc421551SDag-Erling Smørgrav database</a></li> 21bc421551SDag-Erling Smørgrav <li><a href="#naming">Timezone identifiers</a></li> 22bc421551SDag-Erling Smørgrav <li><a href="#abbreviations">Time zone abbreviations</a></li> 23bc421551SDag-Erling Smørgrav <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code> 24bc421551SDag-Erling Smørgrav database</a></li> 25bc421551SDag-Erling Smørgrav <li><a href="#functions">Time and date functions</a></li> 26bc421551SDag-Erling Smørgrav <li><a href="#stability">Interface stability</a></li> 27bc421551SDag-Erling Smørgrav <li><a href="#leapsec">Leap seconds</a></li> 28bc421551SDag-Erling Smørgrav <li><a href="#calendar">Calendrical issues</a></li> 2975411d15SDag-Erling Smørgrav <li><a href="#planets">Time and time zones off earth</a></li> 30212e3524SDag-Erling Smørgrav <li><a href="#see-also">See also</a></li> 31bc421551SDag-Erling Smørgrav </ul> 32bc421551SDag-Erling Smørgrav </nav> 33bc421551SDag-Erling Smørgrav 34bc421551SDag-Erling Smørgrav <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2> 35bc421551SDag-Erling Smørgrav<p> 36bc421551SDag-Erling SmørgravThe <a 37bc421551SDag-Erling Smørgravhref="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code> 38bc421551SDag-Erling Smørgravdatabase</a> attempts to record the history and predicted future of 39bc421551SDag-Erling Smørgravcivil time scales. 40bc421551SDag-Erling SmørgravIt organizes <a href="tz-link.html">time zone and daylight saving time 41bc421551SDag-Erling Smørgravdata</a> by partitioning the world into <a 42bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a> 43bc421551SDag-Erling Smørgravwhose clocks all agree about timestamps that occur after the <a 44bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a> 45bc421551SDag-Erling Smørgrav(1970-01-01 00:00:00 <a 46bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr 47bc421551SDag-Erling Smørgravtitle="Coordinated Universal Time">UTC</abbr></a>). 48bc421551SDag-Erling SmørgravAlthough 1970 is a somewhat-arbitrary cutoff, there are significant 49bc421551SDag-Erling Smørgravchallenges to moving the cutoff earlier even by a decade or two, due 50bc421551SDag-Erling Smørgravto the wide variety of local practices before computer timekeeping 51bc421551SDag-Erling Smørgravbecame prevalent. 52bc421551SDag-Erling SmørgravMost timezones correspond to a notable location and the database 53bc421551SDag-Erling Smørgravrecords all known clock transitions for that location; 54bc421551SDag-Erling Smørgravsome timezones correspond instead to a fixed <abbr>UTC</abbr> offset. 55bc421551SDag-Erling Smørgrav</p> 56bc421551SDag-Erling Smørgrav 57bc421551SDag-Erling Smørgrav<p> 58bc421551SDag-Erling SmørgravEach timezone typically corresponds to a geographical region that is 59bc421551SDag-Erling Smørgravsmaller than a traditional time zone, because clocks in a timezone 60bc421551SDag-Erling Smørgravall agree after 1970 whereas a traditional time zone merely 61bc421551SDag-Erling Smørgravspecifies current standard time. For example, applications that deal 62bc421551SDag-Erling Smørgravwith current and future timestamps in the traditional North 63bc421551SDag-Erling SmørgravAmerican mountain time zone can choose from the timezones 64bc421551SDag-Erling Smørgrav<code>America/Denver</code> which observes US-style daylight saving 65bc421551SDag-Erling Smørgravtime (<abbr>DST</abbr>), 66bc421551SDag-Erling Smørgravand <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>. 67bc421551SDag-Erling SmørgravApplications that also deal with past timestamps in the mountain time 68bc421551SDag-Erling Smørgravzone can choose from over a dozen timezones, such as 69*2447e777SDag-Erling Smørgrav<code>America/Boise</code> and 70bc421551SDag-Erling Smørgrav<code>America/Hermosillo</code>, each of which currently uses mountain 71bc421551SDag-Erling Smørgravtime but differs from other timezones for some timestamps after 1970. 72bc421551SDag-Erling Smørgrav</p> 73bc421551SDag-Erling Smørgrav 74bc421551SDag-Erling Smørgrav<p> 75bc421551SDag-Erling SmørgravClock transitions before 1970 are recorded for location-based timezones, 76bc421551SDag-Erling Smørgravbecause most systems support timestamps before 1970 and could 77bc421551SDag-Erling Smørgravmisbehave if data entries were omitted for pre-1970 transitions. 78bc421551SDag-Erling SmørgravHowever, the database is not designed for and does not suffice for 79bc421551SDag-Erling Smørgravapplications requiring accurate handling of all past times everywhere, 80bc421551SDag-Erling Smørgravas it would take far too much effort and guesswork to record all 81bc421551SDag-Erling Smørgravdetails of pre-1970 civil timekeeping. 82bc421551SDag-Erling SmørgravAlthough some information outside the scope of the database is 83bc421551SDag-Erling Smørgravcollected in a file <code>backzone</code> that is distributed along 84bc421551SDag-Erling Smørgravwith the database proper, this file is less reliable and does not 85bc421551SDag-Erling Smørgravnecessarily follow database guidelines. 86bc421551SDag-Erling Smørgrav</p> 87bc421551SDag-Erling Smørgrav 88bc421551SDag-Erling Smørgrav<p> 89bc421551SDag-Erling SmørgravAs described below, reference source code for using the 90bc421551SDag-Erling Smørgrav<code><abbr>tz</abbr></code> database is also available. 91bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> code is upwards compatible with <a 92bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international 93bc421551SDag-Erling Smørgravstandard for <a 94bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems. 95ff2c98b3SDag-Erling SmørgravAs of this writing, the current edition of POSIX is 96ff2c98b3SDag-Erling Smørgrav<a href="https://pubs.opengroup.org/onlinepubs/9799919799/">POSIX.1-2024</a> 97ff2c98b3SDag-Erling Smørgrav(The Open Group Base Specifications Issue 8, IEEE Std 1003.1-2024). 98ff2c98b3SDag-Erling SmørgravUnlike its predecessors 99ff2c98b3SDag-Erling Smørgrav<a href="https://archive.org/details/POSIX.1-1988">POSIX.1-1988</a> through 100ff2c98b3SDag-Erling Smørgrav<a href="https://pubs.opengroup.org/onlinepubs/9699919799/">POSIX.1-2017</a>, 101ff2c98b3SDag-Erling SmørgravPOSIX.1-2024 requires support for the 102a979394aSDag-Erling Smørgrav<code><abbr>tz</abbr></code> database, which has a 103a979394aSDag-Erling Smørgravmodel for describing civil time that is more complex than the 104ff2c98b3SDag-Erling Smørgravstandard and daylight saving times required by earlier POSIX editions. 105bc421551SDag-Erling SmørgravA <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can 106bc421551SDag-Erling Smørgravhave more than two changes per year, these changes need not merely 107bc421551SDag-Erling Smørgravflip back and forth between two alternatives, and the rules themselves 108bc421551SDag-Erling Smørgravcan change at times. 109bc421551SDag-Erling SmørgravWhether and when a timezone changes its clock, 110ff2c98b3SDag-Erling Smørgravand even the timezone’s notional base offset from <abbr>UTC</abbr>, 111bc421551SDag-Erling Smørgravare variable. 112ff2c98b3SDag-Erling SmørgravIt does not always make sense to talk about a timezone’s 113ff2c98b3SDag-Erling Smørgrav“base offset”, which is not necessarily a single number. 114bc421551SDag-Erling Smørgrav</p> 115bc421551SDag-Erling Smørgrav 116bc421551SDag-Erling Smørgrav <h2 id="naming">Timezone identifiers</h2> 117bc421551SDag-Erling Smørgrav<p> 118bc421551SDag-Erling SmørgravEach timezone has a name that uniquely identifies the timezone. 119bc421551SDag-Erling SmørgravInexperienced users are not expected to select these names unaided. 120bc421551SDag-Erling SmørgravDistributors should provide documentation and/or a simple selection 121bc421551SDag-Erling Smørgravinterface that explains each name via a map or via descriptive text like 122ff2c98b3SDag-Erling Smørgrav“Czech Republic” instead of the timezone name “<code>Europe/Prague</code>”. 123bc421551SDag-Erling SmørgravIf geolocation information is available, a selection interface can 124bc421551SDag-Erling Smørgravlocate the user on a timezone map or prioritize names that are 125bc421551SDag-Erling Smørgravgeographically close. For an example selection interface, see the 126bc421551SDag-Erling Smørgrav<code>tzselect</code> program in the <code><abbr>tz</abbr></code> code. 127ff2c98b3SDag-Erling SmørgravUnicode’s <a href="https://cldr.unicode.org">Common Locale Data 128967a49a2SDag-Erling SmørgravRepository (<abbr>CLDR</abbr>)</a> 129967a49a2SDag-Erling Smørgravcontains data that may be useful for other selection 130bc421551SDag-Erling Smørgravinterfaces; it maps timezone names like <code>Europe/Prague</code> to 131ff2c98b3SDag-Erling Smørgravlocale-dependent strings like “Prague”, “Praha”, “Прага”, and “布拉格”. 132bc421551SDag-Erling Smørgrav</p> 133bc421551SDag-Erling Smørgrav 134bc421551SDag-Erling Smørgrav<p> 135bc421551SDag-Erling SmørgravThe naming conventions attempt to strike a balance 136bc421551SDag-Erling Smørgravamong the following goals: 137bc421551SDag-Erling Smørgrav</p> 138bc421551SDag-Erling Smørgrav 139bc421551SDag-Erling Smørgrav<ul> 140bc421551SDag-Erling Smørgrav <li> 141bc421551SDag-Erling Smørgrav Uniquely identify every timezone where clocks have agreed since 1970. 142bc421551SDag-Erling Smørgrav This is essential for the intended use: static clocks keeping local 143bc421551SDag-Erling Smørgrav civil time. 144bc421551SDag-Erling Smørgrav </li> 145bc421551SDag-Erling Smørgrav <li> 146ff2c98b3SDag-Erling Smørgrav Indicate to experts where the timezone’s clocks typically are. 147bc421551SDag-Erling Smørgrav </li> 148bc421551SDag-Erling Smørgrav <li> 149bc421551SDag-Erling Smørgrav Be robust in the presence of political changes. 150bc421551SDag-Erling Smørgrav For example, names are typically not tied to countries, to avoid 151bc421551SDag-Erling Smørgrav incompatibilities when countries change their name (e.g., 152ff2c98b3SDag-Erling Smørgrav Swaziland→Eswatini) or when locations change countries (e.g., Hong 153bc421551SDag-Erling Smørgrav Kong from UK colony to China). 154bc421551SDag-Erling Smørgrav There is no requirement that every country or national 155bc421551SDag-Erling Smørgrav capital must have a timezone name. 156bc421551SDag-Erling Smørgrav </li> 157bc421551SDag-Erling Smørgrav <li> 158bc421551SDag-Erling Smørgrav Be portable to a wide variety of implementations. 159bc421551SDag-Erling Smørgrav </li> 160bc421551SDag-Erling Smørgrav <li> 161bc421551SDag-Erling Smørgrav Use a consistent naming conventions over the entire world. 162bc421551SDag-Erling Smørgrav </li> 163bc421551SDag-Erling Smørgrav</ul> 164bc421551SDag-Erling Smørgrav 165bc421551SDag-Erling Smørgrav<p> 166a979394aSDag-Erling SmørgravNames normally have the format 167bc421551SDag-Erling Smørgrav<var>AREA</var><code>/</code><var>LOCATION</var>, where 168bc421551SDag-Erling Smørgrav<var>AREA</var> is a continent or ocean, and 169bc421551SDag-Erling Smørgrav<var>LOCATION</var> is a specific location within the area. 170ff2c98b3SDag-Erling SmørgravNorth and South America share the same area, <code>America</code>. 171ff2c98b3SDag-Erling SmørgravTypical names are <code>Africa/Cairo</code>, 172ff2c98b3SDag-Erling Smørgrav<code>America/New_York</code>, and <code>Pacific/Honolulu</code>. 173bc421551SDag-Erling SmørgravSome names are further qualified to help avoid confusion; for example, 174ff2c98b3SDag-Erling Smørgrav<code>America/Indiana/Petersburg</code> distinguishes Petersburg, 175bc421551SDag-Erling SmørgravIndiana from other Petersburgs in America. 176bc421551SDag-Erling Smørgrav</p> 177bc421551SDag-Erling Smørgrav 178bc421551SDag-Erling Smørgrav<p> 179bc421551SDag-Erling SmørgravHere are the general guidelines used for 180bc421551SDag-Erling Smørgravchoosing timezone names, 181bc421551SDag-Erling Smørgravin decreasing order of importance: 182bc421551SDag-Erling Smørgrav</p> 183bc421551SDag-Erling Smørgrav 184bc421551SDag-Erling Smørgrav<ul> 185bc421551SDag-Erling Smørgrav <li> 186bc421551SDag-Erling Smørgrav Use only valid POSIX file name components (i.e., the parts of 187ff2c98b3SDag-Erling Smørgrav names other than "<code>/</code>"). 188ff2c98b3SDag-Erling Smørgrav Do not use the file name components "<code>.</code>" and 189ff2c98b3SDag-Erling Smørgrav "<code>..</code>". 190bc421551SDag-Erling Smørgrav Within a file name component, use only <a 191bc421551SDag-Erling Smørgrav href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters, 192ff2c98b3SDag-Erling Smørgrav "<code>.</code>", "<code>-</code>" and "<code>_</code>". 193bc421551SDag-Erling Smørgrav Do not use digits, as that might create an ambiguity with <a 194ff2c98b3SDag-Erling Smørgrav href="https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html#tag_08_03">POSIX’s 195ff2c98b3SDag-Erling Smørgrav proleptic <code>TZ</code> strings</a>. 196bc421551SDag-Erling Smørgrav A file name component must not exceed 14 characters or start with 197ff2c98b3SDag-Erling Smørgrav "<code>-</code>". 198bc421551SDag-Erling Smørgrav E.g., prefer <code>America/Noronha</code> to 199bc421551SDag-Erling Smørgrav <code>America/Fernando_de_Noronha</code>. 200bc421551SDag-Erling Smørgrav Exceptions: see the discussion of legacy names below. 201bc421551SDag-Erling Smørgrav </li> 202bc421551SDag-Erling Smørgrav <li> 203ff2c98b3SDag-Erling Smørgrav A name must not be empty, or contain "<code>//</code>", or 204ff2c98b3SDag-Erling Smørgrav start or end with "<code>/</code>". 205ff2c98b3SDag-Erling Smørgrav Also, a name must not be "<code>Etc/Unknown</code>", as 206967a49a2SDag-Erling Smørgrav <abbr>CLDR</abbr> uses that string for an unknown or invalid timezone. 207bc421551SDag-Erling Smørgrav </li> 208bc421551SDag-Erling Smørgrav <li> 209bc421551SDag-Erling Smørgrav Do not use names that differ only in case. 210bc421551SDag-Erling Smørgrav Although the reference implementation is case-sensitive, some 211bc421551SDag-Erling Smørgrav other implementations are not, and they would mishandle names 212bc421551SDag-Erling Smørgrav differing only in case. 213bc421551SDag-Erling Smørgrav </li> 214bc421551SDag-Erling Smørgrav <li> 215bc421551SDag-Erling Smørgrav If one name <var>A</var> is an initial prefix of another 216bc421551SDag-Erling Smørgrav name <var>AB</var> (ignoring case), then <var>B</var> must not 217ff2c98b3SDag-Erling Smørgrav start with "<code>/</code>", as a regular file cannot have the 218bc421551SDag-Erling Smørgrav same name as a directory in POSIX. 219bc421551SDag-Erling Smørgrav For example, <code>America/New_York</code> precludes 220bc421551SDag-Erling Smørgrav <code>America/New_York/Bronx</code>. 221bc421551SDag-Erling Smørgrav </li> 222bc421551SDag-Erling Smørgrav <li> 223bc421551SDag-Erling Smørgrav Uninhabited regions like the North Pole and Bouvet Island 224bc421551SDag-Erling Smørgrav do not need locations, since local time is not defined there. 225bc421551SDag-Erling Smørgrav </li> 226bc421551SDag-Erling Smørgrav <li> 227967a49a2SDag-Erling Smørgrav If all clocks in a region have agreed since 1970, 228967a49a2SDag-Erling Smørgrav give them just one name even if some of the clocks disagreed before 1970, 229967a49a2SDag-Erling Smørgrav or reside in different countries or in notable or faraway locations. 230bc421551SDag-Erling Smørgrav Otherwise these tables would become annoyingly large. 231967a49a2SDag-Erling Smørgrav For example, do not create a name <code>Indian/Crozet</code> 232967a49a2SDag-Erling Smørgrav as a near-duplicate or alias of <code>Asia/Dubai</code> 233967a49a2SDag-Erling Smørgrav merely because they are different countries or territories, 234967a49a2SDag-Erling Smørgrav or their clocks disagreed before 1970, or the 235967a49a2SDag-Erling Smørgrav <a href="https://en.wikipedia.org/wiki/Crozet_Islands">Crozet Islands</a> 236967a49a2SDag-Erling Smørgrav are notable in their own right, 237967a49a2SDag-Erling Smørgrav or the Crozet Islands are not adjacent to other locations 238967a49a2SDag-Erling Smørgrav that use <code>Asia/Dubai</code>. 239bc421551SDag-Erling Smørgrav </li> 240bc421551SDag-Erling Smørgrav <li> 241bc421551SDag-Erling Smørgrav If boundaries between regions are fluid, such as during a war or 242bc421551SDag-Erling Smørgrav insurrection, do not bother to create a new timezone merely 243bc421551SDag-Erling Smørgrav because of yet another boundary change. This helps prevent table 244bc421551SDag-Erling Smørgrav bloat and simplifies maintenance. 245bc421551SDag-Erling Smørgrav </li> 246bc421551SDag-Erling Smørgrav <li> 247bc421551SDag-Erling Smørgrav If a name is ambiguous, use a less ambiguous alternative; 248bc421551SDag-Erling Smørgrav e.g., many cities are named San José and Georgetown, so 249bc421551SDag-Erling Smørgrav prefer <code>America/Costa_Rica</code> to 250bc421551SDag-Erling Smørgrav <code>America/San_Jose</code> and <code>America/Guyana</code> 251bc421551SDag-Erling Smørgrav to <code>America/Georgetown</code>. 252bc421551SDag-Erling Smørgrav </li> 253bc421551SDag-Erling Smørgrav <li> 254bc421551SDag-Erling Smørgrav Keep locations compact. 255bc421551SDag-Erling Smørgrav Use cities or small islands, not countries or regions, so that any 256bc421551SDag-Erling Smørgrav future changes do not split individual locations into different 257bc421551SDag-Erling Smørgrav timezones. 258bc421551SDag-Erling Smørgrav E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>, 259bc421551SDag-Erling Smørgrav since 260bc421551SDag-Erling Smørgrav <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France 261bc421551SDag-Erling Smørgrav has had multiple time zones</a>. 262bc421551SDag-Erling Smørgrav </li> 263bc421551SDag-Erling Smørgrav <li> 264bc421551SDag-Erling Smørgrav Use mainstream English spelling, e.g., prefer 265bc421551SDag-Erling Smørgrav <code>Europe/Rome</code> to <code>Europa/Roma</code>, and 266bc421551SDag-Erling Smørgrav prefer <code>Europe/Athens</code> to the Greek 267bc421551SDag-Erling Smørgrav <code>Ευρώπη/Αθήνα</code> or the Romanized 268bc421551SDag-Erling Smørgrav <code>Evrópi/Athína</code>. 269bc421551SDag-Erling Smørgrav The POSIX file name restrictions encourage this guideline. 270bc421551SDag-Erling Smørgrav </li> 271bc421551SDag-Erling Smørgrav <li> 272bc421551SDag-Erling Smørgrav Use the most populous among locations in a region, 273bc421551SDag-Erling Smørgrav e.g., prefer <code>Asia/Shanghai</code> to 274bc421551SDag-Erling Smørgrav <code>Asia/Beijing</code>. 275bc421551SDag-Erling Smørgrav Among locations with similar populations, pick the best-known 276bc421551SDag-Erling Smørgrav location, e.g., prefer <code>Europe/Rome</code> to 277bc421551SDag-Erling Smørgrav <code>Europe/Milan</code>. 278bc421551SDag-Erling Smørgrav </li> 279bc421551SDag-Erling Smørgrav <li> 280bc421551SDag-Erling Smørgrav Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to 281bc421551SDag-Erling Smørgrav <code>Atlantic/Canaries</code>. 282bc421551SDag-Erling Smørgrav </li> 283bc421551SDag-Erling Smørgrav <li> 284ff2c98b3SDag-Erling Smørgrav Omit common suffixes like "<code>_Islands</code>" and 285ff2c98b3SDag-Erling Smørgrav "<code>_City</code>", unless that would lead to ambiguity. 286bc421551SDag-Erling Smørgrav E.g., prefer <code>America/Cayman</code> to 287bc421551SDag-Erling Smørgrav <code>America/Cayman_Islands</code> and 288bc421551SDag-Erling Smørgrav <code>America/Guatemala</code> to 289bc421551SDag-Erling Smørgrav <code>America/Guatemala_City</code>, but prefer 290bc421551SDag-Erling Smørgrav <code>America/Mexico_City</code> to 291bc421551SDag-Erling Smørgrav <code>America/Mexico</code> 292bc421551SDag-Erling Smørgrav because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the 293bc421551SDag-Erling Smørgrav country of Mexico has several time zones</a>. 294bc421551SDag-Erling Smørgrav </li> 295bc421551SDag-Erling Smørgrav <li> 296ff2c98b3SDag-Erling Smørgrav Use "<code>_</code>" to represent a space. 297bc421551SDag-Erling Smørgrav </li> 298bc421551SDag-Erling Smørgrav <li> 299ff2c98b3SDag-Erling Smørgrav Omit "<code>.</code>" from abbreviations in names. 300bc421551SDag-Erling Smørgrav E.g., prefer <code>Atlantic/St_Helena</code> to 301bc421551SDag-Erling Smørgrav <code>Atlantic/St._Helena</code>. 302bc421551SDag-Erling Smørgrav </li> 303bc421551SDag-Erling Smørgrav <li> 304bc421551SDag-Erling Smørgrav Do not change established names if they only marginally violate 305bc421551SDag-Erling Smørgrav the above guidelines. 306bc421551SDag-Erling Smørgrav For example, do not change the existing name <code>Europe/Rome</code> to 307ff2c98b3SDag-Erling Smørgrav <code>Europe/Milan</code> merely because Milan’s population has grown 308ff2c98b3SDag-Erling Smørgrav to be somewhat greater than Rome’s. 309bc421551SDag-Erling Smørgrav </li> 310bc421551SDag-Erling Smørgrav <li> 311bc421551SDag-Erling Smørgrav If a name is changed, put its old spelling in the 312ff2c98b3SDag-Erling Smørgrav "<code>backward</code>" file as a link to the new spelling. 313bc421551SDag-Erling Smørgrav This means old spellings will continue to work. 314bc421551SDag-Erling Smørgrav Ordinarily a name change should occur only in the rare case when 315ff2c98b3SDag-Erling Smørgrav a location’s consensus English-language spelling changes; for example, 316bc421551SDag-Erling Smørgrav in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code> 317bc421551SDag-Erling Smørgrav due to long-time widespread use of the new city name instead of the old. 318bc421551SDag-Erling Smørgrav </li> 319bc421551SDag-Erling Smørgrav</ul> 320bc421551SDag-Erling Smørgrav 321bc421551SDag-Erling Smørgrav<p> 322bc421551SDag-Erling SmørgravGuidelines have evolved with time, and names following old versions of 323bc421551SDag-Erling Smørgravthese guidelines might not follow the current version. When guidelines 324bc421551SDag-Erling Smørgravhave changed, old names continue to be supported. Guideline changes 325bc421551SDag-Erling Smørgravhave included the following: 326bc421551SDag-Erling Smørgrav</p> 327bc421551SDag-Erling Smørgrav 328bc421551SDag-Erling Smørgrav<ul> 329bc421551SDag-Erling Smørgrav<li> 330bc421551SDag-Erling SmørgravOlder versions of this package used a different naming scheme. 331ff2c98b3SDag-Erling SmørgravSee the file "<code>backward</code>" for most of these older names 332ff2c98b3SDag-Erling Smørgrav(e.g., <code>US/Eastern</code> instead of <code>America/New_York</code>). 333bc421551SDag-Erling SmørgravThe other old-fashioned names still supported are 334ff2c98b3SDag-Erling Smørgrav<code>WET</code>, <code>CET</code>, <code>MET</code>, and 335ff2c98b3SDag-Erling Smørgrav<code>EET</code> (see the file "<code>europe</code>"). 336bc421551SDag-Erling Smørgrav</li> 337bc421551SDag-Erling Smørgrav 338bc421551SDag-Erling Smørgrav<li> 339bc421551SDag-Erling SmørgravOlder versions of this package defined legacy names that are 340bc421551SDag-Erling Smørgravincompatible with the first guideline of location names, but which are 341bc421551SDag-Erling Smørgravstill supported. 342bc421551SDag-Erling SmørgravThese legacy names are mostly defined in the file 343ff2c98b3SDag-Erling Smørgrav"<code>etcetera</code>". 344ff2c98b3SDag-Erling SmørgravAlso, the file "<code>backward</code>" defines the legacy names 345ff2c98b3SDag-Erling Smørgrav<code>Etc/GMT0</code>, <code>Etc/GMT-0</code>, <code>Etc/GMT+0</code>, 346212e3524SDag-Erling Smørgrav<code>GMT0</code>, <code>GMT-0</code>, <code>GMT+0</code>, 347ff2c98b3SDag-Erling Smørgrav<code>EST5EDT</code>, <code>CST6CDT</code>, 348ff2c98b3SDag-Erling Smørgrav<code>MST7MDT</code>, and <code>PST8PDT</code>. 349bc421551SDag-Erling Smørgrav</li> 350bc421551SDag-Erling Smørgrav 351bc421551SDag-Erling Smørgrav<li> 352bc421551SDag-Erling SmørgravOlder versions of these guidelines said that 353bc421551SDag-Erling Smørgravthere should typically be at least one name for each <a 354bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr 355bc421551SDag-Erling Smørgravtitle="International Organization for Standardization">ISO</abbr> 356bc421551SDag-Erling Smørgrav3166-1</a> officially assigned two-letter code for an inhabited 357bc421551SDag-Erling Smørgravcountry or territory. 358bc421551SDag-Erling SmørgravThis old guideline has been dropped, as it was not needed to handle 359bc421551SDag-Erling Smørgravtimestamps correctly and it increased maintenance burden. 360bc421551SDag-Erling Smørgrav</li> 361bc421551SDag-Erling Smørgrav</ul> 362bc421551SDag-Erling Smørgrav 363bc421551SDag-Erling Smørgrav<p> 364bc421551SDag-Erling SmørgravThe file <code>zone1970.tab</code> lists geographical locations used 365bc421551SDag-Erling Smørgravto name timezones. 366bc421551SDag-Erling SmørgravIt is intended to be an exhaustive list of names for geographic 367bc421551SDag-Erling Smørgravregions as described above; this is a subset of the timezones in the data. 368ff2c98b3SDag-Erling SmørgravAlthough a <code>zone1970.tab</code> location’s 369bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Longitude">longitude</a> 370bc421551SDag-Erling Smørgravcorresponds to 371bc421551SDag-Erling Smørgravits <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean 372ff2c98b3SDag-Erling Smørgravtime (<abbr>LMT</abbr>)</a> offset with one hour for every 15° 373bc421551SDag-Erling Smørgraveast longitude, this relationship is not exact. 374bc421551SDag-Erling SmørgravThe backward-compatibility file <code>zone.tab</code> is similar 375bc421551SDag-Erling Smørgravbut conforms to the older-version guidelines related to <abbr>ISO</abbr> 3166-1; 376bc421551SDag-Erling Smørgravit lists only one country code per entry and unlike <code>zone1970.tab</code> 377bc421551SDag-Erling Smørgravit can list names defined in <code>backward</code>. 37846c59934SDag-Erling SmørgravApplications that process only timestamps from now on can instead use the file 37946c59934SDag-Erling Smørgrav<code>zonenow.tab</code>, which partitions the world more coarsely, 38046c59934SDag-Erling Smørgravinto regions where clocks agree now and in the predicted future; 38146c59934SDag-Erling Smørgravthis file is smaller and simpler than <code>zone1970.tab</code> 38246c59934SDag-Erling Smørgravand <code>zone.tab</code>. 383bc421551SDag-Erling Smørgrav</p> 384bc421551SDag-Erling Smørgrav 385bc421551SDag-Erling Smørgrav<p> 386bc421551SDag-Erling SmørgravThe database defines each timezone name to be a zone, or a link to a zone. 387212e3524SDag-Erling SmørgravThe source file <code>backward</code> defines links 388212e3524SDag-Erling Smørgravand a few zones for backward compatibility. 389bc421551SDag-Erling SmørgravAlthough <code>backward</code> was originally designed to be optional, 390bc421551SDag-Erling Smørgravnowadays distributions typically use it 391212e3524SDag-Erling Smørgravand no great weight should be attached to whether a link or zone 392bc421551SDag-Erling Smørgravis defined in <code>backward</code> or in some other file. 393bc421551SDag-Erling SmørgravThe source file <code>etcetera</code> defines names that may be useful 394a979394aSDag-Erling Smørgravon platforms that do not support proleptic <code>TZ</code> strings 395a979394aSDag-Erling Smørgravlike <code><+08>-8</code>; 396bc421551SDag-Erling Smørgravno other source file other than <code>backward</code> 397bc421551SDag-Erling Smørgravcontains links to its zones. 398ff2c98b3SDag-Erling SmørgravOne of <code>etcetera</code>’s names is <code>Etc/UTC</code>, 399bc421551SDag-Erling Smørgravused by functions like <code>gmtime</code> to obtain leap 400bc421551SDag-Erling Smørgravsecond information on platforms that support leap seconds. 401bc421551SDag-Erling SmørgravAnother <code>etcetera</code> name, <code>GMT</code>, 402bc421551SDag-Erling Smørgravis used by older code releases. 403bc421551SDag-Erling Smørgrav</p> 404bc421551SDag-Erling Smørgrav 405bc421551SDag-Erling Smørgrav <h2 id="abbreviations">Time zone abbreviations</h2> 406bc421551SDag-Erling Smørgrav<p> 407bc421551SDag-Erling SmørgravWhen this package is installed, it generates time zone abbreviations 408ff2c98b3SDag-Erling Smørgravlike <code>EST</code> to be compatible with human tradition and POSIX. 409bc421551SDag-Erling SmørgravHere are the general guidelines used for choosing time zone abbreviations, 410bc421551SDag-Erling Smørgravin decreasing order of importance: 411bc421551SDag-Erling Smørgrav</p> 412bc421551SDag-Erling Smørgrav 413bc421551SDag-Erling Smørgrav<ul> 414bc421551SDag-Erling Smørgrav <li> 415bc421551SDag-Erling Smørgrav Use three to six characters that are ASCII alphanumerics or 416ff2c98b3SDag-Erling Smørgrav "<code>+</code>" or "<code>-</code>". 417bc421551SDag-Erling Smørgrav Previous editions of this database also used characters like 418ff2c98b3SDag-Erling Smørgrav space and "<code>?</code>", but these characters have a 419bc421551SDag-Erling Smørgrav special meaning to the 420bc421551SDag-Erling Smørgrav <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a> 421bc421551SDag-Erling Smørgrav and cause commands like 422ff2c98b3SDag-Erling Smørgrav "<code><a href="https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#set">set</a> 423ff2c98b3SDag-Erling Smørgrav `<a href="https://pubs.opengroup.org/onlinepubs/9799919799/utilities/date.html">date</a>`</code>" 424bc421551SDag-Erling Smørgrav to have unexpected effects. 425bc421551SDag-Erling Smørgrav Previous editions of this guideline required upper-case letters, but the 426bc421551SDag-Erling Smørgrav Congressman who introduced 427bc421551SDag-Erling Smørgrav <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro 428ff2c98b3SDag-Erling Smørgrav Standard Time</a> preferred “ChST”, so lower-case letters are now allowed. 429ff2c98b3SDag-Erling Smørgrav Also, POSIX from 2001 on relaxed the rule to allow "<code>-</code>", 430ff2c98b3SDag-Erling Smørgrav "<code>+</code>", and alphanumeric characters from the portable 431bc421551SDag-Erling Smørgrav character set in the current locale. 432ff2c98b3SDag-Erling Smørgrav In practice ASCII alphanumerics and "<code>+</code>" and 433ff2c98b3SDag-Erling Smørgrav "<code>-</code>" are safe in all locales. 434bc421551SDag-Erling Smørgrav 435bc421551SDag-Erling Smørgrav <p> 436bc421551SDag-Erling Smørgrav In other words, in the C locale the POSIX extended regular 437bc421551SDag-Erling Smørgrav expression <code>[-+[:alnum:]]{3,6}</code> should match the 438bc421551SDag-Erling Smørgrav abbreviation. 439a979394aSDag-Erling Smørgrav This guarantees that all abbreviations could have been specified 440a979394aSDag-Erling Smørgrav explicitly by a POSIX proleptic <code>TZ</code> string. 441bc421551SDag-Erling Smørgrav </p> 442bc421551SDag-Erling Smørgrav </li> 443bc421551SDag-Erling Smørgrav <li> 444bc421551SDag-Erling Smørgrav Use abbreviations that are in common use among English-speakers, 445ff2c98b3SDag-Erling Smørgrav e.g., “EST” for Eastern Standard Time in North America. 446bc421551SDag-Erling Smørgrav We assume that applications translate them to other languages 447bc421551SDag-Erling Smørgrav as part of the normal localization process; for example, 448ff2c98b3SDag-Erling Smørgrav a French application might translate “EST” to “HNE”. 449bc421551SDag-Erling Smørgrav 450bc421551SDag-Erling Smørgrav <p> 451bc421551SDag-Erling Smørgrav <small>These abbreviations (for standard/daylight/etc. time) are: 452bc421551SDag-Erling Smørgrav ACST/ACDT Australian Central, 453bc421551SDag-Erling Smørgrav AST/ADT/APT/AWT/ADDT Atlantic, 454bc421551SDag-Erling Smørgrav AEST/AEDT Australian Eastern, 455bc421551SDag-Erling Smørgrav AHST/AHDT Alaska-Hawaii, 456bc421551SDag-Erling Smørgrav AKST/AKDT Alaska, 457bc421551SDag-Erling Smørgrav AWST/AWDT Australian Western, 458bc421551SDag-Erling Smørgrav BST/BDT Bering, 459bc421551SDag-Erling Smørgrav CAT/CAST Central Africa, 460bc421551SDag-Erling Smørgrav CET/CEST/CEMT Central European, 461bc421551SDag-Erling Smørgrav ChST Chamorro, 46275411d15SDag-Erling Smørgrav CST/CDT/CWT/CPT Central [North America], 463bc421551SDag-Erling Smørgrav CST/CDT China, 464bc421551SDag-Erling Smørgrav GMT/BST/IST/BDST Greenwich, 465bc421551SDag-Erling Smørgrav EAT East Africa, 46675411d15SDag-Erling Smørgrav EST/EDT/EWT/EPT Eastern [North America], 467bc421551SDag-Erling Smørgrav EET/EEST Eastern European, 468bc421551SDag-Erling Smørgrav GST/GDT Guam, 469bc421551SDag-Erling Smørgrav HST/HDT/HWT/HPT Hawaii, 470bc421551SDag-Erling Smørgrav HKT/HKST/HKWT Hong Kong, 471bc421551SDag-Erling Smørgrav IST India, 472bc421551SDag-Erling Smørgrav IST/GMT Irish, 473bc421551SDag-Erling Smørgrav IST/IDT/IDDT Israel, 474bc421551SDag-Erling Smørgrav JST/JDT Japan, 475bc421551SDag-Erling Smørgrav KST/KDT Korea, 476bc421551SDag-Erling Smørgrav MET/MEST Middle European (a backward-compatibility alias for 477bc421551SDag-Erling Smørgrav Central European), 478bc421551SDag-Erling Smørgrav MSK/MSD Moscow, 47975411d15SDag-Erling Smørgrav MST/MDT/MWT/MPT Mountain, 480bc421551SDag-Erling Smørgrav NST/NDT/NWT/NPT/NDDT Newfoundland, 481bc421551SDag-Erling Smørgrav NST/NDT/NWT/NPT Nome, 482bc421551SDag-Erling Smørgrav NZMT/NZST New Zealand through 1945, 483ff2c98b3SDag-Erling Smørgrav NZST/NZDT New Zealand 1946–present, 484bc421551SDag-Erling Smørgrav PKT/PKST Pakistan, 48575411d15SDag-Erling Smørgrav PST/PDT/PWT/PPT Pacific, 486bc421551SDag-Erling Smørgrav PST/PDT Philippine, 487bc421551SDag-Erling Smørgrav SAST South Africa, 488bc421551SDag-Erling Smørgrav SST Samoa, 489bc421551SDag-Erling Smørgrav UTC Universal, 490bc421551SDag-Erling Smørgrav WAT/WAST West Africa, 491bc421551SDag-Erling Smørgrav WET/WEST/WEMT Western European, 492bc421551SDag-Erling Smørgrav WIB Waktu Indonesia Barat, 493bc421551SDag-Erling Smørgrav WIT Waktu Indonesia Timur, 494bc421551SDag-Erling Smørgrav WITA Waktu Indonesia Tengah, 495bc421551SDag-Erling Smørgrav YST/YDT/YWT/YPT/YDDT Yukon</small>. 496bc421551SDag-Erling Smørgrav </p> 497bc421551SDag-Erling Smørgrav </li> 498bc421551SDag-Erling Smørgrav <li> 499bc421551SDag-Erling Smørgrav <p> 500ff2c98b3SDag-Erling Smørgrav For times taken from a city’s longitude, use the 501bc421551SDag-Erling Smørgrav traditional <var>x</var>MT notation. 502ff2c98b3SDag-Erling Smørgrav The only abbreviation like this in current use is <abbr>GMT</abbr>. 503bc421551SDag-Erling Smørgrav The others are for timestamps before 1960, 504bc421551SDag-Erling Smørgrav except that Monrovia Mean Time persisted until 1972. 505ff2c98b3SDag-Erling Smørgrav Typically, numeric abbreviations (e.g., <code>-</code>004430 for 506bc421551SDag-Erling Smørgrav MMT) would cause trouble here, as the numeric strings would exceed 507bc421551SDag-Erling Smørgrav the POSIX length limit. 508bc421551SDag-Erling Smørgrav </p> 509bc421551SDag-Erling Smørgrav 510bc421551SDag-Erling Smørgrav <p> 511bc421551SDag-Erling Smørgrav <small>These abbreviations are: 512bc421551SDag-Erling Smørgrav AMT Asunción, Athens; 51375411d15SDag-Erling Smørgrav BMT Baghdad, Bangkok, Batavia, Bermuda, Bern, Bogotá, 514bc421551SDag-Erling Smørgrav Brussels, Bucharest; 515bc421551SDag-Erling Smørgrav CMT Calamarca, Caracas, Chisinau, Colón, Córdoba; 516bc421551SDag-Erling Smørgrav DMT Dublin/Dunsink; 517bc421551SDag-Erling Smørgrav EMT Easter; 518bc421551SDag-Erling Smørgrav FFMT Fort-de-France; 519bc421551SDag-Erling Smørgrav FMT Funchal; 520bc421551SDag-Erling Smørgrav GMT Greenwich; 521bc421551SDag-Erling Smørgrav HMT Havana, Helsinki, Horta, Howrah; 522bc421551SDag-Erling Smørgrav IMT Irkutsk, Istanbul; 523bc421551SDag-Erling Smørgrav JMT Jerusalem; 524bc421551SDag-Erling Smørgrav KMT Kaunas, Kyiv, Kingston; 52575411d15SDag-Erling Smørgrav LMT Lima, Lisbon, local; 526bc421551SDag-Erling Smørgrav MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo, 527bc421551SDag-Erling Smørgrav Moratuwa, Moscow; 528bc421551SDag-Erling Smørgrav PLMT Phù Liễn; 529bc421551SDag-Erling Smørgrav PMT Paramaribo, Paris, Perm, Pontianak, Prague; 530bc421551SDag-Erling Smørgrav PMMT Port Moresby; 53175411d15SDag-Erling Smørgrav PPMT Port-au-Prince; 532bc421551SDag-Erling Smørgrav QMT Quito; 533bc421551SDag-Erling Smørgrav RMT Rangoon, Riga, Rome; 534bc421551SDag-Erling Smørgrav SDMT Santo Domingo; 535bc421551SDag-Erling Smørgrav SJMT San José; 536bc421551SDag-Erling Smørgrav SMT Santiago, Simferopol, Singapore, Stanley; 537bc421551SDag-Erling Smørgrav TBMT Tbilisi; 538bc421551SDag-Erling Smørgrav TMT Tallinn, Tehran; 53975411d15SDag-Erling Smørgrav WMT Warsaw.</small> 540bc421551SDag-Erling Smørgrav </p> 541bc421551SDag-Erling Smørgrav 542bc421551SDag-Erling Smørgrav <p> 543bc421551SDag-Erling Smørgrav <small>A few abbreviations also follow the pattern that 544bc421551SDag-Erling Smørgrav <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK. 545bc421551SDag-Erling Smørgrav They are: 546ff2c98b3SDag-Erling Smørgrav BMT/BST for Bermuda 1890–1930, 547bc421551SDag-Erling Smørgrav CMT/BST for Calamarca Mean Time and Bolivian Summer Time 548ff2c98b3SDag-Erling Smørgrav 1890–1932, 549bc421551SDag-Erling Smørgrav DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time 550ff2c98b3SDag-Erling Smørgrav 1880–1916, 551ff2c98b3SDag-Erling Smørgrav MMT/MST/MDST for Moscow 1880–1919, and 552ff2c98b3SDag-Erling Smørgrav RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926. 553bc421551SDag-Erling Smørgrav </small> 554bc421551SDag-Erling Smørgrav </p> 555bc421551SDag-Erling Smørgrav </li> 556bc421551SDag-Erling Smørgrav <li> 557ff2c98b3SDag-Erling Smørgrav Use “<abbr>LMT</abbr>” for local mean time of locations before the 558ff2c98b3SDag-Erling Smørgrav introduction of standard time; see “<a href="#scope">Scope of the 559ff2c98b3SDag-Erling Smørgrav <code><abbr>tz</abbr></code> database</a>”. 560bc421551SDag-Erling Smørgrav </li> 561bc421551SDag-Erling Smørgrav <li> 562bc421551SDag-Erling Smørgrav If there is no common English abbreviation, use numeric offsets like 563bc421551SDag-Erling Smørgrav <code>-</code>05 and <code>+</code>0530 that are generated 564ff2c98b3SDag-Erling Smørgrav by <code>zic</code>’s <code>%z</code> notation. 565bc421551SDag-Erling Smørgrav </li> 566bc421551SDag-Erling Smørgrav <li> 567bc421551SDag-Erling Smørgrav Use current abbreviations for older timestamps to avoid confusion. 568bc421551SDag-Erling Smørgrav For example, in 1910 a common English abbreviation for time 569ff2c98b3SDag-Erling Smørgrav in central Europe was “MEZ” (short for both “Middle European 570ff2c98b3SDag-Erling Smørgrav Zone” and for “Mitteleuropäische Zeit” in German). 571ff2c98b3SDag-Erling Smørgrav Nowadays “CET” (“Central European Time”) is more common in 572ff2c98b3SDag-Erling Smørgrav English, and the database uses “CET” even for circa-1910 573bc421551SDag-Erling Smørgrav timestamps as this is less confusing for modern users and avoids 574ff2c98b3SDag-Erling Smørgrav the need for determining when “CET” supplanted “MEZ” in common 575bc421551SDag-Erling Smørgrav usage. 576bc421551SDag-Erling Smørgrav </li> 577bc421551SDag-Erling Smørgrav <li> 578ff2c98b3SDag-Erling Smørgrav Use a consistent style in a timezone’s history. 579bc421551SDag-Erling Smørgrav For example, if a history tends to use numeric 580bc421551SDag-Erling Smørgrav abbreviations and a particular entry could go either way, use a 581bc421551SDag-Erling Smørgrav numeric abbreviation. 582bc421551SDag-Erling Smørgrav </li> 583bc421551SDag-Erling Smørgrav <li> 584bc421551SDag-Erling Smørgrav Use 585bc421551SDag-Erling Smørgrav <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a> 586ff2c98b3SDag-Erling Smørgrav (<abbr>UT</abbr>) (with time zone abbreviation <code>-</code>00) for 587bc421551SDag-Erling Smørgrav locations while uninhabited. 588ff2c98b3SDag-Erling Smørgrav The leading "<code>-</code>" is a flag that the <abbr>UT</abbr> offset is in 589bc421551SDag-Erling Smørgrav some sense undefined; this notation is derived 59028f617deSDag-Erling Smørgrav from <a href="https://www.rfc-editor.org/info/rfc3339/">Internet 591bc421551SDag-Erling Smørgrav <abbr title="Request For Comments">RFC</abbr> 3339</a>. 592ff2c98b3SDag-Erling Smørgrav (The abbreviation Z that 59328f617deSDag-Erling Smørgrav <a href="https://www.rfc-editor.org/info/rfc9557/">Internet 594a979394aSDag-Erling Smørgrav <abbr>RFC</abbr> 9557</a> uses for this concept 595a979394aSDag-Erling Smørgrav would violate the POSIX requirement 596a979394aSDag-Erling Smørgrav of at least three characters in an abbreviation.) 597bc421551SDag-Erling Smørgrav </li> 598bc421551SDag-Erling Smørgrav</ul> 599bc421551SDag-Erling Smørgrav 600bc421551SDag-Erling Smørgrav<p> 601bc421551SDag-Erling SmørgravApplication writers should note that these abbreviations are ambiguous 602ff2c98b3SDag-Erling Smørgravin practice: e.g., CST means one thing in China and something else 603ff2c98b3SDag-Erling Smørgravin North America, and IST can refer to time in India, Ireland or 604bc421551SDag-Erling SmørgravIsrael. 605bc421551SDag-Erling SmørgravTo avoid ambiguity, use numeric <abbr>UT</abbr> offsets like 606ff2c98b3SDag-Erling Smørgrav<code>-</code>0600 instead of time zone abbreviations like CST. 607bc421551SDag-Erling Smørgrav</p> 608bc421551SDag-Erling Smørgrav 609bc421551SDag-Erling Smørgrav <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2> 610bc421551SDag-Erling Smørgrav<p> 611bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> database is not authoritative, and it 612bc421551SDag-Erling Smørgravsurely has errors. 613bc421551SDag-Erling SmørgravCorrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. 614bc421551SDag-Erling SmørgravUsers requiring authoritative data should consult national standards 615ff2c98b3SDag-Erling Smørgravbodies and the references cited in the database’s comments. 616bc421551SDag-Erling Smørgrav</p> 617bc421551SDag-Erling Smørgrav 618bc421551SDag-Erling Smørgrav<p> 619bc421551SDag-Erling SmørgravErrors in the <code><abbr>tz</abbr></code> database arise from many sources: 620bc421551SDag-Erling Smørgrav</p> 621bc421551SDag-Erling Smørgrav 622bc421551SDag-Erling Smørgrav<ul> 623bc421551SDag-Erling Smørgrav <li> 624bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> database predicts future 625bc421551SDag-Erling Smørgrav timestamps, and current predictions 626bc421551SDag-Erling Smørgrav will be incorrect after future governments change the rules. 627bc421551SDag-Erling Smørgrav For example, if today someone schedules a meeting for 13:00 next 62828f617deSDag-Erling Smørgrav October 1, Dublin time, and tomorrow Ireland changes its 629bc421551SDag-Erling Smørgrav daylight saving rules, software can mess up after the rule change 630bc421551SDag-Erling Smørgrav if it blithely relies on conversions made before the change. 631bc421551SDag-Erling Smørgrav </li> 632bc421551SDag-Erling Smørgrav <li> 633bc421551SDag-Erling Smørgrav The pre-1970 entries in this database cover only a tiny sliver of how 634bc421551SDag-Erling Smørgrav clocks actually behaved; the vast majority of the necessary 635bc421551SDag-Erling Smørgrav information was lost or never recorded. 636bc421551SDag-Erling Smørgrav Thousands more timezones would be needed if 637ff2c98b3SDag-Erling Smørgrav the <code><abbr>tz</abbr></code> database’s scope were extended to 638bc421551SDag-Erling Smørgrav cover even just the known or guessed history of standard time; for 639bc421551SDag-Erling Smørgrav example, the current single entry for France would need to split 640bc421551SDag-Erling Smørgrav into dozens of entries, perhaps hundreds. 641bc421551SDag-Erling Smørgrav And in most of the world even this approach would be misleading 642bc421551SDag-Erling Smørgrav due to widespread disagreement or indifference about what times 643bc421551SDag-Erling Smørgrav should be observed. 644bc421551SDag-Erling Smørgrav In her 2015 book 645bc421551SDag-Erling Smørgrav <cite><a 646ff2c98b3SDag-Erling Smørgrav href="https://www.hup.harvard.edu/books/9780674286146">The 647ff2c98b3SDag-Erling Smørgrav Global Transformation of Time, 1870–1950</a></cite>, 648bc421551SDag-Erling Smørgrav Vanessa Ogle writes 649ff2c98b3SDag-Erling Smørgrav “Outside of Europe and North America there was no system of time 650bc421551SDag-Erling Smørgrav zones at all, often not even a stable landscape of mean times, 651ff2c98b3SDag-Erling Smørgrav prior to the middle decades of the twentieth century”. 652bc421551SDag-Erling Smørgrav See: Timothy Shenk, <a 65328f617deSDag-Erling Smørgravhref="https://dissentmagazine.org/online_articles/booked-a-global-history-of-time-vanessa-ogle/">Booked: 654bc421551SDag-Erling Smørgrav A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. 655bc421551SDag-Erling Smørgrav </li> 656bc421551SDag-Erling Smørgrav <li> 657bc421551SDag-Erling Smørgrav Most of the pre-1970 data entries come from unreliable sources, often 658bc421551SDag-Erling Smørgrav astrology books that lack citations and whose compilers evidently 659bc421551SDag-Erling Smørgrav invented entries when the true facts were unknown, without 660bc421551SDag-Erling Smørgrav reporting which entries were known and which were invented. 661bc421551SDag-Erling Smørgrav These books often contradict each other or give implausible entries, 662bc421551SDag-Erling Smørgrav and on the rare occasions when they are checked they are 663bc421551SDag-Erling Smørgrav typically found to be incorrect. 664bc421551SDag-Erling Smørgrav </li> 665bc421551SDag-Erling Smørgrav <li> 666bc421551SDag-Erling Smørgrav For the UK the <code><abbr>tz</abbr></code> database relies on 667bc421551SDag-Erling Smørgrav years of first-class work done by 668bc421551SDag-Erling Smørgrav Joseph Myers and others; see 669ff2c98b3SDag-Erling Smørgrav “<a href="https://www.polyomino.org.uk/british-time/">History of 670ff2c98b3SDag-Erling Smørgrav legal time in Britain</a>”. 671bc421551SDag-Erling Smørgrav Other countries are not done nearly as well. 672bc421551SDag-Erling Smørgrav </li> 673bc421551SDag-Erling Smørgrav <li> 674bc421551SDag-Erling Smørgrav Sometimes, different people in the same city maintain clocks 675bc421551SDag-Erling Smørgrav that differ significantly. 676bc421551SDag-Erling Smørgrav Historically, railway time was used by railroad companies (which 677bc421551SDag-Erling Smørgrav did not always 678bc421551SDag-Erling Smørgrav agree with each other), church-clock time was used for birth 679bc421551SDag-Erling Smørgrav certificates, etc. 680bc421551SDag-Erling Smørgrav More recently, competing political groups might disagree about 681bc421551SDag-Erling Smørgrav clock settings. Often this is merely common practice, but 682bc421551SDag-Erling Smørgrav sometimes it is set by law. 683bc421551SDag-Erling Smørgrav For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France 684bc421551SDag-Erling Smørgrav was legally <abbr>UT</abbr> +00:09:21 outside train stations and 685bc421551SDag-Erling Smørgrav <abbr>UT</abbr> +00:04:21 inside. Other examples include 686bc421551SDag-Erling Smørgrav Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and 687bc421551SDag-Erling Smørgrav Ürümqi to this day. 688bc421551SDag-Erling Smørgrav </li> 689bc421551SDag-Erling Smørgrav <li> 690bc421551SDag-Erling Smørgrav Although a named location in the <code><abbr>tz</abbr></code> 691bc421551SDag-Erling Smørgrav database stands for the containing region, its pre-1970 data 692bc421551SDag-Erling Smørgrav entries are often accurate for only a small subset of that region. 693bc421551SDag-Erling Smørgrav For example, <code>Europe/London</code> stands for the United 694bc421551SDag-Erling Smørgrav Kingdom, but its pre-1847 times are valid only for locations that 695ff2c98b3SDag-Erling Smørgrav have London’s exact meridian, and its 1847 transition 696bc421551SDag-Erling Smørgrav to <abbr>GMT</abbr> is known to be valid only for the L&NW and 697bc421551SDag-Erling Smørgrav the Caledonian railways. 698bc421551SDag-Erling Smørgrav </li> 699bc421551SDag-Erling Smørgrav <li> 700bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> database does not record the 701ff2c98b3SDag-Erling Smørgrav earliest time for which a timezone’s 702bc421551SDag-Erling Smørgrav data entries are thereafter valid for every location in the region. 703bc421551SDag-Erling Smørgrav For example, <code>Europe/London</code> is valid for all locations 704bc421551SDag-Erling Smørgrav in its region after <abbr>GMT</abbr> was made the standard time, 705bc421551SDag-Erling Smørgrav but the date of standardization (1880-08-02) is not in the 706bc421551SDag-Erling Smørgrav <code><abbr>tz</abbr></code> database, other than in commentary. 707bc421551SDag-Erling Smørgrav For many timezones the earliest time of 708bc421551SDag-Erling Smørgrav validity is unknown. 709bc421551SDag-Erling Smørgrav </li> 710bc421551SDag-Erling Smørgrav <li> 711bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> database does not record a 712ff2c98b3SDag-Erling Smørgrav region’s boundaries, and in many cases the boundaries are not known. 713bc421551SDag-Erling Smørgrav For example, the timezone 714bc421551SDag-Erling Smørgrav <code>America/Kentucky/Louisville</code> represents a region 715bc421551SDag-Erling Smørgrav around the city of Louisville, the boundaries of which are 716bc421551SDag-Erling Smørgrav unclear. 717bc421551SDag-Erling Smørgrav </li> 718bc421551SDag-Erling Smørgrav <li> 719bc421551SDag-Erling Smørgrav Changes that are modeled as instantaneous transitions in the 720bc421551SDag-Erling Smørgrav <code><abbr>tz</abbr></code> 721bc421551SDag-Erling Smørgrav database were often spread out over hours, days, or even decades. 722bc421551SDag-Erling Smørgrav </li> 723bc421551SDag-Erling Smørgrav <li> 724bc421551SDag-Erling Smørgrav Even if the time is specified by law, locations sometimes 725bc421551SDag-Erling Smørgrav deliberately flout the law. 726bc421551SDag-Erling Smørgrav </li> 727bc421551SDag-Erling Smørgrav <li> 728bc421551SDag-Erling Smørgrav Early timekeeping practices, even assuming perfect clocks, were 729bc421551SDag-Erling Smørgrav often not specified to the accuracy that the 730bc421551SDag-Erling Smørgrav <code><abbr>tz</abbr></code> database requires. 731bc421551SDag-Erling Smørgrav </li> 732bc421551SDag-Erling Smørgrav <li> 733bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> database cannot represent stopped clocks. 734bc421551SDag-Erling Smørgrav However, on 1911-03-11 at 00:00, some public-facing French clocks 735bc421551SDag-Erling Smørgrav were changed by stopping them for a few minutes to effect a transition. 736bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> database models this via a 737bc421551SDag-Erling Smørgrav backward transition; the relevant French legislation does not 738bc421551SDag-Erling Smørgrav specify exactly how the transition was to occur. 739bc421551SDag-Erling Smørgrav </li> 740bc421551SDag-Erling Smørgrav <li> 741bc421551SDag-Erling Smørgrav Sometimes historical timekeeping was specified more precisely 742bc421551SDag-Erling Smørgrav than what the <code><abbr>tz</abbr></code> code can handle. 743bc421551SDag-Erling Smørgrav For example, from 1880 to 1916 clocks in Ireland observed Dublin Mean 744bc421551SDag-Erling Smørgrav Time (estimated to be <abbr>UT</abbr> 745ff2c98b3SDag-Erling Smørgrav −00:25:21.1); although the <code><abbr>tz</abbr></code> 746bc421551SDag-Erling Smørgrav source data can represent the .1 second, TZif files and the code cannot. 747bc421551SDag-Erling Smørgrav In practice these old specifications were rarely if ever 748bc421551SDag-Erling Smørgrav implemented to subsecond precision. 749bc421551SDag-Erling Smørgrav </li> 750bc421551SDag-Erling Smørgrav <li> 751bc421551SDag-Erling Smørgrav Even when all the timestamp transitions recorded by the 752bc421551SDag-Erling Smørgrav <code><abbr>tz</abbr></code> database are correct, the 753bc421551SDag-Erling Smørgrav <code><abbr>tz</abbr></code> rules that generate them may not 754bc421551SDag-Erling Smørgrav faithfully reflect the historical rules. 755bc421551SDag-Erling Smørgrav For example, from 1922 until World War II the UK moved clocks 756bc421551SDag-Erling Smørgrav forward the day following the third Saturday in April unless that 757bc421551SDag-Erling Smørgrav was Easter, in which case it moved clocks forward the previous 758bc421551SDag-Erling Smørgrav Sunday. 759bc421551SDag-Erling Smørgrav Because the <code><abbr>tz</abbr></code> database has no 760bc421551SDag-Erling Smørgrav way to specify Easter, these exceptional years are entered as 761bc421551SDag-Erling Smørgrav separate <code><abbr>tz</abbr> Rule</code> lines, even though the 762bc421551SDag-Erling Smørgrav legal rules did not change. 763bc421551SDag-Erling Smørgrav When transitions are known but the historical rules behind them are not, 764bc421551SDag-Erling Smørgrav the database contains <code>Zone</code> and <code>Rule</code> 765bc421551SDag-Erling Smørgrav entries that are intended to represent only the generated 766bc421551SDag-Erling Smørgrav transitions, not any underlying historical rules; however, this 767bc421551SDag-Erling Smørgrav intent is recorded at best only in commentary. 768bc421551SDag-Erling Smørgrav </li> 769bc421551SDag-Erling Smørgrav <li> 770bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> database models time 771bc421551SDag-Erling Smørgrav using the <a 772bc421551SDag-Erling Smørgrav href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic 773bc421551SDag-Erling Smørgrav Gregorian calendar</a> with days containing 24 equal-length hours 774bc421551SDag-Erling Smørgrav numbered 00 through 23, except when clock transitions occur. 775bc421551SDag-Erling Smørgrav Pre-standard time is modeled as local mean time. 776bc421551SDag-Erling Smørgrav However, historically many people used other calendars and other timescales. 777bc421551SDag-Erling Smørgrav For example, the Roman Empire used 778bc421551SDag-Erling Smørgrav the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian 779bc421551SDag-Erling Smørgrav calendar</a>, 780bc421551SDag-Erling Smørgrav and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman 781bc421551SDag-Erling Smørgrav timekeeping</a> had twelve varying-length daytime hours with a 782bc421551SDag-Erling Smørgrav non-hour-based system at night. 783bc421551SDag-Erling Smørgrav And even today, some local practices diverge from the Gregorian 784bc421551SDag-Erling Smørgrav calendar with 24-hour days. These divergences range from 785ff2c98b3SDag-Erling Smørgrav relatively minor, such as Japanese bars giving times like 24:30 for the 786bc421551SDag-Erling Smørgrav wee hours of the morning, to more-significant differences such as <a 787ff2c98b3SDag-Erling Smørgrav href="https://theworld.org/stories/2015/01/30/ethiopian-time">the 788bc421551SDag-Erling Smørgrav east African practice of starting the day at dawn</a>, renumbering 789bc421551SDag-Erling Smørgrav the Western 06:00 to be 12:00. These practices are largely outside 790bc421551SDag-Erling Smørgrav the scope of the <code><abbr>tz</abbr></code> code and data, which 791bc421551SDag-Erling Smørgrav provide only limited support for date and time localization 792a979394aSDag-Erling Smørgrav such as that required by POSIX. 793bc421551SDag-Erling Smørgrav If <abbr>DST</abbr> is not used a different time zone 794bc421551SDag-Erling Smørgrav can often do the trick; for example, in Kenya a <code>TZ</code> setting 795bc421551SDag-Erling Smørgrav like <code><-03>3</code> or <code>America/Cayenne</code> starts 796bc421551SDag-Erling Smørgrav the day six hours later than <code>Africa/Nairobi</code> does. 797bc421551SDag-Erling Smørgrav </li> 798bc421551SDag-Erling Smørgrav <li> 799bc421551SDag-Erling Smørgrav Early clocks were less reliable, and data entries do not represent 800bc421551SDag-Erling Smørgrav clock error. 801bc421551SDag-Erling Smørgrav </li> 802bc421551SDag-Erling Smørgrav <li> 803bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> database assumes Universal Time 804bc421551SDag-Erling Smørgrav (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not 805bc421551SDag-Erling Smørgrav standardized for older timestamps. 806bc421551SDag-Erling Smørgrav In the <code><abbr>tz</abbr></code> database commentary, 807bc421551SDag-Erling Smørgrav <abbr>UT</abbr> denotes a family of time standards that includes 808bc421551SDag-Erling Smørgrav Coordinated Universal Time (<abbr>UTC</abbr>) along with other 809bc421551SDag-Erling Smørgrav variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>, 810bc421551SDag-Erling Smørgrav with days starting at midnight. 811bc421551SDag-Erling Smørgrav Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern 812bc421551SDag-Erling Smørgrav timestamps, <abbr>UTC</abbr> was not defined until 1960, so 81375411d15SDag-Erling Smørgrav commentary uses the more general abbreviation <abbr>UT</abbr> for 814bc421551SDag-Erling Smørgrav timestamps that might predate 1960. 815bc421551SDag-Erling Smørgrav Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly, 816bc421551SDag-Erling Smørgrav and since pre-1972 <abbr>UTC</abbr> seconds varied in length, 817bc421551SDag-Erling Smørgrav interpretation of older timestamps can be problematic when 818bc421551SDag-Erling Smørgrav subsecond accuracy is needed. 819bc421551SDag-Erling Smørgrav </li> 820bc421551SDag-Erling Smørgrav <li> 821bc421551SDag-Erling Smørgrav Civil time was not based on atomic time before 1972, and we do not 822bc421551SDag-Erling Smørgrav know the history of 823ff2c98b3SDag-Erling Smørgrav <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth’s 824bc421551SDag-Erling Smørgrav rotation</a> accurately enough to map <a 825bc421551SDag-Erling Smørgrav href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr 826bc421551SDag-Erling Smørgrav title="International System of Units">SI</abbr></a> seconds to 827bc421551SDag-Erling Smørgrav historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a> 828bc421551SDag-Erling Smørgrav to more than about one-hour accuracy. 829ff2c98b3SDag-Erling Smørgrav See: Morrison LV, Stephenson FR, Hohenkerk CY, Zawilski M. 830ff2c98b3SDag-Erling Smørgrav <a href="https://doi.org/10.1098/rspa.2020.0776">Addendum 2020 831ff2c98b3SDag-Erling Smørgrav to ‘Measurement of the Earth’s rotation: 720 BC to AD 2015’</a>. 832ff2c98b3SDag-Erling Smørgrav <cite>Proc Royal Soc A</cite>. 2021;477:20200776. 833bc421551SDag-Erling Smørgrav Also see: Espenak F. <a 834bc421551SDag-Erling Smørgrav href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty 835bc421551SDag-Erling Smørgrav in Delta T (ΔT)</a>. 836bc421551SDag-Erling Smørgrav </li> 837bc421551SDag-Erling Smørgrav <li> 838bc421551SDag-Erling Smørgrav The relationship between POSIX time (that is, <abbr>UTC</abbr> but 839bc421551SDag-Erling Smørgrav ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap 84075411d15SDag-Erling Smørgrav seconds</a>) and <abbr>UTC</abbr> is not agreed upon. 841ff2c98b3SDag-Erling Smørgrav This affects time stamps during the leap second era (1972–2035). 842bc421551SDag-Erling Smørgrav Although the POSIX 843bc421551SDag-Erling Smørgrav clock officially stops during an inserted leap second, at least one 844bc421551SDag-Erling Smørgrav proposed standard has it jumping back a second instead; and in 845bc421551SDag-Erling Smørgrav practice POSIX clocks more typically either progress glacially during 846bc421551SDag-Erling Smørgrav a leap second, or are slightly slowed while near a leap second. 847bc421551SDag-Erling Smørgrav </li> 848bc421551SDag-Erling Smørgrav <li> 849bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> database does not represent how 850bc421551SDag-Erling Smørgrav uncertain its information is. 851bc421551SDag-Erling Smørgrav Ideally it would contain information about when data entries are 852bc421551SDag-Erling Smørgrav incomplete or dicey. 853bc421551SDag-Erling Smørgrav Partial temporal knowledge is a field of active research, though, 854bc421551SDag-Erling Smørgrav and it is not clear how to apply it here. 855bc421551SDag-Erling Smørgrav </li> 856bc421551SDag-Erling Smørgrav</ul> 857bc421551SDag-Erling Smørgrav 858bc421551SDag-Erling Smørgrav<p> 859bc421551SDag-Erling SmørgravIn short, many, perhaps most, of the <code><abbr>tz</abbr></code> 860ff2c98b3SDag-Erling Smørgravdatabase’s pre-1970 and future timestamps are either wrong or 861bc421551SDag-Erling Smørgravmisleading. 862bc421551SDag-Erling SmørgravAny attempt to pass the 863bc421551SDag-Erling Smørgrav<code><abbr>tz</abbr></code> database off as the definition of time 864bc421551SDag-Erling Smørgravshould be unacceptable to anybody who cares about the facts. 865ff2c98b3SDag-Erling SmørgravIn particular, the <code><abbr>tz</abbr></code> database’s 866bc421551SDag-Erling Smørgrav<abbr>LMT</abbr> offsets should not be considered meaningful, and 867bc421551SDag-Erling Smørgravshould not prompt creation of timezones 868bc421551SDag-Erling Smørgravmerely because two locations 869bc421551SDag-Erling Smørgravdiffer in <abbr>LMT</abbr> or transitioned to standard time at 870bc421551SDag-Erling Smørgravdifferent dates. 871bc421551SDag-Erling Smørgrav</p> 872bc421551SDag-Erling Smørgrav 873bc421551SDag-Erling Smørgrav <h2 id="functions">Time and date functions</h2> 874bc421551SDag-Erling Smørgrav<p> 875bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> code contains time and date functions 876bc421551SDag-Erling Smørgravthat are upwards compatible with those of POSIX. 877bc421551SDag-Erling SmørgravCode compatible with this package is already 878bc421551SDag-Erling Smørgrav<a href="tz-link.html#tzdb">part of many platforms</a>, where the 879bc421551SDag-Erling Smørgravprimary use of this package is to update obsolete time-related files. 880bc421551SDag-Erling SmørgravTo do this, you may need to compile the time zone compiler 881a979394aSDag-Erling Smørgrav<code>zic</code> supplied with this package instead of using the 882ff2c98b3SDag-Erling Smørgravsystem <code>zic</code>, since the format of <code>zic</code>’s 883bc421551SDag-Erling Smørgravinput is occasionally extended, and a platform may still be shipping 884bc421551SDag-Erling Smørgravan older <code>zic</code>. 885bc421551SDag-Erling Smørgrav</p> 886bc421551SDag-Erling Smørgrav 887a979394aSDag-Erling Smørgrav<p> 888a979394aSDag-Erling SmørgravIn POSIX, time display in a process is controlled by the 889a979394aSDag-Erling Smørgravenvironment variable <code>TZ</code>, which can have two forms: 890a979394aSDag-Erling Smørgrav</p> 891bc421551SDag-Erling Smørgrav<ul> 892bc421551SDag-Erling Smørgrav <li> 893a979394aSDag-Erling Smørgrav A <dfn>proleptic <code>TZ</code></dfn> value 894a979394aSDag-Erling Smørgrav like <code>CET-1CEST,M3.5.0,M10.5.0/3</code> uses a complex 895a979394aSDag-Erling Smørgrav notation that specifies a single standard time along with daylight 896a979394aSDag-Erling Smørgrav saving rules that apply to all years past, present, and future. 897a979394aSDag-Erling Smørgrav </li> 898a979394aSDag-Erling Smørgrav <li> 899a979394aSDag-Erling Smørgrav A <dfn>geographical <code>TZ</code></dfn> value 900a979394aSDag-Erling Smørgrav like <code>Europe/Berlin</code> names a location that stands for 901a979394aSDag-Erling Smørgrav civil time near that location, which can have more than 902a979394aSDag-Erling Smørgrav one standard time and more than one set of daylight saving rules, 903a979394aSDag-Erling Smørgrav to record timekeeping practice more accurately. 904a979394aSDag-Erling Smørgrav These names are defined by the <code><abbr>tz</abbr></code> database. 905a979394aSDag-Erling Smørgrav </li> 906a979394aSDag-Erling Smørgrav</ul> 907a979394aSDag-Erling Smørgrav 908a979394aSDag-Erling Smørgrav<h3 id="POSIX.1-2017">POSIX.1-2017 properties and limitations</h3> 909bc421551SDag-Erling Smørgrav<p> 910ff2c98b3SDag-Erling SmørgravSome platforms support only the features required by POSIX.1-2017 911ff2c98b3SDag-Erling Smørgravand earlier editions, 912a979394aSDag-Erling Smørgravand have not yet upgraded to POSIX.1-2024. 913a979394aSDag-Erling SmørgravCode intended to be portable to these platforms must deal 914a979394aSDag-Erling Smørgravwith problems that were fixed in later POSIX editions. 915a979394aSDag-Erling Smørgrav</p> 916a979394aSDag-Erling Smørgrav 917a979394aSDag-Erling Smørgrav<ul> 918a979394aSDag-Erling Smørgrav <li> 919a979394aSDag-Erling Smørgrav POSIX.1-2017 does not require support for geographical <code>TZ</code>, 920a979394aSDag-Erling Smørgrav and there is no convenient and efficient way to determine 921a979394aSDag-Erling Smørgrav the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary 922a979394aSDag-Erling Smørgrav timestamps, particularly for timezones 923a979394aSDag-Erling Smørgrav that do not fit into the POSIX model. 924a979394aSDag-Erling Smørgrav </li> 925a979394aSDag-Erling Smørgrav <li> 926a979394aSDag-Erling Smørgrav <p> 927a979394aSDag-Erling Smørgrav The proleptic <code>TZ</code> string, 928a979394aSDag-Erling Smørgrav which is all that POSIX.1-2017 requires, 929a979394aSDag-Erling Smørgrav has a format that is hard to describe and is error-prone in practice. 930a979394aSDag-Erling Smørgrav Also, proleptic <code>TZ</code> strings cannot deal with daylight 931bc421551SDag-Erling Smørgrav saving time rules not based on the Gregorian calendar (as in 93228f617deSDag-Erling Smørgrav Palestine), or with situations where more than two time zone 933bc421551SDag-Erling Smørgrav abbreviations or <abbr>UT</abbr> offsets are used in an area. 934bc421551SDag-Erling Smørgrav </p> 935bc421551SDag-Erling Smørgrav 936bc421551SDag-Erling Smørgrav <p> 937a979394aSDag-Erling Smørgrav A proleptic <code>TZ</code> string has the following format: 938bc421551SDag-Erling Smørgrav </p> 939bc421551SDag-Erling Smørgrav 940bc421551SDag-Erling Smørgrav <p> 941bc421551SDag-Erling Smørgrav <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>]]] 942bc421551SDag-Erling Smørgrav </p> 943bc421551SDag-Erling Smørgrav 944bc421551SDag-Erling Smørgrav <p> 945bc421551SDag-Erling Smørgrav where: 946bc421551SDag-Erling Smørgrav </p> 947bc421551SDag-Erling Smørgrav 948bc421551SDag-Erling Smørgrav <dl> 949bc421551SDag-Erling Smørgrav <dt><var>std</var> and <var>dst</var></dt><dd> 950bc421551SDag-Erling Smørgrav are 3 or more characters specifying the standard 951bc421551SDag-Erling Smørgrav and daylight saving time (<abbr>DST</abbr>) zone abbreviations. 952bc421551SDag-Erling Smørgrav Starting with POSIX.1-2001, <var>std</var> and <var>dst</var> 953ff2c98b3SDag-Erling Smørgrav may also be quoted in angle brackets, like <code><+09></code>; 954bc421551SDag-Erling Smørgrav this allows "<code>+</code>" and "<code>-</code>" in the names. 955bc421551SDag-Erling Smørgrav </dd> 956bc421551SDag-Erling Smørgrav <dt><var>offset</var></dt><dd> 957bc421551SDag-Erling Smørgrav is of the form 958ff2c98b3SDag-Erling Smørgrav <code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code> 959bc421551SDag-Erling Smørgrav and specifies the offset west of <abbr>UT</abbr>. 960ff2c98b3SDag-Erling Smørgrav <var>hh</var> may be a single digit; 961bc421551SDag-Erling Smørgrav 0≤<var>hh</var>≤24. 962bc421551SDag-Erling Smørgrav The default <abbr>DST</abbr> offset is one hour ahead of 963bc421551SDag-Erling Smørgrav standard time. 964bc421551SDag-Erling Smørgrav </dd> 965bc421551SDag-Erling Smørgrav <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> 966bc421551SDag-Erling Smørgrav specifies the beginning and end of <abbr>DST</abbr>. 967bc421551SDag-Erling Smørgrav If this is absent, the system supplies its own ruleset 96875411d15SDag-Erling Smørgrav for <abbr>DST</abbr>, typically current <abbr>US</abbr> 96975411d15SDag-Erling Smørgrav <abbr>DST</abbr> rules. 970bc421551SDag-Erling Smørgrav </dd> 971bc421551SDag-Erling Smørgrav <dt><var>time</var></dt><dd> 972bc421551SDag-Erling Smørgrav takes the form 973ff2c98b3SDag-Erling Smørgrav <var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]] 974bc421551SDag-Erling Smørgrav and defaults to 02:00. 975bc421551SDag-Erling Smørgrav This is the same format as the offset, except that a 976ff2c98b3SDag-Erling Smørgrav leading "<code>+</code>" or "<code>-</code>" is not allowed. 977bc421551SDag-Erling Smørgrav </dd> 978bc421551SDag-Erling Smørgrav <dt><var>date</var></dt><dd> 979bc421551SDag-Erling Smørgrav takes one of the following forms: 980bc421551SDag-Erling Smørgrav <dl> 981bc421551SDag-Erling Smørgrav <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> 982bc421551SDag-Erling Smørgrav origin-1 day number not counting February 29 983bc421551SDag-Erling Smørgrav </dd> 984bc421551SDag-Erling Smørgrav <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> 985bc421551SDag-Erling Smørgrav origin-0 day number counting February 29 if present 986bc421551SDag-Erling Smørgrav </dd> 987bc421551SDag-Erling Smørgrav <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> 988bc421551SDag-Erling Smørgrav (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, 989bc421551SDag-Erling Smørgrav 1≤<var>m</var>≤12)</dt><dd> 990bc421551SDag-Erling Smørgrav for the <var>d</var>th day of week <var>n</var> of 991bc421551SDag-Erling Smørgrav month <var>m</var> of the year, where week 1 is the first 992bc421551SDag-Erling Smørgrav week in which day <var>d</var> appears, and 993ff2c98b3SDag-Erling Smørgrav "<code>5</code>" stands for the last week in which 994bc421551SDag-Erling Smørgrav day <var>d</var> appears (which may be either the 4th or 995bc421551SDag-Erling Smørgrav 5th week). 996bc421551SDag-Erling Smørgrav Typically, this is the only useful form; the <var>n</var> 997bc421551SDag-Erling Smørgrav and <code>J</code><var>n</var> forms are rarely used. 998bc421551SDag-Erling Smørgrav </dd> 999bc421551SDag-Erling Smørgrav </dl> 1000bc421551SDag-Erling Smørgrav </dd> 1001bc421551SDag-Erling Smørgrav </dl> 1002bc421551SDag-Erling Smørgrav 1003bc421551SDag-Erling Smørgrav <p> 1004a979394aSDag-Erling Smørgrav Here is an example proleptic <code>TZ</code> string for New 1005bc421551SDag-Erling Smørgrav Zealand after 2007. 1006bc421551SDag-Erling Smørgrav It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead 1007bc421551SDag-Erling Smørgrav of <abbr>UT</abbr>, and that daylight saving time 1008ff2c98b3SDag-Erling Smørgrav (<abbr>NZDT</abbr>) is observed from September’s last Sunday at 1009ff2c98b3SDag-Erling Smørgrav 02:00 until April’s first Sunday at 03:00: 1010bc421551SDag-Erling Smørgrav </p> 1011bc421551SDag-Erling Smørgrav 1012bc421551SDag-Erling Smørgrav <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> 1013bc421551SDag-Erling Smørgrav 1014bc421551SDag-Erling Smørgrav <p> 1015a979394aSDag-Erling Smørgrav This proleptic <code>TZ</code> string is hard to remember, and 1016bc421551SDag-Erling Smørgrav mishandles some timestamps before 2008. 1017a979394aSDag-Erling Smørgrav With this package you can use a geographical <code>TZ</code> instead: 1018bc421551SDag-Erling Smørgrav </p> 1019bc421551SDag-Erling Smørgrav 1020bc421551SDag-Erling Smørgrav <pre><code>TZ='Pacific/Auckland'</code></pre> 1021bc421551SDag-Erling Smørgrav </li> 1022a979394aSDag-Erling Smørgrav</ul> 1023a979394aSDag-Erling Smørgrav 1024a979394aSDag-Erling Smørgrav<p> 1025a979394aSDag-Erling SmørgravPOSIX.1-2017 also has the limitations of POSIX.1-2024, 1026a979394aSDag-Erling Smørgravdiscussed in the next section. 1027a979394aSDag-Erling Smørgrav</p> 1028a979394aSDag-Erling Smørgrav 1029a979394aSDag-Erling Smørgrav<h3 id="POSIX.1-2024">POSIX.1-2024 properties and limitations</h3> 1030a979394aSDag-Erling Smørgrav<p> 1031a979394aSDag-Erling SmørgravPOSIX.1-2024 extends POSIX.1-2017 in the following significant ways: 1032a979394aSDag-Erling Smørgrav</p> 1033a979394aSDag-Erling Smørgrav<ul> 1034bc421551SDag-Erling Smørgrav <li> 1035a979394aSDag-Erling Smørgrav POSIX.1-2024 requires support for geographical <code>TZ</code>. 1036a979394aSDag-Erling Smørgrav Earlier POSIX editions require support only for proleptic <code>TZ</code>. 1037bc421551SDag-Erling Smørgrav </li> 1038bc421551SDag-Erling Smørgrav <li> 1039a979394aSDag-Erling Smørgrav POSIX.1-2024 requires <code>struct tm</code> 1040a979394aSDag-Erling Smørgrav to have a <abbr>UT</abbr> offset member <code>tm_gmtoff</code> 1041a979394aSDag-Erling Smørgrav and a time zone abbreviation member <code>tm_zone</code>. 1042a979394aSDag-Erling Smørgrav Earlier POSIX editions lack this requirement. 1043a979394aSDag-Erling Smørgrav </li> 1044a979394aSDag-Erling Smørgrav <li> 1045ff2c98b3SDag-Erling Smørgrav DST transition times can range from −167:59:59 1046a979394aSDag-Erling Smørgrav to 167:59:59 instead of merely from 00:00:00 to 24:59:59. 1047a979394aSDag-Erling Smørgrav This allows for proleptic TZ strings 1048a979394aSDag-Erling Smørgrav like <code>"<-02>2<-01>,M3.5.0/-1,M10.5.0/0"</code> 1049ff2c98b3SDag-Erling Smørgrav where the transition time −1:00 means 23:00 the previous day. 1050a979394aSDag-Erling Smørgrav </li> 1051a979394aSDag-Erling Smørgrav</ul> 1052a979394aSDag-Erling Smørgrav<p> 1053a979394aSDag-Erling SmørgravHowever POSIX.1-2024, like earlier POSIX editions, has some limitations: 1054a979394aSDag-Erling Smørgrav<ul> 1055a979394aSDag-Erling Smørgrav <li> 1056bc421551SDag-Erling Smørgrav The <code>TZ</code> environment variable is process-global, which 1057bc421551SDag-Erling Smørgrav makes it hard to write efficient, thread-safe applications that 1058bc421551SDag-Erling Smørgrav need access to multiple timezones. 1059bc421551SDag-Erling Smørgrav </li> 1060bc421551SDag-Erling Smørgrav <li> 1061bc421551SDag-Erling Smørgrav In POSIX, there is no tamper-proof way for a process to learn the 1062ff2c98b3SDag-Erling Smørgrav system’s best idea of local (wall clock) time. 1063bc421551SDag-Erling Smørgrav This is important for applications that an administrator wants 1064ff2c98b3SDag-Erling Smørgrav used only at certain times – without regard to whether the 1065bc421551SDag-Erling Smørgrav user has fiddled the 1066bc421551SDag-Erling Smørgrav <code>TZ</code> environment variable. 1067ff2c98b3SDag-Erling Smørgrav While an administrator can “do everything in <abbr>UT</abbr>” to 1068bc421551SDag-Erling Smørgrav get around the problem, doing so is inconvenient and precludes 1069ff2c98b3SDag-Erling Smørgrav handling daylight saving time shifts – as might be required to 1070bc421551SDag-Erling Smørgrav limit phone calls to off-peak hours. 1071bc421551SDag-Erling Smørgrav </li> 1072bc421551SDag-Erling Smørgrav <li> 1073bc421551SDag-Erling Smørgrav POSIX requires that <code>time_t</code> clock counts exclude leap 1074bc421551SDag-Erling Smørgrav seconds. 1075bc421551SDag-Erling Smørgrav </li> 1076bc421551SDag-Erling Smørgrav <li> 1077a979394aSDag-Erling Smørgrav POSIX does not define the <abbr>DST</abbr> transitions 1078ff2c98b3SDag-Erling Smørgrav for settings like <code>TZ='EST5EDT'</code>. 1079a979394aSDag-Erling Smørgrav Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules 1080a979394aSDag-Erling Smørgrav were used to interpret such values, but this meant that the 1081a979394aSDag-Erling Smørgrav <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each 1082a979394aSDag-Erling Smørgrav time conversion package, and when 1083a979394aSDag-Erling Smørgrav <abbr>US</abbr> time conversion rules changed (as in the United 1084a979394aSDag-Erling Smørgrav States in 1987 and again in 2007), all packages that 1085a979394aSDag-Erling Smørgrav interpreted <code>TZ</code> values had to be updated 1086a979394aSDag-Erling Smørgrav to ensure proper results. 1087a979394aSDag-Erling Smørgrav </li> 1088a979394aSDag-Erling Smørgrav</ul> 1089a979394aSDag-Erling Smørgrav 1090a979394aSDag-Erling Smørgrav<h3 id="POSIX-extensions">Extensions to POSIX in the 1091a979394aSDag-Erling Smørgrav<code><abbr>tz</abbr></code> code</h3> 1092a979394aSDag-Erling Smørgrav<p> 1093a979394aSDag-Erling Smørgrav The <code><abbr>tz</abbr></code> code defines some properties 1094a979394aSDag-Erling Smørgrav left unspecified by POSIX, and attempts to support some 1095a979394aSDag-Erling Smørgrav extensions to POSIX. 1096a979394aSDag-Erling Smørgrav</p> 1097a979394aSDag-Erling Smørgrav 1098a979394aSDag-Erling Smørgrav<ul> 1099a979394aSDag-Erling Smørgrav <li> 1100bc421551SDag-Erling Smørgrav The <code><abbr>tz</abbr></code> code attempts to support all the 1101bc421551SDag-Erling Smørgrav <code>time_t</code> implementations allowed by POSIX. 1102bc421551SDag-Erling Smørgrav The <code>time_t</code> type represents a nonnegative count of seconds 1103bc421551SDag-Erling Smørgrav since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds. 1104bc421551SDag-Erling Smørgrav In practice, <code>time_t</code> is usually a signed 64- or 32-bit 1105bc421551SDag-Erling Smørgrav integer; 32-bit signed <code>time_t</code> values stop working after 1106bc421551SDag-Erling Smørgrav 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these 1107bc421551SDag-Erling Smørgrav days typically use a signed 64-bit integer. 1108bc421551SDag-Erling Smørgrav Unsigned 32-bit integers are used on one or two platforms, and 36-bit 1109bc421551SDag-Erling Smørgrav and 40-bit integers are also used occasionally. 1110bc421551SDag-Erling Smørgrav Although earlier POSIX versions allowed <code>time_t</code> to be a 1111bc421551SDag-Erling Smørgrav floating-point type, this was not supported by any practical system, 1112a979394aSDag-Erling Smørgrav and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both 1113bc421551SDag-Erling Smørgrav require <code>time_t</code> to be an integer type. 1114bc421551SDag-Erling Smørgrav </li> 1115bc421551SDag-Erling Smørgrav <li> 1116bc421551SDag-Erling Smørgrav <p> 1117a979394aSDag-Erling Smørgrav If the <code>TZ</code> environment variable uses the geographical format, 1118a979394aSDag-Erling Smørgrav it is used in generating 1119a979394aSDag-Erling Smørgrav the name of a file from which time-related information is read. 1120ff2c98b3SDag-Erling Smørgrav The file’s format is <dfn><abbr>TZif</abbr></dfn>, 1121bc421551SDag-Erling Smørgrav a timezone information format that contains binary data; see 112228f617deSDag-Erling Smørgrav <a href="https://www.rfc-editor.org/info/rfc9636/">Internet 1123967a49a2SDag-Erling Smørgrav <abbr>RFC</abbr> 9636</a>. 1124bc421551SDag-Erling Smørgrav The daylight saving time rules to be used for a 1125bc421551SDag-Erling Smørgrav particular timezone are encoded in the 1126bc421551SDag-Erling Smørgrav <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>, 1127bc421551SDag-Erling Smørgrav Australian, and other rules to be encoded, and 1128bc421551SDag-Erling Smørgrav allows for situations where more than two time zone 1129bc421551SDag-Erling Smørgrav abbreviations are used. 1130bc421551SDag-Erling Smørgrav </p> 1131bc421551SDag-Erling Smørgrav <p> 1132a979394aSDag-Erling Smørgrav When the <code><abbr>tz</abbr></code> code was developed in the 1980s, 1133a979394aSDag-Erling Smørgrav it was recognized that allowing the <code>TZ</code> environment 1134ff2c98b3SDag-Erling Smørgrav variable to take on values such as <code>America/New_York</code> 1135ff2c98b3SDag-Erling Smørgrav might cause old programs (that expect <code>TZ</code> to have a 1136a979394aSDag-Erling Smørgrav certain format) to operate incorrectly; consideration was given to using 1137bc421551SDag-Erling Smørgrav some other environment variable (for example, <code>TIMEZONE</code>) 1138ff2c98b3SDag-Erling Smørgrav to hold the string used to generate the <abbr>TZif</abbr> file’s name. 1139bc421551SDag-Erling Smørgrav In the end, however, it was decided to continue using 1140bc421551SDag-Erling Smørgrav <code>TZ</code>: it is widely used for time zone purposes; 1141bc421551SDag-Erling Smørgrav separately maintaining both <code>TZ</code> 1142bc421551SDag-Erling Smørgrav and <code>TIMEZONE</code> seemed a nuisance; and systems where 1143ff2c98b3SDag-Erling Smørgrav new forms of <code>TZ</code> might cause problems can simply 1144ff2c98b3SDag-Erling Smørgrav use legacy settings such as <code>TZ='EST5EDT'</code> which 1145ff2c98b3SDag-Erling Smørgrav can be used by new programs as well as by old programs that 1146bc421551SDag-Erling Smørgrav assume pre-POSIX <code>TZ</code> values. 1147bc421551SDag-Erling Smørgrav </p> 1148bc421551SDag-Erling Smørgrav </li> 1149bc421551SDag-Erling Smørgrav <li> 1150bc421551SDag-Erling Smørgrav Functions <code>tzalloc</code>, <code>tzfree</code>, 1151bc421551SDag-Erling Smørgrav <code>localtime_rz</code>, and <code>mktime_z</code> for 1152bc421551SDag-Erling Smørgrav more-efficient thread-safe applications that need to use multiple 1153bc421551SDag-Erling Smørgrav timezones. 1154bc421551SDag-Erling Smørgrav The <code>tzalloc</code> and <code>tzfree</code> functions 1155bc421551SDag-Erling Smørgrav allocate and free objects of type <code>timezone_t</code>, 1156bc421551SDag-Erling Smørgrav and <code>localtime_rz</code> and <code>mktime_z</code> are 1157bc421551SDag-Erling Smørgrav like <code>localtime_r</code> and <code>mktime</code> with an 1158bc421551SDag-Erling Smørgrav extra <code>timezone_t</code> argument. 1159a979394aSDag-Erling Smørgrav The functions were inspired by <a href="https://netbsd.org">NetBSD</a>. 1160bc421551SDag-Erling Smørgrav </li> 1161bc421551SDag-Erling Smørgrav <li> 1162bc421551SDag-Erling Smørgrav Negative <code>time_t</code> values are supported, on systems 1163bc421551SDag-Erling Smørgrav where <code>time_t</code> is signed. 1164bc421551SDag-Erling Smørgrav </li> 1165bc421551SDag-Erling Smørgrav <li> 1166bc421551SDag-Erling Smørgrav These functions can account for leap seconds; 1167bc421551SDag-Erling Smørgrav see <a href="#leapsec">Leap seconds</a> below. 1168bc421551SDag-Erling Smørgrav </li> 1169bc421551SDag-Erling Smørgrav</ul> 1170bc421551SDag-Erling Smørgrav 1171bc421551SDag-Erling Smørgrav<h3 id="vestigial">POSIX features no longer needed</h3> 1172bc421551SDag-Erling Smørgrav<p> 1173bc421551SDag-Erling SmørgravPOSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a> 1174bc421551SDag-Erling Smørgravdefine some <a href="https://en.wikipedia.org/wiki/API"><abbr 1175bc421551SDag-Erling Smørgravtitle="application programming interface">API</abbr>s</a> that are vestigial: 1176bc421551SDag-Erling Smørgravthey are not needed, and are relics of a too-simple model that does 1177bc421551SDag-Erling Smørgravnot suffice to handle many real-world timestamps. 1178bc421551SDag-Erling SmørgravAlthough the <code><abbr>tz</abbr></code> code supports these 1179bc421551SDag-Erling Smørgravvestigial <abbr>API</abbr>s for backwards compatibility, they should 1180bc421551SDag-Erling Smørgravbe avoided in portable applications. 1181bc421551SDag-Erling SmørgravThe vestigial <abbr>API</abbr>s are: 1182bc421551SDag-Erling Smørgrav</p> 1183bc421551SDag-Erling Smørgrav<ul> 1184bc421551SDag-Erling Smørgrav <li> 1185bc421551SDag-Erling Smørgrav The POSIX <code>tzname</code> variable does not suffice and is no 1186bc421551SDag-Erling Smørgrav longer needed. 1187a979394aSDag-Erling Smørgrav It is planned to be removed in a future edition of POSIX. 1188ff2c98b3SDag-Erling Smørgrav To get a timestamp’s time zone abbreviation, consult 1189bc421551SDag-Erling Smørgrav the <code>tm_zone</code> member if available; otherwise, 1190ff2c98b3SDag-Erling Smørgrav use <code>strftime</code>’s <code>"%Z"</code> conversion 1191bc421551SDag-Erling Smørgrav specification. 1192bc421551SDag-Erling Smørgrav </li> 1193bc421551SDag-Erling Smørgrav <li> 1194bc421551SDag-Erling Smørgrav The POSIX <code>daylight</code> and <code>timezone</code> 1195bc421551SDag-Erling Smørgrav variables do not suffice and are no longer needed. 1196a979394aSDag-Erling Smørgrav They are planned to be removed in a future edition of POSIX. 1197ff2c98b3SDag-Erling Smørgrav To get a timestamp’s <abbr>UT</abbr> offset, consult 1198bc421551SDag-Erling Smørgrav the <code>tm_gmtoff</code> member if available; otherwise, 1199bc421551SDag-Erling Smørgrav subtract values returned by <code>localtime</code> 1200bc421551SDag-Erling Smørgrav and <code>gmtime</code> using the rules of the Gregorian calendar, 1201ff2c98b3SDag-Erling Smørgrav or use <code>strftime</code>’s <code>"%z"</code> conversion 1202bc421551SDag-Erling Smørgrav specification if a string like <code>"+0900"</code> suffices. 1203bc421551SDag-Erling Smørgrav </li> 1204bc421551SDag-Erling Smørgrav <li> 1205bc421551SDag-Erling Smørgrav The <code>tm_isdst</code> member is almost never needed and most of 120628f617deSDag-Erling Smørgrav its uses should be discouraged in favor of the 120728f617deSDag-Erling Smørgrav <abbr>API</abbr>s mentioned above. 1208967a49a2SDag-Erling Smørgrav It was intended as an index into the <code>tzname</code> variable, 1209967a49a2SDag-Erling Smørgrav but as mentioned previously that usage is obsolete. 1210bc421551SDag-Erling Smørgrav Although it can still be used in arguments to 1211bc421551SDag-Erling Smørgrav <code>mktime</code> to disambiguate timestamps near 1212bc421551SDag-Erling Smørgrav a <abbr>DST</abbr> transition when the clock jumps back on 1213bc421551SDag-Erling Smørgrav platforms lacking <code>tm_gmtoff</code>, this 1214967a49a2SDag-Erling Smørgrav disambiguation works only for proleptic <code>TZ</code> strings; 1215967a49a2SDag-Erling Smørgrav it does not work in general for geographical timezones, 1216967a49a2SDag-Erling Smørgrav such as when a location changes to a time zone with a 1217bc421551SDag-Erling Smørgrav lesser <abbr>UT</abbr> offset. 1218bc421551SDag-Erling Smørgrav </li> 1219bc421551SDag-Erling Smørgrav</ul> 1220bc421551SDag-Erling Smørgrav 1221bc421551SDag-Erling Smørgrav<h3 id="other-portability">Other portability notes</h3> 1222bc421551SDag-Erling Smørgrav<ul> 1223bc421551SDag-Erling Smørgrav <li> 1224bc421551SDag-Erling Smørgrav The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition 1225bc421551SDag-Erling Smørgrav UNIX</a> <code>timezone</code> function is not present in this 1226ff2c98b3SDag-Erling Smørgrav package; it is impossible to reliably map <code>timezone</code>’s 1227ff2c98b3SDag-Erling Smørgrav arguments (a “minutes west of <abbr>GMT</abbr>” value and a 1228ff2c98b3SDag-Erling Smørgrav “daylight saving time in effect” flag) to a time zone 1229bc421551SDag-Erling Smørgrav abbreviation, and we refuse to guess. 1230bc421551SDag-Erling Smørgrav Programs that in the past used the <code>timezone</code> function 1231bc421551SDag-Erling Smørgrav may now examine <code>localtime(&clock)->tm_zone</code> 1232bc421551SDag-Erling Smørgrav (if <code>TM_ZONE</code> is defined) or 1233967a49a2SDag-Erling Smørgrav use <code>strftime</code> with a <code>%Z</code> conversion specification 1234967a49a2SDag-Erling Smørgrav to learn the correct time 1235bc421551SDag-Erling Smørgrav zone abbreviation to use. 1236bc421551SDag-Erling Smørgrav </li> 1237bc421551SDag-Erling Smørgrav <li> 1238bc421551SDag-Erling Smørgrav The <a 1239bc421551SDag-Erling Smørgrav href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a> 1240bc421551SDag-Erling Smørgrav <code>gettimeofday</code> function is not 1241bc421551SDag-Erling Smørgrav used in this package. 1242bc421551SDag-Erling Smørgrav This formerly let users obtain the current <abbr>UTC</abbr> offset 1243bc421551SDag-Erling Smørgrav and <abbr>DST</abbr> flag, but this functionality was removed in 1244bc421551SDag-Erling Smørgrav later versions of <abbr>BSD</abbr>. 1245bc421551SDag-Erling Smørgrav </li> 1246bc421551SDag-Erling Smørgrav <li> 1247bc421551SDag-Erling Smørgrav In <abbr>SVR2</abbr>, time conversion fails for near-minimum or 1248bc421551SDag-Erling Smørgrav near-maximum <code>time_t</code> values when doing conversions 1249bc421551SDag-Erling Smørgrav for places that do not use <abbr>UT</abbr>. 1250bc421551SDag-Erling Smørgrav This package takes care to do these conversions correctly. 1251bc421551SDag-Erling Smørgrav A comment in the source code tells how to get compatibly wrong 1252bc421551SDag-Erling Smørgrav results. 1253bc421551SDag-Erling Smørgrav </li> 1254bc421551SDag-Erling Smørgrav <li> 1255bc421551SDag-Erling Smørgrav The functions that are conditionally compiled 125675411d15SDag-Erling Smørgrav if <code>STD_INSPIRED</code> is nonzero should, at this point, be 1257bc421551SDag-Erling Smørgrav looked on primarily as food for thought. 1258ff2c98b3SDag-Erling Smørgrav They are not in any sense “standard compatible” – some are 1259bc421551SDag-Erling Smørgrav not, in fact, specified in <em>any</em> standard. 1260bc421551SDag-Erling Smørgrav They do, however, represent responses of various authors to 1261bc421551SDag-Erling Smørgrav standardization proposals. 1262bc421551SDag-Erling Smørgrav </li> 1263bc421551SDag-Erling Smørgrav <li> 1264bc421551SDag-Erling Smørgrav Other time conversion proposals, in particular those supported by the 1265bc421551SDag-Erling Smørgrav <a href="https://howardhinnant.github.io/date/tz.html">Time Zone 1266bc421551SDag-Erling Smørgrav Database Parser</a>, offer a wider selection of functions 1267bc421551SDag-Erling Smørgrav that provide capabilities beyond those provided here. 1268bc421551SDag-Erling Smørgrav The absence of such functions from this package is not meant to 1269bc421551SDag-Erling Smørgrav discourage the development, standardization, or use of such 1270bc421551SDag-Erling Smørgrav functions. 1271bc421551SDag-Erling Smørgrav Rather, their absence reflects the decision to make this package 1272bc421551SDag-Erling Smørgrav contain valid extensions to POSIX, to ensure its broad 1273bc421551SDag-Erling Smørgrav acceptability. 1274bc421551SDag-Erling Smørgrav If more powerful time conversion functions can be standardized, so 1275bc421551SDag-Erling Smørgrav much the better. 1276bc421551SDag-Erling Smørgrav </li> 1277bc421551SDag-Erling Smørgrav</ul> 1278bc421551SDag-Erling Smørgrav 1279bc421551SDag-Erling Smørgrav <h2 id="stability">Interface stability</h2> 1280bc421551SDag-Erling Smørgrav<p> 1281bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> code and data supply the following interfaces: 1282bc421551SDag-Erling Smørgrav</p> 1283bc421551SDag-Erling Smørgrav 1284bc421551SDag-Erling Smørgrav<ul> 1285bc421551SDag-Erling Smørgrav <li> 1286bc421551SDag-Erling Smørgrav A set of timezone names as per 1287ff2c98b3SDag-Erling Smørgrav “<a href="#naming">Timezone identifiers</a>” above. 1288bc421551SDag-Erling Smørgrav </li> 1289bc421551SDag-Erling Smørgrav <li> 1290ff2c98b3SDag-Erling Smørgrav Library functions described in “<a href="#functions">Time and date 1291ff2c98b3SDag-Erling Smørgrav functions</a>” above. 1292bc421551SDag-Erling Smørgrav </li> 1293bc421551SDag-Erling Smørgrav <li> 1294bc421551SDag-Erling Smørgrav The programs <code>tzselect</code>, <code>zdump</code>, 1295bc421551SDag-Erling Smørgrav and <code>zic</code>, documented in their man pages. 1296bc421551SDag-Erling Smørgrav </li> 1297bc421551SDag-Erling Smørgrav <li> 1298bc421551SDag-Erling Smørgrav The format of <code>zic</code> input files, documented in 1299bc421551SDag-Erling Smørgrav the <code>zic</code> man page. 1300bc421551SDag-Erling Smørgrav </li> 1301bc421551SDag-Erling Smørgrav <li> 1302bc421551SDag-Erling Smørgrav The format of <code>zic</code> output files, documented in 1303bc421551SDag-Erling Smørgrav the <code>tzfile</code> man page. 1304bc421551SDag-Erling Smørgrav </li> 1305bc421551SDag-Erling Smørgrav <li> 1306bc421551SDag-Erling Smørgrav The format of zone table files, documented in <code>zone1970.tab</code>. 1307bc421551SDag-Erling Smørgrav </li> 1308bc421551SDag-Erling Smørgrav <li> 1309bc421551SDag-Erling Smørgrav The format of the country code file, documented in <code>iso3166.tab</code>. 1310bc421551SDag-Erling Smørgrav </li> 1311bc421551SDag-Erling Smørgrav <li> 1312bc421551SDag-Erling Smørgrav The version number of the code and data, as the first line of 1313ff2c98b3SDag-Erling Smørgrav the text file "<code>version</code>" in each release. 1314bc421551SDag-Erling Smørgrav </li> 1315bc421551SDag-Erling Smørgrav</ul> 1316bc421551SDag-Erling Smørgrav 1317bc421551SDag-Erling Smørgrav<p> 1318bc421551SDag-Erling SmørgravInterface changes in a release attempt to preserve compatibility with 1319bc421551SDag-Erling Smørgravrecent releases. 1320bc421551SDag-Erling SmørgravFor example, <code><abbr>tz</abbr></code> data files typically do not 132175411d15SDag-Erling Smørgravrely on recently added <code>zic</code> features, so that users can 1322bc421551SDag-Erling Smørgravrun older <code>zic</code> versions to process newer data files. 1323bc421551SDag-Erling Smørgrav<a href="tz-link.html#download">Downloading 1324bc421551SDag-Erling Smørgravthe <code><abbr>tz</abbr></code> database</a> describes how releases 1325bc421551SDag-Erling Smørgravare tagged and distributed. 1326bc421551SDag-Erling Smørgrav</p> 1327bc421551SDag-Erling Smørgrav 1328bc421551SDag-Erling Smørgrav<p> 1329bc421551SDag-Erling SmørgravInterfaces not listed above are less stable. 1330bc421551SDag-Erling SmørgravFor example, users should not rely on particular <abbr>UT</abbr> 1331bc421551SDag-Erling Smørgravoffsets or abbreviations for timestamps, as data entries are often 1332bc421551SDag-Erling Smørgravbased on guesswork and these guesses may be corrected or improved. 1333bc421551SDag-Erling Smørgrav</p> 1334bc421551SDag-Erling Smørgrav 1335bc421551SDag-Erling Smørgrav<p> 1336bc421551SDag-Erling SmørgravTimezone boundaries are not part of the stable interface. 1337bc421551SDag-Erling SmørgravFor example, even though the <samp>Asia/Bangkok</samp> timezone 1338bc421551SDag-Erling Smørgravcurrently includes Chang Mai, Hanoi, and Phnom Penh, this is not part 1339bc421551SDag-Erling Smørgravof the stable interface and the timezone can split at any time. 1340bc421551SDag-Erling SmørgravIf a calendar application records a future event in some location other 1341ff2c98b3SDag-Erling Smørgravthan Bangkok by putting <samp>Asia/Bangkok</samp> in the event’s record, 1342bc421551SDag-Erling Smørgravthe application should be robust in the presence of timezone splits 1343bc421551SDag-Erling Smørgravbetween now and the future time. 1344bc421551SDag-Erling Smørgrav</p> 1345bc421551SDag-Erling Smørgrav 1346bc421551SDag-Erling Smørgrav <h2 id="leapsec">Leap seconds</h2> 1347bc421551SDag-Erling Smørgrav<p> 134875411d15SDag-Erling SmørgravLeap seconds were introduced in 1972 to accommodate the 134975411d15SDag-Erling Smørgravdifference between atomic time and the less regular rotation of the earth. 1350a979394aSDag-Erling SmørgravUnfortunately they have caused so many problems with civil 1351a979394aSDag-Erling Smørgravtimekeeping that there are 1352a979394aSDag-Erling Smørgrav<a href="https://www.bipm.org/en/cgpm-2022/resolution-4">plans 1353a979394aSDag-Erling Smørgravto discontinue them by 2035</a>. 1354a979394aSDag-Erling SmørgravEven if these plans come to fruition, a record of leap seconds will still be 1355a979394aSDag-Erling Smørgravneeded to resolve timestamps from 1972 through 2035, 1356a979394aSDag-Erling Smørgravand there may also be a need to record whatever mechanism replaces them. 135775411d15SDag-Erling Smørgrav</p> 135875411d15SDag-Erling Smørgrav 135975411d15SDag-Erling Smørgrav<p> 1360bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> code and data can account for leap seconds, 1361bc421551SDag-Erling Smørgravthanks to code contributed by Bradley White. 1362bc421551SDag-Erling SmørgravHowever, the leap second support of this package is rarely used directly 1363bc421551SDag-Erling Smørgravbecause POSIX requires leap seconds to be excluded and many 1364bc421551SDag-Erling Smørgravsoftware packages would mishandle leap seconds if they were present. 1365bc421551SDag-Erling SmørgravInstead, leap seconds are more commonly handled by occasionally adjusting 1366bc421551SDag-Erling Smørgravthe operating system kernel clock as described in 1367bc421551SDag-Erling Smørgrav<a href="tz-link.html#precision">Precision timekeeping</a>, 1368bc421551SDag-Erling Smørgravand this package by default installs a <samp>leapseconds</samp> file 1369bc421551SDag-Erling Smørgravcommonly used by 1370bc421551SDag-Erling Smørgrav<a href="https://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a> 1371bc421551SDag-Erling Smørgravsoftware that adjusts the kernel clock. 1372bc421551SDag-Erling SmørgravHowever, kernel-clock twiddling approximates UTC only roughly, 1373ff2c98b3SDag-Erling Smørgravand systems needing more precise UTC can use this package’s leap 1374bc421551SDag-Erling Smørgravsecond support directly. 1375bc421551SDag-Erling Smørgrav</p> 1376bc421551SDag-Erling Smørgrav 1377bc421551SDag-Erling Smørgrav<p> 137875411d15SDag-Erling SmørgravThe directly supported mechanism assumes that <code>time_t</code> 1379bc421551SDag-Erling Smørgravcounts of seconds since the POSIX epoch normally include leap seconds, 1380bc421551SDag-Erling Smørgravas opposed to POSIX <code>time_t</code> counts which exclude leap seconds. 1381bc421551SDag-Erling SmørgravThis modified timescale is converted to <abbr>UTC</abbr> 1382bc421551SDag-Erling Smørgravat the same point that time zone and <abbr>DST</abbr> 1383ff2c98b3SDag-Erling Smørgravadjustments are applied – 1384ff2c98b3SDag-Erling Smørgravnamely, at calls to <code>localtime</code> and analogous functions – 1385bc421551SDag-Erling Smørgravand the process is driven by leap second information 1386bc421551SDag-Erling Smørgravstored in alternate versions of the <abbr>TZif</abbr> files. 1387bc421551SDag-Erling SmørgravBecause a leap second adjustment may be needed even 1388bc421551SDag-Erling Smørgravif no time zone correction is desired, 1389bc421551SDag-Erling Smørgravcalls to <code>gmtime</code>-like functions 1390bc421551SDag-Erling Smørgravalso need to consult a <abbr>TZif</abbr> file, 1391bc421551SDag-Erling Smørgravconventionally named <samp><abbr>Etc/UTC</abbr></samp> 1392bc421551SDag-Erling Smørgrav(<samp><abbr>GMT</abbr></samp> in previous versions), 1393bc421551SDag-Erling Smørgravto see whether leap second corrections are needed. 1394ff2c98b3SDag-Erling SmørgravTo convert an application’s <code>time_t</code> timestamps to or from 1395bc421551SDag-Erling SmørgravPOSIX <code>time_t</code> timestamps (for use when, say, 1396bc421551SDag-Erling Smørgravembedding or interpreting timestamps in portable 1397bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a> 1398bc421551SDag-Erling Smørgravfiles), 1399bc421551SDag-Erling Smørgravthe application can call the utility functions 1400bc421551SDag-Erling Smørgrav<code>time2posix</code> and <code>posix2time</code> 1401bc421551SDag-Erling Smørgravincluded with this package. 1402bc421551SDag-Erling Smørgrav</p> 1403bc421551SDag-Erling Smørgrav 1404bc421551SDag-Erling Smørgrav<p> 1405bc421551SDag-Erling SmørgravIf the POSIX-compatible <abbr>TZif</abbr> file set is installed 1406bc421551SDag-Erling Smørgravin a directory whose basename is <samp>zoneinfo</samp>, the 1407bc421551SDag-Erling Smørgravleap-second-aware file set is by default installed in a separate 1408bc421551SDag-Erling Smørgravdirectory <samp>zoneinfo-leaps</samp>. 1409bc421551SDag-Erling SmørgravAlthough each process can have its own time zone by setting 1410bc421551SDag-Erling Smørgravits <code>TZ</code> environment variable, there is no support for some 1411bc421551SDag-Erling Smørgravprocesses being leap-second aware while other processes are 1412bc421551SDag-Erling SmørgravPOSIX-compatible; the leap-second choice is system-wide. 1413bc421551SDag-Erling SmørgravSo if you configure your kernel to count leap seconds, you should also 1414bc421551SDag-Erling Smørgravdiscard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp> 1415bc421551SDag-Erling Smørgravto <samp>zoneinfo</samp>. 1416bc421551SDag-Erling SmørgravAlternatively, you can install just one set of <abbr>TZif</abbr> files 1417ff2c98b3SDag-Erling Smørgravin the first place; see the <code>REDO</code> variable in this package’s 1418bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>. 1419bc421551SDag-Erling Smørgrav</p> 1420bc421551SDag-Erling Smørgrav 1421bc421551SDag-Erling Smørgrav <h2 id="calendar">Calendrical issues</h2> 1422bc421551SDag-Erling Smørgrav<p> 1423bc421551SDag-Erling SmørgravCalendrical issues are a bit out of scope for a time zone database, 1424bc421551SDag-Erling Smørgravbut they indicate the sort of problems that we would run into if we 1425bc421551SDag-Erling Smørgravextended the time zone database further into the past. 1426bc421551SDag-Erling SmørgravAn excellent resource in this area is Edward M. Reingold 1427bc421551SDag-Erling Smørgravand Nachum Dershowitz, <cite><a 1428ff2c98b3SDag-Erling Smørgravhref="https://www.cambridge.org/fr/universitypress/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical 1429bc421551SDag-Erling SmørgravCalculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018). 1430ff2c98b3SDag-Erling SmørgravOther information and sources are given in the file "<code>calendars</code>" 1431bc421551SDag-Erling Smørgravin the <code><abbr>tz</abbr></code> distribution. 1432bc421551SDag-Erling SmørgravThey sometimes disagree. 1433bc421551SDag-Erling Smørgrav</p> 1434bc421551SDag-Erling Smørgrav 143575411d15SDag-Erling Smørgrav <h2 id="planets">Time and time zones off Earth</h2> 143675411d15SDag-Erling Smørgrav<p> 1437212e3524SDag-Erling SmørgravEfforts are underway to establish a reference timescale for the Moon, which has 143875411d15SDag-Erling Smørgravdays roughly equivalent to 29.5 Earth days, and where relativistic 143975411d15SDag-Erling Smørgraveffects cause clocks to tick slightly faster than on Earth. 1440212e3524SDag-Erling SmørgravThe European Space Agency <a 1441212e3524SDag-Erling Smørgravhref="https://www.esa.int/Applications/Satellite_navigation/Telling_time_on_the_Moon">began 1442212e3524SDag-Erling Smørgravconsidering</a> the problem in 2023, and in 2024 1443212e3524SDag-Erling Smørgrav<abbr title="National Aeronautics and Space Administration">NASA</abbr> 1444212e3524SDag-Erling Smørgravwas <a 1445ff2c98b3SDag-Erling Smørgravhref="https://bidenwhitehouse.archives.gov/wp-content/uploads/2024/04/Celestial-Time-Standardization-Policy.pdf">ordered</a> 1446a979394aSDag-Erling Smørgravto consider the establishment of Coordinated Lunar Time (<abbr>LTC</abbr>). 1447212e3524SDag-Erling SmørgravIn 2025 a team at China’s 1448212e3524SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Purple_Mountain_Observatory">Purple 1449212e3524SDag-Erling SmørgravMountain Observatory</a> published 1450212e3524SDag-Erling Smørgrav<a href="https://doi.org/10.1051/0004-6361/202557345">Lunar Time Ephemeris 1451212e3524SDag-Erling Smørgrav440</a>, the first formal proposal for a standard 1452212e3524SDag-Erling Smørgravfor Temps Coordonné Lunaire (<abbr>TCL</abbr>). 1453212e3524SDag-Erling SmørgravA <a href="https://www.bipm.org/documents/20126/284836054/CGPM-2026-Draft-Resolutions.pdf">draft 1454212e3524SDag-Erling Smørgravresolution of the 13–15 October 2026 General Conference on Weights 1455212e3524SDag-Erling Smørgravand Measures</a> recommends that the <a href="https://www.bipm.org/en/">Bureau 1456212e3524SDag-Erling SmørgravInternational des Poids et Mesures</a> collaborate with space agencies 1457212e3524SDag-Erling Smørgravand other organizations on this matter. 145875411d15SDag-Erling Smørgrav</p> 145975411d15SDag-Erling Smørgrav 1460bc421551SDag-Erling Smørgrav<p> 1461ff2c98b3SDag-Erling SmørgravSome people’s work schedules have used 1462bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>. 1463bc421551SDag-Erling SmørgravJet Propulsion Laboratory (JPL) coordinators kept Mars time on 1464bc421551SDag-Erling Smørgravand off during the 1465bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars 1466bc421551SDag-Erling SmørgravPathfinder</a> mission (1997). 1467bc421551SDag-Erling SmørgravSome of their family members also adapted to Mars time. 1468bc421551SDag-Erling SmørgravDozens of special Mars watches were built for JPL workers who kept 1469bc421551SDag-Erling SmørgravMars time during the 1470bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars 1471ff2c98b3SDag-Erling SmørgravExploration Rovers (MER)</a> mission (2004–2018). 1472bc421551SDag-Erling SmørgravThese timepieces looked like normal Seikos and Citizens but were adjusted 1473bc421551SDag-Erling Smørgravto use Mars seconds rather than terrestrial seconds, although 1474bc421551SDag-Erling Smørgravunfortunately the adjusted watches were unreliable and appear to have 1475bc421551SDag-Erling Smørgravhad only limited use. 1476bc421551SDag-Erling Smørgrav</p> 1477bc421551SDag-Erling Smørgrav 1478bc421551SDag-Erling Smørgrav<p> 1479ff2c98b3SDag-Erling SmørgravA Mars solar day is called a “sol” and has a mean period equal to 1480bc421551SDag-Erling Smørgravabout 24 hours 39 minutes 35.244 seconds in terrestrial time. 1481bc421551SDag-Erling SmørgravIt is divided into a conventional 24-hour clock, so each Mars second 1482bc421551SDag-Erling Smørgravequals about 1.02749125 terrestrial seconds. 1483ff2c98b3SDag-Erling Smørgrav(One MER worker noted, “If I am working Mars hours, and Mars hours are 1484ff2c98b3SDag-Erling Smørgrav2.5% more than Earth hours, shouldn’t I get an extra 2.5% pay raise?”) 1485bc421551SDag-Erling Smørgrav</p> 1486bc421551SDag-Erling Smørgrav 1487bc421551SDag-Erling Smørgrav<p> 1488bc421551SDag-Erling SmørgravThe <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime 1489bc421551SDag-Erling Smørgravmeridian</a> of Mars goes through the center of the crater 1490bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in 1491bc421551SDag-Erling Smørgravhonor of the British astronomer who built the Greenwich telescope that 1492ff2c98b3SDag-Erling Smørgravdefines Earth’s prime meridian. 1493bc421551SDag-Erling SmørgravMean solar time on the Mars prime meridian is 1494bc421551SDag-Erling Smørgravcalled Mars Coordinated Time (<abbr>MTC</abbr>). 1495bc421551SDag-Erling Smørgrav</p> 1496bc421551SDag-Erling Smørgrav 1497bc421551SDag-Erling Smørgrav<p> 1498bc421551SDag-Erling SmørgravEach landed mission on Mars has adopted a different reference for 1499bc421551SDag-Erling Smørgravsolar timekeeping, so there is no real standard for Mars time zones. 1500ff2c98b3SDag-Erling SmørgravFor example, the MER mission defined two time zones “Local 1501ff2c98b3SDag-Erling SmørgravSolar Time A” and “Local Solar Time B” for its two missions, each zone 1502bc421551SDag-Erling Smørgravdesigned so that its time equals local true solar time at 1503bc421551SDag-Erling Smørgravapproximately the middle of the nominal mission. 1504bc421551SDag-Erling SmørgravThe A and B zones differ enough so that an MER worker assigned to 1505ff2c98b3SDag-Erling Smørgravthe A zone might suffer “Mars lag” when switching to work in the B zone. 1506ff2c98b3SDag-Erling SmørgravSuch a “time zone” is not particularly suited for any application 1507bc421551SDag-Erling Smørgravother than the mission itself. 1508bc421551SDag-Erling Smørgrav</p> 1509bc421551SDag-Erling Smørgrav 1510bc421551SDag-Erling Smørgrav<p> 1511bc421551SDag-Erling SmørgravMany calendars have been proposed for Mars, but none have achieved 1512bc421551SDag-Erling Smørgravwide acceptance. 1513bc421551SDag-Erling SmørgravAstronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a 1514bc421551SDag-Erling Smørgravsequential count of Mars solar days elapsed since about 1873-12-29 1515bc421551SDag-Erling Smørgrav12:00 <abbr>GMT</abbr>. 1516bc421551SDag-Erling Smørgrav</p> 1517bc421551SDag-Erling Smørgrav 1518bc421551SDag-Erling Smørgrav<p> 1519bc421551SDag-Erling SmørgravIn our solar system, Mars is the planet with time and calendar most 1520ff2c98b3SDag-Erling Smørgravlike Earth’s. 1521bc421551SDag-Erling SmørgravOn other planets, Sun-based time and calendars would work quite 1522bc421551SDag-Erling Smørgravdifferently. 1523ff2c98b3SDag-Erling SmørgravFor example, although Mercury’s 1524bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal 1525bc421551SDag-Erling Smørgravrotation period</a> is 58.646 Earth days, Mercury revolves around the 1526ff2c98b3SDag-Erling SmørgravSun so rapidly that an observer on Mercury’s equator would see a 1527bc421551SDag-Erling Smørgravsunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a 1528bc421551SDag-Erling SmørgravMercury day. 1529bc421551SDag-Erling SmørgravVenus is more complicated, partly because its rotation is slightly 1530bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>: 1531bc421551SDag-Erling Smørgravits year is 1.92 of its days. 1532bc421551SDag-Erling SmørgravGas giants like Jupiter are trickier still, as their polar and 1533bc421551SDag-Erling Smørgravequatorial regions rotate at different rates, so that the length of a 1534bc421551SDag-Erling Smørgravday depends on latitude. 1535bc421551SDag-Erling SmørgravThis effect is most pronounced on Neptune, where the day is about 12 1536bc421551SDag-Erling Smørgravhours at the poles and 18 hours at the equator. 1537bc421551SDag-Erling Smørgrav</p> 1538bc421551SDag-Erling Smørgrav 1539bc421551SDag-Erling Smørgrav<p> 1540bc421551SDag-Erling SmørgravAlthough the <code><abbr>tz</abbr></code> database does not support 1541bc421551SDag-Erling Smørgravtime on other planets, it is documented here in the hopes that support 1542bc421551SDag-Erling Smørgravwill be added eventually. 1543bc421551SDag-Erling Smørgrav</p> 1544bc421551SDag-Erling Smørgrav 1545bc421551SDag-Erling Smørgrav<p> 1546bc421551SDag-Erling SmørgravSources for time on other planets: 1547bc421551SDag-Erling Smørgrav</p> 1548bc421551SDag-Erling Smørgrav 1549bc421551SDag-Erling Smørgrav<ul> 1550bc421551SDag-Erling Smørgrav <li> 1551bc421551SDag-Erling Smørgrav Michael Allison and Robert Schmunk, 1552ff2c98b3SDag-Erling Smørgrav “<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical 1553ff2c98b3SDag-Erling Smørgrav Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>” 155428f617deSDag-Erling Smørgrav (2023-05-15). 1555bc421551SDag-Erling Smørgrav </li> 1556bc421551SDag-Erling Smørgrav <li> 1557bc421551SDag-Erling Smørgrav Zara Mirmalek, 1558bc421551SDag-Erling Smørgrav <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making 1559bc421551SDag-Erling Smørgrav Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854. 1560bc421551SDag-Erling Smørgrav </li> 1561bc421551SDag-Erling Smørgrav <li> 1562bc421551SDag-Erling Smørgrav Jia-Rui Chong, 1563ff2c98b3SDag-Erling Smørgrav “<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays 1564ff2c98b3SDag-Erling Smørgrav Fit for a Martian</a>”, <cite>Los Angeles Times</cite> 1565ff2c98b3SDag-Erling Smørgrav (2004-01-14), pp A1, A20–A21. 1566bc421551SDag-Erling Smørgrav </li> 1567bc421551SDag-Erling Smørgrav <li> 1568bc421551SDag-Erling Smørgrav Tom Chmielewski, 1569ff2c98b3SDag-Erling Smørgrav “<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet 1570ff2c98b3SDag-Erling Smørgrav Lag Is Worse on Mars</a>”, <cite>The Atlantic</cite> (2015-02-26) 1571bc421551SDag-Erling Smørgrav </li> 1572bc421551SDag-Erling Smørgrav <li> 1573bc421551SDag-Erling Smørgrav Matt Williams, 1574ff2c98b3SDag-Erling Smørgrav “<a href="https://www.universetoday.com/articles/days-of-the-planets">How 1575ff2c98b3SDag-Erling Smørgrav long is a day on the other planets of the solar system?</a>” 1576bc421551SDag-Erling Smørgrav (2016-01-20). 1577bc421551SDag-Erling Smørgrav </li> 1578bc421551SDag-Erling Smørgrav</ul> 1579212e3524SDag-Erling Smørgrav</main> 1580212e3524SDag-Erling Smørgrav 1581212e3524SDag-Erling Smørgrav<aside> 1582212e3524SDag-Erling Smørgrav<h2 id="see-also">See also</h2> 1583212e3524SDag-Erling Smørgrav<ul> 1584212e3524SDag-Erling Smørgrav<li><a href="tz-link.html">Time zone and daylight saving time data</a></li> 1585212e3524SDag-Erling Smørgrav<li><a href="tz-art.html">Time and the arts</a></li> 1586212e3524SDag-Erling Smørgrav</ul> 1587212e3524SDag-Erling Smørgrav</aside> 1588bc421551SDag-Erling Smørgrav 1589bc421551SDag-Erling Smørgrav<footer> 1590bc421551SDag-Erling Smørgrav<hr> 1591ff2c98b3SDag-Erling SmørgravThis web page is in the public domain, so clarified as of 1592ff2c98b3SDag-Erling Smørgrav2009-05-17 by Arthur David Olson. 1593ff2c98b3SDag-Erling Smørgrav<br> 1594ff2c98b3SDag-Erling SmørgravPlease send corrections to this web page to the 1595ff2c98b3SDag-Erling Smørgrav<a href="mailto:tz@iana.org">time zone mailing list</a>. 1596ff2c98b3SDag-Erling SmørgravThe mailing list and its archives are public, 1597ff2c98b3SDag-Erling Smørgravso please do not send confidential information. 1598bc421551SDag-Erling Smørgrav</footer> 1599bc421551SDag-Erling Smørgrav</body> 1600bc421551SDag-Erling Smørgrav</html> 1601