1339631Sphilip<!DOCTYPE html> 2325057Sphilip<html lang="en"> 3325057Sphilip<head> 4325057Sphilip <title>Theory and pragmatics of the tz code and data</title> 5325057Sphilip <meta charset="UTF-8"> 6339631Sphilip <style> 7339631Sphilip pre {margin-left: 2em; white-space: pre-wrap;} 8339631Sphilip </style> 9325057Sphilip</head> 10325057Sphilip 11325057Sphilip<body> 12331663Sphilip<h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1> 13325057Sphilip <h3>Outline</h3> 14325057Sphilip <nav> 15325057Sphilip <ul> 16331663Sphilip <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code> 17331663Sphilip database</a></li> 18345671Sphilip <li><a href="#naming">Timezone identifiers</a></li> 19325057Sphilip <li><a href="#abbreviations">Time zone abbreviations</a></li> 20331663Sphilip <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code> 21331663Sphilip database</a></li> 22325057Sphilip <li><a href="#functions">Time and date functions</a></li> 23325057Sphilip <li><a href="#stability">Interface stability</a></li> 24325057Sphilip <li><a href="#calendar">Calendrical issues</a></li> 25325057Sphilip <li><a href="#planets">Time and time zones on other planets</a></li> 26325057Sphilip </ul> 27325057Sphilip </nav> 28325057Sphilip 29331663Sphilip<section> 30331663Sphilip <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2> 31325057Sphilip<p> 32331663SphilipThe <a 33331663Sphiliphref="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code> 34331663Sphilipdatabase</a> attempts to record the history and predicted future of 35331663Sphilipall computer-based clocks that track civil time. 36331663SphilipIt organizes <a href="tz-link.html">time zone and daylight saving time 37331663Sphilipdata</a> by partitioning the world into <a 38339631Sphiliphref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a> 39333313Sphilipwhose clocks all agree about timestamps that occur after the <a 40331663Sphiliphref="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a> 41331663Sphilip(1970-01-01 00:00:00 <a 42331663Sphiliphref="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr 43331663Sphiliptitle="Coordinated Universal Time">UTC</abbr></a>). 44339631SphilipThe database labels each timezone with a notable location and 45331663Sphiliprecords all known clock transitions for that location. 46331663SphilipAlthough 1970 is a somewhat-arbitrary cutoff, there are significant 47331663Sphilipchallenges to moving the cutoff earlier even by a decade or two, due 48331663Sphilipto the wide variety of local practices before computer timekeeping 49331663Sphilipbecame prevalent. 50325057Sphilip</p> 51325057Sphilip 52325057Sphilip<p> 53339631SphilipEach timezone typically corresponds to a geographical region that is 54339631Sphilipsmaller than a traditional time zone, because clocks in a timezone 55339631Sphilipall agree after 1970 whereas a traditional time zone merely 56339631Sphilipspecifies current standard time. For example, applications that deal 57339631Sphilipwith current and future timestamps in the traditional North 58339631SphilipAmerican mountain time zone can choose from the timezones 59339631Sphilip<code>America/Denver</code> which observes US-style daylight saving 60339631Sphiliptime, <code>America/Mazatlan</code> which observes Mexican-style DST, 61339631Sphilipand <code>America/Phoenix</code> which does not observe DST. 62339631SphilipApplications that also deal with past timestamps in the mountain time 63339631Sphilipzone can choose from over a dozen timezones, such as 64339631Sphilip<code>America/Boise</code>, <code>America/Edmonton</code>, and 65339631Sphilip<code>America/Hermosillo</code>, each of which currently uses mountain 66339631Sphiliptime but differs from other timezones for some timestamps after 1970. 67339631Sphilip</p> 68339631Sphilip 69339631Sphilip<p> 70339631SphilipClock transitions before 1970 are recorded for each timezone, 71325057Sphilipbecause most systems support timestamps before 1970 and could 72325057Sphilipmisbehave if data entries were omitted for pre-1970 transitions. 73325057SphilipHowever, the database is not designed for and does not suffice for 74325057Sphilipapplications requiring accurate handling of all past times everywhere, 75325057Sphilipas it would take far too much effort and guesswork to record all 76325057Sphilipdetails of pre-1970 civil timekeeping. 77333313SphilipAlthough some information outside the scope of the database is 78328476Sphilipcollected in a file <code>backzone</code> that is distributed along 79328476Sphilipwith the database proper, this file is less reliable and does not 80328476Sphilipnecessarily follow database guidelines. 81325057Sphilip</p> 82325057Sphilip 83325057Sphilip<p> 84331663SphilipAs described below, reference source code for using the 85331663Sphilip<code><abbr>tz</abbr></code> database is also available. 86331663SphilipThe <code><abbr>tz</abbr></code> code is upwards compatible with <a 87331663Sphiliphref="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international 88331663Sphilipstandard for <a 89331663Sphiliphref="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems. 90331663SphilipAs of this writing, the current edition of POSIX is: <a 91331663Sphiliphref="http://pubs.opengroup.org/onlinepubs/9699919799/"> The Open 92333313SphilipGroup Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018 93331663SphilipEdition. 94331663SphilipBecause the database's scope encompasses real-world changes to civil 95331663Sphiliptimekeeping, its model for describing time is more complex than the 96331663Sphilipstandard and daylight saving times supported by POSIX. 97339631SphilipA <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can 98331663Sphiliphave more than two changes per year, these changes need not merely 99331663Sphilipflip back and forth between two alternatives, and the rules themselves 100331663Sphilipcan change at times. 101339631SphilipWhether and when a timezone changes its 102339631Sphilipclock, and even the timezone's notional base offset from UTC, are variable. 103339631SphilipIt does not always make sense to talk about a timezone's 104339631Sphilip"base offset", which is not necessarily a single number. 105325057Sphilip</p> 106325057Sphilip 107331663Sphilip</section> 108325057Sphilip 109331663Sphilip<section> 110345671Sphilip <h2 id="naming">Timezone identifiers</h2> 111325057Sphilip<p> 112345671SphilipEach timezone has a name that uniquely identifies the timezone. 113325057SphilipInexperienced users are not expected to select these names unaided. 114325057SphilipDistributors should provide documentation and/or a simple selection 115339631Sphilipinterface that explains each name via a map or via descriptive text like 116339631Sphilip"Ruthenia" instead of the timezone name "<code>Europe/Uzhgorod</code>". 117339631SphilipIf geolocation information is available, a selection interface can 118339631Sphiliplocate the user on a timezone map or prioritize names that are 119339631Sphilipgeographically close. For an example selection interface, see the 120333313Sphilip<code>tzselect</code> program in the <code><abbr>tz</abbr></code> code. 121331663SphilipThe <a href="http://cldr.unicode.org/">Unicode Common Locale Data 122331663SphilipRepository</a> contains data that may be useful for other selection 123339631Sphilipinterfaces; it maps timezone names like <code>Europe/Uzhgorod</code> 124339631Sphilipto CLDR names like <code>uauzh</code> which are in turn mapped to 125339631Sphiliplocale-dependent strings like "Uzhhorod", "Ungv��r", "��������������", and 126339631Sphilip"���������������". 127325057Sphilip</p> 128325057Sphilip 129325057Sphilip<p> 130331663SphilipThe naming conventions attempt to strike a balance 131325057Sphilipamong the following goals: 132325057Sphilip</p> 133331663Sphilip 134325057Sphilip<ul> 135325057Sphilip <li> 136339631Sphilip Uniquely identify every timezone where clocks have agreed since 1970. 137331663Sphilip This is essential for the intended use: static clocks keeping local 138331663Sphilip civil time. 139325057Sphilip </li> 140325057Sphilip <li> 141339631Sphilip Indicate to experts where the timezone's clocks typically are. 142325057Sphilip </li> 143325057Sphilip <li> 144331663Sphilip Be robust in the presence of political changes. 145345671Sphilip For example, names are typically not tied to countries, to avoid 146331663Sphilip incompatibilities when countries change their name (e.g., 147345671Sphilip Swaziland→Eswatini) or when locations change countries (e.g., Hong 148331663Sphilip Kong from UK colony to China). 149345671Sphilip There is no requirement that every country or national 150345671Sphilip capital must have a timezone name. 151325057Sphilip </li> 152325057Sphilip <li> 153331663Sphilip Be portable to a wide variety of implementations. 154325057Sphilip </li> 155325057Sphilip <li> 156331663Sphilip Use a consistent naming conventions over the entire world. 157325057Sphilip </li> 158325057Sphilip</ul> 159331663Sphilip 160325057Sphilip<p> 161331663SphilipNames normally have the form 162331663Sphilip<var>AREA</var><code>/</code><var>LOCATION</var>, where 163339631Sphilip<var>AREA</var> is a continent or ocean, and 164339631Sphilip<var>LOCATION</var> is a specific location within the area. 165331663SphilipNorth and South America share the same area, '<code>America</code>'. 166331663SphilipTypical names are '<code>Africa/Cairo</code>', 167331663Sphilip'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'. 168333313SphilipSome names are further qualified to help avoid confusion; for example, 169333313Sphilip'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg, 170333313SphilipIndiana from other Petersburgs in America. 171325057Sphilip</p> 172325057Sphilip 173325057Sphilip<p> 174331663SphilipHere are the general guidelines used for 175339631Sphilipchoosing timezone names, 176325057Sphilipin decreasing order of importance: 177325057Sphilip</p> 178331663Sphilip 179325057Sphilip<ul> 180325057Sphilip <li> 181331663Sphilip Use only valid POSIX file name components (i.e., the parts of 182331663Sphilip names other than '<code>/</code>'). 183331663Sphilip Do not use the file name components '<code>.</code>' and 184331663Sphilip '<code>..</code>'. 185331663Sphilip Within a file name component, use only <a 186331663Sphilip href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters, 187331663Sphilip '<code>.</code>', '<code>-</code>' and '<code>_</code>'. 188331663Sphilip Do not use digits, as that might create an ambiguity with <a 189331663Sphilip href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX 190331663Sphilip <code>TZ</code> strings</a>. 191331663Sphilip A file name component must not exceed 14 characters or start with 192331663Sphilip '<code>-</code>'. 193333313Sphilip E.g., prefer <code>Asia/Brunei</code> to 194333313Sphilip <code>Asia/Bandar_Seri_Begawan</code>. 195331663Sphilip Exceptions: see the discussion of legacy names below. 196325057Sphilip </li> 197325057Sphilip <li> 198331663Sphilip A name must not be empty, or contain '<code>//</code>', or 199331663Sphilip start or end with '<code>/</code>'. 200325057Sphilip </li> 201325057Sphilip <li> 202331663Sphilip Do not use names that differ only in case. 203331663Sphilip Although the reference implementation is case-sensitive, some 204331663Sphilip other implementations are not, and they would mishandle names 205331663Sphilip differing only in case. 206325057Sphilip </li> 207325057Sphilip <li> 208331663Sphilip If one name <var>A</var> is an initial prefix of another 209331663Sphilip name <var>AB</var> (ignoring case), then <var>B</var> must not 210331663Sphilip start with '<code>/</code>', as a regular file cannot have the 211331663Sphilip same name as a directory in POSIX. 212333313Sphilip For example, <code>America/New_York</code> precludes 213333313Sphilip <code>America/New_York/Bronx</code>. 214325057Sphilip </li> 215325057Sphilip <li> 216331663Sphilip Uninhabited regions like the North Pole and Bouvet Island 217331663Sphilip do not need locations, since local time is not defined there. 218325057Sphilip </li> 219325057Sphilip <li> 220339631Sphilip If all the clocks in a timezone have agreed since 1970, 221339631Sphilip do not bother to include more than one timezone 222339631Sphilip even if some of the clocks disagreed before 1970. 223331663Sphilip Otherwise these tables would become annoyingly large. 224325057Sphilip </li> 225325057Sphilip <li> 226345671Sphilip If boundaries between regions are fluid, such as during a war or 227345671Sphilip insurrection, do not bother to create a new timezone merely 228345671Sphilip because of yet another boundary change. This helps prevent table 229345671Sphilip bloat and simplifies maintenance. 230345671Sphilip </li> 231345671Sphilip <li> 232331663Sphilip If a name is ambiguous, use a less ambiguous alternative; 233331663Sphilip e.g., many cities are named San Jos�� and Georgetown, so 234333313Sphilip prefer <code>America/Costa_Rica</code> to 235333313Sphilip <code>America/San_Jose</code> and <code>America/Guyana</code> 236333313Sphilip to <code>America/Georgetown</code>. 237325057Sphilip </li> 238325057Sphilip <li> 239331663Sphilip Keep locations compact. 240331663Sphilip Use cities or small islands, not countries or regions, so that any 241331663Sphilip future changes do not split individual locations into different 242339631Sphilip timezones. 243333313Sphilip E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>, 244333313Sphilip since 245331663Sphilip <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France 246331663Sphilip has had multiple time zones</a>. 247325057Sphilip </li> 248325057Sphilip <li> 249333313Sphilip Use mainstream English spelling, e.g., prefer 250339631Sphilip <code>Europe/Rome</code> to <code>Europa/Roma</code>, and 251333313Sphilip prefer <code>Europe/Athens</code> to the Greek 252339631Sphilip <code>������������/����������</code> or the Romanized 253339631Sphilip <code>Evr��pi/Ath��na</code>. 254331663Sphilip The POSIX file name restrictions encourage this guideline. 255325057Sphilip </li> 256325057Sphilip <li> 257331663Sphilip Use the most populous among locations in a region, 258333313Sphilip e.g., prefer <code>Asia/Shanghai</code> to 259333313Sphilip <code>Asia/Beijing</code>. 260331663Sphilip Among locations with similar populations, pick the best-known 261333313Sphilip location, e.g., prefer <code>Europe/Rome</code> to 262333313Sphilip <code>Europe/Milan</code>. 263325057Sphilip </li> 264325057Sphilip <li> 265333313Sphilip Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to 266333313Sphilip <code>Atlantic/Canaries</code>. 267325057Sphilip </li> 268325057Sphilip <li> 269331663Sphilip Omit common suffixes like '<code>_Islands</code>' and 270331663Sphilip '<code>_City</code>', unless that would lead to ambiguity. 271333313Sphilip E.g., prefer <code>America/Cayman</code> to 272333313Sphilip <code>America/Cayman_Islands</code> and 273333313Sphilip <code>America/Guatemala</code> to 274333313Sphilip <code>America/Guatemala_City</code>, but prefer 275333313Sphilip <code>America/Mexico_City</code> to 276333313Sphilip <code>America/Mexico</code> 277331663Sphilip because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the 278331663Sphilip country of Mexico has several time zones</a>. 279325057Sphilip </li> 280325057Sphilip <li> 281331663Sphilip Use '<code>_</code>' to represent a space. 282325057Sphilip </li> 283325057Sphilip <li> 284331663Sphilip Omit '<code>.</code>' from abbreviations in names. 285333313Sphilip E.g., prefer <code>Atlantic/St_Helena</code> to 286333313Sphilip <code>Atlantic/St._Helena</code>. 287325057Sphilip </li> 288325057Sphilip <li> 289331663Sphilip Do not change established names if they only marginally violate 290331663Sphilip the above guidelines. 291333313Sphilip For example, do not change the existing name <code>Europe/Rome</code> to 292333313Sphilip <code>Europe/Milan</code> merely because Milan's population has grown 293331663Sphilip to be somewhat greater than Rome's. 294325057Sphilip </li> 295325057Sphilip <li> 296331663Sphilip If a name is changed, put its old spelling in the 297331663Sphilip '<code>backward</code>' file. 298331663Sphilip This means old spellings will continue to work. 299325057Sphilip </li> 300325057Sphilip</ul> 301325057Sphilip 302325057Sphilip<p> 303345671SphilipGuidelines have evolved with time, and names following old versions of 304345671Sphilipthis guideline might not follow the current version. When guidelines 305345671Sphiliphave changed, old names continue to be supported. Guideline changes 306345671Sphiliphave included the following: 307325057Sphilip</p> 308325057Sphilip 309345671Sphilip<ul> 310345671Sphilip<li> 311345671SphilipOlder versions of this package used a different naming scheme. 312325057SphilipSee the file '<code>backward</code>' for most of these older names 313325057Sphilip(e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>'). 314325057SphilipThe other old-fashioned names still supported are 315331663Sphilip'<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and 316331663Sphilip'<code>EET</code>' (see the file '<code>europe</code>'). 317345671Sphilip</li> 318325057Sphilip 319345671Sphilip<li> 320325057SphilipOlder versions of this package defined legacy names that are 321331663Sphilipincompatible with the first guideline of location names, but which are 322331663Sphilipstill supported. 323331663SphilipThese legacy names are mostly defined in the file 324331663Sphilip'<code>etcetera</code>'. 325331663SphilipAlso, the file '<code>backward</code>' defines the legacy names 326331663Sphilip'<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', 327331663Sphilipand the file '<code>northamerica</code>' defines the legacy names 328331663Sphilip'<code>EST5EDT</code>', '<code>CST6CDT</code>', 329331663Sphilip'<code>MST7MDT</code>', and '<code>PST8PDT</code>'. 330345671Sphilip</li> 331345671Sphilip 332345671Sphilip<li> 333345671SphilipOlder versions of this guideline said that 334345671Sphilipthere should typically be at least one name for each <a 335345671Sphiliphref="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr 336345671Sphiliptitle="International Organization for Standardization">ISO</abbr> 337345671Sphilip3166-1</a> officially assigned two-letter code for an inhabited 338345671Sphilipcountry or territory. 339345671SphilipThis old guideline has been dropped, as it was not needed to handle 340345671Sphiliptimestamps correctly and it increased maintenance burden. 341345671Sphilip</li> 342345671Sphilip</ul> 343345671Sphilip 344345671Sphilip<p> 345345671SphilipThe file '<code>zone1970.tab</code>' lists geographical locations used 346345671Sphilipto name timezones. 347345671SphilipIt is intended to be an exhaustive list of names for geographic 348345671Sphilipregions as described above; this is a subset of the timezones in the data. 349345671SphilipAlthough a '<code>zone1970.tab</code>' location's 350345671Sphilip<a href="https://en.wikipedia.org/wiki/Longitude">longitude</a> 351345671Sphilipcorresponds to 352345671Sphilipits <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean 353345671Sphiliptime (<abbr>LMT</abbr>)</a> offset with one hour for every 15° 354345671Sphilipeast longitude, this relationship is not exact. 355325057Sphilip</p> 356325057Sphilip 357325057Sphilip<p> 358331663SphilipExcluding '<code>backward</code>' should not affect the other data. 359331663SphilipIf '<code>backward</code>' is excluded, excluding 360331663Sphilip'<code>etcetera</code>' should not affect the remaining data. 361325057Sphilip</p> 362331663Sphilip</section> 363325057Sphilip 364331663Sphilip<section> 365331663Sphilip <h2 id="abbreviations">Time zone abbreviations</h2> 366325057Sphilip<p> 367325057SphilipWhen this package is installed, it generates time zone abbreviations 368325057Sphiliplike '<code>EST</code>' to be compatible with human tradition and POSIX. 369331663SphilipHere are the general guidelines used for choosing time zone abbreviations, 370325057Sphilipin decreasing order of importance: 371331663Sphilip</p> 372331663Sphilip 373325057Sphilip<ul> 374325057Sphilip <li> 375331663Sphilip Use three to six characters that are ASCII alphanumerics or 376331663Sphilip '<code>+</code>' or '<code>-</code>'. 377331663Sphilip Previous editions of this database also used characters like 378333313Sphilip space and '<code>?</code>', but these characters have a 379333313Sphilip special meaning to the 380333313Sphilip <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a> 381333313Sphilip and cause commands like 382331663Sphilip '<code><a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a> 383331663Sphilip `<a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>' 384331663Sphilip to have unexpected effects. 385331663Sphilip Previous editions of this guideline required upper-case letters, but the 386331663Sphilip Congressman who introduced 387331663Sphilip <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro 388331663Sphilip Standard Time</a> preferred "ChST", so lower-case letters are now 389331663Sphilip allowed. 390331663Sphilip Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>', 391331663Sphilip '<code>+</code>', and alphanumeric characters from the portable 392331663Sphilip character set in the current locale. 393331663Sphilip In practice ASCII alphanumerics and '<code>+</code>' and 394331663Sphilip '<code>-</code>' are safe in all locales. 395325057Sphilip 396331663Sphilip <p> 397331663Sphilip In other words, in the C locale the POSIX extended regular 398331663Sphilip expression <code>[-+[:alnum:]]{3,6}</code> should match the 399331663Sphilip abbreviation. 400331663Sphilip This guarantees that all abbreviations could have been specified by a 401331663Sphilip POSIX <code>TZ</code> string. 402331663Sphilip </p> 403325057Sphilip </li> 404325057Sphilip <li> 405331663Sphilip Use abbreviations that are in common use among English-speakers, 406331663Sphilip e.g., 'EST' for Eastern Standard Time in North America. 407331663Sphilip We assume that applications translate them to other languages 408331663Sphilip as part of the normal localization process; for example, 409331663Sphilip a French application might translate 'EST' to 'HNE'. 410328476Sphilip 411331663Sphilip <p> 412331663Sphilip <small>These abbreviations (for standard/daylight/etc. time) are: 413331663Sphilip ACST/ACDT Australian Central, 414331663Sphilip AST/ADT/APT/AWT/ADDT Atlantic, 415331663Sphilip AEST/AEDT Australian Eastern, 416331663Sphilip AHST/AHDT Alaska-Hawaii, 417331663Sphilip AKST/AKDT Alaska, 418331663Sphilip AWST/AWDT Australian Western, 419331663Sphilip BST/BDT Bering, 420331663Sphilip CAT/CAST Central Africa, 421331663Sphilip CET/CEST/CEMT Central European, 422331663Sphilip ChST Chamorro, 423331663Sphilip CST/CDT/CWT/CPT/CDDT Central [North America], 424331663Sphilip CST/CDT China, 425331663Sphilip GMT/BST/IST/BDST Greenwich, 426331663Sphilip EAT East Africa, 427331663Sphilip EST/EDT/EWT/EPT/EDDT Eastern [North America], 428331663Sphilip EET/EEST Eastern European, 429342669Sphilip GST/GDT Guam, 430339940Sphilip HST/HDT/HWT/HPT Hawaii, 431331663Sphilip HKT/HKST Hong Kong, 432331663Sphilip IST India, 433331663Sphilip IST/GMT Irish, 434331663Sphilip IST/IDT/IDDT Israel, 435331663Sphilip JST/JDT Japan, 436331663Sphilip KST/KDT Korea, 437331663Sphilip MET/MEST Middle European (a backward-compatibility alias for 438331663Sphilip Central European), 439331663Sphilip MSK/MSD Moscow, 440331663Sphilip MST/MDT/MWT/MPT/MDDT Mountain, 441331663Sphilip NST/NDT/NWT/NPT/NDDT Newfoundland, 442331663Sphilip NST/NDT/NWT/NPT Nome, 443331663Sphilip NZMT/NZST New Zealand through 1945, 444331663Sphilip NZST/NZDT New Zealand 1946–present, 445331663Sphilip PKT/PKST Pakistan, 446331663Sphilip PST/PDT/PWT/PPT/PDDT Pacific, 447339631Sphilip PST/PDT Philippine, 448331663Sphilip SAST South Africa, 449331663Sphilip SST Samoa, 450331663Sphilip WAT/WAST West Africa, 451331663Sphilip WET/WEST/WEMT Western European, 452331663Sphilip WIB Waktu Indonesia Barat, 453331663Sphilip WIT Waktu Indonesia Timur, 454331663Sphilip WITA Waktu Indonesia Tengah, 455331663Sphilip YST/YDT/YWT/YPT/YDDT Yukon</small>. 456331663Sphilip </p> 457325057Sphilip </li> 458325057Sphilip <li> 459331663Sphilip <p> 460331663Sphilip For times taken from a city's longitude, use the 461331663Sphilip traditional <var>x</var>MT notation. 462331663Sphilip The only abbreviation like this in current use is '<abbr>GMT</abbr>'. 463331663Sphilip The others are for timestamps before 1960, 464331663Sphilip except that Monrovia Mean Time persisted until 1972. 465331663Sphilip Typically, numeric abbreviations (e.g., '<code>-</code>004430' for 466331663Sphilip MMT) would cause trouble here, as the numeric strings would exceed 467331663Sphilip the POSIX length limit. 468331663Sphilip </p> 469328476Sphilip 470331663Sphilip <p> 471331663Sphilip <small>These abbreviations are: 472331663Sphilip AMT Amsterdam, Asunci��n, Athens; 473331663Sphilip BMT Baghdad, Bangkok, Batavia, Bern, Bogot��, Bridgetown, Brussels, 474331663Sphilip Bucharest; 475331663Sphilip CMT Calamarca, Caracas, Chisinau, Col��n, Copenhagen, C��rdoba; 476331663Sphilip DMT Dublin/Dunsink; 477331663Sphilip EMT Easter; 478331663Sphilip FFMT Fort-de-France; 479331663Sphilip FMT Funchal; 480331663Sphilip GMT Greenwich; 481331663Sphilip HMT Havana, Helsinki, Horta, Howrah; 482331663Sphilip IMT Irkutsk, Istanbul; 483331663Sphilip JMT Jerusalem; 484331663Sphilip KMT Kaunas, Kiev, Kingston; 485331663Sphilip LMT Lima, Lisbon, local, Luanda; 486331663Sphilip MMT Macassar, Madras, Mal��, Managua, Minsk, Monrovia, Montevideo, 487331663Sphilip Moratuwa, Moscow; 488331663Sphilip PLMT Ph�� Li���n; 489331663Sphilip PMT Paramaribo, Paris, Perm, Pontianak, Prague; 490331663Sphilip PMMT Port Moresby; 491331663Sphilip QMT Quito; 492331663Sphilip RMT Rangoon, Riga, Rome; 493331663Sphilip SDMT Santo Domingo; 494331663Sphilip SJMT San Jos��; 495331663Sphilip SMT Santiago, Simferopol, Singapore, Stanley; 496331663Sphilip TBMT Tbilisi; 497331663Sphilip TMT Tallinn, Tehran; 498331663Sphilip WMT Warsaw</small>. 499331663Sphilip </p> 500328476Sphilip 501331663Sphilip <p> 502331663Sphilip <small>A few abbreviations also follow the pattern that 503339631Sphilip <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK. 504331663Sphilip They are: 505331663Sphilip CMT/BST for Calamarca Mean Time and Bolivian Summer Time 506331663Sphilip 1890–1932, 507331663Sphilip DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time 508331663Sphilip 1880–1916, 509331663Sphilip MMT/MST/MDST for Moscow 1880–1919, and 510331663Sphilip RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926. 511331663Sphilip An extra-special case is SET for Swedish Time (<em>svensk 512331663Sphilip normaltid</em>) 1879–1899, 3° west of the Stockholm 513331663Sphilip Observatory.</small> 514331663Sphilip </p> 515325057Sphilip </li> 516325057Sphilip <li> 517331663Sphilip Use '<abbr>LMT</abbr>' for local mean time of locations before the 518331663Sphilip introduction of standard time; see "<a href="#scope">Scope of the 519331663Sphilip <code><abbr>tz</abbr></code> database</a>". 520325057Sphilip </li> 521325057Sphilip <li> 522331663Sphilip If there is no common English abbreviation, use numeric offsets like 523339631Sphilip <code>-</code>05 and <code>+</code>0530 that are generated 524331663Sphilip by <code>zic</code>'s <code>%z</code> notation. 525325057Sphilip </li> 526325057Sphilip <li> 527331663Sphilip Use current abbreviations for older timestamps to avoid confusion. 528331663Sphilip For example, in 1910 a common English abbreviation for time 529331663Sphilip in central Europe was 'MEZ' (short for both "Middle European 530331663Sphilip Zone" and for "Mitteleurop��ische Zeit" in German). 531331663Sphilip Nowadays 'CET' ("Central European Time") is more common in 532331663Sphilip English, and the database uses 'CET' even for circa-1910 533331663Sphilip timestamps as this is less confusing for modern users and avoids 534331663Sphilip the need for determining when 'CET' supplanted 'MEZ' in common 535331663Sphilip usage. 536325057Sphilip </li> 537325057Sphilip <li> 538339631Sphilip Use a consistent style in a timezone's history. 539339631Sphilip For example, if a history tends to use numeric 540331663Sphilip abbreviations and a particular entry could go either way, use a 541331663Sphilip numeric abbreviation. 542325057Sphilip </li> 543325057Sphilip <li> 544331663Sphilip Use 545331663Sphilip <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a> 546331663Sphilip (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for 547331663Sphilip locations while uninhabited. 548331663Sphilip The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in 549331663Sphilip some sense undefined; this notation is derived 550331663Sphilip from <a href="https://tools.ietf.org/html/rfc3339">Internet 551339631Sphilip <abbr title="Request For Comments">RFC</abbr> 3339</a>. 552325057Sphilip </li> 553325057Sphilip</ul> 554331663Sphilip 555325057Sphilip<p> 556325057SphilipApplication writers should note that these abbreviations are ambiguous 557328476Sphilipin practice: e.g., 'CST' means one thing in China and something else 558328476Sphilipin North America, and 'IST' can refer to time in India, Ireland or 559331663SphilipIsrael. 560331663SphilipTo avoid ambiguity, use numeric <abbr>UT</abbr> offsets like 561328476Sphilip'<code>-</code>0600' instead of time zone abbreviations like 'CST'. 562325057Sphilip</p> 563331663Sphilip</section> 564325057Sphilip 565331663Sphilip<section> 566331663Sphilip <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2> 567325057Sphilip<p> 568331663SphilipThe <code><abbr>tz</abbr></code> database is not authoritative, and it 569331663Sphilipsurely has errors. 570328476SphilipCorrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. 571325057SphilipUsers requiring authoritative data should consult national standards 572325057Sphilipbodies and the references cited in the database's comments. 573325057Sphilip</p> 574325057Sphilip 575325057Sphilip<p> 576331663SphilipErrors in the <code><abbr>tz</abbr></code> database arise from many sources: 577325057Sphilip</p> 578331663Sphilip 579325057Sphilip<ul> 580325057Sphilip <li> 581331663Sphilip The <code><abbr>tz</abbr></code> database predicts future 582331663Sphilip timestamps, and current predictions 583331663Sphilip will be incorrect after future governments change the rules. 584331663Sphilip For example, if today someone schedules a meeting for 13:00 next 585331663Sphilip October 1, Casablanca time, and tomorrow Morocco changes its 586331663Sphilip daylight saving rules, software can mess up after the rule change 587331663Sphilip if it blithely relies on conversions made before the change. 588325057Sphilip </li> 589325057Sphilip <li> 590331663Sphilip The pre-1970 entries in this database cover only a tiny sliver of how 591331663Sphilip clocks actually behaved; the vast majority of the necessary 592331663Sphilip information was lost or never recorded. 593339631Sphilip Thousands more timezones would be needed if 594331663Sphilip the <code><abbr>tz</abbr></code> database's scope were extended to 595331663Sphilip cover even just the known or guessed history of standard time; for 596331663Sphilip example, the current single entry for France would need to split 597331663Sphilip into dozens of entries, perhaps hundreds. 598331663Sphilip And in most of the world even this approach would be misleading 599331663Sphilip due to widespread disagreement or indifference about what times 600331663Sphilip should be observed. 601331663Sphilip In her 2015 book 602331663Sphilip <cite><a 603331663Sphilip href="http://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The 604331663Sphilip Global Transformation of Time, 1870–1950</a></cite>, 605331663Sphilip Vanessa Ogle writes 606331663Sphilip "Outside of Europe and North America there was no system of time 607331663Sphilip zones at all, often not even a stable landscape of mean times, 608331663Sphilip prior to the middle decades of the twentieth century". 609331663Sphilip See: Timothy Shenk, <a 610331663Sphiliphref="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked: 611331663Sphilip A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. 612325057Sphilip </li> 613325057Sphilip <li> 614331663Sphilip Most of the pre-1970 data entries come from unreliable sources, often 615331663Sphilip astrology books that lack citations and whose compilers evidently 616331663Sphilip invented entries when the true facts were unknown, without 617331663Sphilip reporting which entries were known and which were invented. 618331663Sphilip These books often contradict each other or give implausible entries, 619331663Sphilip and on the rare occasions when they are checked they are 620331663Sphilip typically found to be incorrect. 621325057Sphilip </li> 622325057Sphilip <li> 623331663Sphilip For the UK the <code><abbr>tz</abbr></code> database relies on 624331663Sphilip years of first-class work done by 625331663Sphilip Joseph Myers and others; see 626331663Sphilip "<a href="https://www.polyomino.org.uk/british-time/">History of 627331663Sphilip legal time in Britain</a>". 628331663Sphilip Other countries are not done nearly as well. 629325057Sphilip </li> 630325057Sphilip <li> 631331663Sphilip Sometimes, different people in the same city maintain clocks 632331663Sphilip that differ significantly. 633331663Sphilip Historically, railway time was used by railroad companies (which 634331663Sphilip did not always 635331663Sphilip agree with each other), church-clock time was used for birth 636331663Sphilip certificates, etc. 637331663Sphilip More recently, competing political groups might disagree about 638331663Sphilip clock settings. Often this is merely common practice, but 639331663Sphilip sometimes it is set by law. 640331663Sphilip For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France 641331663Sphilip was legally <abbr>UT</abbr> +00:09:21 outside train stations and 642331663Sphilip <abbr>UT</abbr> +00:04:21 inside. Other examples include 643331663Sphilip Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and 644331663Sphilip ��r��mqi to this day. 645325057Sphilip </li> 646325057Sphilip <li> 647331663Sphilip Although a named location in the <code><abbr>tz</abbr></code> 648331663Sphilip database stands for the containing region, its pre-1970 data 649331663Sphilip entries are often accurate for only a small subset of that region. 650331663Sphilip For example, <code>Europe/London</code> stands for the United 651331663Sphilip Kingdom, but its pre-1847 times are valid only for locations that 652331663Sphilip have London's exact meridian, and its 1847 transition 653331663Sphilip to <abbr>GMT</abbr> is known to be valid only for the L&NW and 654331663Sphilip the Caledonian railways. 655325057Sphilip </li> 656325057Sphilip <li> 657331663Sphilip The <code><abbr>tz</abbr></code> database does not record the 658339631Sphilip earliest time for which a timezone's 659331663Sphilip data entries are thereafter valid for every location in the region. 660331663Sphilip For example, <code>Europe/London</code> is valid for all locations 661331663Sphilip in its region after <abbr>GMT</abbr> was made the standard time, 662331663Sphilip but the date of standardization (1880-08-02) is not in the 663331663Sphilip <code><abbr>tz</abbr></code> database, other than in commentary. 664339631Sphilip For many timezones the earliest time of 665331663Sphilip validity is unknown. 666325057Sphilip </li> 667325057Sphilip <li> 668331663Sphilip The <code><abbr>tz</abbr></code> database does not record a 669331663Sphilip region's boundaries, and in many cases the boundaries are not known. 670339631Sphilip For example, the timezone 671331663Sphilip <code>America/Kentucky/Louisville</code> represents a region 672331663Sphilip around the city of Louisville, the boundaries of which are 673331663Sphilip unclear. 674325057Sphilip </li> 675325057Sphilip <li> 676331663Sphilip Changes that are modeled as instantaneous transitions in the 677331663Sphilip <code><abbr>tz</abbr></code> 678331663Sphilip database were often spread out over hours, days, or even decades. 679325057Sphilip </li> 680325057Sphilip <li> 681331663Sphilip Even if the time is specified by law, locations sometimes 682331663Sphilip deliberately flout the law. 683325057Sphilip </li> 684325057Sphilip <li> 685331663Sphilip Early timekeeping practices, even assuming perfect clocks, were 686331663Sphilip often not specified to the accuracy that the 687331663Sphilip <code><abbr>tz</abbr></code> database requires. 688325057Sphilip </li> 689325057Sphilip <li> 690331663Sphilip Sometimes historical timekeeping was specified more precisely 691331663Sphilip than what the <code><abbr>tz</abbr></code> code can handle. 692331663Sphilip For example, from 1909 to 1937 <a 693331663Sphilip href="https://www.staff.science.uu.nl/~gent0113/wettijd/wettijd.htm" 694331663Sphilip hreflang="nl">Netherlands clocks</a> were legally Amsterdam Mean 695331663Sphilip Time (estimated to be <abbr>UT</abbr> 696331663Sphilip +00:19:32.13), but the <code><abbr>tz</abbr></code> 697331663Sphilip code cannot represent the fractional second. 698331663Sphilip In practice these old specifications were rarely if ever 699331663Sphilip implemented to subsecond precision. 700325057Sphilip </li> 701325057Sphilip <li> 702331663Sphilip Even when all the timestamp transitions recorded by the 703331663Sphilip <code><abbr>tz</abbr></code> database are correct, the 704331663Sphilip <code><abbr>tz</abbr></code> rules that generate them may not 705331663Sphilip faithfully reflect the historical rules. 706331663Sphilip For example, from 1922 until World War II the UK moved clocks 707331663Sphilip forward the day following the third Saturday in April unless that 708331663Sphilip was Easter, in which case it moved clocks forward the previous 709331663Sphilip Sunday. 710331663Sphilip Because the <code><abbr>tz</abbr></code> database has no 711331663Sphilip way to specify Easter, these exceptional years are entered as 712331663Sphilip separate <code><abbr>tz</abbr> Rule</code> lines, even though the 713331663Sphilip legal rules did not change. 714339631Sphilip When transitions are known but the historical rules behind them are not, 715339631Sphilip the database contains <code>Zone</code> and <code>Rule</code> 716339631Sphilip entries that are intended to represent only the generated 717339631Sphilip transitions, not any underlying historical rules; however, this 718339631Sphilip intent is recorded at best only in commentary. 719325057Sphilip </li> 720325057Sphilip <li> 721339631Sphilip The <code><abbr>tz</abbr></code> database models time 722331663Sphilip using the <a 723331663Sphilip href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic 724339631Sphilip Gregorian calendar</a> with days containing 24 equal-length hours 725339631Sphilip numbered 00 through 23, except when clock transitions occur. 726339631Sphilip Pre-standard time is modeled as local mean time. 727339631Sphilip However, historically many people used other calendars and other timescales. 728331663Sphilip For example, the Roman Empire used 729331663Sphilip the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian 730331663Sphilip calendar</a>, 731331663Sphilip and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman 732331663Sphilip timekeeping</a> had twelve varying-length daytime hours with a 733331663Sphilip non-hour-based system at night. 734339631Sphilip And even today, some local practices diverge from the Gregorian 735339631Sphilip calendar with 24-hour days. These divergences range from 736339631Sphilip relatively minor, such as Japanese bars giving times like "24:30" for the 737339631Sphilip wee hours of the morning, to more-significant differences such as <a 738339631Sphilip href="https://www.pri.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the 739339631Sphilip east African practice of starting the day at dawn</a>, renumbering 740339631Sphilip the Western 06:00 to be 12:00. These practices are largely outside 741339631Sphilip the scope of the <code><abbr>tz</abbr></code> code and data, which 742339631Sphilip provide only limited support for date and time localization 743339631Sphilip such as that required by POSIX. If DST is not used a different time zone 744339631Sphilip can often do the trick; for example, in Kenya a <code>TZ</code> setting 745339631Sphilip like <code><-03>3</code> or <code>America/Cayenne</code> starts 746339631Sphilip the day six hours later than <code>Africa/Nairobi</code> does. 747325057Sphilip </li> 748325057Sphilip <li> 749331663Sphilip Early clocks were less reliable, and data entries do not represent 750331663Sphilip clock error. 751325057Sphilip </li> 752325057Sphilip <li> 753331663Sphilip The <code><abbr>tz</abbr></code> database assumes Universal Time 754331663Sphilip (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not 755331663Sphilip standardized for older timestamps. 756331663Sphilip In the <code><abbr>tz</abbr></code> database commentary, 757331663Sphilip <abbr>UT</abbr> denotes a family of time standards that includes 758331663Sphilip Coordinated Universal Time (<abbr>UTC</abbr>) along with other 759331663Sphilip variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>, 760331663Sphilip with days starting at midnight. 761331663Sphilip Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern 762331663Sphilip timestamps, <abbr>UTC</abbr> was not defined until 1960, so 763331663Sphilip commentary uses the more-general abbreviation <abbr>UT</abbr> for 764331663Sphilip timestamps that might predate 1960. 765331663Sphilip Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly, 766331663Sphilip and since pre-1972 <abbr>UTC</abbr> seconds varied in length, 767331663Sphilip interpretation of older timestamps can be problematic when 768331663Sphilip subsecond accuracy is needed. 769325057Sphilip </li> 770325057Sphilip <li> 771333313Sphilip Civil time was not based on atomic time before 1972, and we do not 772331663Sphilip know the history of 773331663Sphilip <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's 774331663Sphilip rotation</a> accurately enough to map <a 775331663Sphilip href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr 776331663Sphilip title="International System of Units">SI</abbr></a> seconds to 777331663Sphilip historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a> 778331663Sphilip to more than about one-hour accuracy. 779331663Sphilip See: Stephenson FR, Morrison LV, Hohenkerk CY. 780339631Sphilip <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of 781331663Sphilip the Earth's rotation: 720 BC to AD 2015</a>. 782331663Sphilip <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404. 783331663Sphilip Also see: Espenak F. <a 784331663Sphilip href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty 785331663Sphilip in Delta T (��T)</a>. 786325057Sphilip </li> 787325057Sphilip <li> 788331663Sphilip The relationship between POSIX time (that is, <abbr>UTC</abbr> but 789331663Sphilip ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap 790331663Sphilip seconds</a>) and <abbr>UTC</abbr> is not agreed upon after 1972. 791331663Sphilip Although the POSIX 792331663Sphilip clock officially stops during an inserted leap second, at least one 793331663Sphilip proposed standard has it jumping back a second instead; and in 794331663Sphilip practice POSIX clocks more typically either progress glacially during 795331663Sphilip a leap second, or are slightly slowed while near a leap second. 796325057Sphilip </li> 797325057Sphilip <li> 798331663Sphilip The <code><abbr>tz</abbr></code> database does not represent how 799331663Sphilip uncertain its information is. 800331663Sphilip Ideally it would contain information about when data entries are 801331663Sphilip incomplete or dicey. 802331663Sphilip Partial temporal knowledge is a field of active research, though, 803333313Sphilip and it is not clear how to apply it here. 804325057Sphilip </li> 805325057Sphilip</ul> 806331663Sphilip 807325057Sphilip<p> 808331663SphilipIn short, many, perhaps most, of the <code><abbr>tz</abbr></code> 809331663Sphilipdatabase's pre-1970 and future timestamps are either wrong or 810331663Sphilipmisleading. 811331663SphilipAny attempt to pass the 812331663Sphilip<code><abbr>tz</abbr></code> database off as the definition of time 813331663Sphilipshould be unacceptable to anybody who cares about the facts. 814331663SphilipIn particular, the <code><abbr>tz</abbr></code> database's 815331663Sphilip<abbr>LMT</abbr> offsets should not be considered meaningful, and 816339631Sphilipshould not prompt creation of timezones 817331663Sphilipmerely because two locations 818331663Sphilipdiffer in <abbr>LMT</abbr> or transitioned to standard time at 819331663Sphilipdifferent dates. 820325057Sphilip</p> 821331663Sphilip</section> 822325057Sphilip 823331663Sphilip<section> 824331663Sphilip <h2 id="functions">Time and date functions</h2> 825325057Sphilip<p> 826331663SphilipThe <code><abbr>tz</abbr></code> code contains time and date functions 827331663Sphilipthat are upwards compatible with those of POSIX. 828331663SphilipCode compatible with this package is already 829331663Sphilip<a href="tz-link.html#tzdb">part of many platforms</a>, where the 830331663Sphilipprimary use of this package is to update obsolete time-related files. 831331663SphilipTo do this, you may need to compile the time zone compiler 832331663Sphilip'<code>zic</code>' supplied with this package instead of using the 833331663Sphilipsystem '<code>zic</code>', since the format of <code>zic</code>'s 834331663Sphilipinput is occasionally extended, and a platform may still be shipping 835331663Sphilipan older <code>zic</code>. 836325057Sphilip</p> 837325057Sphilip 838331663Sphilip<h3 id="POSIX">POSIX properties and limitations</h3> 839325057Sphilip<ul> 840325057Sphilip <li> 841325057Sphilip <p> 842331663Sphilip In POSIX, time display in a process is controlled by the 843331663Sphilip environment variable <code>TZ</code>. 844331663Sphilip Unfortunately, the POSIX 845331663Sphilip <code>TZ</code> string takes a form that is hard to describe and 846331663Sphilip is error-prone in practice. 847333313Sphilip Also, POSIX <code>TZ</code> strings cannot deal with daylight 848331663Sphilip saving time rules not based on the Gregorian calendar (as in 849331663Sphilip Iran), or with situations where more than two time zone 850331663Sphilip abbreviations or <abbr>UT</abbr> offsets are used in an area. 851325057Sphilip </p> 852331663Sphilip 853325057Sphilip <p> 854331663Sphilip The POSIX <code>TZ</code> string takes the following form: 855325057Sphilip </p> 856331663Sphilip 857325057Sphilip <p> 858331663Sphilip <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>]]] 859325057Sphilip </p> 860331663Sphilip 861325057Sphilip <p> 862331663Sphilip where: 863331663Sphilip </p> 864331663Sphilip 865325057Sphilip <dl> 866325057Sphilip <dt><var>std</var> and <var>dst</var></dt><dd> 867331663Sphilip are 3 or more characters specifying the standard 868339631Sphilip and daylight saving time (<abbr>DST</abbr>) zone abbreviations. 869331663Sphilip Starting with POSIX.1-2001, <var>std</var> and <var>dst</var> 870331663Sphilip may also be in a quoted form like '<code><+09></code>'; 871331663Sphilip this allows "<code>+</code>" and "<code>-</code>" in the names. 872325057Sphilip </dd> 873325057Sphilip <dt><var>offset</var></dt><dd> 874331663Sphilip is of the form 875331663Sphilip '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' 876331663Sphilip and specifies the offset west of <abbr>UT</abbr>. 877331663Sphilip '<var>hh</var>' may be a single digit; 878331663Sphilip 0≤<var>hh</var>≤24. 879331663Sphilip The default <abbr>DST</abbr> offset is one hour ahead of 880331663Sphilip standard time. 881325057Sphilip </dd> 882325057Sphilip <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> 883331663Sphilip specifies the beginning and end of <abbr>DST</abbr>. 884331663Sphilip If this is absent, the system supplies its own ruleset 885331663Sphilip for <abbr>DST</abbr>, and its rules can differ from year to year; 886331663Sphilip typically <abbr>US</abbr> <abbr>DST</abbr> rules are used. 887325057Sphilip </dd> 888325057Sphilip <dt><var>time</var></dt><dd> 889331663Sphilip takes the form 890331663Sphilip '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]' 891331663Sphilip and defaults to 02:00. 892331663Sphilip This is the same format as the offset, except that a 893331663Sphilip leading '<code>+</code>' or '<code>-</code>' is not allowed. 894325057Sphilip </dd> 895325057Sphilip <dt><var>date</var></dt><dd> 896331663Sphilip takes one of the following forms: 897325057Sphilip <dl> 898325057Sphilip <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> 899331663Sphilip origin-1 day number not counting February 29 900331663Sphilip </dd> 901325057Sphilip <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> 902331663Sphilip origin-0 day number counting February 29 if present 903325057Sphilip </dd> 904331663Sphilip <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> 905331663Sphilip (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, 906331663Sphilip 1≤<var>m</var>≤12)</dt><dd> 907331663Sphilip for the <var>d</var>th day of week <var>n</var> of 908331663Sphilip month <var>m</var> of the year, where week 1 is the first 909331663Sphilip week in which day <var>d</var> appears, and 910331663Sphilip '<code>5</code>' stands for the last week in which 911331663Sphilip day <var>d</var> appears (which may be either the 4th or 912331663Sphilip 5th week). 913331663Sphilip Typically, this is the only useful form; the <var>n</var> 914331663Sphilip and <code>J</code><var>n</var> forms are rarely used. 915331663Sphilip </dd> 916331663Sphilip </dl> 917331663Sphilip </dd> 918331663Sphilip </dl> 919325057Sphilip 920331663Sphilip <p> 921331663Sphilip Here is an example POSIX <code>TZ</code> string for New 922331663Sphilip Zealand after 2007. 923331663Sphilip It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead 924331663Sphilip of <abbr>UT</abbr>, and that daylight saving time 925331663Sphilip (<abbr>NZDT</abbr>) is observed from September's last Sunday at 926331663Sphilip 02:00 until April's first Sunday at 03:00: 927331663Sphilip </p> 928325057Sphilip 929331663Sphilip <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> 930325057Sphilip 931331663Sphilip <p> 932331663Sphilip This POSIX <code>TZ</code> string is hard to remember, and 933331663Sphilip mishandles some timestamps before 2008. 934331663Sphilip With this package you can use this instead: 935331663Sphilip </p> 936331663Sphilip 937331663Sphilip <pre><code>TZ='Pacific/Auckland'</code></pre> 938325057Sphilip </li> 939325057Sphilip <li> 940339631Sphilip POSIX does not define the <abbr>DST</abbr> transitions 941339631Sphilip for <code>TZ</code> values like 942331663Sphilip "<code>EST5EDT</code>". 943339631Sphilip Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules 944339631Sphilip were used to interpret such values, but this meant that the 945339631Sphilip <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each 946339631Sphilip program that did time conversion. This meant that when 947339631Sphilip <abbr>US</abbr> time conversion rules changed (as in the United 948339631Sphilip States in 1987), all programs that did time conversion had to be 949331663Sphilip recompiled to ensure proper results. 950325057Sphilip </li> 951325057Sphilip <li> 952331663Sphilip The <code>TZ</code> environment variable is process-global, which 953331663Sphilip makes it hard to write efficient, thread-safe applications that 954339631Sphilip need access to multiple timezones. 955325057Sphilip </li> 956325057Sphilip <li> 957333313Sphilip In POSIX, there is no tamper-proof way for a process to learn the 958331663Sphilip system's best idea of local wall clock. 959339631Sphilip This is important for applications that an administrator wants 960331663Sphilip used only at certain times – without regard to whether the 961331663Sphilip user has fiddled the 962331663Sphilip <code>TZ</code> environment variable. 963331663Sphilip While an administrator can "do everything in <abbr>UT</abbr>" to 964331663Sphilip get around the problem, doing so is inconvenient and precludes 965339631Sphilip handling daylight saving time shifts – as might be required to 966339631Sphilip limit phone calls to off-peak hours. 967325057Sphilip </li> 968325057Sphilip <li> 969331663Sphilip POSIX provides no convenient and efficient way to determine 970331663Sphilip the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary 971339631Sphilip timestamps, particularly for timezones 972331663Sphilip that do not fit into the POSIX model. 973325057Sphilip </li> 974325057Sphilip <li> 975331663Sphilip POSIX requires that systems ignore leap seconds. 976325057Sphilip </li> 977325057Sphilip <li> 978331663Sphilip The <code><abbr>tz</abbr></code> code attempts to support all the 979331663Sphilip <code>time_t</code> implementations allowed by POSIX. 980331663Sphilip The <code>time_t</code> type represents a nonnegative count of seconds 981331663Sphilip since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds. 982331663Sphilip In practice, <code>time_t</code> is usually a signed 64- or 32-bit 983331663Sphilip integer; 32-bit signed <code>time_t</code> values stop working after 984331663Sphilip 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these 985331663Sphilip days typically use a signed 64-bit integer. 986331663Sphilip Unsigned 32-bit integers are used on one or two platforms, and 36-bit 987331663Sphilip and 40-bit integers are also used occasionally. 988331663Sphilip Although earlier POSIX versions allowed <code>time_t</code> to be a 989339631Sphilip floating-point type, this was not supported by any practical system, 990331663Sphilip and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both 991331663Sphilip require <code>time_t</code> to be an integer type. 992325057Sphilip </li> 993325057Sphilip</ul> 994331663Sphilip 995331663Sphilip<h3 id="POSIX-extensions">Extensions to POSIX in the 996331663Sphilip<code><abbr>tz</abbr></code> code</h3> 997325057Sphilip<ul> 998325057Sphilip <li> 999325057Sphilip <p> 1000331663Sphilip The <code>TZ</code> environment variable is used in generating 1001339631Sphilip the name of a file from which time-related information is read 1002331663Sphilip (or is interpreted �� la POSIX); <code>TZ</code> is no longer 1003339631Sphilip constrained to be a string containing abbreviations 1004339631Sphilip and numeric data as described <a href="#POSIX">above</a>. 1005339631Sphilip The file's format is <dfn><abbr>TZif</abbr></dfn>, 1006345671Sphilip a timezone information format that contains binary data; see 1007345671Sphilip <a href="https://tools.ietf.org/html/8536">Internet 1008345671Sphilip <abbr>RFC</abbr> 8536</a>. 1009331663Sphilip The daylight saving time rules to be used for a 1010339631Sphilip particular timezone are encoded in the 1011339631Sphilip <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>, 1012339631Sphilip Australian, and other rules to be encoded, and 1013331663Sphilip allows for situations where more than two time zone 1014331663Sphilip abbreviations are used. 1015325057Sphilip </p> 1016325057Sphilip <p> 1017331663Sphilip It was recognized that allowing the <code>TZ</code> environment 1018331663Sphilip variable to take on values such as '<code>America/New_York</code>' 1019331663Sphilip might cause "old" programs (that expect <code>TZ</code> to have a 1020331663Sphilip certain form) to operate incorrectly; consideration was given to using 1021331663Sphilip some other environment variable (for example, <code>TIMEZONE</code>) 1022339631Sphilip to hold the string used to generate the <abbr>TZif</abbr> file's name. 1023331663Sphilip In the end, however, it was decided to continue using 1024331663Sphilip <code>TZ</code>: it is widely used for time zone purposes; 1025331663Sphilip separately maintaining both <code>TZ</code> 1026331663Sphilip and <code>TIMEZONE</code> seemed a nuisance; and systems where 1027331663Sphilip "new" forms of <code>TZ</code> might cause problems can simply 1028339631Sphilip use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which 1029339631Sphilip can be used by "new" programs as well as by "old" programs that 1030339631Sphilip assume pre-POSIX <code>TZ</code> values. 1031325057Sphilip </p> 1032331663Sphilip </li> 1033331663Sphilip <li> 1034331663Sphilip The code supports platforms with a <abbr>UT</abbr> offset member 1035331663Sphilip in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>. 1036331663Sphilip </li> 1037331663Sphilip <li> 1038331663Sphilip The code supports platforms with a time zone abbreviation member in 1039331663Sphilip <code>struct tm</code>, e.g., <code>tm_zone</code>. 1040331663Sphilip </li> 1041331663Sphilip <li> 1042331663Sphilip Functions <code>tzalloc</code>, <code>tzfree</code>, 1043331663Sphilip <code>localtime_rz</code>, and <code>mktime_z</code> for 1044331663Sphilip more-efficient thread-safe applications that need to use multiple 1045339631Sphilip timezones. 1046331663Sphilip The <code>tzalloc</code> and <code>tzfree</code> functions 1047331663Sphilip allocate and free objects of type <code>timezone_t</code>, 1048331663Sphilip and <code>localtime_rz</code> and <code>mktime_z</code> are 1049331663Sphilip like <code>localtime_r</code> and <code>mktime</code> with an 1050331663Sphilip extra <code>timezone_t</code> argument. 1051331663Sphilip The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>. 1052331663Sphilip </li> 1053331663Sphilip <li> 1054331663Sphilip A function <code>tzsetwall</code> has been added to arrange for the 1055331663Sphilip system's best approximation to local wall clock time to be delivered 1056331663Sphilip by subsequent calls to <code>localtime</code>. 1057331663Sphilip Source code for portable applications that "must" run on local wall 1058331663Sphilip clock time should call <code>tzsetwall</code>; 1059333313Sphilip if such code is moved to "old" systems that do not 1060333313Sphilip provide <code>tzsetwall</code>, you will not be able to generate an 1061331663Sphilip executable program. 1062331663Sphilip (These functions also arrange for local wall clock time to 1063331663Sphilip be used if <code>tzset</code> is called – directly or 1064333313Sphilip indirectly – and there is no <code>TZ</code> environment 1065331663Sphilip variable; portable applications should not, however, rely on this 1066333313Sphilip behavior since it is not the way <a 1067333313Sphilip href="https://en.wikipedia.org/wiki/UNIX_System_V#SVR2"><abbr>SVR2</abbr></a> 1068333313Sphilip systems behave.) 1069331663Sphilip </li> 1070331663Sphilip <li> 1071331663Sphilip Negative <code>time_t</code> values are supported, on systems 1072331663Sphilip where <code>time_t</code> is signed. 1073331663Sphilip </li> 1074331663Sphilip <li> 1075331663Sphilip These functions can account for leap seconds, thanks to Bradley White. 1076331663Sphilip </li> 1077325057Sphilip</ul> 1078331663Sphilip 1079331663Sphilip<h3 id="vestigial">POSIX features no longer needed</h3> 1080325057Sphilip<p> 1081331663SphilipPOSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a> 1082331663Sphilipdefine some <a href="https://en.wikipedia.org/wiki/API"><abbr 1083331663Sphiliptitle="application programming interface">API</abbr>s</a> that are vestigial: 1084331663Sphilipthey are not needed, and are relics of a too-simple model that does 1085331663Sphilipnot suffice to handle many real-world timestamps. 1086331663SphilipAlthough the <code><abbr>tz</abbr></code> code supports these 1087331663Sphilipvestigial <abbr>API</abbr>s for backwards compatibility, they should 1088331663Sphilipbe avoided in portable applications. 1089331663SphilipThe vestigial <abbr>API</abbr>s are: 1090325057Sphilip</p> 1091325057Sphilip<ul> 1092325057Sphilip <li> 1093331663Sphilip The POSIX <code>tzname</code> variable does not suffice and is no 1094331663Sphilip longer needed. 1095331663Sphilip To get a timestamp's time zone abbreviation, consult 1096331663Sphilip the <code>tm_zone</code> member if available; otherwise, 1097331663Sphilip use <code>strftime</code>'s <code>"%Z"</code> conversion 1098331663Sphilip specification. 1099325057Sphilip </li> 1100325057Sphilip <li> 1101331663Sphilip The POSIX <code>daylight</code> and <code>timezone</code> 1102331663Sphilip variables do not suffice and are no longer needed. 1103331663Sphilip To get a timestamp's <abbr>UT</abbr> offset, consult 1104331663Sphilip the <code>tm_gmtoff</code> member if available; otherwise, 1105331663Sphilip subtract values returned by <code>localtime</code> 1106331663Sphilip and <code>gmtime</code> using the rules of the Gregorian calendar, 1107331663Sphilip or use <code>strftime</code>'s <code>"%z"</code> conversion 1108331663Sphilip specification if a string like <code>"+0900"</code> suffices. 1109325057Sphilip </li> 1110325057Sphilip <li> 1111331663Sphilip The <code>tm_isdst</code> member is almost never needed and most of 1112331663Sphilip its uses should be discouraged in favor of the abovementioned 1113331663Sphilip <abbr>API</abbr>s. 1114331663Sphilip Although it can still be used in arguments to 1115331663Sphilip <code>mktime</code> to disambiguate timestamps near 1116331663Sphilip a <abbr>DST</abbr> transition when the clock jumps back, this 1117331663Sphilip disambiguation does not work when standard time itself jumps back, 1118331663Sphilip which can occur when a location changes to a time zone with a 1119331663Sphilip lesser <abbr>UT</abbr> offset. 1120325057Sphilip </li> 1121331663Sphilip</ul> 1122331663Sphilip 1123331663Sphilip<h3 id="other-portability">Other portability notes</h3> 1124331663Sphilip<ul> 1125325057Sphilip <li> 1126331663Sphilip The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition 1127331663Sphilip UNIX</a> <code>timezone</code> function is not present in this 1128333313Sphilip package; it is impossible to reliably map <code>timezone</code>'s 1129331663Sphilip arguments (a "minutes west of <abbr>GMT</abbr>" value and a 1130331663Sphilip "daylight saving time in effect" flag) to a time zone 1131331663Sphilip abbreviation, and we refuse to guess. 1132331663Sphilip Programs that in the past used the <code>timezone</code> function 1133331663Sphilip may now examine <code>localtime(&clock)->tm_zone</code> 1134331663Sphilip (if <code>TM_ZONE</code> is defined) or 1135331663Sphilip <code>tzname[localtime(&clock)->tm_isdst]</code> 1136331663Sphilip (if <code>HAVE_TZNAME</code> is defined) to learn the correct time 1137331663Sphilip zone abbreviation to use. 1138325057Sphilip </li> 1139331663Sphilip <li> 1140333313Sphilip The <a 1141333313Sphilip href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a> 1142333313Sphilip <code>gettimeofday</code> function is not 1143331663Sphilip used in this package. 1144331663Sphilip This formerly let users obtain the current <abbr>UTC</abbr> offset 1145331663Sphilip and <abbr>DST</abbr> flag, but this functionality was removed in 1146331663Sphilip later versions of <abbr>BSD</abbr>. 1147331663Sphilip </li> 1148331663Sphilip <li> 1149331663Sphilip In <abbr>SVR2</abbr>, time conversion fails for near-minimum or 1150331663Sphilip near-maximum <code>time_t</code> values when doing conversions 1151333313Sphilip for places that do not use <abbr>UT</abbr>. 1152331663Sphilip This package takes care to do these conversions correctly. 1153331663Sphilip A comment in the source code tells how to get compatibly wrong 1154331663Sphilip results. 1155331663Sphilip </li> 1156331663Sphilip <li> 1157331663Sphilip The functions that are conditionally compiled 1158331663Sphilip if <code>STD_INSPIRED</code> is defined should, at this point, be 1159331663Sphilip looked on primarily as food for thought. 1160331663Sphilip They are not in any sense "standard compatible" – some are 1161331663Sphilip not, in fact, specified in <em>any</em> standard. 1162331663Sphilip They do, however, represent responses of various authors to 1163331663Sphilip standardization proposals. 1164331663Sphilip </li> 1165331663Sphilip <li> 1166339631Sphilip Other time conversion proposals, in particular those supported by the 1167339631Sphilip <a href="https://howardhinnant.github.io/date/tz.html">Time Zone 1168339631Sphilip Database Parser</a>, offer a wider selection of functions 1169331663Sphilip that provide capabilities beyond those provided here. 1170331663Sphilip The absence of such functions from this package is not meant to 1171331663Sphilip discourage the development, standardization, or use of such 1172331663Sphilip functions. 1173331663Sphilip Rather, their absence reflects the decision to make this package 1174331663Sphilip contain valid extensions to POSIX, to ensure its broad 1175331663Sphilip acceptability. 1176331663Sphilip If more powerful time conversion functions can be standardized, so 1177331663Sphilip much the better. 1178331663Sphilip </li> 1179325057Sphilip</ul> 1180331663Sphilip</section> 1181325057Sphilip 1182331663Sphilip<section> 1183331663Sphilip <h2 id="stability">Interface stability</h2> 1184325057Sphilip<p> 1185331663SphilipThe <code><abbr>tz</abbr></code> code and data supply the following interfaces: 1186325057Sphilip</p> 1187325057Sphilip 1188325057Sphilip<ul> 1189325057Sphilip <li> 1190339631Sphilip A set of timezone names as per 1191345671Sphilip "<a href="#naming">Timezone identifiers</a>" above. 1192325057Sphilip </li> 1193325057Sphilip <li> 1194331663Sphilip Library functions described in "<a href="#functions">Time and date 1195331663Sphilip functions</a>" above. 1196325057Sphilip </li> 1197325057Sphilip <li> 1198331663Sphilip The programs <code>tzselect</code>, <code>zdump</code>, 1199331663Sphilip and <code>zic</code>, documented in their man pages. 1200325057Sphilip </li> 1201325057Sphilip <li> 1202331663Sphilip The format of <code>zic</code> input files, documented in 1203331663Sphilip the <code>zic</code> man page. 1204325057Sphilip </li> 1205325057Sphilip <li> 1206331663Sphilip The format of <code>zic</code> output files, documented in 1207331663Sphilip the <code>tzfile</code> man page. 1208325057Sphilip </li> 1209325057Sphilip <li> 1210331663Sphilip The format of zone table files, documented in <code>zone1970.tab</code>. 1211325057Sphilip </li> 1212325057Sphilip <li> 1213331663Sphilip The format of the country code file, documented in <code>iso3166.tab</code>. 1214325057Sphilip </li> 1215325057Sphilip <li> 1216331663Sphilip The version number of the code and data, as the first line of 1217331663Sphilip the text file '<code>version</code>' in each release. 1218325057Sphilip </li> 1219325057Sphilip</ul> 1220331663Sphilip 1221325057Sphilip<p> 1222325057SphilipInterface changes in a release attempt to preserve compatibility with 1223331663Sphiliprecent releases. 1224331663SphilipFor example, <code><abbr>tz</abbr></code> data files typically do not 1225331663Sphiliprely on recently-added <code>zic</code> features, so that users can 1226331663Sphiliprun older <code>zic</code> versions to process newer data files. 1227331663Sphilip<a href="tz-link.html#download">Downloading 1228331663Sphilipthe <code><abbr>tz</abbr></code> database</a> describes how releases 1229331663Sphilipare tagged and distributed. 1230325057Sphilip</p> 1231325057Sphilip 1232325057Sphilip<p> 1233331663SphilipInterfaces not listed above are less stable. 1234331663SphilipFor example, users should not rely on particular <abbr>UT</abbr> 1235331663Sphilipoffsets or abbreviations for timestamps, as data entries are often 1236331663Sphilipbased on guesswork and these guesses may be corrected or improved. 1237325057Sphilip</p> 1238345671Sphilip 1239345671Sphilip<p> 1240345671SphilipTimezone boundaries are not part of the stable interface. 1241345671SphilipFor example, even though the <samp>Asia/Bangkok</samp> timezone 1242345671Sphilipcurrently includes Chang Mai, Hanoi, and Phnom Penh, this is not part 1243345671Sphilipof the stable interface and the timezone can split at any time. 1244345671SphilipIf a calendar application records a future event in some location other 1245345671Sphilipthan Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record, 1246345671Sphilipthe application should be robust in the presence of timezone splits 1247345671Sphilipbetween now and the future time. 1248345671Sphilip</p> 1249331663Sphilip</section> 1250325057Sphilip 1251331663Sphilip<section> 1252331663Sphilip <h2 id="calendar">Calendrical issues</h2> 1253325057Sphilip<p> 1254325057SphilipCalendrical issues are a bit out of scope for a time zone database, 1255325057Sphilipbut they indicate the sort of problems that we would run into if we 1256331663Sphilipextended the time zone database further into the past. 1257333313SphilipAn excellent resource in this area is Edward M. Reingold 1258333313Sphilipand Nachum Dershowitz, <cite><a 1259333313Sphiliphref="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical 1260333313SphilipCalculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018). 1261331663SphilipOther information and sources are given in the file '<code>calendars</code>' 1262331663Sphilipin the <code><abbr>tz</abbr></code> distribution. 1263331663SphilipThey sometimes disagree. 1264325057Sphilip</p> 1265331663Sphilip</section> 1266325057Sphilip 1267331663Sphilip<section> 1268331663Sphilip <h2 id="planets">Time and time zones on other planets</h2> 1269325057Sphilip<p> 1270331663SphilipSome people's work schedules 1271339631Sphilipuse <a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>. 1272333313SphilipJet Propulsion Laboratory (JPL) coordinators kept Mars time on 1273333313Sphilipand off during the 1274342669Sphilip<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars 1275331663SphilipPathfinder</a> mission. 1276333313SphilipSome of their family members also adapted to Mars time. 1277331663SphilipDozens of special Mars watches were built for JPL workers who kept 1278331663SphilipMars time during the Mars Exploration Rovers mission (2004). 1279331663SphilipThese timepieces look like normal Seikos and Citizens but use Mars 1280331663Sphilipseconds rather than terrestrial seconds. 1281325057Sphilip</p> 1282325057Sphilip 1283325057Sphilip<p> 1284325057SphilipA Mars solar day is called a "sol" and has a mean period equal to 1285331663Sphilipabout 24 hours 39 minutes 35.244 seconds in terrestrial time. 1286331663SphilipIt is divided into a conventional 24-hour clock, so each Mars second 1287331663Sphilipequals about 1.02749125 terrestrial seconds. 1288325057Sphilip</p> 1289325057Sphilip 1290325057Sphilip<p> 1291331663SphilipThe <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime 1292331663Sphilipmeridian</a> of Mars goes through the center of the crater 1293331663Sphilip<a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in 1294331663Sphiliphonor of the British astronomer who built the Greenwich telescope that 1295331663Sphilipdefines Earth's prime meridian. 1296331663SphilipMean solar time on the Mars prime meridian is 1297342669Sphilipcalled Mars Coordinated Time (<abbr>MTC</abbr>). 1298325057Sphilip</p> 1299325057Sphilip 1300325057Sphilip<p> 1301325057SphilipEach landed mission on Mars has adopted a different reference for 1302339631Sphilipsolar timekeeping, so there is no real standard for Mars time zones. 1303331663SphilipFor example, the 1304331663Sphilip<a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars 1305331663SphilipExploration Rover</a> project (2004) defined two time zones "Local 1306331663SphilipSolar Time A" and "Local Solar Time B" for its two missions, each zone 1307331663Sphilipdesigned so that its time equals local true solar time at 1308331663Sphilipapproximately the middle of the nominal mission. 1309331663SphilipSuch a "time zone" is not particularly suited for any application 1310331663Sphilipother than the mission itself. 1311325057Sphilip</p> 1312325057Sphilip 1313325057Sphilip<p> 1314325057SphilipMany calendars have been proposed for Mars, but none have achieved 1315331663Sphilipwide acceptance. 1316331663SphilipAstronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a 1317325057Sphilipsequential count of Mars solar days elapsed since about 1873-12-29 1318331663Sphilip12:00 <abbr>GMT</abbr>. 1319325057Sphilip</p> 1320325057Sphilip 1321325057Sphilip<p> 1322325057SphilipIn our solar system, Mars is the planet with time and calendar most 1323331663Sphiliplike Earth's. 1324331663SphilipOn other planets, Sun-based time and calendars would work quite 1325331663Sphilipdifferently. 1326331663SphilipFor example, although Mercury's 1327331663Sphilip<a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal 1328331663Sphiliprotation period</a> is 58.646 Earth days, Mercury revolves around the 1329331663SphilipSun so rapidly that an observer on Mercury's equator would see a 1330331663Sphilipsunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a 1331331663SphilipMercury day. 1332331663SphilipVenus is more complicated, partly because its rotation is slightly 1333331663Sphilip<a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>: 1334331663Sphilipits year is 1.92 of its days. 1335331663SphilipGas giants like Jupiter are trickier still, as their polar and 1336331663Sphilipequatorial regions rotate at different rates, so that the length of a 1337331663Sphilipday depends on latitude. 1338331663SphilipThis effect is most pronounced on Neptune, where the day is about 12 1339331663Sphiliphours at the poles and 18 hours at the equator. 1340325057Sphilip</p> 1341325057Sphilip 1342325057Sphilip<p> 1343331663SphilipAlthough the <code><abbr>tz</abbr></code> database does not support 1344331663Sphiliptime on other planets, it is documented here in the hopes that support 1345331663Sphilipwill be added eventually. 1346325057Sphilip</p> 1347325057Sphilip 1348325057Sphilip<p> 1349331663SphilipSources for time on other planets: 1350325057Sphilip</p> 1351331663Sphilip 1352325057Sphilip<ul> 1353325057Sphilip <li> 1354331663Sphilip Michael Allison and Robert Schmunk, 1355331663Sphilip "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical 1356331663Sphilip Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" 1357331663Sphilip (2015-06-30). 1358325057Sphilip </li> 1359325057Sphilip <li> 1360331663Sphilip Jia-Rui Chong, 1361331663Sphilip "<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays 1362331663Sphilip Fit for a Martian</a>", <cite>Los Angeles Times</cite> 1363333313Sphilip (2004-01-14), pp A1, A20–A21. 1364325057Sphilip </li> 1365325057Sphilip <li> 1366331663Sphilip Tom Chmielewski, 1367331663Sphilip "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet 1368331663Sphilip Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26) 1369325057Sphilip </li> 1370325057Sphilip <li> 1371331663Sphilip Matt Williams, 1372331663Sphilip "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How 1373331663Sphilip long is a day on the other planets of the solar system?</a>" 1374339631Sphilip (2016-01-20). 1375325057Sphilip </li> 1376325057Sphilip</ul> 1377331663Sphilip</section> 1378325057Sphilip 1379331663Sphilip<footer> 1380331663Sphilip <hr> 1381331663Sphilip This file is in the public domain, so clarified as of 2009-05-17 by 1382331663Sphilip Arthur David Olson. 1383331663Sphilip</footer> 1384325057Sphilip</body> 1385325057Sphilip</html> 1386