theory.html revision 1.2
1 1.1 christos <!DOCTYPE html> 2 1.1 christos <html lang="en"> 3 1.1 christos <head> 4 1.1 christos <title>Theory and pragmatics of the tz code and data</title> 5 1.1 christos <meta charset="UTF-8"> 6 1.1 christos </head> 7 1.1 christos 8 1.1 christos <!-- The somewhat-unusal indenting style in this file is intended to 9 1.1 christos shrink the output of the shell command 'diff Theory Theory.html', 10 1.1 christos where 'Theory' was the plain text file that this file is derived 11 1.1 christos from. The 'Theory' file used leading white space to indent, and 12 1.1 christos when possible that indentation is preserved here. Eventually we 13 1.1 christos may stop doing this and remove this comment. --> 14 1.1 christos 15 1.1 christos <body> 16 1.1 christos <h1>Theory and pragmatics of the tz code and data</h1> 17 1.1 christos <h3>Outline</h3> 18 1.1 christos <nav> 19 1.1 christos <ul> 20 1.1 christos <li><a href="#scope">Scope of the tz database</a></li> 21 1.1 christos <li><a href="#naming">Names of time zone rules</a></li> 22 1.1 christos <li><a href="#abbreviations">Time zone abbreviations</a></li> 23 1.1 christos <li><a href="#accuracy">Accuracy of the tz database</a></li> 24 1.1 christos <li><a href="#functions">Time and date functions</a></li> 25 1.1 christos <li><a href="#stability">Interface stability</a></li> 26 1.1 christos <li><a href="#calendar">Calendrical issues</a></li> 27 1.1 christos <li><a href="#planets">Time and time zones on other planets</a></li> 28 1.1 christos </ul> 29 1.1 christos </nav> 30 1.1 christos 31 1.1 christos 32 1.1 christos <section> 33 1.1 christos <h2 id="scope">Scope of the tz database</h2> 34 1.1 christos <p> 35 1.1 christos The tz database attempts to record the history and predicted future of 36 1.1 christos all computer-based clocks that track civil time. To represent this 37 1.1 christos data, the world is partitioned into regions whose clocks all agree 38 1.1 christos about timestamps that occur after the somewhat-arbitrary cutoff point 39 1.1 christos of the POSIX Epoch (1970-01-01 00:00:00 UTC). For each such region, 40 1.1 christos the database records all known clock transitions, and labels the region 41 1.1 christos with a notable location. Although 1970 is a somewhat-arbitrary 42 1.1 christos cutoff, there are significant challenges to moving the cutoff earlier 43 1.1 christos even by a decade or two, due to the wide variety of local practices 44 1.1 christos before computer timekeeping became prevalent. 45 1.1 christos </p> 46 1.1 christos 47 1.1 christos <p> 48 1.1 christos Clock transitions before 1970 are recorded for each such location, 49 1.1 christos because most systems support timestamps before 1970 and could 50 1.1 christos misbehave if data entries were omitted for pre-1970 transitions. 51 1.1 christos However, the database is not designed for and does not suffice for 52 1.1 christos applications requiring accurate handling of all past times everywhere, 53 1.1 christos as it would take far too much effort and guesswork to record all 54 1.1 christos details of pre-1970 civil timekeeping. 55 1.2 christos Athough some information outside the scope of the database is 56 1.2 christos collected in a file <code>backzone</code> that is distributed along 57 1.2 christos with the database proper, this file is less reliable and does not 58 1.2 christos necessarily follow database guidelines. 59 1.1 christos </p> 60 1.1 christos 61 1.1 christos <p> 62 1.1 christos As described below, reference source code for using the tz database is 63 1.1 christos also available. The tz code is upwards compatible with POSIX, an 64 1.1 christos international standard for UNIX-like systems. As of this writing, the 65 1.1 christos current edition of POSIX is: 66 1.1 christos <a href="http://pubs.opengroup.org/onlinepubs/9699919799/"> 67 1.1 christos The Open Group Base Specifications Issue 7</a>, 68 1.1 christos IEEE Std 1003.1-2008, 2016 Edition. 69 1.1 christos </p> 70 1.1 christos </section> 71 1.1 christos 72 1.1 christos 73 1.1 christos 74 1.1 christos <section> 75 1.1 christos <h2 id="naming">Names of time zone rules</h2> 76 1.1 christos <p> 77 1.1 christos Each of the database's time zone rules has a unique name. 78 1.1 christos Inexperienced users are not expected to select these names unaided. 79 1.1 christos Distributors should provide documentation and/or a simple selection 80 1.1 christos interface that explains the names; for one example, see the 'tzselect' 81 1.1 christos program in the tz code. The 82 1.1 christos <a href="http://cldr.unicode.org/">Unicode Common Locale Data 83 1.1 christos Repository</a> contains data that may be useful for other 84 1.1 christos selection interfaces. 85 1.1 christos </p> 86 1.1 christos 87 1.1 christos <p> 88 1.1 christos The time zone rule naming conventions attempt to strike a balance 89 1.1 christos among the following goals: 90 1.1 christos </p> 91 1.1 christos <ul> 92 1.1 christos <li> 93 1.1 christos Uniquely identify every region where clocks have agreed since 1970. 94 1.1 christos This is essential for the intended use: static clocks keeping local 95 1.1 christos civil time. 96 1.1 christos </li> 97 1.1 christos <li> 98 1.1 christos Indicate to experts where that region is. 99 1.1 christos </li> 100 1.1 christos <li> 101 1.1 christos Be robust in the presence of political changes. For example, names 102 1.1 christos of countries are ordinarily not used, to avoid incompatibilities 103 1.1 christos when countries change their name (e.g. Zaire→Congo) or when 104 1.1 christos locations change countries (e.g. Hong Kong from UK colony to 105 1.1 christos China). 106 1.1 christos </li> 107 1.1 christos <li> 108 1.1 christos Be portable to a wide variety of implementations. 109 1.1 christos </li> 110 1.1 christos <li> 111 1.1 christos Use a consistent naming conventions over the entire world. 112 1.1 christos </li> 113 1.1 christos </ul> 114 1.1 christos <p> 115 1.1 christos Names normally have the 116 1.1 christos form <var>AREA</var><code>/</code><var>LOCATION</var>, 117 1.1 christos where <var>AREA</var> is the name of a continent or ocean, 118 1.1 christos and <var>LOCATION</var> is the name of a specific 119 1.1 christos location within that region. North and South America share the same 120 1.1 christos area, '<code>America</code>'. Typical names are 121 1.1 christos '<code>Africa/Cairo</code>', '<code>America/New_York</code>', and 122 1.1 christos '<code>Pacific/Honolulu</code>'. 123 1.1 christos </p> 124 1.1 christos 125 1.1 christos <p> 126 1.1 christos Here are the general rules used for choosing location names, 127 1.1 christos in decreasing order of importance: 128 1.1 christos </p> 129 1.1 christos <ul> 130 1.1 christos <li> 131 1.1 christos Use only valid POSIX file name components (i.e., the parts of 132 1.1 christos names other than '<code>/</code>'). Do not use the file name 133 1.1 christos components '<code>.</code>' and '<code>..</code>'. 134 1.1 christos Within a file name component, 135 1.1 christos use only ASCII letters, '<code>.</code>', 136 1.1 christos '<code>-</code>' and '<code>_</code>'. Do not use 137 1.1 christos digits, as that might create an ambiguity with POSIX 138 1.1 christos TZ strings. A file name component must not exceed 14 139 1.1 christos characters or start with '<code>-</code>'. E.g., 140 1.1 christos prefer '<code>Brunei</code>' to 141 1.1 christos '<code>Bandar_Seri_Begawan</code>'. Exceptions: see 142 1.1 christos the discussion 143 1.1 christos of legacy names below. 144 1.1 christos </li> 145 1.1 christos <li> 146 1.1 christos A name must not be empty, or contain '<code>//</code>', or 147 1.1 christos start or end with '<code>/</code>'. 148 1.1 christos </li> 149 1.1 christos <li> 150 1.1 christos Do not use names that differ only in case. Although the reference 151 1.1 christos implementation is case-sensitive, some other implementations 152 1.1 christos are not, and they would mishandle names differing only in case. 153 1.1 christos </li> 154 1.1 christos <li> 155 1.1 christos If one name <var>A</var> is an initial prefix of another 156 1.1 christos name <var>AB</var> (ignoring case), then <var>B</var> 157 1.1 christos must not start with '<code>/</code>', as a 158 1.1 christos regular file cannot have 159 1.1 christos the same name as a directory in POSIX. For example, 160 1.1 christos '<code>America/New_York</code>' precludes 161 1.1 christos '<code>America/New_York/Bronx</code>'. 162 1.1 christos </li> 163 1.1 christos <li> 164 1.1 christos Uninhabited regions like the North Pole and Bouvet Island 165 1.1 christos do not need locations, since local time is not defined there. 166 1.1 christos </li> 167 1.1 christos <li> 168 1.1 christos There should typically be at least one name for each ISO 3166-1 169 1.1 christos officially assigned two-letter code for an inhabited country 170 1.1 christos or territory. 171 1.1 christos </li> 172 1.1 christos <li> 173 1.1 christos If all the clocks in a region have agreed since 1970, 174 1.1 christos don't bother to include more than one location 175 1.1 christos even if subregions' clocks disagreed before 1970. 176 1.1 christos Otherwise these tables would become annoyingly large. 177 1.1 christos </li> 178 1.1 christos <li> 179 1.1 christos If a name is ambiguous, use a less ambiguous alternative; 180 1.1 christos e.g. many cities are named San Jos and Georgetown, so 181 1.1 christos prefer '<code>Costa_Rica</code>' to '<code>San_Jose</code>' and '<code>Guyana</code>' to '<code>Georgetown</code>'. 182 1.1 christos </li> 183 1.1 christos <li> 184 1.1 christos Keep locations compact. Use cities or small islands, not countries 185 1.1 christos or regions, so that any future time zone changes do not split 186 1.1 christos locations into different time zones. E.g. prefer 187 1.1 christos '<code>Paris</code>' to '<code>France</code>', since 188 1.1 christos France has had multiple time zones. 189 1.1 christos </li> 190 1.1 christos <li> 191 1.1 christos Use mainstream English spelling, e.g. prefer 192 1.1 christos '<code>Rome</code>' to '<code>Roma</code>', and prefer 193 1.1 christos '<code>Athens</code>' to the Greek 194 1.1 christos '<code></code>' or the Romanized 195 1.1 christos '<code>Athna</code>'. 196 1.1 christos The POSIX file name restrictions encourage this rule. 197 1.1 christos </li> 198 1.1 christos <li> 199 1.1 christos Use the most populous among locations in a zone, 200 1.1 christos e.g. prefer '<code>Shanghai</code>' to 201 1.1 christos '<code>Beijing</code>'. Among locations with 202 1.1 christos similar populations, pick the best-known location, 203 1.1 christos e.g. prefer '<code>Rome</code>' to '<code>Milan</code>'. 204 1.1 christos </li> 205 1.1 christos <li> 206 1.1 christos Use the singular form, e.g. prefer '<code>Canary</code>' to '<code>Canaries</code>'. 207 1.1 christos </li> 208 1.1 christos <li> 209 1.1 christos Omit common suffixes like '<code>_Islands</code>' and 210 1.1 christos '<code>_City</code>', unless that would lead to 211 1.1 christos ambiguity. E.g. prefer '<code>Cayman</code>' to 212 1.1 christos '<code>Cayman_Islands</code>' and 213 1.1 christos '<code>Guatemala</code>' to 214 1.1 christos '<code>Guatemala_City</code>', but prefer 215 1.1 christos '<code>Mexico_City</code>' to '<code>Mexico</code>' 216 1.1 christos because the country 217 1.1 christos of Mexico has several time zones. 218 1.1 christos </li> 219 1.1 christos <li> 220 1.1 christos Use '<code>_</code>' to represent a space. 221 1.1 christos </li> 222 1.1 christos <li> 223 1.1 christos Omit '<code>.</code>' from abbreviations in names, e.g. prefer 224 1.1 christos '<code>St_Helena</code>' to '<code>St._Helena</code>'. 225 1.1 christos </li> 226 1.1 christos <li> 227 1.1 christos Do not change established names if they only marginally 228 1.1 christos violate the above rules. For example, don't change 229 1.1 christos the existing name '<code>Rome</code>' to 230 1.1 christos '<code>Milan</code>' merely because 231 1.1 christos Milan's population has grown to be somewhat greater 232 1.1 christos than Rome's. 233 1.1 christos </li> 234 1.1 christos <li> 235 1.1 christos If a name is changed, put its old spelling in the 236 1.1 christos '<code>backward</code>' file. 237 1.1 christos This means old spellings will continue to work. 238 1.1 christos </li> 239 1.1 christos </ul> 240 1.1 christos 241 1.1 christos <p> 242 1.1 christos The file '<code>zone1970.tab</code>' lists geographical locations used 243 1.1 christos to name time 244 1.1 christos zone rules. It is intended to be an exhaustive list of names for 245 1.1 christos geographic regions as described above; this is a subset of the names 246 1.1 christos in the data. Although a '<code>zone1970.tab</code>' location's longitude 247 1.2 christos corresponds to its LMT offset with one hour for every 15° east 248 1.1 christos longitude, this relationship is not exact. 249 1.1 christos </p> 250 1.1 christos 251 1.1 christos <p> 252 1.1 christos Older versions of this package used a different naming scheme, 253 1.1 christos and these older names are still supported. 254 1.1 christos See the file '<code>backward</code>' for most of these older names 255 1.1 christos (e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>'). 256 1.1 christos The other old-fashioned names still supported are 257 1.1 christos '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and '<code>EET</code>' (see the file '<code>europe</code>'). 258 1.1 christos </p> 259 1.1 christos 260 1.1 christos <p> 261 1.1 christos Older versions of this package defined legacy names that are 262 1.1 christos incompatible with the first rule of location names, but which are 263 1.1 christos still supported. These legacy names are mostly defined in the file 264 1.1 christos '<code>etcetera</code>'. Also, the file '<code>backward</code>' defines the legacy names 265 1.1 christos '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', and the file '<code>northamerica</code>' defines the 266 1.1 christos legacy names '<code>EST5EDT</code>', '<code>CST6CDT</code>', '<code>MST7MDT</code>', and '<code>PST8PDT</code>'. 267 1.1 christos </p> 268 1.1 christos 269 1.1 christos <p> 270 1.1 christos Excluding '<code>backward</code>' should not affect the other data. If 271 1.1 christos '<code>backward</code>' is excluded, excluding '<code>etcetera</code>' should not affect the 272 1.1 christos remaining data. 273 1.1 christos </p> 274 1.1 christos 275 1.1 christos 276 1.1 christos </section> 277 1.1 christos <section> 278 1.1 christos <h2 id="abbreviations">Time zone abbreviations</h2> 279 1.1 christos <p> 280 1.1 christos When this package is installed, it generates time zone abbreviations 281 1.1 christos like '<code>EST</code>' to be compatible with human tradition and POSIX. 282 1.1 christos Here are the general rules used for choosing time zone abbreviations, 283 1.1 christos in decreasing order of importance: 284 1.1 christos <ul> 285 1.1 christos <li> 286 1.2 christos Use three to six characters that are ASCII alphanumerics or 287 1.1 christos '<code>+</code>' or '<code>-</code>'. 288 1.1 christos Previous editions of this database also used characters like 289 1.1 christos '<code> </code>' and '<code>?</code>', but these 290 1.1 christos characters have a special meaning to 291 1.1 christos the shell and cause commands like 292 1.1 christos '<code>set `date`</code>' 293 1.1 christos to have unexpected effects. 294 1.1 christos Previous editions of this rule required upper-case letters, 295 1.1 christos but the Congressman who introduced Chamorro Standard Time 296 1.1 christos preferred "ChST", so lower-case letters are now allowed. 297 1.1 christos Also, POSIX from 2001 on relaxed the rule to allow 298 1.1 christos '<code>-</code>', '<code>+</code>', 299 1.1 christos and alphanumeric characters from the portable character set 300 1.1 christos in the current locale. In practice ASCII alphanumerics and 301 1.1 christos '<code>+</code>' and '<code>-</code>' are safe in all locales. 302 1.1 christos 303 1.1 christos In other words, in the C locale the POSIX extended regular 304 1.2 christos expression <code>[-+[:alnum:]]{3,6}</code> should match 305 1.1 christos the abbreviation. 306 1.1 christos This guarantees that all abbreviations could have been 307 1.1 christos specified by a POSIX TZ string. 308 1.1 christos </li> 309 1.1 christos <li> 310 1.1 christos Use abbreviations that are in common use among English-speakers, 311 1.1 christos e.g. 'EST' for Eastern Standard Time in North America. 312 1.1 christos We assume that applications translate them to other languages 313 1.1 christos as part of the normal localization process; for example, 314 1.1 christos a French application might translate 'EST' to 'HNE'. 315 1.2 christos 316 1.2 christos <p><small>These abbreviations (for standard/daylight/etc. time) are: 317 1.2 christos ACST/ACDT Australian Central, 318 1.2 christos AST/ADT/APT/AWT/ADDT Atlantic, 319 1.2 christos AEST/AEDT Australian Eastern, 320 1.2 christos AHST/AHDT Alaska-Hawaii, 321 1.2 christos AKST/AKDT Alaska, 322 1.2 christos AWST/AWDT Australian Western, 323 1.2 christos BST/BDT Bering, 324 1.2 christos CAT/CAST Central Africa, 325 1.2 christos CET/CEST/CEMT Central European, 326 1.2 christos ChST Chamorro, 327 1.2 christos CST/CDT/CWT/CPT/CDDT Central [North America], 328 1.2 christos CST/CDT China, 329 1.2 christos GMT/BST/IST/BDST Greenwich, 330 1.2 christos EAT East Africa, 331 1.2 christos EST/EDT/EWT/EPT/EDDT Eastern [North America], 332 1.2 christos EET/EEST Eastern European, 333 1.2 christos GST Guam, 334 1.2 christos HST/HDT Hawaii, 335 1.2 christos HKT/HKST Hong Kong, 336 1.2 christos IST India, 337 1.2 christos IST/GMT Irish, 338 1.2 christos IST/IDT/IDDT Israel, 339 1.2 christos JST/JDT Japan, 340 1.2 christos KST/KDT Korea, 341 1.2 christos MET/MEST Middle European (a backward-compatibility alias for Central European), 342 1.2 christos MSK/MSD Moscow, 343 1.2 christos MST/MDT/MWT/MPT/MDDT Mountain, 344 1.2 christos NST/NDT/NWT/NPT/NDDT Newfoundland, 345 1.2 christos NST/NDT/NWT/NPT Nome, 346 1.2 christos NZMT/NZST New Zealand through 1945, 347 1.2 christos NZST/NZDT New Zealand 1946–present, 348 1.2 christos PKT/PKST Pakistan, 349 1.2 christos PST/PDT/PWT/PPT/PDDT Pacific, 350 1.2 christos SAST South Africa, 351 1.2 christos SST Samoa, 352 1.2 christos WAT/WAST West Africa, 353 1.2 christos WET/WEST/WEMT Western European, 354 1.2 christos WIB Waktu Indonesia Barat, 355 1.2 christos WIT Waktu Indonesia Timur, 356 1.2 christos WITA Waktu Indonesia Tengah, 357 1.2 christos YST/YDT/YWT/YPT/YDDT Yukon</small>.</p> 358 1.1 christos </li> 359 1.1 christos <li> 360 1.1 christos For zones whose times are taken from a city's longitude, use the 361 1.2 christos traditional <var>x</var>MT notation. The only abbreviation like this 362 1.2 christos in current use is 'GMT'. The others are for timestamps before 1960, 363 1.2 christos except that Monrovia Mean Time persisted until 1972. Typically, 364 1.2 christos numeric abbreviations (e.g., '<code>-</code>004430' for MMT) would 365 1.2 christos cause trouble here, as the numeric strings would exceed the POSIX length limit. 366 1.2 christos 367 1.2 christos <p><small>These abbreviations are: 368 1.2 christos AMT Amsterdam, Asuncin, Athens; 369 1.2 christos BMT Baghdad, Bangkok, Batavia, Bern, Bogot, Bridgetown, Brussels, Bucharest; 370 1.2 christos CMT Calamarca, Caracas, Chisinau, Coln, Copenhagen, Crdoba; 371 1.2 christos DMT Dublin/Dunsink; 372 1.2 christos EMT Easter; 373 1.2 christos FFMT Fort-de-France; 374 1.2 christos FMT Funchal; 375 1.2 christos GMT Greenwich; 376 1.2 christos HMT Havana, Helsinki, Horta, Howrah; 377 1.2 christos IMT Irkutsk, Istanbul; 378 1.2 christos JMT Jerusalem; 379 1.2 christos KMT Kaunas, Kiev, Kingston; 380 1.2 christos LMT Lima, Lisbon, local, Luanda; 381 1.2 christos MMT Macassar, Madras, Mal, Managua, Minsk, Monrovia, Montevideo, Moratuwa, 382 1.2 christos Moscow; 383 1.2 christos PLMT Ph Lin; 384 1.2 christos PMT Paramaribo, Paris, Perm, Pontianak, Prague; 385 1.2 christos PMMT Port Moresby; 386 1.2 christos QMT Quito; 387 1.2 christos RMT Rangoon, Riga, Rome; 388 1.2 christos SDMT Santo Domingo; 389 1.2 christos SJMT San Jos; 390 1.2 christos SMT Santiago, Simferopol, Singapore, Stanley; 391 1.2 christos TBMT Tbilisi; 392 1.2 christos TMT Tallinn, Tehran; 393 1.2 christos WMT Warsaw</small>.</p> 394 1.2 christos 395 1.2 christos <p><small>A few abbreviations also follow the pattern that 396 1.2 christos GMT/BST established for time in the UK. They are: 397 1.2 christos 398 1.2 christos CMT/BST for Calamarca Mean Time and Bolivian Summer Time 399 1.2 christos 1890–1932, DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time 400 1.2 christos 1880–1916, MMT/MST/MDST for Moscow 1880–1919, and RMT/LST 401 1.2 christos for Riga Mean Time and Latvian Summer time 1880–1926. 402 1.2 christos An extra-special case is SET for Swedish Time (<em>svensk 403 1.2 christos normaltid</em>) 1879–1899, 3° west of the Stockholm 404 1.2 christos Observatory.</small></p> 405 1.1 christos </li> 406 1.1 christos <li> 407 1.1 christos Use 'LMT' for local mean time of locations before the introduction 408 1.1 christos of standard time; see "<a href="#scope">Scope of the 409 1.1 christos tz database</a>". 410 1.1 christos </li> 411 1.1 christos <li> 412 1.1 christos If there is no common English abbreviation, use numeric offsets like 413 1.1 christos <code>-</code>05 and <code>+</code>0830 that are 414 1.1 christos generated by zic's <code>%z</code> notation. 415 1.1 christos </li> 416 1.1 christos <li> 417 1.1 christos Use current abbreviations for older timestamps to avoid confusion. 418 1.1 christos For example, in 1910 a common English abbreviation for UT +01 419 1.1 christos in central Europe was 'MEZ' (short for both "Middle European 420 1.1 christos Zone" and for "Mitteleuropische Zeit" in German). Nowadays 421 1.1 christos 'CET' ("Central European Time") is more common in English, and 422 1.1 christos the database uses 'CET' even for circa-1910 timestamps as this 423 1.1 christos is less confusing for modern users and avoids the need for 424 1.1 christos determining when 'CET' supplanted 'MEZ' in common usage. 425 1.1 christos </li> 426 1.1 christos <li> 427 1.1 christos Use a consistent style in a zone's history. For example, if a zone's 428 1.1 christos history tends to use numeric abbreviations and a particular 429 1.1 christos entry could go either way, use a numeric abbreviation. 430 1.1 christos </li> 431 1.1 christos <li> 432 1.1 christos Use UT (with time zone abbreviation '<code>-</code>00') for 433 1.1 christos locations while uninhabited. The leading 434 1.1 christos '<code>-</code>' is a flag that the time 435 1.1 christos zone is in some sense undefined; this notation is 436 1.1 christos derived from Internet RFC 3339. 437 1.1 christos </li> 438 1.1 christos </ul> 439 1.1 christos <p> 440 1.1 christos Application writers should note that these abbreviations are ambiguous 441 1.2 christos in practice: e.g., 'CST' means one thing in China and something else 442 1.2 christos in North America, and 'IST' can refer to time in India, Ireland or 443 1.2 christos Israel. To avoid ambiguity, use numeric UT offsets like 444 1.2 christos '<code>-</code>0600' instead of time zone abbreviations like 'CST'. 445 1.1 christos </p> 446 1.1 christos </section> 447 1.1 christos 448 1.1 christos 449 1.1 christos <section> 450 1.1 christos <h2 id="accuracy">Accuracy of the tz database</h2> 451 1.1 christos <p> 452 1.1 christos The tz database is not authoritative, and it surely has errors. 453 1.2 christos Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. 454 1.1 christos Users requiring authoritative data should consult national standards 455 1.1 christos bodies and the references cited in the database's comments. 456 1.1 christos </p> 457 1.1 christos 458 1.1 christos <p> 459 1.1 christos Errors in the tz database arise from many sources: 460 1.1 christos </p> 461 1.1 christos <ul> 462 1.1 christos <li> 463 1.1 christos The tz database predicts future timestamps, and current predictions 464 1.1 christos will be incorrect after future governments change the rules. 465 1.1 christos For example, if today someone schedules a meeting for 13:00 next 466 1.1 christos October 1, Casablanca time, and tomorrow Morocco changes its 467 1.1 christos daylight saving rules, software can mess up after the rule change 468 1.1 christos if it blithely relies on conversions made before the change. 469 1.1 christos </li> 470 1.1 christos <li> 471 1.1 christos The pre-1970 entries in this database cover only a tiny sliver of how 472 1.1 christos clocks actually behaved; the vast majority of the necessary 473 1.1 christos information was lost or never recorded. Thousands more zones would 474 1.1 christos be needed if the tz database's scope were extended to cover even 475 1.1 christos just the known or guessed history of standard time; for example, 476 1.1 christos the current single entry for France would need to split into dozens 477 1.1 christos of entries, perhaps hundreds. And in most of the world even this 478 1.1 christos approach would be misleading due to widespread disagreement or 479 1.1 christos indifference about what times should be observed. In her 2015 book 480 1.1 christos <cite>The Global Transformation of Time, 1870-1950</cite>, Vanessa Ogle writes 481 1.1 christos "Outside of Europe and North America there was no system of time 482 1.1 christos zones at all, often not even a stable landscape of mean times, 483 1.1 christos prior to the middle decades of the twentieth century". See: 484 1.1 christos Timothy Shenk, <a 485 1.1 christos href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked: 486 1.1 christos A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. 487 1.1 christos </li> 488 1.1 christos <li> 489 1.1 christos Most of the pre-1970 data entries come from unreliable sources, often 490 1.1 christos astrology books that lack citations and whose compilers evidently 491 1.1 christos invented entries when the true facts were unknown, without 492 1.1 christos reporting which entries were known and which were invented. 493 1.1 christos These books often contradict each other or give implausible entries, 494 1.1 christos and on the rare occasions when they are checked they are 495 1.1 christos typically found to be incorrect. 496 1.1 christos </li> 497 1.1 christos <li> 498 1.1 christos For the UK the tz database relies on years of first-class work done by 499 1.1 christos Joseph Myers and others; see 500 1.1 christos "<a href="https://www.polyomino.org.uk/british-time/">History of 501 1.1 christos legal time in Britain</a>". 502 1.1 christos Other countries are not done nearly as well. 503 1.1 christos </li> 504 1.1 christos <li> 505 1.1 christos Sometimes, different people in the same city would maintain clocks 506 1.1 christos that differed significantly. Railway time was used by railroad 507 1.1 christos companies (which did not always agree with each other), 508 1.1 christos church-clock time was used for birth certificates, etc. 509 1.1 christos Often this was merely common practice, but sometimes it was set by law. 510 1.1 christos For example, from 1891 to 1911 the UT offset in France was legally 511 1.1 christos 0:09:21 outside train stations and 0:04:21 inside. 512 1.1 christos </li> 513 1.1 christos <li> 514 1.1 christos Although a named location in the tz database stands for the 515 1.1 christos containing region, its pre-1970 data entries are often accurate for 516 1.1 christos only a small subset of that region. For example, <code>Europe/London</code> 517 1.1 christos stands for the United Kingdom, but its pre-1847 times are valid 518 1.1 christos only for locations that have London's exact meridian, and its 1847 519 1.1 christos transition to GMT is known to be valid only for the L&NW and the 520 1.1 christos Caledonian railways. 521 1.1 christos </li> 522 1.1 christos <li> 523 1.1 christos The tz database does not record the earliest time for which a zone's 524 1.1 christos data entries are thereafter valid for every location in the region. 525 1.1 christos For example, <code>Europe/London</code> is valid for all locations in its 526 1.1 christos region after GMT was made the standard time, but the date of 527 1.1 christos standardization (1880-08-02) is not in the tz database, other than 528 1.1 christos in commentary. For many zones the earliest time of validity is 529 1.1 christos unknown. 530 1.1 christos </li> 531 1.1 christos <li> 532 1.1 christos The tz database does not record a region's boundaries, and in many 533 1.1 christos cases the boundaries are not known. For example, the zone 534 1.1 christos <code>America/Kentucky/Louisville</code> represents a region around 535 1.1 christos the city of 536 1.1 christos Louisville, the boundaries of which are unclear. 537 1.1 christos </li> 538 1.1 christos <li> 539 1.1 christos Changes that are modeled as instantaneous transitions in the tz 540 1.1 christos database were often spread out over hours, days, or even decades. 541 1.1 christos </li> 542 1.1 christos <li> 543 1.1 christos Even if the time is specified by law, locations sometimes 544 1.1 christos deliberately flout the law. 545 1.1 christos </li> 546 1.1 christos <li> 547 1.1 christos Early timekeeping practices, even assuming perfect clocks, were 548 1.1 christos often not specified to the accuracy that the tz database requires. 549 1.1 christos </li> 550 1.1 christos <li> 551 1.1 christos Sometimes historical timekeeping was specified more precisely 552 1.1 christos than what the tz database can handle. For example, from 1909 to 553 1.1 christos 1937 Netherlands clocks were legally UT +00:19:32.13, but the tz 554 1.1 christos database cannot represent the fractional second. 555 1.1 christos </li> 556 1.1 christos <li> 557 1.1 christos Even when all the timestamp transitions recorded by the tz database 558 1.1 christos are correct, the tz rules that generate them may not faithfully 559 1.1 christos reflect the historical rules. For example, from 1922 until World 560 1.1 christos War II the UK moved clocks forward the day following the third 561 1.1 christos Saturday in April unless that was Easter, in which case it moved 562 1.1 christos clocks forward the previous Sunday. Because the tz database has no 563 1.1 christos way to specify Easter, these exceptional years are entered as 564 1.1 christos separate tz Rule lines, even though the legal rules did not change. 565 1.1 christos </li> 566 1.1 christos <li> 567 1.1 christos The tz database models pre-standard time using the proleptic Gregorian 568 1.1 christos calendar and local mean time (LMT), but many people used other 569 1.1 christos calendars and other timescales. For example, the Roman Empire used 570 1.1 christos the Julian calendar, and had 12 varying-length daytime hours with a 571 1.1 christos non-hour-based system at night. 572 1.1 christos </li> 573 1.1 christos <li> 574 1.1 christos Early clocks were less reliable, and data entries do not represent 575 1.1 christos clock error. 576 1.1 christos </li> 577 1.1 christos <li> 578 1.1 christos The tz database assumes Universal Time (UT) as an origin, even 579 1.1 christos though UT is not standardized for older timestamps. In the tz 580 1.1 christos database commentary, UT denotes a family of time standards that 581 1.1 christos includes Coordinated Universal Time (UTC) along with other variants 582 1.1 christos such as UT1 and GMT, with days starting at midnight. Although UT 583 1.1 christos equals UTC for modern timestamps, UTC was not defined until 1960, 584 1.1 christos so commentary uses the more-general abbreviation UT for timestamps 585 1.1 christos that might predate 1960. Since UT, UT1, etc. disagree slightly, 586 1.1 christos and since pre-1972 UTC seconds varied in length, interpretation of 587 1.1 christos older timestamps can be problematic when subsecond accuracy is 588 1.1 christos needed. 589 1.1 christos </li> 590 1.1 christos <li> 591 1.1 christos Civil time was not based on atomic time before 1972, and we don't 592 1.1 christos know the history of earth's rotation accurately enough to map SI 593 1.1 christos seconds to historical solar time to more than about one-hour 594 1.1 christos accuracy. See: Stephenson FR, Morrison LV, Hohenkerk CY. 595 1.1 christos <a href="http://dx.doi.org/10.1098/rspa.2016.0404">Measurement 596 1.1 christos of the Earth's rotation: 720 BC to AD 2015</a>. 597 1.1 christos <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404. 598 1.1 christos Also see: Espenak F. <a 599 1.1 christos href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty 600 1.1 christos in Delta T (T)</a>. 601 1.1 christos </li> 602 1.1 christos <li> 603 1.1 christos The relationship between POSIX time (that is, UTC but ignoring leap 604 1.1 christos seconds) and UTC is not agreed upon after 1972. Although the POSIX 605 1.1 christos clock officially stops during an inserted leap second, at least one 606 1.1 christos proposed standard has it jumping back a second instead; and in 607 1.1 christos practice POSIX clocks more typically either progress glacially during 608 1.1 christos a leap second, or are slightly slowed while near a leap second. 609 1.1 christos </li> 610 1.1 christos <li> 611 1.1 christos The tz database does not represent how uncertain its information is. 612 1.1 christos Ideally it would contain information about when data entries are 613 1.1 christos incomplete or dicey. Partial temporal knowledge is a field of 614 1.1 christos active research, though, and it's not clear how to apply it here. 615 1.1 christos </li> 616 1.1 christos </ul> 617 1.1 christos <p> 618 1.1 christos In short, many, perhaps most, of the tz database's pre-1970 and future 619 1.1 christos timestamps are either wrong or misleading. Any attempt to pass the 620 1.1 christos tz database off as the definition of time should be unacceptable to 621 1.1 christos anybody who cares about the facts. In particular, the tz database's 622 1.1 christos LMT offsets should not be considered meaningful, and should not prompt 623 1.1 christos creation of zones merely because two locations differ in LMT or 624 1.1 christos transitioned to standard time at different dates. 625 1.1 christos </p> 626 1.1 christos </section> 627 1.1 christos 628 1.1 christos 629 1.1 christos <section> 630 1.1 christos <h2 id="functions">Time and date functions</h2> 631 1.1 christos <p> 632 1.1 christos The tz code contains time and date functions that are upwards 633 1.1 christos compatible with those of POSIX. 634 1.1 christos </p> 635 1.1 christos 636 1.1 christos <p> 637 1.1 christos POSIX has the following properties and limitations. 638 1.1 christos </p> 639 1.1 christos <ul> 640 1.1 christos <li> 641 1.1 christos <p> 642 1.1 christos In POSIX, time display in a process is controlled by the 643 1.1 christos environment variable TZ. Unfortunately, the POSIX TZ string takes 644 1.1 christos a form that is hard to describe and is error-prone in practice. 645 1.1 christos Also, POSIX TZ strings can't deal with other (for example, Israeli) 646 1.1 christos daylight saving time rules, or situations where more than two 647 1.1 christos time zone abbreviations are used in an area. 648 1.1 christos </p> 649 1.1 christos <p> 650 1.1 christos The POSIX TZ string takes the following form: 651 1.1 christos </p> 652 1.1 christos <p> 653 1.1 christos <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>]]] 654 1.1 christos </p> 655 1.1 christos <p> 656 1.1 christos where: 657 1.1 christos <dl> 658 1.1 christos <dt><var>std</var> and <var>dst</var></dt><dd> 659 1.1 christos are 3 or more characters specifying the standard 660 1.1 christos and daylight saving time (DST) zone names. 661 1.1 christos Starting with POSIX.1-2001, <var>std</var> 662 1.1 christos and <var>dst</var> may also be 663 1.2 christos in a quoted form like '<code><+09></code>'; this allows 664 1.1 christos "<code>+</code>" and "<code>-</code>" in the names. 665 1.1 christos </dd> 666 1.1 christos <dt><var>offset</var></dt><dd> 667 1.1 christos is of the form 668 1.1 christos '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' 669 1.1 christos and specifies the offset west of UT. '<var>hh</var>' 670 1.1 christos may be a single digit; 0≤<var>hh</var>≤24. 671 1.1 christos The default DST offset is one hour ahead of standard time. 672 1.1 christos </dd> 673 1.1 christos <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> 674 1.1 christos specifies the beginning and end of DST. If this is absent, 675 1.1 christos the system supplies its own rules for DST, and these can 676 1.1 christos differ from year to year; typically US DST rules are used. 677 1.1 christos </dd> 678 1.1 christos <dt><var>time</var></dt><dd> 679 1.1 christos takes the form 680 1.1 christos '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]' 681 1.1 christos and defaults to 02:00. 682 1.1 christos This is the same format as the offset, except that a 683 1.1 christos leading '<code>+</code>' or '<code>-</code>' is not allowed. 684 1.1 christos </dd> 685 1.1 christos <dt><var>date</var></dt><dd> 686 1.1 christos takes one of the following forms: 687 1.1 christos <dl> 688 1.1 christos <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> 689 1.1 christos origin-1 day number not counting February 29 690 1.1 christos </dd> 691 1.1 christos <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> 692 1.1 christos origin-0 day number counting February 29 if present 693 1.1 christos </dd> 694 1.1 christos <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, 1≤<var>m</var>≤12)</dt><dd> 695 1.1 christos for the <var>d</var>th day of 696 1.1 christos week <var>n</var> of month <var>m</var> of the 697 1.1 christos year, where week 1 is the first week in which 698 1.1 christos day <var>d</var> appears, and '<code>5</code>' 699 1.1 christos stands for the last week in which 700 1.1 christos day <var>d</var> appears 701 1.1 christos (which may be either the 4th or 5th week). 702 1.1 christos Typically, this is the only useful form; 703 1.1 christos the <var>n</var> 704 1.1 christos and <code>J</code><var>n</var> forms are 705 1.1 christos rarely used. 706 1.1 christos </dd> 707 1.1 christos </dl> 708 1.1 christos </dd> 709 1.1 christos </dl> 710 1.1 christos Here is an example POSIX TZ string for New Zealand after 2007. 711 1.2 christos It says that standard time (NZST) is 12 hours ahead of UT, 712 1.1 christos and that daylight saving time (NZDT) is observed from September's 713 1.1 christos last Sunday at 02:00 until April's first Sunday at 03:00: 714 1.1 christos 715 1.1 christos <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> 716 1.1 christos 717 1.1 christos This POSIX TZ string is hard to remember, and mishandles some 718 1.1 christos timestamps before 2008. With this package you can use this 719 1.1 christos instead: 720 1.1 christos 721 1.1 christos <pre><code>TZ='Pacific/Auckland'</code></pre> 722 1.1 christos </li> 723 1.1 christos <li> 724 1.1 christos POSIX does not define the exact meaning of TZ values like 725 1.1 christos "<code>EST5EDT</code>". 726 1.1 christos Typically the current US DST rules are used to interpret such values, 727 1.1 christos but this means that the US DST rules are compiled into each program 728 1.1 christos that does time conversion. This means that when US time conversion 729 1.1 christos rules change (as in the United States in 1987), all programs that 730 1.1 christos do time conversion must be recompiled to ensure proper results. 731 1.1 christos </li> 732 1.1 christos <li> 733 1.1 christos The TZ environment variable is process-global, which makes it hard 734 1.1 christos to write efficient, thread-safe applications that need access 735 1.1 christos to multiple time zones. 736 1.1 christos </li> 737 1.1 christos <li> 738 1.1 christos In POSIX, there's no tamper-proof way for a process to learn the 739 1.1 christos system's best idea of local wall clock. (This is important for 740 1.1 christos applications that an administrator wants used only at certain 741 1.1 christos times – 742 1.1 christos without regard to whether the user has fiddled the TZ environment 743 1.2 christos variable. While an administrator can "do everything in UT" to get 744 1.1 christos around the problem, doing so is inconvenient and precludes handling 745 1.1 christos daylight saving time shifts - as might be required to limit phone 746 1.1 christos calls to off-peak hours.) 747 1.1 christos </li> 748 1.1 christos <li> 749 1.1 christos POSIX provides no convenient and efficient way to determine the UT 750 1.1 christos offset and time zone abbreviation of arbitrary timestamps, 751 1.1 christos particularly for time zone settings that do not fit into the 752 1.1 christos POSIX model. 753 1.1 christos </li> 754 1.1 christos <li> 755 1.1 christos POSIX requires that systems ignore leap seconds. 756 1.1 christos </li> 757 1.1 christos <li> 758 1.1 christos The tz code attempts to support all the <code>time_t</code> 759 1.1 christos implementations allowed by POSIX. The <code>time_t</code> 760 1.1 christos type represents a nonnegative count of 761 1.1 christos seconds since 1970-01-01 00:00:00 UTC, ignoring leap seconds. 762 1.1 christos In practice, <code>time_t</code> is usually a signed 64- or 763 1.1 christos 32-bit integer; 32-bit signed <code>time_t</code> values stop 764 1.1 christos working after 2038-01-19 03:14:07 UTC, so 765 1.1 christos new implementations these days typically use a signed 64-bit integer. 766 1.1 christos Unsigned 32-bit integers are used on one or two platforms, 767 1.1 christos and 36-bit and 40-bit integers are also used occasionally. 768 1.1 christos Although earlier POSIX versions allowed <code>time_t</code> to be a 769 1.1 christos floating-point type, this was not supported by any practical 770 1.1 christos systems, and POSIX.1-2013 and the tz code both 771 1.1 christos require <code>time_t</code> 772 1.1 christos to be an integer type. 773 1.1 christos </li> 774 1.1 christos </ul> 775 1.1 christos <p> 776 1.1 christos These are the extensions that have been made to the POSIX functions: 777 1.1 christos </p> 778 1.1 christos <ul> 779 1.1 christos <li> 780 1.1 christos <p> 781 1.1 christos The TZ environment variable is used in generating the name of a file 782 1.1 christos from which time zone information is read (or is interpreted a la 783 1.1 christos POSIX); TZ is no longer constrained to be a three-letter time zone 784 1.1 christos name followed by a number of hours and an optional three-letter 785 1.1 christos daylight time zone name. The daylight saving time rules to be used 786 1.1 christos for a particular time zone are encoded in the time zone file; 787 1.1 christos the format of the file allows U.S., Australian, and other rules to be 788 1.1 christos encoded, and allows for situations where more than two time zone 789 1.1 christos abbreviations are used. 790 1.1 christos </p> 791 1.1 christos <p> 792 1.1 christos It was recognized that allowing the TZ environment variable to 793 1.1 christos take on values such as '<code>America/New_York</code>' might 794 1.1 christos cause "old" programs 795 1.1 christos (that expect TZ to have a certain form) to operate incorrectly; 796 1.1 christos consideration was given to using some other environment variable 797 1.1 christos (for example, TIMEZONE) to hold the string used to generate the 798 1.1 christos time zone information file name. In the end, however, it was decided 799 1.1 christos to continue using TZ: it is widely used for time zone purposes; 800 1.1 christos separately maintaining both TZ and TIMEZONE seemed a nuisance; 801 1.1 christos and systems where "new" forms of TZ might cause problems can simply 802 1.1 christos use TZ values such as "<code>EST5EDT</code>" which can be used both by 803 1.1 christos "new" programs (a la POSIX) and "old" programs (as zone names and 804 1.1 christos offsets). 805 1.1 christos </p> 806 1.1 christos </li> 807 1.1 christos <li> 808 1.1 christos The code supports platforms with a UT offset member 809 1.1 christos in <code>struct tm</code>, 810 1.1 christos e.g., <code>tm_gmtoff</code>. 811 1.1 christos </li> 812 1.1 christos <li> 813 1.1 christos The code supports platforms with a time zone abbreviation member in 814 1.1 christos <code>struct tm</code>, e.g., <code>tm_zone</code>. 815 1.1 christos </li> 816 1.1 christos <li> 817 1.1 christos Since the TZ environment variable can now be used to control time 818 1.1 christos conversion, the <code>daylight</code> 819 1.1 christos and <code>timezone</code> variables are no longer needed. 820 1.1 christos (These variables are defined and set by <code>tzset</code>; 821 1.1 christos however, their values will not be used 822 1.1 christos by <code>localtime</code>.) 823 1.1 christos </li> 824 1.1 christos <li> 825 1.1 christos Functions <code>tzalloc</code>, <code>tzfree</code>, 826 1.1 christos <code>localtime_rz</code>, and <code>mktime_z</code> for 827 1.1 christos more-efficient thread-safe applications that need to use 828 1.1 christos multiple time zones. The <code>tzalloc</code> 829 1.1 christos and <code>tzfree</code> functions allocate and free objects of 830 1.1 christos type <code>timezone_t</code>, and <code>localtime_rz</code> 831 1.1 christos and <code>mktime_z</code> are like <code>localtime_r</code> 832 1.1 christos and <code>mktime</code> with an extra 833 1.1 christos <code>timezone_t</code> argument. The functions were inspired 834 1.1 christos by NetBSD. 835 1.1 christos </li> 836 1.1 christos <li> 837 1.1 christos A function <code>tzsetwall</code> has been added to arrange 838 1.1 christos for the system's 839 1.1 christos best approximation to local wall clock time to be delivered by 840 1.1 christos subsequent calls to <code>localtime</code>. Source code for portable 841 1.1 christos applications that "must" run on local wall clock time should call 842 1.1 christos <code>tzsetwall</code>; if such code is moved to "old" systems that don't 843 1.1 christos provide tzsetwall, you won't be able to generate an executable program. 844 1.1 christos (These time zone functions also arrange for local wall clock time to be 845 1.1 christos used if tzset is called – directly or indirectly – 846 1.1 christos and there's no TZ 847 1.1 christos environment variable; portable applications should not, however, rely 848 1.1 christos on this behavior since it's not the way SVR2 systems behave.) 849 1.1 christos </li> 850 1.1 christos <li> 851 1.1 christos Negative <code>time_t</code> values are supported, on systems 852 1.1 christos where <code>time_t</code> is signed. 853 1.1 christos </li> 854 1.1 christos <li> 855 1.1 christos These functions can account for leap seconds, thanks to Bradley White. 856 1.1 christos </li> 857 1.1 christos </ul> 858 1.1 christos <p> 859 1.1 christos Points of interest to folks with other systems: 860 1.1 christos </p> 861 1.1 christos <ul> 862 1.1 christos <li> 863 1.1 christos Code compatible with this package is already part of many platforms, 864 1.1 christos including GNU/Linux, Android, the BSDs, Chromium OS, Cygwin, AIX, iOS, 865 1.1 christos BlackBery 10, macOS, Microsoft Windows, OpenVMS, and Solaris. 866 1.1 christos On such hosts, the primary use of this package 867 1.1 christos is to update obsolete time zone rule tables. 868 1.1 christos To do this, you may need to compile the time zone compiler 869 1.1 christos '<code>zic</code>' supplied with this package instead of using 870 1.1 christos the system '<code>zic</code>', since the format 871 1.1 christos of <code>zic</code>'s input is occasionally extended, and a 872 1.1 christos platform may still be shipping an older <code>zic</code>. 873 1.1 christos </li> 874 1.1 christos <li> 875 1.1 christos The UNIX Version 7 <code>timezone</code> function is not 876 1.1 christos present in this package; 877 1.1 christos it's impossible to reliably map timezone's arguments (a "minutes west 878 1.1 christos of GMT" value and a "daylight saving time in effect" flag) to a 879 1.1 christos time zone abbreviation, and we refuse to guess. 880 1.1 christos Programs that in the past used the timezone function may now examine 881 1.1 christos <code>localtime(&clock)->tm_zone</code> 882 1.1 christos (if <code>TM_ZONE</code> is defined) or 883 1.1 christos <code>tzname[localtime(&clock)->tm_isdst]</code> 884 1.1 christos (if <code>HAVE_TZNAME</code> is defined) 885 1.1 christos to learn the correct time zone abbreviation to use. 886 1.1 christos </li> 887 1.1 christos <li> 888 1.1 christos The 4.2BSD <code>gettimeofday</code> function is not used in 889 1.1 christos this package. 890 1.1 christos This formerly let users obtain the current UTC offset and DST flag, 891 1.1 christos but this functionality was removed in later versions of BSD. 892 1.1 christos </li> 893 1.1 christos <li> 894 1.1 christos In SVR2, time conversion fails for near-minimum or near-maximum 895 1.1 christos <code>time_t</code> values when doing conversions for places 896 1.1 christos that don't use UT. 897 1.1 christos This package takes care to do these conversions correctly. 898 1.1 christos A comment in the source code tells how to get compatibly wrong 899 1.1 christos results. 900 1.1 christos </li> 901 1.1 christos </ul> 902 1.1 christos <p> 903 1.1 christos The functions that are conditionally compiled 904 1.1 christos if <code>STD_INSPIRED</code> is defined 905 1.1 christos should, at this point, be looked on primarily as food for thought. They are 906 1.1 christos not in any sense "standard compatible" – some are not, in fact, 907 1.1 christos specified in <em>any</em> standard. They do, however, represent responses of 908 1.1 christos various authors to 909 1.1 christos standardization proposals. 910 1.1 christos </p> 911 1.1 christos 912 1.1 christos <p> 913 1.1 christos Other time conversion proposals, in particular the one developed by folks at 914 1.1 christos Hewlett Packard, offer a wider selection of functions that provide capabilities 915 1.1 christos beyond those provided here. The absence of such functions from this package 916 1.1 christos is not meant to discourage the development, standardization, or use of such 917 1.1 christos functions. Rather, their absence reflects the decision to make this package 918 1.1 christos contain valid extensions to POSIX, to ensure its broad acceptability. If 919 1.1 christos more powerful time conversion functions can be standardized, so much the 920 1.1 christos better. 921 1.1 christos </p> 922 1.1 christos </section> 923 1.1 christos 924 1.1 christos 925 1.1 christos <section> 926 1.1 christos <h2 id="stability">Interface stability</h2> 927 1.1 christos <p> 928 1.1 christos The tz code and data supply the following interfaces: 929 1.1 christos </p> 930 1.1 christos <ul> 931 1.1 christos <li> 932 1.1 christos A set of zone names as per "<a href="#naming">Names of time zone 933 1.1 christos rules</a>" above. 934 1.1 christos </li> 935 1.1 christos <li> 936 1.1 christos Library functions described in "<a href="#functions">Time and date 937 1.1 christos functions</a>" above. 938 1.1 christos </li> 939 1.1 christos <li> 940 1.1 christos The programs <code>tzselect</code>, <code>zdump</code>, 941 1.1 christos and <code>zic</code>, documented in their man pages. 942 1.1 christos </li> 943 1.1 christos <li> 944 1.1 christos The format of <code>zic</code> input files, documented in 945 1.1 christos the <code>zic</code> man page. 946 1.1 christos </li> 947 1.1 christos <li> 948 1.1 christos The format of <code>zic</code> output files, documented in 949 1.1 christos the <code>tzfile</code> man page. 950 1.1 christos </li> 951 1.1 christos <li> 952 1.1 christos The format of zone table files, documented in <code>zone1970.tab</code>. 953 1.1 christos </li> 954 1.1 christos <li> 955 1.1 christos The format of the country code file, documented in <code>iso3166.tab</code>. 956 1.1 christos </li> 957 1.1 christos <li> 958 1.1 christos The version number of the code and data, as the first line of 959 1.1 christos the text file '<code>version</code>' in each release. 960 1.1 christos </li> 961 1.1 christos </ul> 962 1.1 christos <p> 963 1.1 christos Interface changes in a release attempt to preserve compatibility with 964 1.1 christos recent releases. For example, tz data files typically do not rely on 965 1.1 christos recently-added <code>zic</code> features, so that users can run 966 1.1 christos older <code>zic</code> versions to process newer data 967 1.2 christos files. <a href="tz-link.html">Sources for time zone and daylight 968 1.1 christos saving time data</a> describes how 969 1.1 christos releases are tagged and distributed. 970 1.1 christos </p> 971 1.1 christos 972 1.1 christos <p> 973 1.1 christos Interfaces not listed above are less stable. For example, users 974 1.1 christos should not rely on particular UT offsets or abbreviations for 975 1.1 christos timestamps, as data entries are often based on guesswork and these 976 1.1 christos guesses may be corrected or improved. 977 1.1 christos </p> 978 1.1 christos </section> 979 1.1 christos 980 1.1 christos 981 1.1 christos <section> 982 1.1 christos <h2 id="calendar">Calendrical issues</h2> 983 1.1 christos <p> 984 1.1 christos Calendrical issues are a bit out of scope for a time zone database, 985 1.1 christos but they indicate the sort of problems that we would run into if we 986 1.1 christos extended the time zone database further into the past. An excellent 987 1.1 christos resource in this area is Nachum Dershowitz and Edward M. Reingold, 988 1.1 christos <cite><a href="https://www.cs.tau.ac.il/~nachum/calendar-book/third-edition/">Calendrical 989 1.1 christos Calculations: Third Edition</a></cite>, Cambridge University Press (2008). 990 1.1 christos Other information and sources are given in the file '<samp>calendars</samp>' 991 1.1 christos in the tz distribution. They sometimes disagree. 992 1.1 christos </p> 993 1.1 christos </section> 994 1.1 christos 995 1.1 christos 996 1.1 christos <section> 997 1.1 christos <h2 id="planets">Time and time zones on other planets</h2> 998 1.1 christos <p> 999 1.1 christos Some people's work schedules use Mars time. Jet Propulsion Laboratory 1000 1.1 christos (JPL) coordinators have kept Mars time on and off at least since 1997 1001 1.1 christos for the Mars Pathfinder mission. Some of their family members have 1002 1.1 christos also adapted to Mars time. Dozens of special Mars watches were built 1003 1.1 christos for JPL workers who kept Mars time during the Mars Exploration 1004 1.1 christos Rovers mission (2004). These timepieces look like normal Seikos and 1005 1.1 christos Citizens but use Mars seconds rather than terrestrial seconds. 1006 1.1 christos </p> 1007 1.1 christos 1008 1.1 christos <p> 1009 1.1 christos A Mars solar day is called a "sol" and has a mean period equal to 1010 1.1 christos about 24 hours 39 minutes 35.244 seconds in terrestrial time. It is 1011 1.1 christos divided into a conventional 24-hour clock, so each Mars second equals 1012 1.1 christos about 1.02749125 terrestrial seconds. 1013 1.1 christos </p> 1014 1.1 christos 1015 1.1 christos <p> 1016 1.1 christos The prime meridian of Mars goes through the center of the crater 1017 1.1 christos Airy-0, named in honor of the British astronomer who built the 1018 1.1 christos Greenwich telescope that defines Earth's prime meridian. Mean solar 1019 1.1 christos time on the Mars prime meridian is called Mars Coordinated Time (MTC). 1020 1.1 christos </p> 1021 1.1 christos 1022 1.1 christos <p> 1023 1.1 christos Each landed mission on Mars has adopted a different reference for 1024 1.1 christos solar time keeping, so there is no real standard for Mars time zones. 1025 1.1 christos For example, the Mars Exploration Rover project (2004) defined two 1026 1.1 christos time zones "Local Solar Time A" and "Local Solar Time B" for its two 1027 1.1 christos missions, each zone designed so that its time equals local true solar 1028 1.1 christos time at approximately the middle of the nominal mission. Such a "time 1029 1.1 christos zone" is not particularly suited for any application other than the 1030 1.1 christos mission itself. 1031 1.1 christos </p> 1032 1.1 christos 1033 1.1 christos <p> 1034 1.1 christos Many calendars have been proposed for Mars, but none have achieved 1035 1.1 christos wide acceptance. Astronomers often use Mars Sol Date (MSD) which is a 1036 1.1 christos sequential count of Mars solar days elapsed since about 1873-12-29 1037 1.1 christos 12:00 GMT. 1038 1.1 christos </p> 1039 1.1 christos 1040 1.1 christos <p> 1041 1.1 christos In our solar system, Mars is the planet with time and calendar most 1042 1.1 christos like Earth's. On other planets, Sun-based time and calendars would 1043 1.1 christos work quite differently. For example, although Mercury's sidereal 1044 1.1 christos rotation period is 58.646 Earth days, Mercury revolves around the Sun 1045 1.1 christos so rapidly that an observer on Mercury's equator would see a sunrise 1046 1.1 christos only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a Mercury 1047 1.1 christos day. Venus is more complicated, partly because its rotation is 1048 1.1 christos slightly retrograde: its year is 1.92 of its days. Gas giants like 1049 1.1 christos Jupiter are trickier still, as their polar and equatorial regions 1050 1.1 christos rotate at different rates, so that the length of a day depends on 1051 1.1 christos latitude. This effect is most pronounced on Neptune, where the day is 1052 1.1 christos about 12 hours at the poles and 18 hours at the equator. 1053 1.1 christos </p> 1054 1.1 christos 1055 1.1 christos <p> 1056 1.1 christos Although the tz database does not support time on other planets, it is 1057 1.1 christos documented here in the hopes that support will be added eventually. 1058 1.1 christos </p> 1059 1.1 christos 1060 1.1 christos <p> 1061 1.1 christos Sources: 1062 1.1 christos </p> 1063 1.1 christos <ul> 1064 1.1 christos <li> 1065 1.1 christos Michael Allison and Robert Schmunk, 1066 1.1 christos "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical 1067 1.1 christos Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" 1068 1.2 christos (2015-06-30). 1069 1.1 christos </li> 1070 1.1 christos <li> 1071 1.1 christos Jia-Rui Chong, 1072 1.1 christos "<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays 1073 1.1 christos Fit for a Martian</a>", Los Angeles Times 1074 1.1 christos (2004-01-14), pp A1, A20-A21. 1075 1.1 christos </li> 1076 1.1 christos <li> 1077 1.1 christos Tom Chmielewski, 1078 1.1 christos "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet 1079 1.1 christos Lag Is Worse on Mars</a>", The Atlantic (2015-02-26) 1080 1.1 christos </li> 1081 1.1 christos <li> 1082 1.1 christos Matt Williams, 1083 1.1 christos "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How 1084 1.1 christos long is a day on the other planets of the solar system?</a>" 1085 1.1 christos (2017-04-27). 1086 1.1 christos </li> 1087 1.1 christos </ul> 1088 1.1 christos </section> 1089 1.1 christos 1090 1.1 christos <footer> 1091 1.1 christos <hr> 1092 1.1 christos This file is in the public domain, so clarified as of 2009-05-17 by 1093 1.1 christos Arthur David Olson. 1094 1.1 christos </footer> 1095 1.1 christos </body> 1096 1.1 christos </html> 1097
Indexes created Fri Sep 26 08:10:20 GMT 2025