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