189abb9f8SPhilip Paeps<!DOCTYPE html> 28d7edd17SPhilip Paeps<html lang="en"> 38d7edd17SPhilip Paeps<head> 48d7edd17SPhilip Paeps <title>Theory and pragmatics of the tz code and data</title> 58d7edd17SPhilip Paeps <meta charset="UTF-8"> 689abb9f8SPhilip Paeps <style> 789abb9f8SPhilip Paeps pre {margin-left: 2em; white-space: pre-wrap;} 889abb9f8SPhilip Paeps </style> 98d7edd17SPhilip Paeps</head> 108d7edd17SPhilip Paeps 118d7edd17SPhilip Paeps<body> 1246bee4edSPhilip Paeps<h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1> 138d7edd17SPhilip Paeps <h3>Outline</h3> 148d7edd17SPhilip Paeps <nav> 158d7edd17SPhilip Paeps <ul> 1646bee4edSPhilip Paeps <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code> 1746bee4edSPhilip Paeps database</a></li> 18ad48359aSPhilip Paeps <li><a href="#naming">Timezone identifiers</a></li> 198d7edd17SPhilip Paeps <li><a href="#abbreviations">Time zone abbreviations</a></li> 2046bee4edSPhilip Paeps <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code> 2146bee4edSPhilip Paeps database</a></li> 228d7edd17SPhilip Paeps <li><a href="#functions">Time and date functions</a></li> 238d7edd17SPhilip Paeps <li><a href="#stability">Interface stability</a></li> 24798c0c0bSPhilip Paeps <li><a href="#leapsec">Leap seconds</a></li> 258d7edd17SPhilip Paeps <li><a href="#calendar">Calendrical issues</a></li> 26259e2ad7SPhilip Paeps <li><a href="#planets">Time and time zones off earth</a></li> 278d7edd17SPhilip Paeps </ul> 288d7edd17SPhilip Paeps </nav> 298d7edd17SPhilip Paeps 308d7edd17SPhilip Paeps<section> 3146bee4edSPhilip Paeps <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2> 328d7edd17SPhilip Paeps<p> 3346bee4edSPhilip PaepsThe <a 3446bee4edSPhilip Paepshref="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code> 3546bee4edSPhilip Paepsdatabase</a> attempts to record the history and predicted future of 3612a899b6SPhilip Paepscivil time scales. 3746bee4edSPhilip PaepsIt organizes <a href="tz-link.html">time zone and daylight saving time 3846bee4edSPhilip Paepsdata</a> by partitioning the world into <a 3989abb9f8SPhilip Paepshref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a> 40d81c2dd9SPhilip Paepswhose clocks all agree about timestamps that occur after the <a 4146bee4edSPhilip Paepshref="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a> 4246bee4edSPhilip Paeps(1970-01-01 00:00:00 <a 4346bee4edSPhilip Paepshref="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr 4446bee4edSPhilip Paepstitle="Coordinated Universal Time">UTC</abbr></a>). 4546bee4edSPhilip PaepsAlthough 1970 is a somewhat-arbitrary cutoff, there are significant 4646bee4edSPhilip Paepschallenges to moving the cutoff earlier even by a decade or two, due 4746bee4edSPhilip Paepsto the wide variety of local practices before computer timekeeping 4846bee4edSPhilip Paepsbecame prevalent. 4994c2d487SPhilip PaepsMost timezones correspond to a notable location and the database 5094c2d487SPhilip Paepsrecords all known clock transitions for that location; 5194c2d487SPhilip Paepssome timezones correspond instead to a fixed <abbr>UTC</abbr> offset. 528d7edd17SPhilip Paeps</p> 538d7edd17SPhilip Paeps 548d7edd17SPhilip Paeps<p> 5589abb9f8SPhilip PaepsEach timezone typically corresponds to a geographical region that is 5689abb9f8SPhilip Paepssmaller than a traditional time zone, because clocks in a timezone 5789abb9f8SPhilip Paepsall agree after 1970 whereas a traditional time zone merely 5889abb9f8SPhilip Paepsspecifies current standard time. For example, applications that deal 5989abb9f8SPhilip Paepswith current and future timestamps in the traditional North 6089abb9f8SPhilip PaepsAmerican mountain time zone can choose from the timezones 6189abb9f8SPhilip Paeps<code>America/Denver</code> which observes US-style daylight saving 6294c2d487SPhilip Paepstime (<abbr>DST</abbr>), 6394c2d487SPhilip Paepsand <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>. 6489abb9f8SPhilip PaepsApplications that also deal with past timestamps in the mountain time 6589abb9f8SPhilip Paepszone can choose from over a dozen timezones, such as 6689abb9f8SPhilip Paeps<code>America/Boise</code>, <code>America/Edmonton</code>, and 6789abb9f8SPhilip Paeps<code>America/Hermosillo</code>, each of which currently uses mountain 6889abb9f8SPhilip Paepstime but differs from other timezones for some timestamps after 1970. 6989abb9f8SPhilip Paeps</p> 7089abb9f8SPhilip Paeps 7189abb9f8SPhilip Paeps<p> 7294c2d487SPhilip PaepsClock transitions before 1970 are recorded for location-based timezones, 738d7edd17SPhilip Paepsbecause most systems support timestamps before 1970 and could 748d7edd17SPhilip Paepsmisbehave if data entries were omitted for pre-1970 transitions. 758d7edd17SPhilip PaepsHowever, the database is not designed for and does not suffice for 768d7edd17SPhilip Paepsapplications requiring accurate handling of all past times everywhere, 778d7edd17SPhilip Paepsas it would take far too much effort and guesswork to record all 788d7edd17SPhilip Paepsdetails of pre-1970 civil timekeeping. 79d81c2dd9SPhilip PaepsAlthough some information outside the scope of the database is 80f2fcff28SPhilip Paepscollected in a file <code>backzone</code> that is distributed along 81f2fcff28SPhilip Paepswith the database proper, this file is less reliable and does not 82f2fcff28SPhilip Paepsnecessarily follow database guidelines. 838d7edd17SPhilip Paeps</p> 848d7edd17SPhilip Paeps 858d7edd17SPhilip Paeps<p> 8646bee4edSPhilip PaepsAs described below, reference source code for using the 8746bee4edSPhilip Paeps<code><abbr>tz</abbr></code> database is also available. 8846bee4edSPhilip PaepsThe <code><abbr>tz</abbr></code> code is upwards compatible with <a 8946bee4edSPhilip Paepshref="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international 9046bee4edSPhilip Paepsstandard for <a 9146bee4edSPhilip Paepshref="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems. 92e273650fSPhilip PaepsAs of this writing, the current edition of POSIX is POSIX.1-2024, 93e273650fSPhilip Paepswhich has been published but not yet in HTML form. 94e273650fSPhilip PaepsUnlike its predecessor POSIX.1-2017 (<a 952865ab3fSPhilip Paepshref="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open 96d81c2dd9SPhilip PaepsGroup Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018 97e273650fSPhilip PaepsEdition), POSIX.1-2024 requires support for the 98e273650fSPhilip Paeps<code><abbr>tz</abbr></code> database, which has a 99e273650fSPhilip Paepsmodel for describing civil time that is more complex than the 100e273650fSPhilip Paepsstandard and daylight saving times required by POSIX.1-2017. 10189abb9f8SPhilip PaepsA <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can 10246bee4edSPhilip Paepshave more than two changes per year, these changes need not merely 10346bee4edSPhilip Paepsflip back and forth between two alternatives, and the rules themselves 10446bee4edSPhilip Paepscan change at times. 105798c0c0bSPhilip PaepsWhether and when a timezone changes its clock, 106798c0c0bSPhilip Paepsand even the timezone's notional base offset from <abbr>UTC</abbr>, 107798c0c0bSPhilip Paepsare variable. 10889abb9f8SPhilip PaepsIt does not always make sense to talk about a timezone's 10989abb9f8SPhilip Paeps"base offset", which is not necessarily a single number. 1108d7edd17SPhilip Paeps</p> 11146bee4edSPhilip Paeps 1128d7edd17SPhilip Paeps</section> 1138d7edd17SPhilip Paeps 1148d7edd17SPhilip Paeps<section> 115ad48359aSPhilip Paeps <h2 id="naming">Timezone identifiers</h2> 1168d7edd17SPhilip Paeps<p> 117ad48359aSPhilip PaepsEach timezone has a name that uniquely identifies the timezone. 1188d7edd17SPhilip PaepsInexperienced users are not expected to select these names unaided. 1198d7edd17SPhilip PaepsDistributors should provide documentation and/or a simple selection 12089abb9f8SPhilip Paepsinterface that explains each name via a map or via descriptive text like 12112a899b6SPhilip Paeps"Czech Republic" instead of the timezone name "<code>Europe/Prague</code>". 12289abb9f8SPhilip PaepsIf geolocation information is available, a selection interface can 12389abb9f8SPhilip Paepslocate the user on a timezone map or prioritize names that are 12489abb9f8SPhilip Paepsgeographically close. For an example selection interface, see the 125d81c2dd9SPhilip Paeps<code>tzselect</code> program in the <code><abbr>tz</abbr></code> code. 126*46226b01SPhilip PaepsUnicode's <a href="https://cldr.unicode.org">Common Locale Data 127*46226b01SPhilip PaepsRepository (<abbr>CLDR</abbr>)</a> 128*46226b01SPhilip Paepscontains data that may be useful for other selection 12912a899b6SPhilip Paepsinterfaces; it maps timezone names like <code>Europe/Prague</code> to 13012a899b6SPhilip Paepslocale-dependent strings like "Prague", "Praha", "Прага", and "布拉格". 1318d7edd17SPhilip Paeps</p> 1328d7edd17SPhilip Paeps 1338d7edd17SPhilip Paeps<p> 13446bee4edSPhilip PaepsThe naming conventions attempt to strike a balance 1358d7edd17SPhilip Paepsamong the following goals: 1368d7edd17SPhilip Paeps</p> 13746bee4edSPhilip Paeps 1388d7edd17SPhilip Paeps<ul> 1398d7edd17SPhilip Paeps <li> 14089abb9f8SPhilip Paeps Uniquely identify every timezone where clocks have agreed since 1970. 1418d7edd17SPhilip Paeps This is essential for the intended use: static clocks keeping local 1428d7edd17SPhilip Paeps civil time. 1438d7edd17SPhilip Paeps </li> 1448d7edd17SPhilip Paeps <li> 14589abb9f8SPhilip Paeps Indicate to experts where the timezone's clocks typically are. 1468d7edd17SPhilip Paeps </li> 1478d7edd17SPhilip Paeps <li> 14846bee4edSPhilip Paeps Be robust in the presence of political changes. 149ad48359aSPhilip Paeps For example, names are typically not tied to countries, to avoid 15046bee4edSPhilip Paeps incompatibilities when countries change their name (e.g., 151ad48359aSPhilip Paeps Swaziland→Eswatini) or when locations change countries (e.g., Hong 15246bee4edSPhilip Paeps Kong from UK colony to China). 153ad48359aSPhilip Paeps There is no requirement that every country or national 154ad48359aSPhilip Paeps capital must have a timezone name. 1558d7edd17SPhilip Paeps </li> 1568d7edd17SPhilip Paeps <li> 1578d7edd17SPhilip Paeps Be portable to a wide variety of implementations. 1588d7edd17SPhilip Paeps </li> 1598d7edd17SPhilip Paeps <li> 1608d7edd17SPhilip Paeps Use a consistent naming conventions over the entire world. 1618d7edd17SPhilip Paeps </li> 1628d7edd17SPhilip Paeps</ul> 16346bee4edSPhilip Paeps 1648d7edd17SPhilip Paeps<p> 165e273650fSPhilip PaepsNames normally have the format 16646bee4edSPhilip Paeps<var>AREA</var><code>/</code><var>LOCATION</var>, where 16789abb9f8SPhilip Paeps<var>AREA</var> is a continent or ocean, and 16889abb9f8SPhilip Paeps<var>LOCATION</var> is a specific location within the area. 16946bee4edSPhilip PaepsNorth and South America share the same area, '<code>America</code>'. 17046bee4edSPhilip PaepsTypical names are '<code>Africa/Cairo</code>', 17146bee4edSPhilip Paeps'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'. 172d81c2dd9SPhilip PaepsSome names are further qualified to help avoid confusion; for example, 173d81c2dd9SPhilip Paeps'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg, 174d81c2dd9SPhilip PaepsIndiana from other Petersburgs in America. 1758d7edd17SPhilip Paeps</p> 1768d7edd17SPhilip Paeps 1778d7edd17SPhilip Paeps<p> 17846bee4edSPhilip PaepsHere are the general guidelines used for 17989abb9f8SPhilip Paepschoosing timezone names, 1808d7edd17SPhilip Paepsin decreasing order of importance: 1818d7edd17SPhilip Paeps</p> 18246bee4edSPhilip Paeps 1838d7edd17SPhilip Paeps<ul> 1848d7edd17SPhilip Paeps <li> 1858d7edd17SPhilip Paeps Use only valid POSIX file name components (i.e., the parts of 18646bee4edSPhilip Paeps names other than '<code>/</code>'). 18746bee4edSPhilip Paeps Do not use the file name components '<code>.</code>' and 18846bee4edSPhilip Paeps '<code>..</code>'. 18946bee4edSPhilip Paeps Within a file name component, use only <a 19046bee4edSPhilip Paeps href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters, 19146bee4edSPhilip Paeps '<code>.</code>', '<code>-</code>' and '<code>_</code>'. 19246bee4edSPhilip Paeps Do not use digits, as that might create an ambiguity with <a 193e273650fSPhilip Paeps href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX's proleptic 19446bee4edSPhilip Paeps <code>TZ</code> strings</a>. 19546bee4edSPhilip Paeps A file name component must not exceed 14 characters or start with 19646bee4edSPhilip Paeps '<code>-</code>'. 19794c2d487SPhilip Paeps E.g., prefer <code>America/Noronha</code> to 19894c2d487SPhilip Paeps <code>America/Fernando_de_Noronha</code>. 19946bee4edSPhilip Paeps Exceptions: see the discussion of legacy names below. 2008d7edd17SPhilip Paeps </li> 2018d7edd17SPhilip Paeps <li> 2028d7edd17SPhilip Paeps A name must not be empty, or contain '<code>//</code>', or 2038d7edd17SPhilip Paeps start or end with '<code>/</code>'. 204*46226b01SPhilip Paeps Also, a name must not be '<code>Etc/Unknown</code>', as 205*46226b01SPhilip Paeps <abbr>CLDR</abbr> uses that string for an unknown or invalid timezone. 2068d7edd17SPhilip Paeps </li> 2078d7edd17SPhilip Paeps <li> 20846bee4edSPhilip Paeps Do not use names that differ only in case. 20946bee4edSPhilip Paeps Although the reference implementation is case-sensitive, some 21046bee4edSPhilip Paeps other implementations are not, and they would mishandle names 21146bee4edSPhilip Paeps differing only in case. 2128d7edd17SPhilip Paeps </li> 2138d7edd17SPhilip Paeps <li> 2148d7edd17SPhilip Paeps If one name <var>A</var> is an initial prefix of another 21546bee4edSPhilip Paeps name <var>AB</var> (ignoring case), then <var>B</var> must not 21646bee4edSPhilip Paeps start with '<code>/</code>', as a regular file cannot have the 21746bee4edSPhilip Paeps same name as a directory in POSIX. 218d81c2dd9SPhilip Paeps For example, <code>America/New_York</code> precludes 219d81c2dd9SPhilip Paeps <code>America/New_York/Bronx</code>. 2208d7edd17SPhilip Paeps </li> 2218d7edd17SPhilip Paeps <li> 2228d7edd17SPhilip Paeps Uninhabited regions like the North Pole and Bouvet Island 2238d7edd17SPhilip Paeps do not need locations, since local time is not defined there. 2248d7edd17SPhilip Paeps </li> 2258d7edd17SPhilip Paeps <li> 226*46226b01SPhilip Paeps If all clocks in a region have agreed since 1970, 227*46226b01SPhilip Paeps give them just one name even if some of the clocks disagreed before 1970, 228*46226b01SPhilip Paeps or reside in different countries or in notable or faraway locations. 2298d7edd17SPhilip Paeps Otherwise these tables would become annoyingly large. 230*46226b01SPhilip Paeps For example, do not create a name <code>Indian/Crozet</code> 231*46226b01SPhilip Paeps as a near-duplicate or alias of <code>Asia/Dubai</code> 232*46226b01SPhilip Paeps merely because they are different countries or territories, 233*46226b01SPhilip Paeps or their clocks disagreed before 1970, or the 234*46226b01SPhilip Paeps <a href="https://en.wikipedia.org/wiki/Crozet_Islands">Crozet Islands</a> 235*46226b01SPhilip Paeps are notable in their own right, 236*46226b01SPhilip Paeps or the Crozet Islands are not adjacent to other locations 237*46226b01SPhilip Paeps that use <code>Asia/Dubai</code>. 2388d7edd17SPhilip Paeps </li> 2398d7edd17SPhilip Paeps <li> 240ad48359aSPhilip Paeps If boundaries between regions are fluid, such as during a war or 241ad48359aSPhilip Paeps insurrection, do not bother to create a new timezone merely 242ad48359aSPhilip Paeps because of yet another boundary change. This helps prevent table 243ad48359aSPhilip Paeps bloat and simplifies maintenance. 244ad48359aSPhilip Paeps </li> 245ad48359aSPhilip Paeps <li> 2468d7edd17SPhilip Paeps If a name is ambiguous, use a less ambiguous alternative; 24746bee4edSPhilip Paeps e.g., many cities are named San José and Georgetown, so 248d81c2dd9SPhilip Paeps prefer <code>America/Costa_Rica</code> to 249d81c2dd9SPhilip Paeps <code>America/San_Jose</code> and <code>America/Guyana</code> 250d81c2dd9SPhilip Paeps to <code>America/Georgetown</code>. 2518d7edd17SPhilip Paeps </li> 2528d7edd17SPhilip Paeps <li> 25346bee4edSPhilip Paeps Keep locations compact. 25446bee4edSPhilip Paeps Use cities or small islands, not countries or regions, so that any 25546bee4edSPhilip Paeps future changes do not split individual locations into different 25689abb9f8SPhilip Paeps timezones. 257d81c2dd9SPhilip Paeps E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>, 258d81c2dd9SPhilip Paeps since 25946bee4edSPhilip Paeps <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France 26046bee4edSPhilip Paeps has had multiple time zones</a>. 2618d7edd17SPhilip Paeps </li> 2628d7edd17SPhilip Paeps <li> 263d81c2dd9SPhilip Paeps Use mainstream English spelling, e.g., prefer 26489abb9f8SPhilip Paeps <code>Europe/Rome</code> to <code>Europa/Roma</code>, and 265d81c2dd9SPhilip Paeps prefer <code>Europe/Athens</code> to the Greek 26689abb9f8SPhilip Paeps <code>Ευρώπη/Αθήνα</code> or the Romanized 26789abb9f8SPhilip Paeps <code>Evrópi/Athína</code>. 26846bee4edSPhilip Paeps The POSIX file name restrictions encourage this guideline. 2698d7edd17SPhilip Paeps </li> 2708d7edd17SPhilip Paeps <li> 27146bee4edSPhilip Paeps Use the most populous among locations in a region, 272d81c2dd9SPhilip Paeps e.g., prefer <code>Asia/Shanghai</code> to 273d81c2dd9SPhilip Paeps <code>Asia/Beijing</code>. 27446bee4edSPhilip Paeps Among locations with similar populations, pick the best-known 275d81c2dd9SPhilip Paeps location, e.g., prefer <code>Europe/Rome</code> to 276d81c2dd9SPhilip Paeps <code>Europe/Milan</code>. 2778d7edd17SPhilip Paeps </li> 2788d7edd17SPhilip Paeps <li> 279d81c2dd9SPhilip Paeps Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to 280d81c2dd9SPhilip Paeps <code>Atlantic/Canaries</code>. 2818d7edd17SPhilip Paeps </li> 2828d7edd17SPhilip Paeps <li> 2838d7edd17SPhilip Paeps Omit common suffixes like '<code>_Islands</code>' and 28446bee4edSPhilip Paeps '<code>_City</code>', unless that would lead to ambiguity. 285d81c2dd9SPhilip Paeps E.g., prefer <code>America/Cayman</code> to 286d81c2dd9SPhilip Paeps <code>America/Cayman_Islands</code> and 287d81c2dd9SPhilip Paeps <code>America/Guatemala</code> to 288d81c2dd9SPhilip Paeps <code>America/Guatemala_City</code>, but prefer 289d81c2dd9SPhilip Paeps <code>America/Mexico_City</code> to 290d81c2dd9SPhilip Paeps <code>America/Mexico</code> 29146bee4edSPhilip Paeps because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the 29246bee4edSPhilip Paeps country of Mexico has several time zones</a>. 2938d7edd17SPhilip Paeps </li> 2948d7edd17SPhilip Paeps <li> 2958d7edd17SPhilip Paeps Use '<code>_</code>' to represent a space. 2968d7edd17SPhilip Paeps </li> 2978d7edd17SPhilip Paeps <li> 29846bee4edSPhilip Paeps Omit '<code>.</code>' from abbreviations in names. 299d81c2dd9SPhilip Paeps E.g., prefer <code>Atlantic/St_Helena</code> to 300d81c2dd9SPhilip Paeps <code>Atlantic/St._Helena</code>. 3018d7edd17SPhilip Paeps </li> 3028d7edd17SPhilip Paeps <li> 30346bee4edSPhilip Paeps Do not change established names if they only marginally violate 30446bee4edSPhilip Paeps the above guidelines. 305d81c2dd9SPhilip Paeps For example, do not change the existing name <code>Europe/Rome</code> to 306d81c2dd9SPhilip Paeps <code>Europe/Milan</code> merely because Milan's population has grown 30746bee4edSPhilip Paeps to be somewhat greater than Rome's. 3088d7edd17SPhilip Paeps </li> 3098d7edd17SPhilip Paeps <li> 3108d7edd17SPhilip Paeps If a name is changed, put its old spelling in the 3118ea5af2bSPhilip Paeps '<code>backward</code>' file as a link to the new spelling. 3128d7edd17SPhilip Paeps This means old spellings will continue to work. 313dd5f96c4SPhilip Paeps Ordinarily a name change should occur only in the rare case when 314dd5f96c4SPhilip Paeps a location's consensus English-language spelling changes; for example, 315dd5f96c4SPhilip Paeps in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code> 316dd5f96c4SPhilip Paeps due to long-time widespread use of the new city name instead of the old. 3178d7edd17SPhilip Paeps </li> 3188d7edd17SPhilip Paeps</ul> 3198d7edd17SPhilip Paeps 3208d7edd17SPhilip Paeps<p> 321ad48359aSPhilip PaepsGuidelines have evolved with time, and names following old versions of 3222865ab3fSPhilip Paepsthese guidelines might not follow the current version. When guidelines 323ad48359aSPhilip Paepshave changed, old names continue to be supported. Guideline changes 324ad48359aSPhilip Paepshave included the following: 3258d7edd17SPhilip Paeps</p> 3268d7edd17SPhilip Paeps 327ad48359aSPhilip Paeps<ul> 328ad48359aSPhilip Paeps<li> 329ad48359aSPhilip PaepsOlder versions of this package used a different naming scheme. 3308d7edd17SPhilip PaepsSee the file '<code>backward</code>' for most of these older names 3318d7edd17SPhilip Paeps(e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>'). 3328d7edd17SPhilip PaepsThe other old-fashioned names still supported are 33346bee4edSPhilip Paeps'<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and 33446bee4edSPhilip Paeps'<code>EET</code>' (see the file '<code>europe</code>'). 335ad48359aSPhilip Paeps</li> 3368d7edd17SPhilip Paeps 337ad48359aSPhilip Paeps<li> 3388d7edd17SPhilip PaepsOlder versions of this package defined legacy names that are 33946bee4edSPhilip Paepsincompatible with the first guideline of location names, but which are 34046bee4edSPhilip Paepsstill supported. 34146bee4edSPhilip PaepsThese legacy names are mostly defined in the file 34246bee4edSPhilip Paeps'<code>etcetera</code>'. 34346bee4edSPhilip PaepsAlso, the file '<code>backward</code>' defines the legacy names 3449142a2a3SPhilip Paeps'<code>Etc/GMT0</code>', '<code>Etc/GMT-0</code>', '<code>Etc/GMT+0</code>', 34546bee4edSPhilip Paeps'<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', 34646bee4edSPhilip Paepsand the file '<code>northamerica</code>' defines the legacy names 34746bee4edSPhilip Paeps'<code>EST5EDT</code>', '<code>CST6CDT</code>', 34846bee4edSPhilip Paeps'<code>MST7MDT</code>', and '<code>PST8PDT</code>'. 349ad48359aSPhilip Paeps</li> 350ad48359aSPhilip Paeps 351ad48359aSPhilip Paeps<li> 3522865ab3fSPhilip PaepsOlder versions of these guidelines said that 353ad48359aSPhilip Paepsthere should typically be at least one name for each <a 354ad48359aSPhilip Paepshref="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr 355ad48359aSPhilip Paepstitle="International Organization for Standardization">ISO</abbr> 356ad48359aSPhilip Paeps3166-1</a> officially assigned two-letter code for an inhabited 357ad48359aSPhilip Paepscountry or territory. 358ad48359aSPhilip PaepsThis old guideline has been dropped, as it was not needed to handle 359ad48359aSPhilip Paepstimestamps correctly and it increased maintenance burden. 360ad48359aSPhilip Paeps</li> 361ad48359aSPhilip Paeps</ul> 362ad48359aSPhilip Paeps 363ad48359aSPhilip Paeps<p> 3648ea5af2bSPhilip PaepsThe file <code>zone1970.tab</code> lists geographical locations used 365ad48359aSPhilip Paepsto name timezones. 366ad48359aSPhilip PaepsIt is intended to be an exhaustive list of names for geographic 367ad48359aSPhilip Paepsregions as described above; this is a subset of the timezones in the data. 3688ea5af2bSPhilip PaepsAlthough a <code>zone1970.tab</code> location's 369ad48359aSPhilip Paeps<a href="https://en.wikipedia.org/wiki/Longitude">longitude</a> 370ad48359aSPhilip Paepscorresponds to 371ad48359aSPhilip Paepsits <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean 372ad48359aSPhilip Paepstime (<abbr>LMT</abbr>)</a> offset with one hour for every 15° 373ad48359aSPhilip Paepseast longitude, this relationship is not exact. 3748ea5af2bSPhilip PaepsThe backward-compatibility file <code>zone.tab</code> is similar 3758ea5af2bSPhilip Paepsbut conforms to the older-version guidelines related to <abbr>ISO</abbr> 3166-1; 3768ea5af2bSPhilip Paepsit lists only one country code per entry and unlike <code>zone1970.tab</code> 3778ea5af2bSPhilip Paepsit can list names defined in <code>backward</code>. 3782723c7ffSPhilip PaepsApplications that process only timestamps from now on can instead use the file 3792723c7ffSPhilip Paeps<code>zonenow.tab</code>, which partitions the world more coarsely, 3802723c7ffSPhilip Paepsinto regions where clocks agree now and in the predicted future; 3812723c7ffSPhilip Paepsthis file is smaller and simpler than <code>zone1970.tab</code> 3822723c7ffSPhilip Paepsand <code>zone.tab</code>. 3838d7edd17SPhilip Paeps</p> 3848d7edd17SPhilip Paeps 3858d7edd17SPhilip Paeps<p> 3868ea5af2bSPhilip PaepsThe database defines each timezone name to be a zone, or a link to a zone. 3878ea5af2bSPhilip PaepsThe source file <code>backward</code> defines links for backward 3888ea5af2bSPhilip Paepscompatibility; it does not define zones. 3898ea5af2bSPhilip PaepsAlthough <code>backward</code> was originally designed to be optional, 3908ea5af2bSPhilip Paepsnowadays distributions typically use it 3918ea5af2bSPhilip Paepsand no great weight should be attached to whether a link 3928ea5af2bSPhilip Paepsis defined in <code>backward</code> or in some other file. 3938ea5af2bSPhilip PaepsThe source file <code>etcetera</code> defines names that may be useful 394e273650fSPhilip Paepson platforms that do not support proleptic <code>TZ</code> strings 395e273650fSPhilip Paepslike <code><+08>-8</code>; 3968ea5af2bSPhilip Paepsno other source file other than <code>backward</code> 3978ea5af2bSPhilip Paepscontains links to its zones. 3989f9fc6bbSPhilip PaepsOne of <code>etcetera</code>'s names is <code>Etc/UTC</code>, 3998ea5af2bSPhilip Paepsused by functions like <code>gmtime</code> to obtain leap 4008ea5af2bSPhilip Paepssecond information on platforms that support leap seconds. 4019f9fc6bbSPhilip PaepsAnother <code>etcetera</code> name, <code>GMT</code>, 4029f9fc6bbSPhilip Paepsis used by older code releases. 4038d7edd17SPhilip Paeps</p> 4048d7edd17SPhilip Paeps</section> 40546bee4edSPhilip Paeps 4068d7edd17SPhilip Paeps<section> 4078d7edd17SPhilip Paeps <h2 id="abbreviations">Time zone abbreviations</h2> 4088d7edd17SPhilip Paeps<p> 4098d7edd17SPhilip PaepsWhen this package is installed, it generates time zone abbreviations 4108d7edd17SPhilip Paepslike '<code>EST</code>' to be compatible with human tradition and POSIX. 41146bee4edSPhilip PaepsHere are the general guidelines used for choosing time zone abbreviations, 4128d7edd17SPhilip Paepsin decreasing order of importance: 41346bee4edSPhilip Paeps</p> 41446bee4edSPhilip Paeps 4158d7edd17SPhilip Paeps<ul> 4168d7edd17SPhilip Paeps <li> 417f2fcff28SPhilip Paeps Use three to six characters that are ASCII alphanumerics or 4188d7edd17SPhilip Paeps '<code>+</code>' or '<code>-</code>'. 4198d7edd17SPhilip Paeps Previous editions of this database also used characters like 420d81c2dd9SPhilip Paeps space and '<code>?</code>', but these characters have a 421d81c2dd9SPhilip Paeps special meaning to the 422d81c2dd9SPhilip Paeps <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a> 423d81c2dd9SPhilip Paeps and cause commands like 4242865ab3fSPhilip Paeps '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a> 4252865ab3fSPhilip Paeps `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>' 4268d7edd17SPhilip Paeps to have unexpected effects. 42746bee4edSPhilip Paeps Previous editions of this guideline required upper-case letters, but the 42846bee4edSPhilip Paeps Congressman who introduced 42946bee4edSPhilip Paeps <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro 43046bee4edSPhilip Paeps Standard Time</a> preferred "ChST", so lower-case letters are now 43146bee4edSPhilip Paeps allowed. 43246bee4edSPhilip Paeps Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>', 43346bee4edSPhilip Paeps '<code>+</code>', and alphanumeric characters from the portable 43446bee4edSPhilip Paeps character set in the current locale. 43546bee4edSPhilip Paeps In practice ASCII alphanumerics and '<code>+</code>' and 43646bee4edSPhilip Paeps '<code>-</code>' are safe in all locales. 4378d7edd17SPhilip Paeps 43846bee4edSPhilip Paeps <p> 4398d7edd17SPhilip Paeps In other words, in the C locale the POSIX extended regular 44046bee4edSPhilip Paeps expression <code>[-+[:alnum:]]{3,6}</code> should match the 44146bee4edSPhilip Paeps abbreviation. 442e273650fSPhilip Paeps This guarantees that all abbreviations could have been specified 443e273650fSPhilip Paeps explicitly by a POSIX proleptic <code>TZ</code> string. 44446bee4edSPhilip Paeps </p> 4458d7edd17SPhilip Paeps </li> 4468d7edd17SPhilip Paeps <li> 4478d7edd17SPhilip Paeps Use abbreviations that are in common use among English-speakers, 44846bee4edSPhilip Paeps e.g., 'EST' for Eastern Standard Time in North America. 4498d7edd17SPhilip Paeps We assume that applications translate them to other languages 4508d7edd17SPhilip Paeps as part of the normal localization process; for example, 4518d7edd17SPhilip Paeps a French application might translate 'EST' to 'HNE'. 452f2fcff28SPhilip Paeps 45346bee4edSPhilip Paeps <p> 45446bee4edSPhilip Paeps <small>These abbreviations (for standard/daylight/etc. time) are: 455f2fcff28SPhilip Paeps ACST/ACDT Australian Central, 456f2fcff28SPhilip Paeps AST/ADT/APT/AWT/ADDT Atlantic, 457f2fcff28SPhilip Paeps AEST/AEDT Australian Eastern, 458f2fcff28SPhilip Paeps AHST/AHDT Alaska-Hawaii, 459f2fcff28SPhilip Paeps AKST/AKDT Alaska, 460f2fcff28SPhilip Paeps AWST/AWDT Australian Western, 461f2fcff28SPhilip Paeps BST/BDT Bering, 462f2fcff28SPhilip Paeps CAT/CAST Central Africa, 463f2fcff28SPhilip Paeps CET/CEST/CEMT Central European, 464f2fcff28SPhilip Paeps ChST Chamorro, 465259e2ad7SPhilip Paeps CST/CDT/CWT/CPT Central [North America], 466f2fcff28SPhilip Paeps CST/CDT China, 467f2fcff28SPhilip Paeps GMT/BST/IST/BDST Greenwich, 468f2fcff28SPhilip Paeps EAT East Africa, 469259e2ad7SPhilip Paeps EST/EDT/EWT/EPT Eastern [North America], 470f2fcff28SPhilip Paeps EET/EEST Eastern European, 4712c5e84ccSPhilip Paeps GST/GDT Guam, 472b9994124SPhilip Paeps HST/HDT/HWT/HPT Hawaii, 473798c0c0bSPhilip Paeps HKT/HKST/HKWT Hong Kong, 474f2fcff28SPhilip Paeps IST India, 475f2fcff28SPhilip Paeps IST/GMT Irish, 476f2fcff28SPhilip Paeps IST/IDT/IDDT Israel, 477f2fcff28SPhilip Paeps JST/JDT Japan, 478f2fcff28SPhilip Paeps KST/KDT Korea, 47946bee4edSPhilip Paeps MET/MEST Middle European (a backward-compatibility alias for 48046bee4edSPhilip Paeps Central European), 481f2fcff28SPhilip Paeps MSK/MSD Moscow, 482259e2ad7SPhilip Paeps MST/MDT/MWT/MPT Mountain, 483f2fcff28SPhilip Paeps NST/NDT/NWT/NPT/NDDT Newfoundland, 484f2fcff28SPhilip Paeps NST/NDT/NWT/NPT Nome, 485f2fcff28SPhilip Paeps NZMT/NZST New Zealand through 1945, 486f2fcff28SPhilip Paeps NZST/NZDT New Zealand 1946–present, 487f2fcff28SPhilip Paeps PKT/PKST Pakistan, 488259e2ad7SPhilip Paeps PST/PDT/PWT/PPT Pacific, 48989abb9f8SPhilip Paeps PST/PDT Philippine, 490f2fcff28SPhilip Paeps SAST South Africa, 491f2fcff28SPhilip Paeps SST Samoa, 4929f9fc6bbSPhilip Paeps UTC Universal, 493f2fcff28SPhilip Paeps WAT/WAST West Africa, 494f2fcff28SPhilip Paeps WET/WEST/WEMT Western European, 495f2fcff28SPhilip Paeps WIB Waktu Indonesia Barat, 496f2fcff28SPhilip Paeps WIT Waktu Indonesia Timur, 497f2fcff28SPhilip Paeps WITA Waktu Indonesia Tengah, 49846bee4edSPhilip Paeps YST/YDT/YWT/YPT/YDDT Yukon</small>. 49946bee4edSPhilip Paeps </p> 5008d7edd17SPhilip Paeps </li> 5018d7edd17SPhilip Paeps <li> 50246bee4edSPhilip Paeps <p> 50346bee4edSPhilip Paeps For times taken from a city's longitude, use the 50446bee4edSPhilip Paeps traditional <var>x</var>MT notation. 50546bee4edSPhilip Paeps The only abbreviation like this in current use is '<abbr>GMT</abbr>'. 50646bee4edSPhilip Paeps The others are for timestamps before 1960, 50746bee4edSPhilip Paeps except that Monrovia Mean Time persisted until 1972. 50846bee4edSPhilip Paeps Typically, numeric abbreviations (e.g., '<code>-</code>004430' for 50946bee4edSPhilip Paeps MMT) would cause trouble here, as the numeric strings would exceed 51046bee4edSPhilip Paeps the POSIX length limit. 51146bee4edSPhilip Paeps </p> 512f2fcff28SPhilip Paeps 51346bee4edSPhilip Paeps <p> 51446bee4edSPhilip Paeps <small>These abbreviations are: 51594c2d487SPhilip Paeps AMT Asunción, Athens; 516259e2ad7SPhilip Paeps BMT Baghdad, Bangkok, Batavia, Bermuda, Bern, Bogotá, 517dc505d53SPhilip Paeps Brussels, Bucharest; 51894c2d487SPhilip Paeps CMT Calamarca, Caracas, Chisinau, Colón, Córdoba; 519f2fcff28SPhilip Paeps DMT Dublin/Dunsink; 520f2fcff28SPhilip Paeps EMT Easter; 521f2fcff28SPhilip Paeps FFMT Fort-de-France; 522f2fcff28SPhilip Paeps FMT Funchal; 523f2fcff28SPhilip Paeps GMT Greenwich; 524f2fcff28SPhilip Paeps HMT Havana, Helsinki, Horta, Howrah; 525f2fcff28SPhilip Paeps IMT Irkutsk, Istanbul; 526f2fcff28SPhilip Paeps JMT Jerusalem; 5279f9fc6bbSPhilip Paeps KMT Kaunas, Kyiv, Kingston; 528259e2ad7SPhilip Paeps LMT Lima, Lisbon, local; 52946bee4edSPhilip Paeps MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo, 53046bee4edSPhilip Paeps Moratuwa, Moscow; 531f2fcff28SPhilip Paeps PLMT Phù Liễn; 532f2fcff28SPhilip Paeps PMT Paramaribo, Paris, Perm, Pontianak, Prague; 533f2fcff28SPhilip Paeps PMMT Port Moresby; 534259e2ad7SPhilip Paeps PPMT Port-au-Prince; 535f2fcff28SPhilip Paeps QMT Quito; 536f2fcff28SPhilip Paeps RMT Rangoon, Riga, Rome; 537f2fcff28SPhilip Paeps SDMT Santo Domingo; 538f2fcff28SPhilip Paeps SJMT San José; 539f2fcff28SPhilip Paeps SMT Santiago, Simferopol, Singapore, Stanley; 540f2fcff28SPhilip Paeps TBMT Tbilisi; 541f2fcff28SPhilip Paeps TMT Tallinn, Tehran; 542259e2ad7SPhilip Paeps WMT Warsaw.</small> 54346bee4edSPhilip Paeps </p> 544f2fcff28SPhilip Paeps 54546bee4edSPhilip Paeps <p> 54646bee4edSPhilip Paeps <small>A few abbreviations also follow the pattern that 54789abb9f8SPhilip Paeps <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK. 54846bee4edSPhilip Paeps They are: 549dc505d53SPhilip Paeps BMT/BST for Bermuda 1890–1930, 550f2fcff28SPhilip Paeps CMT/BST for Calamarca Mean Time and Bolivian Summer Time 55146bee4edSPhilip Paeps 1890–1932, 55246bee4edSPhilip Paeps DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time 55346bee4edSPhilip Paeps 1880–1916, 55446bee4edSPhilip Paeps MMT/MST/MDST for Moscow 1880–1919, and 55546bee4edSPhilip Paeps RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926. 55694c2d487SPhilip Paeps </small> 55746bee4edSPhilip Paeps </p> 5588d7edd17SPhilip Paeps </li> 5598d7edd17SPhilip Paeps <li> 56046bee4edSPhilip Paeps Use '<abbr>LMT</abbr>' for local mean time of locations before the 56146bee4edSPhilip Paeps introduction of standard time; see "<a href="#scope">Scope of the 56246bee4edSPhilip Paeps <code><abbr>tz</abbr></code> database</a>". 5638d7edd17SPhilip Paeps </li> 5648d7edd17SPhilip Paeps <li> 5658d7edd17SPhilip Paeps If there is no common English abbreviation, use numeric offsets like 56689abb9f8SPhilip Paeps <code>-</code>05 and <code>+</code>0530 that are generated 56746bee4edSPhilip Paeps by <code>zic</code>'s <code>%z</code> notation. 5688d7edd17SPhilip Paeps </li> 5698d7edd17SPhilip Paeps <li> 5708d7edd17SPhilip Paeps Use current abbreviations for older timestamps to avoid confusion. 57146bee4edSPhilip Paeps For example, in 1910 a common English abbreviation for time 5728d7edd17SPhilip Paeps in central Europe was 'MEZ' (short for both "Middle European 57346bee4edSPhilip Paeps Zone" and for "Mitteleuropäische Zeit" in German). 57446bee4edSPhilip Paeps Nowadays 'CET' ("Central European Time") is more common in 57546bee4edSPhilip Paeps English, and the database uses 'CET' even for circa-1910 57646bee4edSPhilip Paeps timestamps as this is less confusing for modern users and avoids 57746bee4edSPhilip Paeps the need for determining when 'CET' supplanted 'MEZ' in common 57846bee4edSPhilip Paeps usage. 5798d7edd17SPhilip Paeps </li> 5808d7edd17SPhilip Paeps <li> 58189abb9f8SPhilip Paeps Use a consistent style in a timezone's history. 58289abb9f8SPhilip Paeps For example, if a history tends to use numeric 58346bee4edSPhilip Paeps abbreviations and a particular entry could go either way, use a 58446bee4edSPhilip Paeps numeric abbreviation. 5858d7edd17SPhilip Paeps </li> 5868d7edd17SPhilip Paeps <li> 58746bee4edSPhilip Paeps Use 58846bee4edSPhilip Paeps <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a> 58946bee4edSPhilip Paeps (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for 59046bee4edSPhilip Paeps locations while uninhabited. 59146bee4edSPhilip Paeps The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in 59246bee4edSPhilip Paeps some sense undefined; this notation is derived 593*46226b01SPhilip Paeps from <a href="https://www.rfc-editor.org/rfc/rfc3339">Internet 59489abb9f8SPhilip Paeps <abbr title="Request For Comments">RFC</abbr> 3339</a>. 595e273650fSPhilip Paeps (The abbreviation 'Z' that 596*46226b01SPhilip Paeps <a href="https://www.rfc-editor.org/rfc/rfc9557">Internet 597e273650fSPhilip Paeps <abbr>RFC</abbr> 9557</a> uses for this concept 598e273650fSPhilip Paeps would violate the POSIX requirement 599e273650fSPhilip Paeps of at least three characters in an abbreviation.) 6008d7edd17SPhilip Paeps </li> 6018d7edd17SPhilip Paeps</ul> 60246bee4edSPhilip Paeps 6038d7edd17SPhilip Paeps<p> 6048d7edd17SPhilip PaepsApplication writers should note that these abbreviations are ambiguous 605f2fcff28SPhilip Paepsin practice: e.g., 'CST' means one thing in China and something else 606f2fcff28SPhilip Paepsin North America, and 'IST' can refer to time in India, Ireland or 60746bee4edSPhilip PaepsIsrael. 60846bee4edSPhilip PaepsTo avoid ambiguity, use numeric <abbr>UT</abbr> offsets like 609f2fcff28SPhilip Paeps'<code>-</code>0600' instead of time zone abbreviations like 'CST'. 6108d7edd17SPhilip Paeps</p> 6118d7edd17SPhilip Paeps</section> 6128d7edd17SPhilip Paeps 6138d7edd17SPhilip Paeps<section> 61446bee4edSPhilip Paeps <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2> 6158d7edd17SPhilip Paeps<p> 61646bee4edSPhilip PaepsThe <code><abbr>tz</abbr></code> database is not authoritative, and it 61746bee4edSPhilip Paepssurely has errors. 618f2fcff28SPhilip PaepsCorrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. 6198d7edd17SPhilip PaepsUsers requiring authoritative data should consult national standards 6208d7edd17SPhilip Paepsbodies and the references cited in the database's comments. 6218d7edd17SPhilip Paeps</p> 6228d7edd17SPhilip Paeps 6238d7edd17SPhilip Paeps<p> 62446bee4edSPhilip PaepsErrors in the <code><abbr>tz</abbr></code> database arise from many sources: 6258d7edd17SPhilip Paeps</p> 62646bee4edSPhilip Paeps 6278d7edd17SPhilip Paeps<ul> 6288d7edd17SPhilip Paeps <li> 62946bee4edSPhilip Paeps The <code><abbr>tz</abbr></code> database predicts future 63046bee4edSPhilip Paeps timestamps, and current predictions 6318d7edd17SPhilip Paeps will be incorrect after future governments change the rules. 6328d7edd17SPhilip Paeps For example, if today someone schedules a meeting for 13:00 next 6338d7edd17SPhilip Paeps October 1, Casablanca time, and tomorrow Morocco changes its 6348d7edd17SPhilip Paeps daylight saving rules, software can mess up after the rule change 6358d7edd17SPhilip Paeps if it blithely relies on conversions made before the change. 6368d7edd17SPhilip Paeps </li> 6378d7edd17SPhilip Paeps <li> 6388d7edd17SPhilip Paeps The pre-1970 entries in this database cover only a tiny sliver of how 6398d7edd17SPhilip Paeps clocks actually behaved; the vast majority of the necessary 64046bee4edSPhilip Paeps information was lost or never recorded. 64189abb9f8SPhilip Paeps Thousands more timezones would be needed if 64246bee4edSPhilip Paeps the <code><abbr>tz</abbr></code> database's scope were extended to 64346bee4edSPhilip Paeps cover even just the known or guessed history of standard time; for 64446bee4edSPhilip Paeps example, the current single entry for France would need to split 64546bee4edSPhilip Paeps into dozens of entries, perhaps hundreds. 64646bee4edSPhilip Paeps And in most of the world even this approach would be misleading 64746bee4edSPhilip Paeps due to widespread disagreement or indifference about what times 64846bee4edSPhilip Paeps should be observed. 64946bee4edSPhilip Paeps In her 2015 book 65046bee4edSPhilip Paeps <cite><a 6515f33eb72SPhilip Paeps href="https://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The 65246bee4edSPhilip Paeps Global Transformation of Time, 1870–1950</a></cite>, 65346bee4edSPhilip Paeps Vanessa Ogle writes 6548d7edd17SPhilip Paeps "Outside of Europe and North America there was no system of time 6558d7edd17SPhilip Paeps zones at all, often not even a stable landscape of mean times, 65646bee4edSPhilip Paeps prior to the middle decades of the twentieth century". 65746bee4edSPhilip Paeps See: Timothy Shenk, <a 6588d7edd17SPhilip Paepshref="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked: 6598d7edd17SPhilip Paeps A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. 6608d7edd17SPhilip Paeps </li> 6618d7edd17SPhilip Paeps <li> 6628d7edd17SPhilip Paeps Most of the pre-1970 data entries come from unreliable sources, often 6638d7edd17SPhilip Paeps astrology books that lack citations and whose compilers evidently 6648d7edd17SPhilip Paeps invented entries when the true facts were unknown, without 6658d7edd17SPhilip Paeps reporting which entries were known and which were invented. 6668d7edd17SPhilip Paeps These books often contradict each other or give implausible entries, 6678d7edd17SPhilip Paeps and on the rare occasions when they are checked they are 6688d7edd17SPhilip Paeps typically found to be incorrect. 6698d7edd17SPhilip Paeps </li> 6708d7edd17SPhilip Paeps <li> 67146bee4edSPhilip Paeps For the UK the <code><abbr>tz</abbr></code> database relies on 67246bee4edSPhilip Paeps years of first-class work done by 6738d7edd17SPhilip Paeps Joseph Myers and others; see 6748d7edd17SPhilip Paeps "<a href="https://www.polyomino.org.uk/british-time/">History of 6758d7edd17SPhilip Paeps legal time in Britain</a>". 6768d7edd17SPhilip Paeps Other countries are not done nearly as well. 6778d7edd17SPhilip Paeps </li> 6788d7edd17SPhilip Paeps <li> 67946bee4edSPhilip Paeps Sometimes, different people in the same city maintain clocks 68046bee4edSPhilip Paeps that differ significantly. 68146bee4edSPhilip Paeps Historically, railway time was used by railroad companies (which 68246bee4edSPhilip Paeps did not always 68346bee4edSPhilip Paeps agree with each other), church-clock time was used for birth 68446bee4edSPhilip Paeps certificates, etc. 68546bee4edSPhilip Paeps More recently, competing political groups might disagree about 68646bee4edSPhilip Paeps clock settings. Often this is merely common practice, but 68746bee4edSPhilip Paeps sometimes it is set by law. 68846bee4edSPhilip Paeps For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France 68946bee4edSPhilip Paeps was legally <abbr>UT</abbr> +00:09:21 outside train stations and 69046bee4edSPhilip Paeps <abbr>UT</abbr> +00:04:21 inside. Other examples include 69146bee4edSPhilip Paeps Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and 69246bee4edSPhilip Paeps Ürümqi to this day. 6938d7edd17SPhilip Paeps </li> 6948d7edd17SPhilip Paeps <li> 69546bee4edSPhilip Paeps Although a named location in the <code><abbr>tz</abbr></code> 69646bee4edSPhilip Paeps database stands for the containing region, its pre-1970 data 69746bee4edSPhilip Paeps entries are often accurate for only a small subset of that region. 69846bee4edSPhilip Paeps For example, <code>Europe/London</code> stands for the United 69946bee4edSPhilip Paeps Kingdom, but its pre-1847 times are valid only for locations that 70046bee4edSPhilip Paeps have London's exact meridian, and its 1847 transition 70146bee4edSPhilip Paeps to <abbr>GMT</abbr> is known to be valid only for the L&NW and 70246bee4edSPhilip Paeps the Caledonian railways. 7038d7edd17SPhilip Paeps </li> 7048d7edd17SPhilip Paeps <li> 70546bee4edSPhilip Paeps The <code><abbr>tz</abbr></code> database does not record the 70689abb9f8SPhilip Paeps earliest time for which a timezone's 7078d7edd17SPhilip Paeps data entries are thereafter valid for every location in the region. 70846bee4edSPhilip Paeps For example, <code>Europe/London</code> is valid for all locations 70946bee4edSPhilip Paeps in its region after <abbr>GMT</abbr> was made the standard time, 71046bee4edSPhilip Paeps but the date of standardization (1880-08-02) is not in the 71146bee4edSPhilip Paeps <code><abbr>tz</abbr></code> database, other than in commentary. 71289abb9f8SPhilip Paeps For many timezones the earliest time of 71346bee4edSPhilip Paeps validity is unknown. 7148d7edd17SPhilip Paeps </li> 7158d7edd17SPhilip Paeps <li> 71646bee4edSPhilip Paeps The <code><abbr>tz</abbr></code> database does not record a 71746bee4edSPhilip Paeps region's boundaries, and in many cases the boundaries are not known. 71889abb9f8SPhilip Paeps For example, the timezone 71946bee4edSPhilip Paeps <code>America/Kentucky/Louisville</code> represents a region 72046bee4edSPhilip Paeps around the city of Louisville, the boundaries of which are 72146bee4edSPhilip Paeps unclear. 7228d7edd17SPhilip Paeps </li> 7238d7edd17SPhilip Paeps <li> 72446bee4edSPhilip Paeps Changes that are modeled as instantaneous transitions in the 72546bee4edSPhilip Paeps <code><abbr>tz</abbr></code> 7268d7edd17SPhilip Paeps database were often spread out over hours, days, or even decades. 7278d7edd17SPhilip Paeps </li> 7288d7edd17SPhilip Paeps <li> 7298d7edd17SPhilip Paeps Even if the time is specified by law, locations sometimes 7308d7edd17SPhilip Paeps deliberately flout the law. 7318d7edd17SPhilip Paeps </li> 7328d7edd17SPhilip Paeps <li> 7338d7edd17SPhilip Paeps Early timekeeping practices, even assuming perfect clocks, were 73446bee4edSPhilip Paeps often not specified to the accuracy that the 73546bee4edSPhilip Paeps <code><abbr>tz</abbr></code> database requires. 7368d7edd17SPhilip Paeps </li> 7378d7edd17SPhilip Paeps <li> 73812a899b6SPhilip Paeps The <code><abbr>tz</abbr></code> database cannot represent stopped clocks. 73912a899b6SPhilip Paeps However, on 1911-03-11 at 00:00, some public-facing French clocks 74012a899b6SPhilip Paeps were changed by stopping them for a few minutes to effect a transition. 74112a899b6SPhilip Paeps The <code><abbr>tz</abbr></code> database models this via a 74212a899b6SPhilip Paeps backward transition; the relevant French legislation does not 74312a899b6SPhilip Paeps specify exactly how the transition was to occur. 74412a899b6SPhilip Paeps </li> 74512a899b6SPhilip Paeps <li> 7468d7edd17SPhilip Paeps Sometimes historical timekeeping was specified more precisely 74746bee4edSPhilip Paeps than what the <code><abbr>tz</abbr></code> code can handle. 74894c2d487SPhilip Paeps For example, from 1880 to 1916 clocks in Ireland observed Dublin Mean 74946bee4edSPhilip Paeps Time (estimated to be <abbr>UT</abbr> 7509f9fc6bbSPhilip Paeps −00:25:21.1); although the <code><abbr>tz</abbr></code> 7519f9fc6bbSPhilip Paeps source data can represent the .1 second, TZif files and the code cannot. 75246bee4edSPhilip Paeps In practice these old specifications were rarely if ever 75346bee4edSPhilip Paeps implemented to subsecond precision. 7548d7edd17SPhilip Paeps </li> 7558d7edd17SPhilip Paeps <li> 75646bee4edSPhilip Paeps Even when all the timestamp transitions recorded by the 75746bee4edSPhilip Paeps <code><abbr>tz</abbr></code> database are correct, the 75846bee4edSPhilip Paeps <code><abbr>tz</abbr></code> rules that generate them may not 75946bee4edSPhilip Paeps faithfully reflect the historical rules. 76046bee4edSPhilip Paeps For example, from 1922 until World War II the UK moved clocks 76146bee4edSPhilip Paeps forward the day following the third Saturday in April unless that 76246bee4edSPhilip Paeps was Easter, in which case it moved clocks forward the previous 76346bee4edSPhilip Paeps Sunday. 76446bee4edSPhilip Paeps Because the <code><abbr>tz</abbr></code> database has no 7658d7edd17SPhilip Paeps way to specify Easter, these exceptional years are entered as 76646bee4edSPhilip Paeps separate <code><abbr>tz</abbr> Rule</code> lines, even though the 76746bee4edSPhilip Paeps legal rules did not change. 76889abb9f8SPhilip Paeps When transitions are known but the historical rules behind them are not, 76989abb9f8SPhilip Paeps the database contains <code>Zone</code> and <code>Rule</code> 77089abb9f8SPhilip Paeps entries that are intended to represent only the generated 77189abb9f8SPhilip Paeps transitions, not any underlying historical rules; however, this 77289abb9f8SPhilip Paeps intent is recorded at best only in commentary. 7738d7edd17SPhilip Paeps </li> 7748d7edd17SPhilip Paeps <li> 77589abb9f8SPhilip Paeps The <code><abbr>tz</abbr></code> database models time 77646bee4edSPhilip Paeps using the <a 77746bee4edSPhilip Paeps href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic 77889abb9f8SPhilip Paeps Gregorian calendar</a> with days containing 24 equal-length hours 77989abb9f8SPhilip Paeps numbered 00 through 23, except when clock transitions occur. 78089abb9f8SPhilip Paeps Pre-standard time is modeled as local mean time. 78189abb9f8SPhilip Paeps However, historically many people used other calendars and other timescales. 78246bee4edSPhilip Paeps For example, the Roman Empire used 78346bee4edSPhilip Paeps the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian 78446bee4edSPhilip Paeps calendar</a>, 78546bee4edSPhilip Paeps and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman 78646bee4edSPhilip Paeps timekeeping</a> had twelve varying-length daytime hours with a 7878d7edd17SPhilip Paeps non-hour-based system at night. 78889abb9f8SPhilip Paeps And even today, some local practices diverge from the Gregorian 78989abb9f8SPhilip Paeps calendar with 24-hour days. These divergences range from 79089abb9f8SPhilip Paeps relatively minor, such as Japanese bars giving times like "24:30" for the 79189abb9f8SPhilip Paeps wee hours of the morning, to more-significant differences such as <a 7922723c7ffSPhilip Paeps href="https://theworld.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the 79389abb9f8SPhilip Paeps east African practice of starting the day at dawn</a>, renumbering 79489abb9f8SPhilip Paeps the Western 06:00 to be 12:00. These practices are largely outside 79589abb9f8SPhilip Paeps the scope of the <code><abbr>tz</abbr></code> code and data, which 79689abb9f8SPhilip Paeps provide only limited support for date and time localization 797e273650fSPhilip Paeps such as that required by POSIX. 79894c2d487SPhilip Paeps If <abbr>DST</abbr> is not used a different time zone 79989abb9f8SPhilip Paeps can often do the trick; for example, in Kenya a <code>TZ</code> setting 80089abb9f8SPhilip Paeps like <code><-03>3</code> or <code>America/Cayenne</code> starts 80189abb9f8SPhilip Paeps the day six hours later than <code>Africa/Nairobi</code> does. 8028d7edd17SPhilip Paeps </li> 8038d7edd17SPhilip Paeps <li> 8048d7edd17SPhilip Paeps Early clocks were less reliable, and data entries do not represent 8058d7edd17SPhilip Paeps clock error. 8068d7edd17SPhilip Paeps </li> 8078d7edd17SPhilip Paeps <li> 80846bee4edSPhilip Paeps The <code><abbr>tz</abbr></code> database assumes Universal Time 80946bee4edSPhilip Paeps (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not 81046bee4edSPhilip Paeps standardized for older timestamps. 81146bee4edSPhilip Paeps In the <code><abbr>tz</abbr></code> database commentary, 81246bee4edSPhilip Paeps <abbr>UT</abbr> denotes a family of time standards that includes 81346bee4edSPhilip Paeps Coordinated Universal Time (<abbr>UTC</abbr>) along with other 81446bee4edSPhilip Paeps variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>, 81546bee4edSPhilip Paeps with days starting at midnight. 81646bee4edSPhilip Paeps Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern 81746bee4edSPhilip Paeps timestamps, <abbr>UTC</abbr> was not defined until 1960, so 818259e2ad7SPhilip Paeps commentary uses the more general abbreviation <abbr>UT</abbr> for 81946bee4edSPhilip Paeps timestamps that might predate 1960. 82046bee4edSPhilip Paeps Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly, 82146bee4edSPhilip Paeps and since pre-1972 <abbr>UTC</abbr> seconds varied in length, 82246bee4edSPhilip Paeps interpretation of older timestamps can be problematic when 82346bee4edSPhilip Paeps subsecond accuracy is needed. 8248d7edd17SPhilip Paeps </li> 8258d7edd17SPhilip Paeps <li> 826d81c2dd9SPhilip Paeps Civil time was not based on atomic time before 1972, and we do not 82746bee4edSPhilip Paeps know the history of 82846bee4edSPhilip Paeps <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's 82946bee4edSPhilip Paeps rotation</a> accurately enough to map <a 83046bee4edSPhilip Paeps href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr 83146bee4edSPhilip Paeps title="International System of Units">SI</abbr></a> seconds to 83246bee4edSPhilip Paeps historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a> 83346bee4edSPhilip Paeps to more than about one-hour accuracy. 83446bee4edSPhilip Paeps See: Stephenson FR, Morrison LV, Hohenkerk CY. 83589abb9f8SPhilip Paeps <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of 83646bee4edSPhilip Paeps the Earth's rotation: 720 BC to AD 2015</a>. 8375f33eb72SPhilip Paeps <cite>Proc Royal Soc A</cite>. 2016;472:20160404. 8388d7edd17SPhilip Paeps Also see: Espenak F. <a 8398d7edd17SPhilip Paeps href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty 8408d7edd17SPhilip Paeps in Delta T (ΔT)</a>. 8418d7edd17SPhilip Paeps </li> 8428d7edd17SPhilip Paeps <li> 84346bee4edSPhilip Paeps The relationship between POSIX time (that is, <abbr>UTC</abbr> but 84446bee4edSPhilip Paeps ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap 845259e2ad7SPhilip Paeps seconds</a>) and <abbr>UTC</abbr> is not agreed upon. 846259e2ad7SPhilip Paeps This affects time stamps during the leap second era (1972–2035). 84746bee4edSPhilip Paeps Although the POSIX 8488d7edd17SPhilip Paeps clock officially stops during an inserted leap second, at least one 8498d7edd17SPhilip Paeps proposed standard has it jumping back a second instead; and in 8508d7edd17SPhilip Paeps practice POSIX clocks more typically either progress glacially during 8518d7edd17SPhilip Paeps a leap second, or are slightly slowed while near a leap second. 8528d7edd17SPhilip Paeps </li> 8538d7edd17SPhilip Paeps <li> 85446bee4edSPhilip Paeps The <code><abbr>tz</abbr></code> database does not represent how 85546bee4edSPhilip Paeps uncertain its information is. 8568d7edd17SPhilip Paeps Ideally it would contain information about when data entries are 85746bee4edSPhilip Paeps incomplete or dicey. 85846bee4edSPhilip Paeps Partial temporal knowledge is a field of active research, though, 859d81c2dd9SPhilip Paeps and it is not clear how to apply it here. 8608d7edd17SPhilip Paeps </li> 8618d7edd17SPhilip Paeps</ul> 86246bee4edSPhilip Paeps 8638d7edd17SPhilip Paeps<p> 86446bee4edSPhilip PaepsIn short, many, perhaps most, of the <code><abbr>tz</abbr></code> 86546bee4edSPhilip Paepsdatabase's pre-1970 and future timestamps are either wrong or 86646bee4edSPhilip Paepsmisleading. 86746bee4edSPhilip PaepsAny attempt to pass the 86846bee4edSPhilip Paeps<code><abbr>tz</abbr></code> database off as the definition of time 86946bee4edSPhilip Paepsshould be unacceptable to anybody who cares about the facts. 87046bee4edSPhilip PaepsIn particular, the <code><abbr>tz</abbr></code> database's 87146bee4edSPhilip Paeps<abbr>LMT</abbr> offsets should not be considered meaningful, and 87289abb9f8SPhilip Paepsshould not prompt creation of timezones 87346bee4edSPhilip Paepsmerely because two locations 87446bee4edSPhilip Paepsdiffer in <abbr>LMT</abbr> or transitioned to standard time at 87546bee4edSPhilip Paepsdifferent dates. 8768d7edd17SPhilip Paeps</p> 8778d7edd17SPhilip Paeps</section> 8788d7edd17SPhilip Paeps 8798d7edd17SPhilip Paeps<section> 8808d7edd17SPhilip Paeps <h2 id="functions">Time and date functions</h2> 8818d7edd17SPhilip Paeps<p> 88246bee4edSPhilip PaepsThe <code><abbr>tz</abbr></code> code contains time and date functions 88346bee4edSPhilip Paepsthat are upwards compatible with those of POSIX. 88446bee4edSPhilip PaepsCode compatible with this package is already 88546bee4edSPhilip Paeps<a href="tz-link.html#tzdb">part of many platforms</a>, where the 88646bee4edSPhilip Paepsprimary use of this package is to update obsolete time-related files. 88746bee4edSPhilip PaepsTo do this, you may need to compile the time zone compiler 888e273650fSPhilip Paeps<code>zic</code> supplied with this package instead of using the 889e273650fSPhilip Paepssystem <code>zic</code>, since the format of <code>zic</code>'s 89046bee4edSPhilip Paepsinput is occasionally extended, and a platform may still be shipping 89146bee4edSPhilip Paepsan older <code>zic</code>. 8928d7edd17SPhilip Paeps</p> 8938d7edd17SPhilip Paeps 894e273650fSPhilip Paeps<p> 895e273650fSPhilip PaepsIn POSIX, time display in a process is controlled by the 896e273650fSPhilip Paepsenvironment variable <code>TZ</code>, which can have two forms: 897e273650fSPhilip Paeps</p> 8988d7edd17SPhilip Paeps<ul> 8998d7edd17SPhilip Paeps <li> 900e273650fSPhilip Paeps A <dfn>proleptic <code>TZ</code></dfn> value 901e273650fSPhilip Paeps like <code>CET-1CEST,M3.5.0,M10.5.0/3</code> uses a complex 902e273650fSPhilip Paeps notation that specifies a single standard time along with daylight 903e273650fSPhilip Paeps saving rules that apply to all years past, present, and future. 904e273650fSPhilip Paeps </li> 905e273650fSPhilip Paeps <li> 906e273650fSPhilip Paeps A <dfn>geographical <code>TZ</code></dfn> value 907e273650fSPhilip Paeps like <code>Europe/Berlin</code> names a location that stands for 908e273650fSPhilip Paeps civil time near that location, which can have more than 909e273650fSPhilip Paeps one standard time and more than one set of daylight saving rules, 910e273650fSPhilip Paeps to record timekeeping practice more accurately. 911e273650fSPhilip Paeps These names are defined by the <code><abbr>tz</abbr></code> database. 912e273650fSPhilip Paeps </li> 913e273650fSPhilip Paeps</ul> 914e273650fSPhilip Paeps 915e273650fSPhilip Paeps<h3 id="POSIX.1-2017">POSIX.1-2017 properties and limitations</h3> 9168d7edd17SPhilip Paeps<p> 917e273650fSPhilip PaepsSome platforms support only the features required by POSIX.1-2017, 918e273650fSPhilip Paepsand have not yet upgraded to POSIX.1-2024. 919e273650fSPhilip PaepsCode intended to be portable to these platforms must deal 920e273650fSPhilip Paepswith problems that were fixed in later POSIX editions. 921e273650fSPhilip Paeps</p> 922e273650fSPhilip Paeps 923e273650fSPhilip Paeps<ul> 924e273650fSPhilip Paeps <li> 925e273650fSPhilip Paeps POSIX.1-2017 does not require support for geographical <code>TZ</code>, 926e273650fSPhilip Paeps and there is no convenient and efficient way to determine 927e273650fSPhilip Paeps the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary 928e273650fSPhilip Paeps timestamps, particularly for timezones 929e273650fSPhilip Paeps that do not fit into the POSIX model. 930e273650fSPhilip Paeps </li> 931e273650fSPhilip Paeps <li> 932e273650fSPhilip Paeps <p> 933e273650fSPhilip Paeps The proleptic <code>TZ</code> string, 934e273650fSPhilip Paeps which is all that POSIX.1-2017 requires, 935e273650fSPhilip Paeps has a format that is hard to describe and is error-prone in practice. 936e273650fSPhilip Paeps Also, proleptic <code>TZ</code> strings cannot deal with daylight 93746bee4edSPhilip Paeps saving time rules not based on the Gregorian calendar (as in 938259e2ad7SPhilip Paeps Morocco), or with situations where more than two time zone 93946bee4edSPhilip Paeps abbreviations or <abbr>UT</abbr> offsets are used in an area. 9408d7edd17SPhilip Paeps </p> 94146bee4edSPhilip Paeps 9428d7edd17SPhilip Paeps <p> 943e273650fSPhilip Paeps A proleptic <code>TZ</code> string has the following format: 9448d7edd17SPhilip Paeps </p> 94546bee4edSPhilip Paeps 9468d7edd17SPhilip Paeps <p> 9478d7edd17SPhilip Paeps <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>]]] 9488d7edd17SPhilip Paeps </p> 94946bee4edSPhilip Paeps 9508d7edd17SPhilip Paeps <p> 9518d7edd17SPhilip Paeps where: 95246bee4edSPhilip Paeps </p> 95346bee4edSPhilip Paeps 9548d7edd17SPhilip Paeps <dl> 9558d7edd17SPhilip Paeps <dt><var>std</var> and <var>dst</var></dt><dd> 9568d7edd17SPhilip Paeps are 3 or more characters specifying the standard 95789abb9f8SPhilip Paeps and daylight saving time (<abbr>DST</abbr>) zone abbreviations. 95846bee4edSPhilip Paeps Starting with POSIX.1-2001, <var>std</var> and <var>dst</var> 95946bee4edSPhilip Paeps may also be in a quoted form like '<code><+09></code>'; 96046bee4edSPhilip Paeps this allows "<code>+</code>" and "<code>-</code>" in the names. 9618d7edd17SPhilip Paeps </dd> 9628d7edd17SPhilip Paeps <dt><var>offset</var></dt><dd> 9638d7edd17SPhilip Paeps is of the form 9648d7edd17SPhilip Paeps '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' 96546bee4edSPhilip Paeps and specifies the offset west of <abbr>UT</abbr>. 96646bee4edSPhilip Paeps '<var>hh</var>' may be a single digit; 96746bee4edSPhilip Paeps 0≤<var>hh</var>≤24. 96846bee4edSPhilip Paeps The default <abbr>DST</abbr> offset is one hour ahead of 96946bee4edSPhilip Paeps standard time. 9708d7edd17SPhilip Paeps </dd> 9718d7edd17SPhilip Paeps <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> 97246bee4edSPhilip Paeps specifies the beginning and end of <abbr>DST</abbr>. 97346bee4edSPhilip Paeps If this is absent, the system supplies its own ruleset 974259e2ad7SPhilip Paeps for <abbr>DST</abbr>, typically current <abbr>US</abbr> 975259e2ad7SPhilip Paeps <abbr>DST</abbr> rules. 9768d7edd17SPhilip Paeps </dd> 9778d7edd17SPhilip Paeps <dt><var>time</var></dt><dd> 9788d7edd17SPhilip Paeps takes the form 9798d7edd17SPhilip Paeps '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]' 9808d7edd17SPhilip Paeps and defaults to 02:00. 9818d7edd17SPhilip Paeps This is the same format as the offset, except that a 9828d7edd17SPhilip Paeps leading '<code>+</code>' or '<code>-</code>' is not allowed. 9838d7edd17SPhilip Paeps </dd> 9848d7edd17SPhilip Paeps <dt><var>date</var></dt><dd> 9858d7edd17SPhilip Paeps takes one of the following forms: 9868d7edd17SPhilip Paeps <dl> 9878d7edd17SPhilip Paeps <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> 9888d7edd17SPhilip Paeps origin-1 day number not counting February 29 9898d7edd17SPhilip Paeps </dd> 9908d7edd17SPhilip Paeps <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> 9918d7edd17SPhilip Paeps origin-0 day number counting February 29 if present 9928d7edd17SPhilip Paeps </dd> 99346bee4edSPhilip Paeps <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> 99446bee4edSPhilip Paeps (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, 99546bee4edSPhilip Paeps 1≤<var>m</var>≤12)</dt><dd> 99646bee4edSPhilip Paeps for the <var>d</var>th day of week <var>n</var> of 99746bee4edSPhilip Paeps month <var>m</var> of the year, where week 1 is the first 99846bee4edSPhilip Paeps week in which day <var>d</var> appears, and 99946bee4edSPhilip Paeps '<code>5</code>' stands for the last week in which 100046bee4edSPhilip Paeps day <var>d</var> appears (which may be either the 4th or 100146bee4edSPhilip Paeps 5th week). 100246bee4edSPhilip Paeps Typically, this is the only useful form; the <var>n</var> 100346bee4edSPhilip Paeps and <code>J</code><var>n</var> forms are rarely used. 10048d7edd17SPhilip Paeps </dd> 10058d7edd17SPhilip Paeps </dl> 10068d7edd17SPhilip Paeps </dd> 10078d7edd17SPhilip Paeps </dl> 100846bee4edSPhilip Paeps 100946bee4edSPhilip Paeps <p> 1010e273650fSPhilip Paeps Here is an example proleptic <code>TZ</code> string for New 101146bee4edSPhilip Paeps Zealand after 2007. 101246bee4edSPhilip Paeps It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead 101346bee4edSPhilip Paeps of <abbr>UT</abbr>, and that daylight saving time 101446bee4edSPhilip Paeps (<abbr>NZDT</abbr>) is observed from September's last Sunday at 101546bee4edSPhilip Paeps 02:00 until April's first Sunday at 03:00: 101646bee4edSPhilip Paeps </p> 10178d7edd17SPhilip Paeps 10188d7edd17SPhilip Paeps <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> 10198d7edd17SPhilip Paeps 102046bee4edSPhilip Paeps <p> 1021e273650fSPhilip Paeps This proleptic <code>TZ</code> string is hard to remember, and 102246bee4edSPhilip Paeps mishandles some timestamps before 2008. 1023e273650fSPhilip Paeps With this package you can use a geographical <code>TZ</code> instead: 102446bee4edSPhilip Paeps </p> 10258d7edd17SPhilip Paeps 10268d7edd17SPhilip Paeps <pre><code>TZ='Pacific/Auckland'</code></pre> 10278d7edd17SPhilip Paeps </li> 1028e273650fSPhilip Paeps</ul> 1029e273650fSPhilip Paeps 1030e273650fSPhilip Paeps<p> 1031e273650fSPhilip PaepsPOSIX.1-2017 also has the limitations of POSIX.1-2024, 1032e273650fSPhilip Paepsdiscussed in the next section. 1033e273650fSPhilip Paeps</p> 1034e273650fSPhilip Paeps 1035e273650fSPhilip Paeps<h3 id="POSIX.1-2024">POSIX.1-2024 properties and limitations</h3> 1036e273650fSPhilip Paeps<p> 1037e273650fSPhilip PaepsPOSIX.1-2024 extends POSIX.1-2017 in the following significant ways: 1038e273650fSPhilip Paeps</p> 1039e273650fSPhilip Paeps<ul> 10408d7edd17SPhilip Paeps <li> 1041e273650fSPhilip Paeps POSIX.1-2024 requires support for geographical <code>TZ</code>. 1042e273650fSPhilip Paeps Earlier POSIX editions require support only for proleptic <code>TZ</code>. 10438d7edd17SPhilip Paeps </li> 10448d7edd17SPhilip Paeps <li> 1045e273650fSPhilip Paeps POSIX.1-2024 requires <code>struct tm</code> 1046e273650fSPhilip Paeps to have a <abbr>UT</abbr> offset member <code>tm_gmtoff</code> 1047e273650fSPhilip Paeps and a time zone abbreviation member <code>tm_zone</code>. 1048e273650fSPhilip Paeps Earlier POSIX editions lack this requirement. 1049e273650fSPhilip Paeps </li> 1050e273650fSPhilip Paeps <li> 1051e273650fSPhilip Paeps DST transition times can range from −167:59:59 1052e273650fSPhilip Paeps to 167:59:59 instead of merely from 00:00:00 to 24:59:59. 1053e273650fSPhilip Paeps This allows for proleptic TZ strings 1054e273650fSPhilip Paeps like <code>"<-02>2<-01>,M3.5.0/-1,M10.5.0/0"</code> 1055e273650fSPhilip Paeps where the transition time −1:00 means 23:00 the previous day. 1056e273650fSPhilip Paeps </li> 1057e273650fSPhilip Paeps</ul> 1058e273650fSPhilip Paeps<p> 1059e273650fSPhilip PaepsHowever POSIX.1-2024, like earlier POSIX editions, has some limitations: 1060e273650fSPhilip Paeps<ul> 1061e273650fSPhilip Paeps <li> 106246bee4edSPhilip Paeps The <code>TZ</code> environment variable is process-global, which 106346bee4edSPhilip Paeps makes it hard to write efficient, thread-safe applications that 106489abb9f8SPhilip Paeps need access to multiple timezones. 10658d7edd17SPhilip Paeps </li> 10668d7edd17SPhilip Paeps <li> 1067d81c2dd9SPhilip Paeps In POSIX, there is no tamper-proof way for a process to learn the 10682865ab3fSPhilip Paeps system's best idea of local (wall clock) time. 106989abb9f8SPhilip Paeps This is important for applications that an administrator wants 107046bee4edSPhilip Paeps used only at certain times – without regard to whether the 107146bee4edSPhilip Paeps user has fiddled the 107246bee4edSPhilip Paeps <code>TZ</code> environment variable. 107346bee4edSPhilip Paeps While an administrator can "do everything in <abbr>UT</abbr>" to 107446bee4edSPhilip Paeps get around the problem, doing so is inconvenient and precludes 107589abb9f8SPhilip Paeps handling daylight saving time shifts – as might be required to 107689abb9f8SPhilip Paeps limit phone calls to off-peak hours. 10778d7edd17SPhilip Paeps </li> 10788d7edd17SPhilip Paeps <li> 1079798c0c0bSPhilip Paeps POSIX requires that <code>time_t</code> clock counts exclude leap 1080798c0c0bSPhilip Paeps seconds. 10818d7edd17SPhilip Paeps </li> 10828d7edd17SPhilip Paeps <li> 1083e273650fSPhilip Paeps POSIX does not define the <abbr>DST</abbr> transitions 1084e273650fSPhilip Paeps for <code>TZ</code> values like 1085e273650fSPhilip Paeps "<code>EST5EDT</code>". 1086e273650fSPhilip Paeps Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules 1087e273650fSPhilip Paeps were used to interpret such values, but this meant that the 1088e273650fSPhilip Paeps <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each 1089e273650fSPhilip Paeps time conversion package, and when 1090e273650fSPhilip Paeps <abbr>US</abbr> time conversion rules changed (as in the United 1091e273650fSPhilip Paeps States in 1987 and again in 2007), all packages that 1092e273650fSPhilip Paeps interpreted <code>TZ</code> values had to be updated 1093e273650fSPhilip Paeps to ensure proper results. 1094e273650fSPhilip Paeps </li> 1095e273650fSPhilip Paeps</ul> 1096e273650fSPhilip Paeps 1097e273650fSPhilip Paeps<h3 id="POSIX-extensions">Extensions to POSIX in the 1098e273650fSPhilip Paeps<code><abbr>tz</abbr></code> code</h3> 1099e273650fSPhilip Paeps<p> 1100e273650fSPhilip Paeps The <code><abbr>tz</abbr></code> code defines some properties 1101e273650fSPhilip Paeps left unspecified by POSIX, and attempts to support some 1102e273650fSPhilip Paeps extensions to POSIX. 1103e273650fSPhilip Paeps</p> 1104e273650fSPhilip Paeps 1105e273650fSPhilip Paeps<ul> 1106e273650fSPhilip Paeps <li> 110746bee4edSPhilip Paeps The <code><abbr>tz</abbr></code> code attempts to support all the 110846bee4edSPhilip Paeps <code>time_t</code> implementations allowed by POSIX. 110946bee4edSPhilip Paeps The <code>time_t</code> type represents a nonnegative count of seconds 111046bee4edSPhilip Paeps since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds. 111146bee4edSPhilip Paeps In practice, <code>time_t</code> is usually a signed 64- or 32-bit 111246bee4edSPhilip Paeps integer; 32-bit signed <code>time_t</code> values stop working after 111346bee4edSPhilip Paeps 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these 111446bee4edSPhilip Paeps days typically use a signed 64-bit integer. 111546bee4edSPhilip Paeps Unsigned 32-bit integers are used on one or two platforms, and 36-bit 111646bee4edSPhilip Paeps and 40-bit integers are also used occasionally. 11178d7edd17SPhilip Paeps Although earlier POSIX versions allowed <code>time_t</code> to be a 111889abb9f8SPhilip Paeps floating-point type, this was not supported by any practical system, 1119e273650fSPhilip Paeps and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both 112046bee4edSPhilip Paeps require <code>time_t</code> to be an integer type. 11218d7edd17SPhilip Paeps </li> 11228d7edd17SPhilip Paeps <li> 11238d7edd17SPhilip Paeps <p> 1124e273650fSPhilip Paeps If the <code>TZ</code> environment variable uses the geographical format, 1125e273650fSPhilip Paeps it is used in generating 1126e273650fSPhilip Paeps the name of a file from which time-related information is read. 112789abb9f8SPhilip Paeps The file's format is <dfn><abbr>TZif</abbr></dfn>, 1128ad48359aSPhilip Paeps a timezone information format that contains binary data; see 1129*46226b01SPhilip Paeps <a href="https://www.rfc-editor.org/rfc/9636">Internet 1130*46226b01SPhilip Paeps <abbr>RFC</abbr> 9636</a>. 113146bee4edSPhilip Paeps The daylight saving time rules to be used for a 113289abb9f8SPhilip Paeps particular timezone are encoded in the 113389abb9f8SPhilip Paeps <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>, 113489abb9f8SPhilip Paeps Australian, and other rules to be encoded, and 113546bee4edSPhilip Paeps allows for situations where more than two time zone 11368d7edd17SPhilip Paeps abbreviations are used. 11378d7edd17SPhilip Paeps </p> 11388d7edd17SPhilip Paeps <p> 1139e273650fSPhilip Paeps When the <code><abbr>tz</abbr></code> code was developed in the 1980s, 1140e273650fSPhilip Paeps it was recognized that allowing the <code>TZ</code> environment 114146bee4edSPhilip Paeps variable to take on values such as '<code>America/New_York</code>' 114246bee4edSPhilip Paeps might cause "old" programs (that expect <code>TZ</code> to have a 1143e273650fSPhilip Paeps certain format) to operate incorrectly; consideration was given to using 114446bee4edSPhilip Paeps some other environment variable (for example, <code>TIMEZONE</code>) 114589abb9f8SPhilip Paeps to hold the string used to generate the <abbr>TZif</abbr> file's name. 114646bee4edSPhilip Paeps In the end, however, it was decided to continue using 114746bee4edSPhilip Paeps <code>TZ</code>: it is widely used for time zone purposes; 114846bee4edSPhilip Paeps separately maintaining both <code>TZ</code> 114946bee4edSPhilip Paeps and <code>TIMEZONE</code> seemed a nuisance; and systems where 115046bee4edSPhilip Paeps "new" forms of <code>TZ</code> might cause problems can simply 115189abb9f8SPhilip Paeps use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which 115289abb9f8SPhilip Paeps can be used by "new" programs as well as by "old" programs that 115389abb9f8SPhilip Paeps assume pre-POSIX <code>TZ</code> values. 11548d7edd17SPhilip Paeps </p> 11558d7edd17SPhilip Paeps </li> 11568d7edd17SPhilip Paeps <li> 11578d7edd17SPhilip Paeps Functions <code>tzalloc</code>, <code>tzfree</code>, 11588d7edd17SPhilip Paeps <code>localtime_rz</code>, and <code>mktime_z</code> for 115946bee4edSPhilip Paeps more-efficient thread-safe applications that need to use multiple 116089abb9f8SPhilip Paeps timezones. 116146bee4edSPhilip Paeps The <code>tzalloc</code> and <code>tzfree</code> functions 116246bee4edSPhilip Paeps allocate and free objects of type <code>timezone_t</code>, 116346bee4edSPhilip Paeps and <code>localtime_rz</code> and <code>mktime_z</code> are 116446bee4edSPhilip Paeps like <code>localtime_r</code> and <code>mktime</code> with an 116546bee4edSPhilip Paeps extra <code>timezone_t</code> argument. 1166e273650fSPhilip Paeps The functions were inspired by <a href="https://netbsd.org">NetBSD</a>. 11678d7edd17SPhilip Paeps </li> 11688d7edd17SPhilip Paeps <li> 11698d7edd17SPhilip Paeps Negative <code>time_t</code> values are supported, on systems 11708d7edd17SPhilip Paeps where <code>time_t</code> is signed. 11718d7edd17SPhilip Paeps </li> 11728d7edd17SPhilip Paeps <li> 1173798c0c0bSPhilip Paeps These functions can account for leap seconds; 1174798c0c0bSPhilip Paeps see <a href="#leapsec">Leap seconds</a> below. 11758d7edd17SPhilip Paeps </li> 11768d7edd17SPhilip Paeps</ul> 117746bee4edSPhilip Paeps 117846bee4edSPhilip Paeps<h3 id="vestigial">POSIX features no longer needed</h3> 11798d7edd17SPhilip Paeps<p> 118046bee4edSPhilip PaepsPOSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a> 118146bee4edSPhilip Paepsdefine some <a href="https://en.wikipedia.org/wiki/API"><abbr 118246bee4edSPhilip Paepstitle="application programming interface">API</abbr>s</a> that are vestigial: 118346bee4edSPhilip Paepsthey are not needed, and are relics of a too-simple model that does 118446bee4edSPhilip Paepsnot suffice to handle many real-world timestamps. 118546bee4edSPhilip PaepsAlthough the <code><abbr>tz</abbr></code> code supports these 118646bee4edSPhilip Paepsvestigial <abbr>API</abbr>s for backwards compatibility, they should 118746bee4edSPhilip Paepsbe avoided in portable applications. 118846bee4edSPhilip PaepsThe vestigial <abbr>API</abbr>s are: 11898d7edd17SPhilip Paeps</p> 11908d7edd17SPhilip Paeps<ul> 11918d7edd17SPhilip Paeps <li> 119246bee4edSPhilip Paeps The POSIX <code>tzname</code> variable does not suffice and is no 119346bee4edSPhilip Paeps longer needed. 1194e273650fSPhilip Paeps It is planned to be removed in a future edition of POSIX. 119546bee4edSPhilip Paeps To get a timestamp's time zone abbreviation, consult 119646bee4edSPhilip Paeps the <code>tm_zone</code> member if available; otherwise, 119746bee4edSPhilip Paeps use <code>strftime</code>'s <code>"%Z"</code> conversion 119846bee4edSPhilip Paeps specification. 11998d7edd17SPhilip Paeps </li> 12008d7edd17SPhilip Paeps <li> 120146bee4edSPhilip Paeps The POSIX <code>daylight</code> and <code>timezone</code> 120246bee4edSPhilip Paeps variables do not suffice and are no longer needed. 1203e273650fSPhilip Paeps They are planned to be removed in a future edition of POSIX. 120446bee4edSPhilip Paeps To get a timestamp's <abbr>UT</abbr> offset, consult 120546bee4edSPhilip Paeps the <code>tm_gmtoff</code> member if available; otherwise, 120646bee4edSPhilip Paeps subtract values returned by <code>localtime</code> 120746bee4edSPhilip Paeps and <code>gmtime</code> using the rules of the Gregorian calendar, 120846bee4edSPhilip Paeps or use <code>strftime</code>'s <code>"%z"</code> conversion 120946bee4edSPhilip Paeps specification if a string like <code>"+0900"</code> suffices. 121046bee4edSPhilip Paeps </li> 121146bee4edSPhilip Paeps <li> 121246bee4edSPhilip Paeps The <code>tm_isdst</code> member is almost never needed and most of 121346bee4edSPhilip Paeps its uses should be discouraged in favor of the abovementioned 121446bee4edSPhilip Paeps <abbr>API</abbr>s. 1215*46226b01SPhilip Paeps It was intended as an index into the <code>tzname</code> variable, 1216*46226b01SPhilip Paeps but as mentioned previously that usage is obsolete. 121746bee4edSPhilip Paeps Although it can still be used in arguments to 121846bee4edSPhilip Paeps <code>mktime</code> to disambiguate timestamps near 12195f33eb72SPhilip Paeps a <abbr>DST</abbr> transition when the clock jumps back on 12205f33eb72SPhilip Paeps platforms lacking <code>tm_gmtoff</code>, this 1221*46226b01SPhilip Paeps disambiguation works only for proleptic <code>TZ</code> strings; 1222*46226b01SPhilip Paeps it does not work in general for geographical timezones, 1223*46226b01SPhilip Paeps such as when a location changes to a time zone with a 122446bee4edSPhilip Paeps lesser <abbr>UT</abbr> offset. 122546bee4edSPhilip Paeps </li> 122646bee4edSPhilip Paeps</ul> 122746bee4edSPhilip Paeps 122846bee4edSPhilip Paeps<h3 id="other-portability">Other portability notes</h3> 122946bee4edSPhilip Paeps<ul> 123046bee4edSPhilip Paeps <li> 123146bee4edSPhilip Paeps The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition 123246bee4edSPhilip Paeps UNIX</a> <code>timezone</code> function is not present in this 1233d81c2dd9SPhilip Paeps package; it is impossible to reliably map <code>timezone</code>'s 123446bee4edSPhilip Paeps arguments (a "minutes west of <abbr>GMT</abbr>" value and a 123546bee4edSPhilip Paeps "daylight saving time in effect" flag) to a time zone 123646bee4edSPhilip Paeps abbreviation, and we refuse to guess. 123746bee4edSPhilip Paeps Programs that in the past used the <code>timezone</code> function 123846bee4edSPhilip Paeps may now examine <code>localtime(&clock)->tm_zone</code> 12398d7edd17SPhilip Paeps (if <code>TM_ZONE</code> is defined) or 1240*46226b01SPhilip Paeps use <code>strftime</code> with a <code>%Z</code> conversion specification 1241*46226b01SPhilip Paeps to learn the correct time 124246bee4edSPhilip Paeps zone abbreviation to use. 12438d7edd17SPhilip Paeps </li> 12448d7edd17SPhilip Paeps <li> 1245d81c2dd9SPhilip Paeps The <a 1246d81c2dd9SPhilip Paeps href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a> 1247d81c2dd9SPhilip Paeps <code>gettimeofday</code> function is not 124846bee4edSPhilip Paeps used in this package. 124946bee4edSPhilip Paeps This formerly let users obtain the current <abbr>UTC</abbr> offset 125046bee4edSPhilip Paeps and <abbr>DST</abbr> flag, but this functionality was removed in 125146bee4edSPhilip Paeps later versions of <abbr>BSD</abbr>. 12528d7edd17SPhilip Paeps </li> 12538d7edd17SPhilip Paeps <li> 125446bee4edSPhilip Paeps In <abbr>SVR2</abbr>, time conversion fails for near-minimum or 125546bee4edSPhilip Paeps near-maximum <code>time_t</code> values when doing conversions 1256d81c2dd9SPhilip Paeps for places that do not use <abbr>UT</abbr>. 12578d7edd17SPhilip Paeps This package takes care to do these conversions correctly. 12588d7edd17SPhilip Paeps A comment in the source code tells how to get compatibly wrong 12598d7edd17SPhilip Paeps results. 12608d7edd17SPhilip Paeps </li> 126146bee4edSPhilip Paeps <li> 12628d7edd17SPhilip Paeps The functions that are conditionally compiled 1263259e2ad7SPhilip Paeps if <code>STD_INSPIRED</code> is nonzero should, at this point, be 126446bee4edSPhilip Paeps looked on primarily as food for thought. 126546bee4edSPhilip Paeps They are not in any sense "standard compatible" – some are 126646bee4edSPhilip Paeps not, in fact, specified in <em>any</em> standard. 126746bee4edSPhilip Paeps They do, however, represent responses of various authors to 12688d7edd17SPhilip Paeps standardization proposals. 126946bee4edSPhilip Paeps </li> 127046bee4edSPhilip Paeps <li> 127189abb9f8SPhilip Paeps Other time conversion proposals, in particular those supported by the 127289abb9f8SPhilip Paeps <a href="https://howardhinnant.github.io/date/tz.html">Time Zone 127389abb9f8SPhilip Paeps Database Parser</a>, offer a wider selection of functions 127446bee4edSPhilip Paeps that provide capabilities beyond those provided here. 127546bee4edSPhilip Paeps The absence of such functions from this package is not meant to 127646bee4edSPhilip Paeps discourage the development, standardization, or use of such 127746bee4edSPhilip Paeps functions. 127846bee4edSPhilip Paeps Rather, their absence reflects the decision to make this package 127946bee4edSPhilip Paeps contain valid extensions to POSIX, to ensure its broad 128046bee4edSPhilip Paeps acceptability. 128146bee4edSPhilip Paeps If more powerful time conversion functions can be standardized, so 128246bee4edSPhilip Paeps much the better. 128346bee4edSPhilip Paeps </li> 128446bee4edSPhilip Paeps</ul> 12858d7edd17SPhilip Paeps</section> 12868d7edd17SPhilip Paeps 12878d7edd17SPhilip Paeps<section> 12888d7edd17SPhilip Paeps <h2 id="stability">Interface stability</h2> 12898d7edd17SPhilip Paeps<p> 129046bee4edSPhilip PaepsThe <code><abbr>tz</abbr></code> code and data supply the following interfaces: 12918d7edd17SPhilip Paeps</p> 129246bee4edSPhilip Paeps 12938d7edd17SPhilip Paeps<ul> 12948d7edd17SPhilip Paeps <li> 129589abb9f8SPhilip Paeps A set of timezone names as per 1296ad48359aSPhilip Paeps "<a href="#naming">Timezone identifiers</a>" above. 12978d7edd17SPhilip Paeps </li> 12988d7edd17SPhilip Paeps <li> 12998d7edd17SPhilip Paeps Library functions described in "<a href="#functions">Time and date 13008d7edd17SPhilip Paeps functions</a>" above. 13018d7edd17SPhilip Paeps </li> 13028d7edd17SPhilip Paeps <li> 13038d7edd17SPhilip Paeps The programs <code>tzselect</code>, <code>zdump</code>, 13048d7edd17SPhilip Paeps and <code>zic</code>, documented in their man pages. 13058d7edd17SPhilip Paeps </li> 13068d7edd17SPhilip Paeps <li> 13078d7edd17SPhilip Paeps The format of <code>zic</code> input files, documented in 13088d7edd17SPhilip Paeps the <code>zic</code> man page. 13098d7edd17SPhilip Paeps </li> 13108d7edd17SPhilip Paeps <li> 13118d7edd17SPhilip Paeps The format of <code>zic</code> output files, documented in 13128d7edd17SPhilip Paeps the <code>tzfile</code> man page. 13138d7edd17SPhilip Paeps </li> 13148d7edd17SPhilip Paeps <li> 13158d7edd17SPhilip Paeps The format of zone table files, documented in <code>zone1970.tab</code>. 13168d7edd17SPhilip Paeps </li> 13178d7edd17SPhilip Paeps <li> 13188d7edd17SPhilip Paeps The format of the country code file, documented in <code>iso3166.tab</code>. 13198d7edd17SPhilip Paeps </li> 13208d7edd17SPhilip Paeps <li> 13218d7edd17SPhilip Paeps The version number of the code and data, as the first line of 13228d7edd17SPhilip Paeps the text file '<code>version</code>' in each release. 13238d7edd17SPhilip Paeps </li> 13248d7edd17SPhilip Paeps</ul> 132546bee4edSPhilip Paeps 13268d7edd17SPhilip Paeps<p> 13278d7edd17SPhilip PaepsInterface changes in a release attempt to preserve compatibility with 132846bee4edSPhilip Paepsrecent releases. 132946bee4edSPhilip PaepsFor example, <code><abbr>tz</abbr></code> data files typically do not 1330259e2ad7SPhilip Paepsrely on recently added <code>zic</code> features, so that users can 133146bee4edSPhilip Paepsrun older <code>zic</code> versions to process newer data files. 133246bee4edSPhilip Paeps<a href="tz-link.html#download">Downloading 133346bee4edSPhilip Paepsthe <code><abbr>tz</abbr></code> database</a> describes how releases 133446bee4edSPhilip Paepsare tagged and distributed. 13358d7edd17SPhilip Paeps</p> 13368d7edd17SPhilip Paeps 13378d7edd17SPhilip Paeps<p> 133846bee4edSPhilip PaepsInterfaces not listed above are less stable. 133946bee4edSPhilip PaepsFor example, users should not rely on particular <abbr>UT</abbr> 134046bee4edSPhilip Paepsoffsets or abbreviations for timestamps, as data entries are often 134146bee4edSPhilip Paepsbased on guesswork and these guesses may be corrected or improved. 13428d7edd17SPhilip Paeps</p> 1343ad48359aSPhilip Paeps 1344ad48359aSPhilip Paeps<p> 1345ad48359aSPhilip PaepsTimezone boundaries are not part of the stable interface. 1346ad48359aSPhilip PaepsFor example, even though the <samp>Asia/Bangkok</samp> timezone 1347ad48359aSPhilip Paepscurrently includes Chang Mai, Hanoi, and Phnom Penh, this is not part 1348ad48359aSPhilip Paepsof the stable interface and the timezone can split at any time. 1349ad48359aSPhilip PaepsIf a calendar application records a future event in some location other 1350ad48359aSPhilip Paepsthan Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record, 1351ad48359aSPhilip Paepsthe application should be robust in the presence of timezone splits 1352ad48359aSPhilip Paepsbetween now and the future time. 1353ad48359aSPhilip Paeps</p> 13548d7edd17SPhilip Paeps</section> 13558d7edd17SPhilip Paeps 13568d7edd17SPhilip Paeps<section> 1357798c0c0bSPhilip Paeps <h2 id="leapsec">Leap seconds</h2> 1358798c0c0bSPhilip Paeps<p> 1359259e2ad7SPhilip PaepsLeap seconds were introduced in 1972 to accommodate the 1360259e2ad7SPhilip Paepsdifference between atomic time and the less regular rotation of the earth. 1361e273650fSPhilip PaepsUnfortunately they have caused so many problems with civil 1362e273650fSPhilip Paepstimekeeping that there are 1363e273650fSPhilip Paeps<a href="https://www.bipm.org/en/cgpm-2022/resolution-4">plans 1364e273650fSPhilip Paepsto discontinue them by 2035</a>. 1365e273650fSPhilip PaepsEven if these plans come to fruition, a record of leap seconds will still be 1366e273650fSPhilip Paepsneeded to resolve timestamps from 1972 through 2035, 1367e273650fSPhilip Paepsand there may also be a need to record whatever mechanism replaces them. 1368259e2ad7SPhilip Paeps</p> 1369259e2ad7SPhilip Paeps 1370259e2ad7SPhilip Paeps<p> 1371798c0c0bSPhilip PaepsThe <code><abbr>tz</abbr></code> code and data can account for leap seconds, 1372798c0c0bSPhilip Paepsthanks to code contributed by Bradley White. 1373798c0c0bSPhilip PaepsHowever, the leap second support of this package is rarely used directly 1374798c0c0bSPhilip Paepsbecause POSIX requires leap seconds to be excluded and many 1375798c0c0bSPhilip Paepssoftware packages would mishandle leap seconds if they were present. 1376798c0c0bSPhilip PaepsInstead, leap seconds are more commonly handled by occasionally adjusting 1377798c0c0bSPhilip Paepsthe operating system kernel clock as described in 1378798c0c0bSPhilip Paeps<a href="tz-link.html#precision">Precision timekeeping</a>, 1379798c0c0bSPhilip Paepsand this package by default installs a <samp>leapseconds</samp> file 1380798c0c0bSPhilip Paepscommonly used by 13815f33eb72SPhilip Paeps<a href="https://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a> 1382798c0c0bSPhilip Paepssoftware that adjusts the kernel clock. 1383798c0c0bSPhilip PaepsHowever, kernel-clock twiddling approximates UTC only roughly, 1384259e2ad7SPhilip Paepsand systems needing more precise UTC can use this package's leap 1385798c0c0bSPhilip Paepssecond support directly. 1386798c0c0bSPhilip Paeps</p> 1387798c0c0bSPhilip Paeps 1388798c0c0bSPhilip Paeps<p> 1389259e2ad7SPhilip PaepsThe directly supported mechanism assumes that <code>time_t</code> 1390798c0c0bSPhilip Paepscounts of seconds since the POSIX epoch normally include leap seconds, 1391798c0c0bSPhilip Paepsas opposed to POSIX <code>time_t</code> counts which exclude leap seconds. 1392798c0c0bSPhilip PaepsThis modified timescale is converted to <abbr>UTC</abbr> 139394c2d487SPhilip Paepsat the same point that time zone and <abbr>DST</abbr> 139494c2d487SPhilip Paepsadjustments are applied – 1395798c0c0bSPhilip Paepsnamely, at calls to <code>localtime</code> and analogous functions – 1396798c0c0bSPhilip Paepsand the process is driven by leap second information 1397798c0c0bSPhilip Paepsstored in alternate versions of the <abbr>TZif</abbr> files. 1398798c0c0bSPhilip PaepsBecause a leap second adjustment may be needed even 1399798c0c0bSPhilip Paepsif no time zone correction is desired, 1400798c0c0bSPhilip Paepscalls to <code>gmtime</code>-like functions 1401798c0c0bSPhilip Paepsalso need to consult a <abbr>TZif</abbr> file, 14029f9fc6bbSPhilip Paepsconventionally named <samp><abbr>Etc/UTC</abbr></samp> 14039f9fc6bbSPhilip Paeps(<samp><abbr>GMT</abbr></samp> in previous versions), 1404798c0c0bSPhilip Paepsto see whether leap second corrections are needed. 1405798c0c0bSPhilip PaepsTo convert an application's <code>time_t</code> timestamps to or from 1406798c0c0bSPhilip PaepsPOSIX <code>time_t</code> timestamps (for use when, say, 1407798c0c0bSPhilip Paepsembedding or interpreting timestamps in portable 1408798c0c0bSPhilip Paeps<a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a> 1409798c0c0bSPhilip Paepsfiles), 1410798c0c0bSPhilip Paepsthe application can call the utility functions 1411798c0c0bSPhilip Paeps<code>time2posix</code> and <code>posix2time</code> 1412798c0c0bSPhilip Paepsincluded with this package. 1413798c0c0bSPhilip Paeps</p> 1414798c0c0bSPhilip Paeps 1415798c0c0bSPhilip Paeps<p> 1416798c0c0bSPhilip PaepsIf the POSIX-compatible <abbr>TZif</abbr> file set is installed 1417798c0c0bSPhilip Paepsin a directory whose basename is <samp>zoneinfo</samp>, the 1418798c0c0bSPhilip Paepsleap-second-aware file set is by default installed in a separate 1419798c0c0bSPhilip Paepsdirectory <samp>zoneinfo-leaps</samp>. 1420798c0c0bSPhilip PaepsAlthough each process can have its own time zone by setting 1421798c0c0bSPhilip Paepsits <code>TZ</code> environment variable, there is no support for some 1422798c0c0bSPhilip Paepsprocesses being leap-second aware while other processes are 1423798c0c0bSPhilip PaepsPOSIX-compatible; the leap-second choice is system-wide. 1424798c0c0bSPhilip PaepsSo if you configure your kernel to count leap seconds, you should also 1425798c0c0bSPhilip Paepsdiscard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp> 1426798c0c0bSPhilip Paepsto <samp>zoneinfo</samp>. 1427798c0c0bSPhilip PaepsAlternatively, you can install just one set of <abbr>TZif</abbr> files 1428798c0c0bSPhilip Paepsin the first place; see the <code>REDO</code> variable in this package's 1429798c0c0bSPhilip Paeps<a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>. 1430798c0c0bSPhilip Paeps</p> 1431798c0c0bSPhilip Paeps</section> 1432798c0c0bSPhilip Paeps 1433798c0c0bSPhilip Paeps<section> 14348d7edd17SPhilip Paeps <h2 id="calendar">Calendrical issues</h2> 14358d7edd17SPhilip Paeps<p> 14368d7edd17SPhilip PaepsCalendrical issues are a bit out of scope for a time zone database, 14378d7edd17SPhilip Paepsbut they indicate the sort of problems that we would run into if we 143846bee4edSPhilip Paepsextended the time zone database further into the past. 1439d81c2dd9SPhilip PaepsAn excellent resource in this area is Edward M. Reingold 1440d81c2dd9SPhilip Paepsand Nachum Dershowitz, <cite><a 1441d81c2dd9SPhilip Paepshref="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical 1442d81c2dd9SPhilip PaepsCalculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018). 144346bee4edSPhilip PaepsOther information and sources are given in the file '<code>calendars</code>' 144446bee4edSPhilip Paepsin the <code><abbr>tz</abbr></code> distribution. 144546bee4edSPhilip PaepsThey sometimes disagree. 14468d7edd17SPhilip Paeps</p> 14478d7edd17SPhilip Paeps</section> 14488d7edd17SPhilip Paeps 14498d7edd17SPhilip Paeps<section> 1450259e2ad7SPhilip Paeps <h2 id="planets">Time and time zones off Earth</h2> 1451259e2ad7SPhilip Paeps<p> 1452259e2ad7SPhilip PaepsThe European Space Agency is <a 1453259e2ad7SPhilip Paepshref='https://www.esa.int/Applications/Navigation/Telling_time_on_the_Moon'>considering</a> 1454259e2ad7SPhilip Paepsthe establishment of a reference timescale for the Moon, which has 1455259e2ad7SPhilip Paepsdays roughly equivalent to 29.5 Earth days, and where relativistic 1456259e2ad7SPhilip Paepseffects cause clocks to tick slightly faster than on Earth. 1457e273650fSPhilip PaepsAlso, <abbr title="National Aeronautics and Space Administration">NASA</abbr> 1458e273650fSPhilip Paepshas been <a 1459e273650fSPhilip Paepshref='https://www.whitehouse.gov/wp-content/uploads/2024/04/Celestial-Time-Standardization-Policy.pdf'>ordered</a> 1460e273650fSPhilip Paepsto consider the establishment of Coordinated Lunar Time (<abbr>LTC</abbr>). 1461e273650fSPhilip PaepsIt is not yet known whether the US and European efforts will result in 1462e273650fSPhilip Paepsmultiple timescales on the Moon. 1463259e2ad7SPhilip Paeps</p> 1464259e2ad7SPhilip Paeps 14658d7edd17SPhilip Paeps<p> 146612a899b6SPhilip PaepsSome people's work schedules have used 146712a899b6SPhilip Paeps<a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>. 1468d81c2dd9SPhilip PaepsJet Propulsion Laboratory (JPL) coordinators kept Mars time on 1469d81c2dd9SPhilip Paepsand off during the 14702c5e84ccSPhilip Paeps<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars 147112a899b6SPhilip PaepsPathfinder</a> mission (1997). 1472d81c2dd9SPhilip PaepsSome of their family members also adapted to Mars time. 147346bee4edSPhilip PaepsDozens of special Mars watches were built for JPL workers who kept 147412a899b6SPhilip PaepsMars time during the 147512a899b6SPhilip Paeps<a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars 147612a899b6SPhilip PaepsExploration Rovers (MER)</a> mission (2004–2018). 147712a899b6SPhilip PaepsThese timepieces looked like normal Seikos and Citizens but were adjusted 147812a899b6SPhilip Paepsto use Mars seconds rather than terrestrial seconds, although 147912a899b6SPhilip Paepsunfortunately the adjusted watches were unreliable and appear to have 148012a899b6SPhilip Paepshad only limited use. 14818d7edd17SPhilip Paeps</p> 14828d7edd17SPhilip Paeps 14838d7edd17SPhilip Paeps<p> 14848d7edd17SPhilip PaepsA Mars solar day is called a "sol" and has a mean period equal to 148546bee4edSPhilip Paepsabout 24 hours 39 minutes 35.244 seconds in terrestrial time. 148646bee4edSPhilip PaepsIt is divided into a conventional 24-hour clock, so each Mars second 148746bee4edSPhilip Paepsequals about 1.02749125 terrestrial seconds. 148812a899b6SPhilip Paeps(One MER worker noted, "If I am working Mars hours, and Mars hours are 148912a899b6SPhilip Paeps2.5% more than Earth hours, shouldn't I get an extra 2.5% pay raise?") 14908d7edd17SPhilip Paeps</p> 14918d7edd17SPhilip Paeps 14928d7edd17SPhilip Paeps<p> 149346bee4edSPhilip PaepsThe <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime 149446bee4edSPhilip Paepsmeridian</a> of Mars goes through the center of the crater 149546bee4edSPhilip Paeps<a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in 149646bee4edSPhilip Paepshonor of the British astronomer who built the Greenwich telescope that 149746bee4edSPhilip Paepsdefines Earth's prime meridian. 149846bee4edSPhilip PaepsMean solar time on the Mars prime meridian is 14992c5e84ccSPhilip Paepscalled Mars Coordinated Time (<abbr>MTC</abbr>). 15008d7edd17SPhilip Paeps</p> 15018d7edd17SPhilip Paeps 15028d7edd17SPhilip Paeps<p> 15038d7edd17SPhilip PaepsEach landed mission on Mars has adopted a different reference for 15048d7edd17SPhilip Paepssolar timekeeping, so there is no real standard for Mars time zones. 150512a899b6SPhilip PaepsFor example, the MER mission defined two time zones "Local 150646bee4edSPhilip PaepsSolar Time A" and "Local Solar Time B" for its two missions, each zone 150746bee4edSPhilip Paepsdesigned so that its time equals local true solar time at 150846bee4edSPhilip Paepsapproximately the middle of the nominal mission. 150912a899b6SPhilip PaepsThe A and B zones differ enough so that an MER worker assigned to 151012a899b6SPhilip Paepsthe A zone might suffer "Mars lag" when switching to work in the B zone. 151146bee4edSPhilip PaepsSuch a "time zone" is not particularly suited for any application 151246bee4edSPhilip Paepsother than the mission itself. 15138d7edd17SPhilip Paeps</p> 15148d7edd17SPhilip Paeps 15158d7edd17SPhilip Paeps<p> 15168d7edd17SPhilip PaepsMany calendars have been proposed for Mars, but none have achieved 151746bee4edSPhilip Paepswide acceptance. 151846bee4edSPhilip PaepsAstronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a 15198d7edd17SPhilip Paepssequential count of Mars solar days elapsed since about 1873-12-29 152046bee4edSPhilip Paeps12:00 <abbr>GMT</abbr>. 15218d7edd17SPhilip Paeps</p> 15228d7edd17SPhilip Paeps 15238d7edd17SPhilip Paeps<p> 15248d7edd17SPhilip PaepsIn our solar system, Mars is the planet with time and calendar most 152546bee4edSPhilip Paepslike Earth's. 152646bee4edSPhilip PaepsOn other planets, Sun-based time and calendars would work quite 152746bee4edSPhilip Paepsdifferently. 152846bee4edSPhilip PaepsFor example, although Mercury's 152946bee4edSPhilip Paeps<a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal 153046bee4edSPhilip Paepsrotation period</a> is 58.646 Earth days, Mercury revolves around the 153146bee4edSPhilip PaepsSun so rapidly that an observer on Mercury's equator would see a 153246bee4edSPhilip Paepssunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a 153346bee4edSPhilip PaepsMercury day. 153446bee4edSPhilip PaepsVenus is more complicated, partly because its rotation is slightly 153546bee4edSPhilip Paeps<a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>: 153646bee4edSPhilip Paepsits year is 1.92 of its days. 153746bee4edSPhilip PaepsGas giants like Jupiter are trickier still, as their polar and 153846bee4edSPhilip Paepsequatorial regions rotate at different rates, so that the length of a 153946bee4edSPhilip Paepsday depends on latitude. 154046bee4edSPhilip PaepsThis effect is most pronounced on Neptune, where the day is about 12 154146bee4edSPhilip Paepshours at the poles and 18 hours at the equator. 15428d7edd17SPhilip Paeps</p> 15438d7edd17SPhilip Paeps 15448d7edd17SPhilip Paeps<p> 154546bee4edSPhilip PaepsAlthough the <code><abbr>tz</abbr></code> database does not support 154646bee4edSPhilip Paepstime on other planets, it is documented here in the hopes that support 154746bee4edSPhilip Paepswill be added eventually. 15488d7edd17SPhilip Paeps</p> 15498d7edd17SPhilip Paeps 15508d7edd17SPhilip Paeps<p> 155146bee4edSPhilip PaepsSources for time on other planets: 15528d7edd17SPhilip Paeps</p> 155346bee4edSPhilip Paeps 15548d7edd17SPhilip Paeps<ul> 15558d7edd17SPhilip Paeps <li> 15568d7edd17SPhilip Paeps Michael Allison and Robert Schmunk, 15578d7edd17SPhilip Paeps "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical 15588d7edd17SPhilip Paeps Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" 155912a899b6SPhilip Paeps (2020-03-08). 156012a899b6SPhilip Paeps </li> 156112a899b6SPhilip Paeps <li> 156212a899b6SPhilip Paeps Zara Mirmalek, 156312a899b6SPhilip Paeps <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making 156412a899b6SPhilip Paeps Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854. 15658d7edd17SPhilip Paeps </li> 15668d7edd17SPhilip Paeps <li> 15678d7edd17SPhilip Paeps Jia-Rui Chong, 15682865ab3fSPhilip Paeps "<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays 156946bee4edSPhilip Paeps Fit for a Martian</a>", <cite>Los Angeles Times</cite> 1570d81c2dd9SPhilip Paeps (2004-01-14), pp A1, A20–A21. 15718d7edd17SPhilip Paeps </li> 15728d7edd17SPhilip Paeps <li> 15738d7edd17SPhilip Paeps Tom Chmielewski, 15748d7edd17SPhilip Paeps "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet 157546bee4edSPhilip Paeps Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26) 15768d7edd17SPhilip Paeps </li> 15778d7edd17SPhilip Paeps <li> 15788d7edd17SPhilip Paeps Matt Williams, 15798d7edd17SPhilip Paeps "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How 15808d7edd17SPhilip Paeps long is a day on the other planets of the solar system?</a>" 158189abb9f8SPhilip Paeps (2016-01-20). 15828d7edd17SPhilip Paeps </li> 15838d7edd17SPhilip Paeps</ul> 15848d7edd17SPhilip Paeps</section> 15858d7edd17SPhilip Paeps 15868d7edd17SPhilip Paeps<footer> 15878d7edd17SPhilip Paeps <hr> 15888d7edd17SPhilip Paeps This file is in the public domain, so clarified as of 2009-05-17 by 15898d7edd17SPhilip Paeps Arthur David Olson. 15908d7edd17SPhilip Paeps</footer> 15918d7edd17SPhilip Paeps</body> 15928d7edd17SPhilip Paeps</html> 1593