Theory revision 1.9
1# $NetBSD: Theory,v 1.9 2009/12/31 22:49:15 mlelstv Exp $ 2@(#)Theory 8.3 3This file is in the public domain, so clarified as of 42009-05-17 by Arthur David Olson. 5 6----- Outline ----- 7 8 Time and date functions 9 Names of time zone regions 10 Time zone abbreviations 11 Calendrical issues 12 Time and time zones on Mars 13 14----- Time and date functions ----- 15 16These time and date functions are upwards compatible with POSIX, 17an international standard for UNIX-like systems. 18As of this writing, the current edition of POSIX is: 19 20 Standard for Information technology 21 -- Portable Operating System Interface (POSIX (R)) 22 -- System Interfaces 23 IEEE Std 1003.1, 2004 Edition 24 <http://www.opengroup.org/online-pubs?DOC=7999959899> 25 <http://www.opengroup.org/pubs/catalog/t041.htm> 26 27POSIX has the following properties and limitations. 28 29* In POSIX, time display in a process is controlled by the 30 environment variable TZ. Unfortunately, the POSIX TZ string takes 31 a form that is hard to describe and is error-prone in practice. 32 Also, POSIX TZ strings can't deal with other (for example, Israeli) 33 daylight saving time rules, or situations where more than two 34 time zone abbreviations are used in an area. 35 36 The POSIX TZ string takes the following form: 37 38 stdoffset[dst[offset],date[/time],date[/time]] 39 40 where: 41 42 std and dst 43 are 3 or more characters specifying the standard 44 and daylight saving time (DST) zone names. 45 Starting with POSIX.1-2001, std and dst may also be 46 in a quoted form like "<UTC+10>"; this allows 47 "+" and "-" in the names. 48 offset 49 is of the form `[-]hh:[mm[:ss]]' and specifies the 50 offset west of UTC. The default DST offset is one hour 51 ahead of standard time. 52 date[/time],date[/time] 53 specifies the beginning and end of DST. If this is absent, 54 the system supplies its own rules for DST, and these can 55 differ from year to year; typically US DST rules are used. 56 time 57 takes the form `hh:[mm[:ss]]' and defaults to 02:00. 58 date 59 takes one of the following forms: 60 Jn (1<=n<=365) 61 origin-1 day number not counting February 29 62 n (0<=n<=365) 63 origin-0 day number counting February 29 if present 64 Mm.n.d (0[Sunday]<=d<=6[Saturday], 1<=n<=5, 1<=m<=12) 65 for the dth day of week n of month m of the year, 66 where week 1 is the first week in which day d appears, 67 and `5' stands for the last week in which day d appears 68 (which may be either the 4th or 5th week). 69 70 Here is an example POSIX TZ string, for US Pacific time using rules 71 appropriate from 1987 through 2006: 72 73 TZ='PST8PDT,M4.1.0/02:00,M10.5.0/02:00' 74 75 This POSIX TZ string is hard to remember, and mishandles time stamps 76 before 1987 and after 2006. With this package you can use this 77 instead: 78 79 TZ='America/Los_Angeles' 80 81* POSIX does not define the exact meaning of TZ values like "EST5EDT". 82 Typically the current US DST rules are used to interpret such values, 83 but this means that the US DST rules are compiled into each program 84 that does time conversion. This means that when US time conversion 85 rules change (as in the United States in 1987), all programs that 86 do time conversion must be recompiled to ensure proper results. 87 88* In POSIX, there's no tamper-proof way for a process to learn the 89 system's best idea of local wall clock. (This is important for 90 applications that an administrator wants used only at certain times-- 91 without regard to whether the user has fiddled the "TZ" environment 92 variable. While an administrator can "do everything in UTC" to get 93 around the problem, doing so is inconvenient and precludes handling 94 daylight saving time shifts--as might be required to limit phone 95 calls to off-peak hours.) 96 97* POSIX requires that systems ignore leap seconds. 98 99These are the extensions that have been made to the POSIX functions: 100 101* The "TZ" environment variable is used in generating the name of a file 102 from which time zone information is read (or is interpreted a la 103 POSIX); "TZ" is no longer constrained to be a three-letter time zone 104 name followed by a number of hours and an optional three-letter 105 daylight time zone name. The daylight saving time rules to be used 106 for a particular time zone are encoded in the time zone file; 107 the format of the file allows U.S., Australian, and other rules to be 108 encoded, and allows for situations where more than two time zone 109 abbreviations are used. 110 111 It was recognized that allowing the "TZ" environment variable to 112 take on values such as "America/New_York" might cause "old" programs 113 (that expect "TZ" to have a certain form) to operate incorrectly; 114 consideration was given to using some other environment variable 115 (for example, "TIMEZONE") to hold the string used to generate the 116 time zone information file name. In the end, however, it was decided 117 to continue using "TZ": it is widely used for time zone purposes; 118 separately maintaining both "TZ" and "TIMEZONE" seemed a nuisance; 119 and systems where "new" forms of "TZ" might cause problems can simply 120 use TZ values such as "EST5EDT" which can be used both by 121 "new" programs (a la POSIX) and "old" programs (as zone names and 122 offsets). 123 124* To handle places where more than two time zone abbreviations are used, 125 the functions "localtime" and "gmtime" set tzname[tmp->tm_isdst] 126 (where "tmp" is the value the function returns) to the time zone 127 abbreviation to be used. This differs from POSIX, where the elements 128 of tzname are only changed as a result of calls to tzset. 129 130* Since the "TZ" environment variable can now be used to control time 131 conversion, the "daylight" and "timezone" variables are no longer 132 needed. (These variables are defined and set by "tzset"; however, their 133 values will not be used by "localtime.") 134 135* The "localtime" function has been set up to deliver correct results 136 for near-minimum or near-maximum time_t values. (A comment in the 137 source code tells how to get compatibly wrong results). 138 139* A function "tzsetwall" has been added to arrange for the system's 140 best approximation to local wall clock time to be delivered by 141 subsequent calls to "localtime." Source code for portable 142 applications that "must" run on local wall clock time should call 143 "tzsetwall();" if such code is moved to "old" systems that don't 144 provide tzsetwall, you won't be able to generate an executable program. 145 (These time zone functions also arrange for local wall clock time to be 146 used if tzset is called--directly or indirectly--and there's no "TZ" 147 environment variable; portable applications should not, however, rely 148 on this behavior since it's not the way SVR2 systems behave.) 149 150* These functions can account for leap seconds, thanks to Bradley White. 151 152Points of interest to folks with other systems: 153 154* This package is already part of many POSIX-compliant hosts, 155 including BSD, HP, Linux, Network Appliance, SCO, SGI, and Sun. 156 On such hosts, the primary use of this package 157 is to update obsolete time zone rule tables. 158 To do this, you may need to compile the time zone compiler 159 `zic' supplied with this package instead of using the system `zic', 160 since the format of zic's input changed slightly in late 1994, 161 and many vendors still do not support the new input format. 162 163* The UNIX Version 7 "timezone" function is not present in this package; 164 it's impossible to reliably map timezone's arguments (a "minutes west 165 of GMT" value and a "daylight saving time in effect" flag) to a 166 time zone abbreviation, and we refuse to guess. 167 Programs that in the past used the timezone function may now examine 168 tzname[localtime(&clock)->tm_isdst] to learn the correct time 169 zone abbreviation to use. Alternatively, use 170 localtime(&clock)->tm_zone if this has been enabled. 171 172* The 4.2BSD gettimeofday function is not used in this package. 173 This formerly let users obtain the current UTC offset and DST flag, 174 but this functionality was removed in later versions of BSD. 175 176* In SVR2, time conversion fails for near-minimum or near-maximum 177 time_t values when doing conversions for places that don't use UTC. 178 This package takes care to do these conversions correctly. 179 180The functions that are conditionally compiled if STD_INSPIRED is defined 181should, at this point, be looked on primarily as food for thought. They are 182not in any sense "standard compatible"--some are not, in fact, specified in 183*any* standard. They do, however, represent responses of various authors to 184standardization proposals. 185 186Other time conversion proposals, in particular the one developed by folks at 187Hewlett Packard, offer a wider selection of functions that provide capabilities 188beyond those provided here. The absence of such functions from this package 189is not meant to discourage the development, standardization, or use of such 190functions. Rather, their absence reflects the decision to make this package 191contain valid extensions to POSIX, to ensure its broad acceptability. If 192more powerful time conversion functions can be standardized, so much the 193better. 194 195 196----- Names of time zone rule files ----- 197 198The time zone rule file naming conventions attempt to strike a balance 199among the following goals: 200 201 * Uniquely identify every national region where clocks have all 202 agreed since 1970. This is essential for the intended use: static 203 clocks keeping local civil time. 204 205 * Indicate to humans as to where that region is. This simplifes use. 206 207 * Be robust in the presence of political changes. This reduces the 208 number of updates and backward-compatibility hacks. For example, 209 names of countries are ordinarily not used, to avoid 210 incompatibilities when countries change their name 211 (e.g. Zaire->Congo) or when locations change countries 212 (e.g. Hong Kong from UK colony to China). 213 214 * Be portable to a wide variety of implementations. 215 This promotes use of the technology. 216 217 * Use a consistent naming convention over the entire world. 218 This simplifies both use and maintenance. 219 220This naming convention is not intended for use by inexperienced users 221to select TZ values by themselves (though they can of course examine 222and reuse existing settings). Distributors should provide 223documentation and/or a simple selection interface that explains the 224names; see the 'tzselect' program supplied with this distribution for 225one example. 226 227Names normally have the form AREA/LOCATION, where AREA is the name 228of a continent or ocean, and LOCATION is the name of a specific 229location within that region. North and South America share the same 230area, `America'. Typical names are `Africa/Cairo', `America/New_York', 231and `Pacific/Honolulu'. 232 233Here are the general rules used for choosing location names, 234in decreasing order of importance: 235 236 Use only valid POSIX file name components (i.e., the parts of 237 names other than `/'). Within a file name component, 238 use only ASCII letters, `.', `-' and `_'. Do not use 239 digits, as that might create an ambiguity with POSIX 240 TZ strings. A file name component must not exceed 14 241 characters or start with `-'. E.g., prefer `Brunei' 242 to `Bandar_Seri_Begawan'. 243 Include at least one location per time zone rule set per country. 244 One such location is enough. Use ISO 3166 (see the file 245 iso3166.tab) to help decide whether something is a country. 246 However, uninhabited ISO 3166 regions like Bouvet Island 247 do not need locations, since local time is not defined there. 248 If all the clocks in a country's region have agreed since 1970, 249 don't bother to include more than one location 250 even if subregions' clocks disagreed before 1970. 251 Otherwise these tables would become annoyingly large. 252 If a name is ambiguous, use a less ambiguous alternative; 253 e.g. many cities are named San Jose and Georgetown, so 254 prefer `Costa_Rica' to `San_Jose' and `Guyana' to `Georgetown'. 255 Keep locations compact. Use cities or small islands, not countries 256 or regions, so that any future time zone changes do not split 257 locations into different time zones. E.g. prefer `Paris' 258 to `France', since France has had multiple time zones. 259 Use mainstream English spelling, e.g. prefer `Rome' to `Roma', and 260 prefer `Athens' to the true name (which uses Greek letters). 261 The POSIX file name restrictions encourage this rule. 262 Use the most populous among locations in a country's time zone, 263 e.g. prefer `Shanghai' to `Beijing'. Among locations with 264 similar populations, pick the best-known location, 265 e.g. prefer `Rome' to `Milan'. 266 Use the singular form, e.g. prefer `Canary' to `Canaries'. 267 Omit common suffixes like `_Islands' and `_City', unless that 268 would lead to ambiguity. E.g. prefer `Cayman' to 269 `Cayman_Islands' and `Guatemala' to `Guatemala_City', 270 but prefer `Mexico_City' to `Mexico' because the country 271 of Mexico has several time zones. 272 Use `_' to represent a space. 273 Omit `.' from abbreviations in names, e.g. prefer `St_Helena' 274 to `St._Helena'. 275 Do not change established names if they only marginally 276 violate the above rules. For example, don't change 277 the existing name `Rome' to `Milan' merely because 278 Milan's population has grown to be somewhat greater 279 than Rome's. 280 If a name is changed, put its old spelling in the `backward' file. 281 282The file `zone.tab' lists the geographical locations used to name 283time zone rule files. It is intended to be an exhaustive list 284of canonical names for geographic regions. 285 286Older versions of this package used a different naming scheme, 287and these older names are still supported. 288See the file `backward' for most of these older names 289(e.g. `US/Eastern' instead of `America/New_York'). 290The other old-fashioned names still supported are 291`WET', `CET', `MET', `EET' (see the file `europe'), 292and `Factory' (see the file `factory'). 293 294 295----- Time zone abbreviations ----- 296 297When this package is installed, it generates time zone abbreviations 298like `EST' to be compatible with human tradition and POSIX. 299Here are the general rules used for choosing time zone abbreviations, 300in decreasing order of importance: 301 302 Use abbreviations that consist of three or more ASCII letters. 303 Previous editions of this database also used characters like 304 ' ' and '?', but these characters have a special meaning to 305 the shell and cause commands like 306 set `date` 307 to have unexpected effects. 308 Previous editions of this rule required upper-case letters, 309 but the Congressman who introduced Chamorro Standard Time 310 preferred "ChST", so the rule has been relaxed. 311 312 This rule guarantees that all abbreviations could have 313 been specified by a POSIX TZ string. POSIX 314 requires at least three characters for an 315 abbreviation. POSIX through 2000 says that an abbreviation 316 cannot start with ':', and cannot contain ',', '-', 317 '+', NUL, or a digit. POSIX from 2001 on changes this 318 rule to say that an abbreviation can contain only '-', '+', 319 and alphanumeric characters from the portable character set 320 in the current locale. To be portable to both sets of 321 rules, an abbreviation must therefore use only ASCII 322 letters. 323 324 Use abbreviations that are in common use among English-speakers, 325 e.g. `EST' for Eastern Standard Time in North America. 326 We assume that applications translate them to other languages 327 as part of the normal localization process; for example, 328 a French application might translate `EST' to `HNE'. 329 330 For zones whose times are taken from a city's longitude, use the 331 traditional xMT notation, e.g. `PMT' for Paris Mean Time. 332 The only name like this in current use is `GMT'. 333 334 If there is no common English abbreviation, abbreviate the English 335 translation of the usual phrase used by native speakers. 336 If this is not available or is a phrase mentioning the country 337 (e.g. ``Cape Verde Time''), then: 338 339 When a country has a single or principal time zone region, 340 append `T' to the country's ISO code, e.g. `CVT' for 341 Cape Verde Time. For summer time append `ST'; 342 for double summer time append `DST'; etc. 343 When a country has multiple time zones, take the first three 344 letters of an English place name identifying each zone 345 and then append `T', `ST', etc. as before; 346 e.g. `VLAST' for VLAdivostok Summer Time. 347 348 Use UTC (with time zone abbreviation "zzz") for locations while 349 uninhabited. The "zzz" mnemonic is that these locations are, 350 in some sense, asleep. 351 352Application writers should note that these abbreviations are ambiguous 353in practice: e.g. `EST' has a different meaning in Australia than 354it does in the United States. In new applications, it's often better 355to use numeric UTC offsets like `-0500' instead of time zone 356abbreviations like `EST'; this avoids the ambiguity. 357 358 359----- Calendrical issues ----- 360 361Calendrical issues are a bit out of scope for a time zone database, 362but they indicate the sort of problems that we would run into if we 363extended the time zone database further into the past. An excellent 364resource in this area is Edward M. Reingold and Nachum Dershowitz, 365<a href="http://emr.cs.uiuc.edu/home/reingold/calendar-book/second-edition/"> 366Calendrical Calculations: The Millennium Edition 367</a>, Cambridge University Press (2001). Other information and 368sources are given below. They sometimes disagree. 369 370 371France 372 373Gregorian calendar adopted 1582-12-20. 374French Revolutionary calendar used 1793-11-24 through 1805-12-31, 375and (in Paris only) 1871-05-06 through 1871-05-23. 376 377 378Russia 379 380From Chris Carrier (1996-12-02): 381On 1929-10-01 the Soviet Union instituted an ``Eternal Calendar'' 382with 30-day months plus 5 holidays, with a 5-day week. 383On 1931-12-01 it changed to a 6-day week; in 1934 it reverted to the 384Gregorian calendar while retaining the 6-day week; on 1940-06-27 it 385reverted to the 7-day week. With the 6-day week the usual days 386off were the 6th, 12th, 18th, 24th and 30th of the month. 387(Source: Evitiar Zerubavel, _The Seven Day Circle_) 388 389 390Mark Brader reported a similar story in "The Book of Calendars", edited 391by Frank Parise (1982, Facts on File, ISBN 0-8719-6467-8), page 377. But: 392 393From: Petteri Sulonen (via Usenet) 394Date: 14 Jan 1999 00:00:00 GMT 395... 396 397If your source is correct, how come documents between 1929 -- 1940 were 398still dated using the conventional, Gregorian calendar? 399 400I can post a scan of a document dated December 1, 1934, signed by 401Yenukidze, the secretary, on behalf of Kalinin, the President of the 402Executive Committee of the Supreme Soviet, if you like. 403 404 405 406Sweden (and Finland) 407 408From: Mark Brader 409<a href="news:1996Jul6.012937.29190@sq.com"> 410Subject: Re: Gregorian reform -- a part of locale? 411</a> 412Date: 1996-07-06 413 414In 1700, Denmark made the transition from Julian to Gregorian. Sweden 415decided to *start* a transition in 1700 as well, but rather than have one of 416those unsightly calendar gaps :-), they simply decreed that the next leap 417year after 1696 would be in 1744 -- putting the whole country on a calendar 418different from both Julian and Gregorian for a period of 40 years. 419 420However, in 1704 something went wrong and the plan was not carried through; 421they did, after all, have a leap year that year. And one in 1708. In 1712 422they gave it up and went back to Julian, putting 30 days in February that 423year!... 424 425Then in 1753, Sweden made the transition to Gregorian in the usual manner, 426getting there only 13 years behind the original schedule. 427 428(A previous posting of this story was challenged, and Swedish readers 429produced the following references to support it: "Tiderakning och historia" 430by Natanael Beckman (1924) and "Tid, en bok om tiderakning och 431kalendervasen" by Lars-Olof Lode'n (no date was given).) 432 433 434Grotefend's data 435 436From: "Michael Palmer" [with one obvious typo fixed] 437Subject: Re: Gregorian Calendar (was Re: Another FHC related question 438Newsgroups: soc.genealogy.german 439Date: Tue, 9 Feb 1999 02:32:48 -800 440... 441 442The following is a(n incomplete) listing, arranged chronologically, of 443European states, with the date they converted from the Julian to the 444Gregorian calendar: 445 44604/15 Oct 1582 - Italy (with exceptions), Spain, Portugal, Poland (Roman 447 Catholics and Danzig only) 44809/20 Dec 1582 - France, Lorraine 449 45021 Dec 1582/ 451 01 Jan 1583 - Holland, Brabant, Flanders, Hennegau 45210/21 Feb 1583 - bishopric of Liege (L"uttich) 45313/24 Feb 1583 - bishopric of Augsburg 45404/15 Oct 1583 - electorate of Trier 45505/16 Oct 1583 - Bavaria, bishoprics of Freising, Eichstedt, Regensburg, 456 Salzburg, Brixen 45713/24 Oct 1583 - Austrian Oberelsass and Breisgau 45820/31 Oct 1583 - bishopric of Basel 45902/13 Nov 1583 - duchy of J"ulich-Berg 46002/13 Nov 1583 - electorate and city of K"oln 46104/15 Nov 1583 - bishopric of W"urzburg 46211/22 Nov 1583 - electorate of Mainz 46316/27 Nov 1583 - bishopric of Strassburg and the margraviate of Baden 46417/28 Nov 1583 - bishopric of M"unster and duchy of Cleve 46514/25 Dec 1583 - Steiermark 466 46706/17 Jan 1584 - Austria and Bohemia 46811/22 Jan 1584 - Luzern, Uri, Schwyz, Zug, Freiburg, Solothurn 46912/23 Jan 1584 - Silesia and the Lausitz 47022 Jan/ 471 02 Feb 1584 - Hungary (legally on 21 Oct 1587) 472 Jun 1584 - Unterwalden 47301/12 Jul 1584 - duchy of Westfalen 474 47516/27 Jun 1585 - bishopric of Paderborn 476 47714/25 Dec 1590 - Transylvania 478 47922 Aug/ 480 02 Sep 1612 - duchy of Prussia 481 48213/24 Dec 1614 - Pfalz-Neuburg 483 484 1617 - duchy of Kurland (reverted to the Julian calendar in 485 1796) 486 487 1624 - bishopric of Osnabr"uck 488 489 1630 - bishopric of Minden 490 49115/26 Mar 1631 - bishopric of Hildesheim 492 493 1655 - Kanton Wallis 494 49505/16 Feb 1682 - city of Strassburg 496 49718 Feb/ 498 01 Mar 1700 - Protestant Germany (including Swedish possessions in 499 Germany), Denmark, Norway 50030 Jun/ 501 12 Jul 1700 - Gelderland, Zutphen 50210 Nov/ 503 12 Dec 1700 - Utrecht, Overijssel 504 50531 Dec 1700/ 506 12 Jan 1701 - Friesland, Groningen, Z"urich, Bern, Basel, Geneva, 507 Turgau, and Schaffhausen 508 509 1724 - Glarus, Appenzell, and the city of St. Gallen 510 51101 Jan 1750 - Pisa and Florence 512 51302/14 Sep 1752 - Great Britain 514 51517 Feb/ 516 01 Mar 1753 - Sweden 517 5181760-1812 - Graub"unden 519 520The Russian empire (including Finland and the Baltic states) did not 521convert to the Gregorian calendar until the Soviet revolution of 1917. 522 523Source: H. Grotefend, _Taschenbuch der Zeitrechnung des deutschen 524Mittelalters und der Neuzeit_, herausgegeben von Dr. O. Grotefend 525(Hannover: Hahnsche Buchhandlung, 1941), pp. 26-28. 526 527 528----- Time and time zones on Mars ----- 529 530Some people have adjusted their work schedules to fit Mars time. 531Dozens of special Mars watches were built for Jet Propulsion 532Laboratory workers who kept Mars time during the Mars Exploration 533Rovers mission (2004). These timepieces look like normal Seikos and 534Citizens but use Mars seconds rather than terrestrial seconds. 535 536A Mars solar day is called a "sol" and has a mean period equal to 537about 24 hours 39 minutes 35.244 seconds in terrestrial time. It is 538divided into a conventional 24-hour clock, so each Mars second equals 539about 1.02749125 terrestrial seconds. 540 541The prime meridian of Mars goes through the center of the crater 542Airy-0, named in honor of the British astronomer who built the 543Greenwich telescope that defines Earth's prime meridian. Mean solar 544time on the Mars prime meridian is called Mars Coordinated Time (MTC). 545 546Each landed mission on Mars has adopted a different reference for 547solar time keeping, so there is no real standard for Mars time zones. 548For example, the Mars Exploration Rover project (2004) defined two 549time zones "Local Solar Time A" and "Local Solar Time B" for its two 550missions, each zone designed so that its time equals local true solar 551time at approximately the middle of the nominal mission. Such a "time 552zone" is not particularly suited for any application other than the 553mission itself. 554 555Many calendars have been proposed for Mars, but none have achieved 556wide acceptance. Astronomers often use Mars Sol Date (MSD) which is a 557sequential count of Mars solar days elapsed since about 1873-12-29 55812:00 GMT. 559 560The tz database does not currently support Mars time, but it is 561documented here in the hopes that support will be added eventually. 562 563Sources: 564 565Michael Allison and Robert Schmunk, 566"Technical Notes on Mars Solar Time as Adopted by the Mars24 Sunclock" 567<http://www.giss.nasa.gov/tools/mars24/help/notes.html> (2004-07-30). 568 569Jia-Rui Chong, "Workdays Fit for a Martian", Los Angeles Times 570(2004-01-14), pp A1, A20-A21. 571