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