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