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