1<!DOCTYPE html> 2<html lang="en"> 3<head> 4 <title>Theory and pragmatics of the tz code and data</title> 5 <meta charset="UTF-8"> 6 <style> 7 pre {margin-left: 2em; white-space: pre-wrap;} 8 </style> 9</head> 10 11<body> 12<h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1> 13 <h3>Outline</h3> 14 <nav> 15 <ul> 16 <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code> 17 database</a></li> 18 <li><a href="#naming">Names of timezones</a></li> 19 <li><a href="#abbreviations">Time zone abbreviations</a></li> 20 <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code> 21 database</a></li> 22 <li><a href="#functions">Time and date functions</a></li> 23 <li><a href="#stability">Interface stability</a></li> 24 <li><a href="#calendar">Calendrical issues</a></li> 25 <li><a href="#planets">Time and time zones on other planets</a></li> 26 </ul> 27 </nav> 28 29<section> 30 <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2> 31<p> 32The <a 33href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code> 34database</a> attempts to record the history and predicted future of 35all computer-based clocks that track civil time. 36It organizes <a href="tz-link.html">time zone and daylight saving time 37data</a> by partitioning the world into <a 38href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a> 39whose clocks all agree about timestamps that occur after the <a 40href="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a> 41(1970-01-01 00:00:00 <a 42href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr 43title="Coordinated Universal Time">UTC</abbr></a>). 44The database labels each timezone with a notable location and 45records all known clock transitions for that location. 46Although 1970 is a somewhat-arbitrary cutoff, there are significant 47challenges to moving the cutoff earlier even by a decade or two, due 48to the wide variety of local practices before computer timekeeping 49became prevalent. 50</p> 51 52<p> 53Each timezone typically corresponds to a geographical region that is 54smaller than a traditional time zone, because clocks in a timezone 55all agree after 1970 whereas a traditional time zone merely 56specifies current standard time. For example, applications that deal 57with current and future timestamps in the traditional North 58American mountain time zone can choose from the timezones 59<code>America/Denver</code> which observes US-style daylight saving 60time, <code>America/Mazatlan</code> which observes Mexican-style DST, 61and <code>America/Phoenix</code> which does not observe DST. 62Applications that also deal with past timestamps in the mountain time 63zone can choose from over a dozen timezones, such as 64<code>America/Boise</code>, <code>America/Edmonton</code>, and 65<code>America/Hermosillo</code>, each of which currently uses mountain 66time but differs from other timezones for some timestamps after 1970. 67</p> 68 69<p> 70Clock transitions before 1970 are recorded for each timezone, 71because most systems support timestamps before 1970 and could 72misbehave if data entries were omitted for pre-1970 transitions. 73However, the database is not designed for and does not suffice for 74applications requiring accurate handling of all past times everywhere, 75as it would take far too much effort and guesswork to record all 76details of pre-1970 civil timekeeping. 77Although some information outside the scope of the database is 78collected in a file <code>backzone</code> that is distributed along 79with the database proper, this file is less reliable and does not 80necessarily follow database guidelines. 81</p> 82 83<p> 84As described below, reference source code for using the 85<code><abbr>tz</abbr></code> database is also available. 86The <code><abbr>tz</abbr></code> code is upwards compatible with <a 87href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international 88standard for <a 89href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems. 90As of this writing, the current edition of POSIX is: <a 91href="http://pubs.opengroup.org/onlinepubs/9699919799/"> The Open 92Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018 93Edition. 94Because the database's scope encompasses real-world changes to civil 95timekeeping, its model for describing time is more complex than the 96standard and daylight saving times supported by POSIX. 97A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can 98have more than two changes per year, these changes need not merely 99flip back and forth between two alternatives, and the rules themselves 100can change at times. 101Whether and when a timezone changes its 102clock, and even the timezone's notional base offset from UTC, are variable. 103It does not always make sense to talk about a timezone's 104"base offset", which is not necessarily a single number. 105</p> 106 107</section> 108 109<section> 110 <h2 id="naming">Names of timezones</h2> 111<p> 112Each timezone has a unique name. 113Inexperienced users are not expected to select these names unaided. 114Distributors should provide documentation and/or a simple selection 115interface that explains each name via a map or via descriptive text like 116"Ruthenia" instead of the timezone name "<code>Europe/Uzhgorod</code>". 117If geolocation information is available, a selection interface can 118locate the user on a timezone map or prioritize names that are 119geographically close. For an example selection interface, see the 120<code>tzselect</code> program in the <code><abbr>tz</abbr></code> code. 121The <a href="http://cldr.unicode.org/">Unicode Common Locale Data 122Repository</a> contains data that may be useful for other selection 123interfaces; it maps timezone names like <code>Europe/Uzhgorod</code> 124to CLDR names like <code>uauzh</code> which are in turn mapped to 125locale-dependent strings like "Uzhhorod", "Ungvár", "Ужгород", and 126"乌日哥罗德". 127</p> 128 129<p> 130The naming conventions attempt to strike a balance 131among the following goals: 132</p> 133 134<ul> 135 <li> 136 Uniquely identify every timezone where clocks have agreed since 1970. 137 This is essential for the intended use: static clocks keeping local 138 civil time. 139 </li> 140 <li> 141 Indicate to experts where the timezone's clocks typically are. 142 </li> 143 <li> 144 Be robust in the presence of political changes. 145 For example, names of countries are ordinarily not used, to avoid 146 incompatibilities when countries change their name (e.g., 147 Zaire→Congo) or when locations change countries (e.g., Hong 148 Kong from UK colony to China). 149 </li> 150 <li> 151 Be portable to a wide variety of implementations. 152 </li> 153 <li> 154 Use a consistent naming conventions over the entire world. 155 </li> 156</ul> 157 158<p> 159Names normally have the form 160<var>AREA</var><code>/</code><var>LOCATION</var>, where 161<var>AREA</var> is a continent or ocean, and 162<var>LOCATION</var> is a specific location within the area. 163North and South America share the same area, '<code>America</code>'. 164Typical names are '<code>Africa/Cairo</code>', 165'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'. 166Some names are further qualified to help avoid confusion; for example, 167'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg, 168Indiana from other Petersburgs in America. 169</p> 170 171<p> 172Here are the general guidelines used for 173choosing timezone names, 174in decreasing order of importance: 175</p> 176 177<ul> 178 <li> 179 Use only valid POSIX file name components (i.e., the parts of 180 names other than '<code>/</code>'). 181 Do not use the file name components '<code>.</code>' and 182 '<code>..</code>'. 183 Within a file name component, use only <a 184 href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters, 185 '<code>.</code>', '<code>-</code>' and '<code>_</code>'. 186 Do not use digits, as that might create an ambiguity with <a 187 href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX 188 <code>TZ</code> strings</a>. 189 A file name component must not exceed 14 characters or start with 190 '<code>-</code>'. 191 E.g., prefer <code>Asia/Brunei</code> to 192 <code>Asia/Bandar_Seri_Begawan</code>. 193 Exceptions: see the discussion of legacy names below. 194 </li> 195 <li> 196 A name must not be empty, or contain '<code>//</code>', or 197 start or end with '<code>/</code>'. 198 </li> 199 <li> 200 Do not use names that differ only in case. 201 Although the reference implementation is case-sensitive, some 202 other implementations are not, and they would mishandle names 203 differing only in case. 204 </li> 205 <li> 206 If one name <var>A</var> is an initial prefix of another 207 name <var>AB</var> (ignoring case), then <var>B</var> must not 208 start with '<code>/</code>', as a regular file cannot have the 209 same name as a directory in POSIX. 210 For example, <code>America/New_York</code> precludes 211 <code>America/New_York/Bronx</code>. 212 </li> 213 <li> 214 Uninhabited regions like the North Pole and Bouvet Island 215 do not need locations, since local time is not defined there. 216 </li> 217 <li> 218 There should typically be at least one name for each <a 219 href="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr 220 title="International Organization for Standardization">ISO</abbr> 221 3166-1</a> officially assigned two-letter code for an inhabited 222 country or territory. 223 </li> 224 <li> 225 If all the clocks in a timezone have agreed since 1970, 226 do not bother to include more than one timezone 227 even if some of the clocks disagreed before 1970. 228 Otherwise these tables would become annoyingly large. 229 </li> 230 <li> 231 If a name is ambiguous, use a less ambiguous alternative; 232 e.g., many cities are named San José and Georgetown, so 233 prefer <code>America/Costa_Rica</code> to 234 <code>America/San_Jose</code> and <code>America/Guyana</code> 235 to <code>America/Georgetown</code>. 236 </li> 237 <li> 238 Keep locations compact. 239 Use cities or small islands, not countries or regions, so that any 240 future changes do not split individual locations into different 241 timezones. 242 E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>, 243 since 244 <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France 245 has had multiple time zones</a>. 246 </li> 247 <li> 248 Use mainstream English spelling, e.g., prefer 249 <code>Europe/Rome</code> to <code>Europa/Roma</code>, and 250 prefer <code>Europe/Athens</code> to the Greek 251 <code>Ευρώπη/Αθήνα</code> or the Romanized 252 <code>Evrópi/Athína</code>. 253 The POSIX file name restrictions encourage this guideline. 254 </li> 255 <li> 256 Use the most populous among locations in a region, 257 e.g., prefer <code>Asia/Shanghai</code> to 258 <code>Asia/Beijing</code>. 259 Among locations with similar populations, pick the best-known 260 location, e.g., prefer <code>Europe/Rome</code> to 261 <code>Europe/Milan</code>. 262 </li> 263 <li> 264 Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to 265 <code>Atlantic/Canaries</code>. 266 </li> 267 <li> 268 Omit common suffixes like '<code>_Islands</code>' and 269 '<code>_City</code>', unless that would lead to ambiguity. 270 E.g., prefer <code>America/Cayman</code> to 271 <code>America/Cayman_Islands</code> and 272 <code>America/Guatemala</code> to 273 <code>America/Guatemala_City</code>, but prefer 274 <code>America/Mexico_City</code> to 275 <code>America/Mexico</code> 276 because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the 277 country of Mexico has several time zones</a>. 278 </li> 279 <li> 280 Use '<code>_</code>' to represent a space. 281 </li> 282 <li> 283 Omit '<code>.</code>' from abbreviations in names. 284 E.g., prefer <code>Atlantic/St_Helena</code> to 285 <code>Atlantic/St._Helena</code>. 286 </li> 287 <li> 288 Do not change established names if they only marginally violate 289 the above guidelines. 290 For example, do not change the existing name <code>Europe/Rome</code> to 291 <code>Europe/Milan</code> merely because Milan's population has grown 292 to be somewhat greater than Rome's. 293 </li> 294 <li> 295 If a name is changed, put its old spelling in the 296 '<code>backward</code>' file. 297 This means old spellings will continue to work. 298 </li> 299</ul> 300 301<p> 302The file '<code>zone1970.tab</code>' lists geographical locations used 303to name timezones. 304It is intended to be an exhaustive list of names for geographic 305regions as described above; this is a subset of the timezones in the data. 306Although a '<code>zone1970.tab</code>' location's 307<a href="https://en.wikipedia.org/wiki/Longitude">longitude</a> 308corresponds to 309its <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean 310time (<abbr>LMT</abbr>)</a> offset with one hour for every 15° 311east longitude, this relationship is not exact. 312</p> 313 314<p> 315Older versions of this package used a different naming scheme, 316and these older names are still supported. 317See the file '<code>backward</code>' for most of these older names 318(e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>'). 319The other old-fashioned names still supported are 320'<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and 321'<code>EET</code>' (see the file '<code>europe</code>'). 322</p> 323 324<p> 325Older versions of this package defined legacy names that are 326incompatible with the first guideline of location names, but which are 327still supported. 328These legacy names are mostly defined in the file 329'<code>etcetera</code>'. 330Also, the file '<code>backward</code>' defines the legacy names 331'<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', 332and the file '<code>northamerica</code>' defines the legacy names 333'<code>EST5EDT</code>', '<code>CST6CDT</code>', 334'<code>MST7MDT</code>', and '<code>PST8PDT</code>'. 335</p> 336 337<p> 338Excluding '<code>backward</code>' should not affect the other data. 339If '<code>backward</code>' is excluded, excluding 340'<code>etcetera</code>' should not affect the remaining data. 341</p> 342</section> 343 344<section> 345 <h2 id="abbreviations">Time zone abbreviations</h2> 346<p> 347When this package is installed, it generates time zone abbreviations 348like '<code>EST</code>' to be compatible with human tradition and POSIX. 349Here are the general guidelines used for choosing time zone abbreviations, 350in decreasing order of importance: 351</p> 352 353<ul> 354 <li> 355 Use three to six characters that are ASCII alphanumerics or 356 '<code>+</code>' or '<code>-</code>'. 357 Previous editions of this database also used characters like 358 space and '<code>?</code>', but these characters have a 359 special meaning to the 360 <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a> 361 and cause commands like 362 '<code><a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a> 363 `<a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>' 364 to have unexpected effects. 365 Previous editions of this guideline required upper-case letters, but the 366 Congressman who introduced 367 <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro 368 Standard Time</a> preferred "ChST", so lower-case letters are now 369 allowed. 370 Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>', 371 '<code>+</code>', and alphanumeric characters from the portable 372 character set in the current locale. 373 In practice ASCII alphanumerics and '<code>+</code>' and 374 '<code>-</code>' are safe in all locales. 375 376 <p> 377 In other words, in the C locale the POSIX extended regular 378 expression <code>[-+[:alnum:]]{3,6}</code> should match the 379 abbreviation. 380 This guarantees that all abbreviations could have been specified by a 381 POSIX <code>TZ</code> string. 382 </p> 383 </li> 384 <li> 385 Use abbreviations that are in common use among English-speakers, 386 e.g., 'EST' for Eastern Standard Time in North America. 387 We assume that applications translate them to other languages 388 as part of the normal localization process; for example, 389 a French application might translate 'EST' to 'HNE'. 390 391 <p> 392 <small>These abbreviations (for standard/daylight/etc. time) are: 393 ACST/ACDT Australian Central, 394 AST/ADT/APT/AWT/ADDT Atlantic, 395 AEST/AEDT Australian Eastern, 396 AHST/AHDT Alaska-Hawaii, 397 AKST/AKDT Alaska, 398 AWST/AWDT Australian Western, 399 BST/BDT Bering, 400 CAT/CAST Central Africa, 401 CET/CEST/CEMT Central European, 402 ChST Chamorro, 403 CST/CDT/CWT/CPT/CDDT Central [North America], 404 CST/CDT China, 405 GMT/BST/IST/BDST Greenwich, 406 EAT East Africa, 407 EST/EDT/EWT/EPT/EDDT Eastern [North America], 408 EET/EEST Eastern European, 409 GST Guam, 410 HST/HDT/HWT/HPT Hawaii, 411 HKT/HKST Hong Kong, 412 IST India, 413 IST/GMT Irish, 414 IST/IDT/IDDT Israel, 415 JST/JDT Japan, 416 KST/KDT Korea, 417 MET/MEST Middle European (a backward-compatibility alias for 418 Central European), 419 MSK/MSD Moscow, 420 MST/MDT/MWT/MPT/MDDT Mountain, 421 NST/NDT/NWT/NPT/NDDT Newfoundland, 422 NST/NDT/NWT/NPT Nome, 423 NZMT/NZST New Zealand through 1945, 424 NZST/NZDT New Zealand 1946–present, 425 PKT/PKST Pakistan, 426 PST/PDT/PWT/PPT/PDDT Pacific, 427 PST/PDT Philippine, 428 SAST South Africa, 429 SST Samoa, 430 WAT/WAST West Africa, 431 WET/WEST/WEMT Western European, 432 WIB Waktu Indonesia Barat, 433 WIT Waktu Indonesia Timur, 434 WITA Waktu Indonesia Tengah, 435 YST/YDT/YWT/YPT/YDDT Yukon</small>. 436 </p> 437 </li> 438 <li> 439 <p> 440 For times taken from a city's longitude, use the 441 traditional <var>x</var>MT notation. 442 The only abbreviation like this in current use is '<abbr>GMT</abbr>'. 443 The others are for timestamps before 1960, 444 except that Monrovia Mean Time persisted until 1972. 445 Typically, numeric abbreviations (e.g., '<code>-</code>004430' for 446 MMT) would cause trouble here, as the numeric strings would exceed 447 the POSIX length limit. 448 </p> 449 450 <p> 451 <small>These abbreviations are: 452 AMT Amsterdam, Asunción, Athens; 453 BMT Baghdad, Bangkok, Batavia, Bern, Bogotá, Bridgetown, Brussels, 454 Bucharest; 455 CMT Calamarca, Caracas, Chisinau, Colón, Copenhagen, Córdoba; 456 DMT Dublin/Dunsink; 457 EMT Easter; 458 FFMT Fort-de-France; 459 FMT Funchal; 460 GMT Greenwich; 461 HMT Havana, Helsinki, Horta, Howrah; 462 IMT Irkutsk, Istanbul; 463 JMT Jerusalem; 464 KMT Kaunas, Kiev, Kingston; 465 LMT Lima, Lisbon, local, Luanda; 466 MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo, 467 Moratuwa, Moscow; 468 PLMT Phù Liễn; 469 PMT Paramaribo, Paris, Perm, Pontianak, Prague; 470 PMMT Port Moresby; 471 QMT Quito; 472 RMT Rangoon, Riga, Rome; 473 SDMT Santo Domingo; 474 SJMT San José; 475 SMT Santiago, Simferopol, Singapore, Stanley; 476 TBMT Tbilisi; 477 TMT Tallinn, Tehran; 478 WMT Warsaw</small>. 479 </p> 480 481 <p> 482 <small>A few abbreviations also follow the pattern that 483 <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK. 484 They are: 485 CMT/BST for Calamarca Mean Time and Bolivian Summer Time 486 1890–1932, 487 DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time 488 1880–1916, 489 MMT/MST/MDST for Moscow 1880–1919, and 490 RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926. 491 An extra-special case is SET for Swedish Time (<em>svensk 492 normaltid</em>) 1879–1899, 3° west of the Stockholm 493 Observatory.</small> 494 </p> 495 </li> 496 <li> 497 Use '<abbr>LMT</abbr>' for local mean time of locations before the 498 introduction of standard time; see "<a href="#scope">Scope of the 499 <code><abbr>tz</abbr></code> database</a>". 500 </li> 501 <li> 502 If there is no common English abbreviation, use numeric offsets like 503 <code>-</code>05 and <code>+</code>0530 that are generated 504 by <code>zic</code>'s <code>%z</code> notation. 505 </li> 506 <li> 507 Use current abbreviations for older timestamps to avoid confusion. 508 For example, in 1910 a common English abbreviation for time 509 in central Europe was 'MEZ' (short for both "Middle European 510 Zone" and for "Mitteleuropäische Zeit" in German). 511 Nowadays 'CET' ("Central European Time") is more common in 512 English, and the database uses 'CET' even for circa-1910 513 timestamps as this is less confusing for modern users and avoids 514 the need for determining when 'CET' supplanted 'MEZ' in common 515 usage. 516 </li> 517 <li> 518 Use a consistent style in a timezone's history. 519 For example, if a history tends to use numeric 520 abbreviations and a particular entry could go either way, use a 521 numeric abbreviation. 522 </li> 523 <li> 524 Use 525 <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a> 526 (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for 527 locations while uninhabited. 528 The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in 529 some sense undefined; this notation is derived 530 from <a href="https://tools.ietf.org/html/rfc3339">Internet 531 <abbr title="Request For Comments">RFC</abbr> 3339</a>. 532 </li> 533</ul> 534 535<p> 536Application writers should note that these abbreviations are ambiguous 537in practice: e.g., 'CST' means one thing in China and something else 538in North America, and 'IST' can refer to time in India, Ireland or 539Israel. 540To avoid ambiguity, use numeric <abbr>UT</abbr> offsets like 541'<code>-</code>0600' instead of time zone abbreviations like 'CST'. 542</p> 543</section> 544 545<section> 546 <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2> 547<p> 548The <code><abbr>tz</abbr></code> database is not authoritative, and it 549surely has errors. 550Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. 551Users requiring authoritative data should consult national standards 552bodies and the references cited in the database's comments. 553</p> 554 555<p> 556Errors in the <code><abbr>tz</abbr></code> database arise from many sources: 557</p> 558 559<ul> 560 <li> 561 The <code><abbr>tz</abbr></code> database predicts future 562 timestamps, and current predictions 563 will be incorrect after future governments change the rules. 564 For example, if today someone schedules a meeting for 13:00 next 565 October 1, Casablanca time, and tomorrow Morocco changes its 566 daylight saving rules, software can mess up after the rule change 567 if it blithely relies on conversions made before the change. 568 </li> 569 <li> 570 The pre-1970 entries in this database cover only a tiny sliver of how 571 clocks actually behaved; the vast majority of the necessary 572 information was lost or never recorded. 573 Thousands more timezones would be needed if 574 the <code><abbr>tz</abbr></code> database's scope were extended to 575 cover even just the known or guessed history of standard time; for 576 example, the current single entry for France would need to split 577 into dozens of entries, perhaps hundreds. 578 And in most of the world even this approach would be misleading 579 due to widespread disagreement or indifference about what times 580 should be observed. 581 In her 2015 book 582 <cite><a 583 href="http://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The 584 Global Transformation of Time, 1870–1950</a></cite>, 585 Vanessa Ogle writes 586 "Outside of Europe and North America there was no system of time 587 zones at all, often not even a stable landscape of mean times, 588 prior to the middle decades of the twentieth century". 589 See: Timothy Shenk, <a 590href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked: 591 A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. 592 </li> 593 <li> 594 Most of the pre-1970 data entries come from unreliable sources, often 595 astrology books that lack citations and whose compilers evidently 596 invented entries when the true facts were unknown, without 597 reporting which entries were known and which were invented. 598 These books often contradict each other or give implausible entries, 599 and on the rare occasions when they are checked they are 600 typically found to be incorrect. 601 </li> 602 <li> 603 For the UK the <code><abbr>tz</abbr></code> database relies on 604 years of first-class work done by 605 Joseph Myers and others; see 606 "<a href="https://www.polyomino.org.uk/british-time/">History of 607 legal time in Britain</a>". 608 Other countries are not done nearly as well. 609 </li> 610 <li> 611 Sometimes, different people in the same city maintain clocks 612 that differ significantly. 613 Historically, railway time was used by railroad companies (which 614 did not always 615 agree with each other), church-clock time was used for birth 616 certificates, etc. 617 More recently, competing political groups might disagree about 618 clock settings. Often this is merely common practice, but 619 sometimes it is set by law. 620 For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France 621 was legally <abbr>UT</abbr> +00:09:21 outside train stations and 622 <abbr>UT</abbr> +00:04:21 inside. Other examples include 623 Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and 624 Ürümqi to this day. 625 </li> 626 <li> 627 Although a named location in the <code><abbr>tz</abbr></code> 628 database stands for the containing region, its pre-1970 data 629 entries are often accurate for only a small subset of that region. 630 For example, <code>Europe/London</code> stands for the United 631 Kingdom, but its pre-1847 times are valid only for locations that 632 have London's exact meridian, and its 1847 transition 633 to <abbr>GMT</abbr> is known to be valid only for the L&NW and 634 the Caledonian railways. 635 </li> 636 <li> 637 The <code><abbr>tz</abbr></code> database does not record the 638 earliest time for which a timezone's 639 data entries are thereafter valid for every location in the region. 640 For example, <code>Europe/London</code> is valid for all locations 641 in its region after <abbr>GMT</abbr> was made the standard time, 642 but the date of standardization (1880-08-02) is not in the 643 <code><abbr>tz</abbr></code> database, other than in commentary. 644 For many timezones the earliest time of 645 validity is unknown. 646 </li> 647 <li> 648 The <code><abbr>tz</abbr></code> database does not record a 649 region's boundaries, and in many cases the boundaries are not known. 650 For example, the timezone 651 <code>America/Kentucky/Louisville</code> represents a region 652 around the city of Louisville, the boundaries of which are 653 unclear. 654 </li> 655 <li> 656 Changes that are modeled as instantaneous transitions in the 657 <code><abbr>tz</abbr></code> 658 database were often spread out over hours, days, or even decades. 659 </li> 660 <li> 661 Even if the time is specified by law, locations sometimes 662 deliberately flout the law. 663 </li> 664 <li> 665 Early timekeeping practices, even assuming perfect clocks, were 666 often not specified to the accuracy that the 667 <code><abbr>tz</abbr></code> database requires. 668 </li> 669 <li> 670 Sometimes historical timekeeping was specified more precisely 671 than what the <code><abbr>tz</abbr></code> code can handle. 672 For example, from 1909 to 1937 <a 673 href="https://www.staff.science.uu.nl/~gent0113/wettijd/wettijd.htm" 674 hreflang="nl">Netherlands clocks</a> were legally Amsterdam Mean 675 Time (estimated to be <abbr>UT</abbr> 676 +00:19:32.13), but the <code><abbr>tz</abbr></code> 677 code cannot represent the fractional second. 678 In practice these old specifications were rarely if ever 679 implemented to subsecond precision. 680 </li> 681 <li> 682 Even when all the timestamp transitions recorded by the 683 <code><abbr>tz</abbr></code> database are correct, the 684 <code><abbr>tz</abbr></code> rules that generate them may not 685 faithfully reflect the historical rules. 686 For example, from 1922 until World War II the UK moved clocks 687 forward the day following the third Saturday in April unless that 688 was Easter, in which case it moved clocks forward the previous 689 Sunday. 690 Because the <code><abbr>tz</abbr></code> database has no 691 way to specify Easter, these exceptional years are entered as 692 separate <code><abbr>tz</abbr> Rule</code> lines, even though the 693 legal rules did not change. 694 When transitions are known but the historical rules behind them are not, 695 the database contains <code>Zone</code> and <code>Rule</code> 696 entries that are intended to represent only the generated 697 transitions, not any underlying historical rules; however, this 698 intent is recorded at best only in commentary. 699 </li> 700 <li> 701 The <code><abbr>tz</abbr></code> database models time 702 using the <a 703 href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic 704 Gregorian calendar</a> with days containing 24 equal-length hours 705 numbered 00 through 23, except when clock transitions occur. 706 Pre-standard time is modeled as local mean time. 707 However, historically many people used other calendars and other timescales. 708 For example, the Roman Empire used 709 the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian 710 calendar</a>, 711 and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman 712 timekeeping</a> had twelve varying-length daytime hours with a 713 non-hour-based system at night. 714 And even today, some local practices diverge from the Gregorian 715 calendar with 24-hour days. These divergences range from 716 relatively minor, such as Japanese bars giving times like "24:30" for the 717 wee hours of the morning, to more-significant differences such as <a 718 href="https://www.pri.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the 719 east African practice of starting the day at dawn</a>, renumbering 720 the Western 06:00 to be 12:00. These practices are largely outside 721 the scope of the <code><abbr>tz</abbr></code> code and data, which 722 provide only limited support for date and time localization 723 such as that required by POSIX. If DST is not used a different time zone 724 can often do the trick; for example, in Kenya a <code>TZ</code> setting 725 like <code><-03>3</code> or <code>America/Cayenne</code> starts 726 the day six hours later than <code>Africa/Nairobi</code> does. 727 </li> 728 <li> 729 Early clocks were less reliable, and data entries do not represent 730 clock error. 731 </li> 732 <li> 733 The <code><abbr>tz</abbr></code> database assumes Universal Time 734 (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not 735 standardized for older timestamps. 736 In the <code><abbr>tz</abbr></code> database commentary, 737 <abbr>UT</abbr> denotes a family of time standards that includes 738 Coordinated Universal Time (<abbr>UTC</abbr>) along with other 739 variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>, 740 with days starting at midnight. 741 Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern 742 timestamps, <abbr>UTC</abbr> was not defined until 1960, so 743 commentary uses the more-general abbreviation <abbr>UT</abbr> for 744 timestamps that might predate 1960. 745 Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly, 746 and since pre-1972 <abbr>UTC</abbr> seconds varied in length, 747 interpretation of older timestamps can be problematic when 748 subsecond accuracy is needed. 749 </li> 750 <li> 751 Civil time was not based on atomic time before 1972, and we do not 752 know the history of 753 <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's 754 rotation</a> accurately enough to map <a 755 href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr 756 title="International System of Units">SI</abbr></a> seconds to 757 historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a> 758 to more than about one-hour accuracy. 759 See: Stephenson FR, Morrison LV, Hohenkerk CY. 760 <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of 761 the Earth's rotation: 720 BC to AD 2015</a>. 762 <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404. 763 Also see: Espenak F. <a 764 href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty 765 in Delta T (ΔT)</a>. 766 </li> 767 <li> 768 The relationship between POSIX time (that is, <abbr>UTC</abbr> but 769 ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap 770 seconds</a>) and <abbr>UTC</abbr> is not agreed upon after 1972. 771 Although the POSIX 772 clock officially stops during an inserted leap second, at least one 773 proposed standard has it jumping back a second instead; and in 774 practice POSIX clocks more typically either progress glacially during 775 a leap second, or are slightly slowed while near a leap second. 776 </li> 777 <li> 778 The <code><abbr>tz</abbr></code> database does not represent how 779 uncertain its information is. 780 Ideally it would contain information about when data entries are 781 incomplete or dicey. 782 Partial temporal knowledge is a field of active research, though, 783 and it is not clear how to apply it here. 784 </li> 785</ul> 786 787<p> 788In short, many, perhaps most, of the <code><abbr>tz</abbr></code> 789database's pre-1970 and future timestamps are either wrong or 790misleading. 791Any attempt to pass the 792<code><abbr>tz</abbr></code> database off as the definition of time 793should be unacceptable to anybody who cares about the facts. 794In particular, the <code><abbr>tz</abbr></code> database's 795<abbr>LMT</abbr> offsets should not be considered meaningful, and 796should not prompt creation of timezones 797merely because two locations 798differ in <abbr>LMT</abbr> or transitioned to standard time at 799different dates. 800</p> 801</section> 802 803<section> 804 <h2 id="functions">Time and date functions</h2> 805<p> 806The <code><abbr>tz</abbr></code> code contains time and date functions 807that are upwards compatible with those of POSIX. 808Code compatible with this package is already 809<a href="tz-link.html#tzdb">part of many platforms</a>, where the 810primary use of this package is to update obsolete time-related files. 811To do this, you may need to compile the time zone compiler 812'<code>zic</code>' supplied with this package instead of using the 813system '<code>zic</code>', since the format of <code>zic</code>'s 814input is occasionally extended, and a platform may still be shipping 815an older <code>zic</code>. 816</p> 817 818<h3 id="POSIX">POSIX properties and limitations</h3> 819<ul> 820 <li> 821 <p> 822 In POSIX, time display in a process is controlled by the 823 environment variable <code>TZ</code>. 824 Unfortunately, the POSIX 825 <code>TZ</code> string takes a form that is hard to describe and 826 is error-prone in practice. 827 Also, POSIX <code>TZ</code> strings cannot deal with daylight 828 saving time rules not based on the Gregorian calendar (as in 829 Iran), or with situations where more than two time zone 830 abbreviations or <abbr>UT</abbr> offsets are used in an area. 831 </p> 832 833 <p> 834 The POSIX <code>TZ</code> string takes the following form: 835 </p> 836 837 <p> 838 <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>]]] 839 </p> 840 841 <p> 842 where: 843 </p> 844 845 <dl> 846 <dt><var>std</var> and <var>dst</var></dt><dd> 847 are 3 or more characters specifying the standard 848 and daylight saving time (<abbr>DST</abbr>) zone abbreviations. 849 Starting with POSIX.1-2001, <var>std</var> and <var>dst</var> 850 may also be in a quoted form like '<code><+09></code>'; 851 this allows "<code>+</code>" and "<code>-</code>" in the names. 852 </dd> 853 <dt><var>offset</var></dt><dd> 854 is of the form 855 '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' 856 and specifies the offset west of <abbr>UT</abbr>. 857 '<var>hh</var>' may be a single digit; 858 0≤<var>hh</var>≤24. 859 The default <abbr>DST</abbr> offset is one hour ahead of 860 standard time. 861 </dd> 862 <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> 863 specifies the beginning and end of <abbr>DST</abbr>. 864 If this is absent, the system supplies its own ruleset 865 for <abbr>DST</abbr>, and its rules can differ from year to year; 866 typically <abbr>US</abbr> <abbr>DST</abbr> rules are used. 867 </dd> 868 <dt><var>time</var></dt><dd> 869 takes the form 870 '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]' 871 and defaults to 02:00. 872 This is the same format as the offset, except that a 873 leading '<code>+</code>' or '<code>-</code>' is not allowed. 874 </dd> 875 <dt><var>date</var></dt><dd> 876 takes one of the following forms: 877 <dl> 878 <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> 879 origin-1 day number not counting February 29 880 </dd> 881 <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> 882 origin-0 day number counting February 29 if present 883 </dd> 884 <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> 885 (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, 886 1≤<var>m</var>≤12)</dt><dd> 887 for the <var>d</var>th day of week <var>n</var> of 888 month <var>m</var> of the year, where week 1 is the first 889 week in which day <var>d</var> appears, and 890 '<code>5</code>' stands for the last week in which 891 day <var>d</var> appears (which may be either the 4th or 892 5th week). 893 Typically, this is the only useful form; the <var>n</var> 894 and <code>J</code><var>n</var> forms are rarely used. 895 </dd> 896 </dl> 897 </dd> 898 </dl> 899 900 <p> 901 Here is an example POSIX <code>TZ</code> string for New 902 Zealand after 2007. 903 It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead 904 of <abbr>UT</abbr>, and that daylight saving time 905 (<abbr>NZDT</abbr>) is observed from September's last Sunday at 906 02:00 until April's first Sunday at 03:00: 907 </p> 908 909 <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> 910 911 <p> 912 This POSIX <code>TZ</code> string is hard to remember, and 913 mishandles some timestamps before 2008. 914 With this package you can use this instead: 915 </p> 916 917 <pre><code>TZ='Pacific/Auckland'</code></pre> 918 </li> 919 <li> 920 POSIX does not define the <abbr>DST</abbr> transitions 921 for <code>TZ</code> values like 922 "<code>EST5EDT</code>". 923 Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules 924 were used to interpret such values, but this meant that the 925 <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each 926 program that did time conversion. This meant that when 927 <abbr>US</abbr> time conversion rules changed (as in the United 928 States in 1987), all programs that did time conversion had to be 929 recompiled to ensure proper results. 930 </li> 931 <li> 932 The <code>TZ</code> environment variable is process-global, which 933 makes it hard to write efficient, thread-safe applications that 934 need access to multiple timezones. 935 </li> 936 <li> 937 In POSIX, there is no tamper-proof way for a process to learn the 938 system's best idea of local wall clock. 939 This is important for applications that an administrator wants 940 used only at certain times – without regard to whether the 941 user has fiddled the 942 <code>TZ</code> environment variable. 943 While an administrator can "do everything in <abbr>UT</abbr>" to 944 get around the problem, doing so is inconvenient and precludes 945 handling daylight saving time shifts – as might be required to 946 limit phone calls to off-peak hours. 947 </li> 948 <li> 949 POSIX provides no convenient and efficient way to determine 950 the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary 951 timestamps, particularly for timezones 952 that do not fit into the POSIX model. 953 </li> 954 <li> 955 POSIX requires that systems ignore leap seconds. 956 </li> 957 <li> 958 The <code><abbr>tz</abbr></code> code attempts to support all the 959 <code>time_t</code> implementations allowed by POSIX. 960 The <code>time_t</code> type represents a nonnegative count of seconds 961 since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds. 962 In practice, <code>time_t</code> is usually a signed 64- or 32-bit 963 integer; 32-bit signed <code>time_t</code> values stop working after 964 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these 965 days typically use a signed 64-bit integer. 966 Unsigned 32-bit integers are used on one or two platforms, and 36-bit 967 and 40-bit integers are also used occasionally. 968 Although earlier POSIX versions allowed <code>time_t</code> to be a 969 floating-point type, this was not supported by any practical system, 970 and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both 971 require <code>time_t</code> to be an integer type. 972 </li> 973</ul> 974 975<h3 id="POSIX-extensions">Extensions to POSIX in the 976<code><abbr>tz</abbr></code> code</h3> 977<ul> 978 <li> 979 <p> 980 The <code>TZ</code> environment variable is used in generating 981 the name of a file from which time-related information is read 982 (or is interpreted à la POSIX); <code>TZ</code> is no longer 983 constrained to be a string containing abbreviations 984 and numeric data as described <a href="#POSIX">above</a>. 985 The file's format is <dfn><abbr>TZif</abbr></dfn>, 986 a timezone information format that contains binary data. 987 The daylight saving time rules to be used for a 988 particular timezone are encoded in the 989 <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>, 990 Australian, and other rules to be encoded, and 991 allows for situations where more than two time zone 992 abbreviations are used. 993 </p> 994 <p> 995 It was recognized that allowing the <code>TZ</code> environment 996 variable to take on values such as '<code>America/New_York</code>' 997 might cause "old" programs (that expect <code>TZ</code> to have a 998 certain form) to operate incorrectly; consideration was given to using 999 some other environment variable (for example, <code>TIMEZONE</code>) 1000 to hold the string used to generate the <abbr>TZif</abbr> file's name. 1001 In the end, however, it was decided to continue using 1002 <code>TZ</code>: it is widely used for time zone purposes; 1003 separately maintaining both <code>TZ</code> 1004 and <code>TIMEZONE</code> seemed a nuisance; and systems where 1005 "new" forms of <code>TZ</code> might cause problems can simply 1006 use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which 1007 can be used by "new" programs as well as by "old" programs that 1008 assume pre-POSIX <code>TZ</code> values. 1009 </p> 1010 </li> 1011 <li> 1012 The code supports platforms with a <abbr>UT</abbr> offset member 1013 in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>. 1014 </li> 1015 <li> 1016 The code supports platforms with a time zone abbreviation member in 1017 <code>struct tm</code>, e.g., <code>tm_zone</code>. 1018 </li> 1019 <li> 1020 Functions <code>tzalloc</code>, <code>tzfree</code>, 1021 <code>localtime_rz</code>, and <code>mktime_z</code> for 1022 more-efficient thread-safe applications that need to use multiple 1023 timezones. 1024 The <code>tzalloc</code> and <code>tzfree</code> functions 1025 allocate and free objects of type <code>timezone_t</code>, 1026 and <code>localtime_rz</code> and <code>mktime_z</code> are 1027 like <code>localtime_r</code> and <code>mktime</code> with an 1028 extra <code>timezone_t</code> argument. 1029 The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>. 1030 </li> 1031 <li> 1032 A function <code>tzsetwall</code> has been added to arrange for the 1033 system's best approximation to local wall clock time to be delivered 1034 by subsequent calls to <code>localtime</code>. 1035 Source code for portable applications that "must" run on local wall 1036 clock time should call <code>tzsetwall</code>; 1037 if such code is moved to "old" systems that do not 1038 provide <code>tzsetwall</code>, you will not be able to generate an 1039 executable program. 1040 (These functions also arrange for local wall clock time to 1041 be used if <code>tzset</code> is called – directly or 1042 indirectly – and there is no <code>TZ</code> environment 1043 variable; portable applications should not, however, rely on this 1044 behavior since it is not the way <a 1045 href="https://en.wikipedia.org/wiki/UNIX_System_V#SVR2"><abbr>SVR2</abbr></a> 1046 systems behave.) 1047 </li> 1048 <li> 1049 Negative <code>time_t</code> values are supported, on systems 1050 where <code>time_t</code> is signed. 1051 </li> 1052 <li> 1053 These functions can account for leap seconds, thanks to Bradley White. 1054 </li> 1055</ul> 1056 1057<h3 id="vestigial">POSIX features no longer needed</h3> 1058<p> 1059POSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a> 1060define some <a href="https://en.wikipedia.org/wiki/API"><abbr 1061title="application programming interface">API</abbr>s</a> that are vestigial: 1062they are not needed, and are relics of a too-simple model that does 1063not suffice to handle many real-world timestamps. 1064Although the <code><abbr>tz</abbr></code> code supports these 1065vestigial <abbr>API</abbr>s for backwards compatibility, they should 1066be avoided in portable applications. 1067The vestigial <abbr>API</abbr>s are: 1068</p> 1069<ul> 1070 <li> 1071 The POSIX <code>tzname</code> variable does not suffice and is no 1072 longer needed. 1073 To get a timestamp's time zone abbreviation, consult 1074 the <code>tm_zone</code> member if available; otherwise, 1075 use <code>strftime</code>'s <code>"%Z"</code> conversion 1076 specification. 1077 </li> 1078 <li> 1079 The POSIX <code>daylight</code> and <code>timezone</code> 1080 variables do not suffice and are no longer needed. 1081 To get a timestamp's <abbr>UT</abbr> offset, consult 1082 the <code>tm_gmtoff</code> member if available; otherwise, 1083 subtract values returned by <code>localtime</code> 1084 and <code>gmtime</code> using the rules of the Gregorian calendar, 1085 or use <code>strftime</code>'s <code>"%z"</code> conversion 1086 specification if a string like <code>"+0900"</code> suffices. 1087 </li> 1088 <li> 1089 The <code>tm_isdst</code> member is almost never needed and most of 1090 its uses should be discouraged in favor of the abovementioned 1091 <abbr>API</abbr>s. 1092 Although it can still be used in arguments to 1093 <code>mktime</code> to disambiguate timestamps near 1094 a <abbr>DST</abbr> transition when the clock jumps back, this 1095 disambiguation does not work when standard time itself jumps back, 1096 which can occur when a location changes to a time zone with a 1097 lesser <abbr>UT</abbr> offset. 1098 </li> 1099</ul> 1100 1101<h3 id="other-portability">Other portability notes</h3> 1102<ul> 1103 <li> 1104 The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition 1105 UNIX</a> <code>timezone</code> function is not present in this 1106 package; it is impossible to reliably map <code>timezone</code>'s 1107 arguments (a "minutes west of <abbr>GMT</abbr>" value and a 1108 "daylight saving time in effect" flag) to a time zone 1109 abbreviation, and we refuse to guess. 1110 Programs that in the past used the <code>timezone</code> function 1111 may now examine <code>localtime(&clock)->tm_zone</code> 1112 (if <code>TM_ZONE</code> is defined) or 1113 <code>tzname[localtime(&clock)->tm_isdst]</code> 1114 (if <code>HAVE_TZNAME</code> is defined) to learn the correct time 1115 zone abbreviation to use. 1116 </li> 1117 <li> 1118 The <a 1119 href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a> 1120 <code>gettimeofday</code> function is not 1121 used in this package. 1122 This formerly let users obtain the current <abbr>UTC</abbr> offset 1123 and <abbr>DST</abbr> flag, but this functionality was removed in 1124 later versions of <abbr>BSD</abbr>. 1125 </li> 1126 <li> 1127 In <abbr>SVR2</abbr>, time conversion fails for near-minimum or 1128 near-maximum <code>time_t</code> values when doing conversions 1129 for places that do not use <abbr>UT</abbr>. 1130 This package takes care to do these conversions correctly. 1131 A comment in the source code tells how to get compatibly wrong 1132 results. 1133 </li> 1134 <li> 1135 The functions that are conditionally compiled 1136 if <code>STD_INSPIRED</code> is defined should, at this point, be 1137 looked on primarily as food for thought. 1138 They are not in any sense "standard compatible" – some are 1139 not, in fact, specified in <em>any</em> standard. 1140 They do, however, represent responses of various authors to 1141 standardization proposals. 1142 </li> 1143 <li> 1144 Other time conversion proposals, in particular those supported by the 1145 <a href="https://howardhinnant.github.io/date/tz.html">Time Zone 1146 Database Parser</a>, offer a wider selection of functions 1147 that provide capabilities beyond those provided here. 1148 The absence of such functions from this package is not meant to 1149 discourage the development, standardization, or use of such 1150 functions. 1151 Rather, their absence reflects the decision to make this package 1152 contain valid extensions to POSIX, to ensure its broad 1153 acceptability. 1154 If more powerful time conversion functions can be standardized, so 1155 much the better. 1156 </li> 1157</ul> 1158</section> 1159 1160<section> 1161 <h2 id="stability">Interface stability</h2> 1162<p> 1163The <code><abbr>tz</abbr></code> code and data supply the following interfaces: 1164</p> 1165 1166<ul> 1167 <li> 1168 A set of timezone names as per 1169 "<a href="#naming">Names of timezones</a>" above. 1170 </li> 1171 <li> 1172 Library functions described in "<a href="#functions">Time and date 1173 functions</a>" above. 1174 </li> 1175 <li> 1176 The programs <code>tzselect</code>, <code>zdump</code>, 1177 and <code>zic</code>, documented in their man pages. 1178 </li> 1179 <li> 1180 The format of <code>zic</code> input files, documented in 1181 the <code>zic</code> man page. 1182 </li> 1183 <li> 1184 The format of <code>zic</code> output files, documented in 1185 the <code>tzfile</code> man page. 1186 </li> 1187 <li> 1188 The format of zone table files, documented in <code>zone1970.tab</code>. 1189 </li> 1190 <li> 1191 The format of the country code file, documented in <code>iso3166.tab</code>. 1192 </li> 1193 <li> 1194 The version number of the code and data, as the first line of 1195 the text file '<code>version</code>' in each release. 1196 </li> 1197</ul> 1198 1199<p> 1200Interface changes in a release attempt to preserve compatibility with 1201recent releases. 1202For example, <code><abbr>tz</abbr></code> data files typically do not 1203rely on recently-added <code>zic</code> features, so that users can 1204run older <code>zic</code> versions to process newer data files. 1205<a href="tz-link.html#download">Downloading 1206the <code><abbr>tz</abbr></code> database</a> describes how releases 1207are tagged and distributed. 1208</p> 1209 1210<p> 1211Interfaces not listed above are less stable. 1212For example, users should not rely on particular <abbr>UT</abbr> 1213offsets or abbreviations for timestamps, as data entries are often 1214based on guesswork and these guesses may be corrected or improved. 1215</p> 1216</section> 1217 1218<section> 1219 <h2 id="calendar">Calendrical issues</h2> 1220<p> 1221Calendrical issues are a bit out of scope for a time zone database, 1222but they indicate the sort of problems that we would run into if we 1223extended the time zone database further into the past. 1224An excellent resource in this area is Edward M. Reingold 1225and Nachum Dershowitz, <cite><a 1226href="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical 1227Calculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018). 1228Other information and sources are given in the file '<code>calendars</code>' 1229in the <code><abbr>tz</abbr></code> distribution. 1230They sometimes disagree. 1231</p> 1232</section> 1233 1234<section> 1235 <h2 id="planets">Time and time zones on other planets</h2> 1236<p> 1237Some people's work schedules 1238use <a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>. 1239Jet Propulsion Laboratory (JPL) coordinators kept Mars time on 1240and off during the 1241<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder#End_of_mission">Mars 1242Pathfinder</a> mission. 1243Some of their family members also adapted to Mars time. 1244Dozens of special Mars watches were built for JPL workers who kept 1245Mars time during the Mars Exploration Rovers mission (2004). 1246These timepieces look like normal Seikos and Citizens but use Mars 1247seconds rather than terrestrial seconds. 1248</p> 1249 1250<p> 1251A Mars solar day is called a "sol" and has a mean period equal to 1252about 24 hours 39 minutes 35.244 seconds in terrestrial time. 1253It is divided into a conventional 24-hour clock, so each Mars second 1254equals about 1.02749125 terrestrial seconds. 1255</p> 1256 1257<p> 1258The <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime 1259meridian</a> of Mars goes through the center of the crater 1260<a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in 1261honor of the British astronomer who built the Greenwich telescope that 1262defines Earth's prime meridian. 1263Mean solar time on the Mars prime meridian is 1264called <a href="https://en.wikipedia.org/wiki/Mars_Coordinated_Time">Mars 1265Coordinated Time (<abbr>MTC</abbr>)</a>. 1266</p> 1267 1268<p> 1269Each landed mission on Mars has adopted a different reference for 1270solar timekeeping, so there is no real standard for Mars time zones. 1271For example, the 1272<a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars 1273Exploration Rover</a> project (2004) defined two time zones "Local 1274Solar Time A" and "Local Solar Time B" for its two missions, each zone 1275designed so that its time equals local true solar time at 1276approximately the middle of the nominal mission. 1277Such a "time zone" is not particularly suited for any application 1278other than the mission itself. 1279</p> 1280 1281<p> 1282Many calendars have been proposed for Mars, but none have achieved 1283wide acceptance. 1284Astronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a 1285sequential count of Mars solar days elapsed since about 1873-12-29 128612:00 <abbr>GMT</abbr>. 1287</p> 1288 1289<p> 1290In our solar system, Mars is the planet with time and calendar most 1291like Earth's. 1292On other planets, Sun-based time and calendars would work quite 1293differently. 1294For example, although Mercury's 1295<a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal 1296rotation period</a> is 58.646 Earth days, Mercury revolves around the 1297Sun so rapidly that an observer on Mercury's equator would see a 1298sunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a 1299Mercury day. 1300Venus is more complicated, partly because its rotation is slightly 1301<a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>: 1302its year is 1.92 of its days. 1303Gas giants like Jupiter are trickier still, as their polar and 1304equatorial regions rotate at different rates, so that the length of a 1305day depends on latitude. 1306This effect is most pronounced on Neptune, where the day is about 12 1307hours at the poles and 18 hours at the equator. 1308</p> 1309 1310<p> 1311Although the <code><abbr>tz</abbr></code> database does not support 1312time on other planets, it is documented here in the hopes that support 1313will be added eventually. 1314</p> 1315 1316<p> 1317Sources for time on other planets: 1318</p> 1319 1320<ul> 1321 <li> 1322 Michael Allison and Robert Schmunk, 1323 "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical 1324 Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" 1325 (2015-06-30). 1326 </li> 1327 <li> 1328 Jia-Rui Chong, 1329 "<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays 1330 Fit for a Martian</a>", <cite>Los Angeles Times</cite> 1331 (2004-01-14), pp A1, A20–A21. 1332 </li> 1333 <li> 1334 Tom Chmielewski, 1335 "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet 1336 Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26) 1337 </li> 1338 <li> 1339 Matt Williams, 1340 "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How 1341 long is a day on the other planets of the solar system?</a>" 1342 (2016-01-20). 1343 </li> 1344</ul> 1345</section> 1346 1347<footer> 1348 <hr> 1349 This file is in the public domain, so clarified as of 2009-05-17 by 1350 Arthur David Olson. 1351</footer> 1352</body> 1353</html> 1354