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