[tz] [PATCH 2/3] Convert Theory file to HTML

* calendars: New file, containing the calendars section of what used to be the Theory file. * theory.html: New file, containing the HTMLized equivalent of the non-calendar part of ... * Theory: ... this file, which was removed. Only formatting was changed, aside from moving the calendrical section to the new file 'calendars'. * CONTRIBUTING, zone1970.tab: * Makefile (COMMON, VERSION_DEPS): Adjust to move. * NEWS: Document the move. * tz-link.htm: Link to new file. --- CONTRIBUTING | 2 +- Makefile | 7 +- NEWS | 4 + Theory | 888 ------------------------------------------------- calendars | 173 ++++++++++ theory.html | 1034 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ tz-link.htm | 5 +- zone1970.tab | 4 +- 8 files changed, 1222 insertions(+), 895 deletions(-) delete mode 100644 Theory create mode 100644 calendars create mode 100644 theory.html diff --git a/CONTRIBUTING b/CONTRIBUTING index 6ce6bfd..716f32b 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -17,7 +17,7 @@ To email small changes, please run a POSIX shell command like 'diff -u old/europe new/europe >myfix.patch', and attach myfix.patch to the email. -For more-elaborate changes, please read the Theory file and browse +For more-elaborate changes, please read the theory.html file and browse the mailing list archives <https://mm.icann.org/pipermail/tz/> for examples of patches that tend to work well. Additions to data should contain commentary citing reliable sources as diff --git a/Makefile b/Makefile index fa755ad..c92edc0 100644 --- a/Makefile +++ b/Makefile @@ -419,7 +419,8 @@ MANTXTS= newctime.3.txt newstrftime.3.txt newtzset.3.txt \ time2posix.3.txt \ tzfile.5.txt tzselect.8.txt zic.8.txt zdump.8.txt \ date.1.txt -COMMON= CONTRIBUTING LICENSE Makefile NEWS README Theory version +COMMON= calendars CONTRIBUTING LICENSE Makefile \ + NEWS README theory.html version WEB_PAGES= tz-art.htm tz-how-to.html tz-link.htm DOCS= $(MANS) date.1 $(MANTXTS) $(WEB_PAGES) PRIMARY_YDATA= africa antarctica asia australasia \ @@ -446,7 +447,7 @@ ENCHILADA= $(COMMON) $(DOCS) $(SOURCES) $(DATA) $(MISC) $(TZS) tzdata.zi # This list is not the same as the output of 'git ls-files', since # .gitignore is not distributed. VERSION_DEPS= \ - CONTRIBUTING LICENSE Makefile NEWS README Theory \ + calendars CONTRIBUTING LICENSE Makefile NEWS README \ africa antarctica asctime.c asia australasia \ backward backzone \ checklinks.awk checktab.awk \ @@ -455,7 +456,7 @@ VERSION_DEPS= \ leap-seconds.list leapseconds.awk localtime.c \ newctime.3 newstrftime.3 newtzset.3 northamerica \ pacificnew private.h \ - southamerica strftime.c systemv \ + southamerica strftime.c systemv theory.html \ time2posix.3 tz-art.htm tz-how-to.html tz-link.htm \ tzfile.5 tzfile.h tzselect.8 tzselect.ksh \ workman.sh yearistype.sh \ diff --git a/NEWS b/NEWS index 660a3fe..7fc32c0 100644 --- a/NEWS +++ b/NEWS @@ -136,6 +136,10 @@ Unreleased, experimental changes Changes to documentation and commentary + The two new files 'theory.html' and 'calendars' contain the + contents of the removed file 'Theory'. The goal is to document + tzdb theory more accessibly. + The zic man page now documents abbreviation rules. tz-link.htm now covers how to apply tzdata changes to clients. diff --git a/Theory b/Theory deleted file mode 100644 index 328423a..0000000 --- a/Theory +++ /dev/null @@ -1,888 +0,0 @@ -Theory and pragmatics of the tz code and data - - ------ Outline ----- - - Scope of the tz database - Names of time zone rules - Time zone abbreviations - Accuracy of the tz database - Time and date functions - Interface stability - Calendrical issues - Time and time zones on other planets - - ------ Scope of the tz database ----- - -The tz database attempts to record the history and predicted future of -all computer-based clocks that track civil time. To represent this -data, the world is partitioned into regions whose clocks all agree -about timestamps that occur after the somewhat-arbitrary cutoff point -of the POSIX Epoch (1970-01-01 00:00:00 UTC). For each such region, -the database records all known clock transitions, and labels the region -with a notable location. Although 1970 is a somewhat-arbitrary -cutoff, there are significant challenges to moving the cutoff earlier -even by a decade or two, due to the wide variety of local practices -before computer timekeeping became prevalent. - -Clock transitions before 1970 are recorded for each such location, -because most systems support timestamps before 1970 and could -misbehave if data entries were omitted for pre-1970 transitions. -However, the database is not designed for and does not suffice for -applications requiring accurate handling of all past times everywhere, -as it would take far too much effort and guesswork to record all -details of pre-1970 civil timekeeping. - -As described below, reference source code for using the tz database is -also available. The tz code is upwards compatible with POSIX, an -international standard for UNIX-like systems. As of this writing, the -current edition of POSIX is: - - The Open Group Base Specifications Issue 7 - IEEE Std 1003.1-2008, 2016 Edition - <http://pubs.opengroup.org/onlinepubs/9699919799/> - - - ------ Names of time zone rules ----- - -Each of the database's time zone rules has a unique name. -Inexperienced users are not expected to select these names unaided. -Distributors should provide documentation and/or a simple selection -interface that explains the names; for one example, see the 'tzselect' -program in the tz code. The Unicode Common Locale Data Repository -<http://cldr.unicode.org/> contains data that may be useful for other -selection interfaces. - -The time zone rule naming conventions attempt to strike a balance -among the following goals: - - * Uniquely identify every region where clocks have agreed since 1970. - This is essential for the intended use: static clocks keeping local - civil time. - - * Indicate to experts where that region is. - - * Be robust in the presence of political changes. For example, names - of countries are ordinarily not used, to avoid incompatibilities - when countries change their name (e.g. Zaire->Congo) or when - locations change countries (e.g. Hong Kong from UK colony to - China). - - * Be portable to a wide variety of implementations. - - * Use a consistent naming conventions over the entire world. - -Names normally have the form AREA/LOCATION, where AREA is the name -of a continent or ocean, and LOCATION is the name of a specific -location within that region. North and South America share the same -area, 'America'. Typical names are 'Africa/Cairo', 'America/New_York', -and 'Pacific/Honolulu'. - -Here are the general rules used for choosing location names, -in decreasing order of importance: - - Use only valid POSIX file name components (i.e., the parts of - names other than '/'). Do not use the file name - components '.' and '..'. Within a file name component, - use only ASCII letters, '.', '-' and '_'. Do not use - digits, as that might create an ambiguity with POSIX - TZ strings. A file name component must not exceed 14 - characters or start with '-'. E.g., prefer 'Brunei' - to 'Bandar_Seri_Begawan'. Exceptions: see the discussion - of legacy names below. - A name must not be empty, or contain '//', or start or end with '/'. - Do not use names that differ only in case. Although the reference - implementation is case-sensitive, some other implementations - are not, and they would mishandle names differing only in case. - If one name A is an initial prefix of another name AB (ignoring case), - then B must not start with '/', as a regular file cannot have - the same name as a directory in POSIX. For example, - 'America/New_York' precludes 'America/New_York/Bronx'. - Uninhabited regions like the North Pole and Bouvet Island - do not need locations, since local time is not defined there. - There should typically be at least one name for each ISO 3166-1 - officially assigned two-letter code for an inhabited country - or territory. - If all the clocks in a region have agreed since 1970, - don't bother to include more than one location - even if subregions' clocks disagreed before 1970. - Otherwise these tables would become annoyingly large. - If a name is ambiguous, use a less ambiguous alternative; - e.g. many cities are named San José and Georgetown, so - prefer 'Costa_Rica' to 'San_Jose' and 'Guyana' to 'Georgetown'. - Keep locations compact. Use cities or small islands, not countries - or regions, so that any future time zone changes do not split - locations into different time zones. E.g. prefer 'Paris' - to 'France', since France has had multiple time zones. - Use mainstream English spelling, e.g. prefer 'Rome' to 'Roma', and - prefer 'Athens' to the Greek 'Αθήνα' or the Romanized 'Athína'. - The POSIX file name restrictions encourage this rule. - Use the most populous among locations in a zone, - e.g. prefer 'Shanghai' to 'Beijing'. Among locations with - similar populations, pick the best-known location, - e.g. prefer 'Rome' to 'Milan'. - Use the singular form, e.g. prefer 'Canary' to 'Canaries'. - Omit common suffixes like '_Islands' and '_City', unless that - would lead to ambiguity. E.g. prefer 'Cayman' to - 'Cayman_Islands' and 'Guatemala' to 'Guatemala_City', - but prefer 'Mexico_City' to 'Mexico' because the country - of Mexico has several time zones. - Use '_' to represent a space. - Omit '.' from abbreviations in names, e.g. prefer 'St_Helena' - to 'St._Helena'. - Do not change established names if they only marginally - violate the above rules. For example, don't change - the existing name 'Rome' to 'Milan' merely because - Milan's population has grown to be somewhat greater - than Rome's. - If a name is changed, put its old spelling in the 'backward' file. - This means old spellings will continue to work. - -The file 'zone1970.tab' lists geographical locations used to name time -zone rules. It is intended to be an exhaustive list of names for -geographic regions as described above; this is a subset of the names -in the data. Although a 'zone1970.tab' location's longitude -corresponds to its LMT offset with one hour for every 15 degrees east -longitude, this relationship is not exact. - -Older versions of this package used a different naming scheme, -and these older names are still supported. -See the file 'backward' for most of these older names -(e.g., 'US/Eastern' instead of 'America/New_York'). -The other old-fashioned names still supported are -'WET', 'CET', 'MET', and 'EET' (see the file 'europe'). - -Older versions of this package defined legacy names that are -incompatible with the first rule of location names, but which are -still supported. These legacy names are mostly defined in the file -'etcetera'. Also, the file 'backward' defines the legacy names -'GMT0', 'GMT-0' and 'GMT+0', and the file 'northamerica' defines the -legacy names 'EST5EDT', 'CST6CDT', 'MST7MDT', and 'PST8PDT'. - -Excluding 'backward' should not affect the other data. If -'backward' is excluded, excluding 'etcetera' should not affect the -remaining data. - - ------ Time zone abbreviations ----- - -When this package is installed, it generates time zone abbreviations -like 'EST' to be compatible with human tradition and POSIX. -Here are the general rules used for choosing time zone abbreviations, -in decreasing order of importance: - - Use three or more characters that are ASCII alphanumerics or '+' or '-'. - Previous editions of this database also used characters like - ' ' and '?', but these characters have a special meaning to - the shell and cause commands like - set `date` - to have unexpected effects. - Previous editions of this rule required upper-case letters, - but the Congressman who introduced Chamorro Standard Time - preferred "ChST", so lower-case letters are now allowed. - Also, POSIX from 2001 on relaxed the rule to allow '-', '+', - and alphanumeric characters from the portable character set - in the current locale. In practice ASCII alphanumerics and - '+' and '-' are safe in all locales. - - In other words, in the C locale the POSIX extended regular - expression [-+[:alnum:]]{3,} should match the abbreviation. - This guarantees that all abbreviations could have been - specified by a POSIX TZ string. - - Use abbreviations that are in common use among English-speakers, - e.g. 'EST' for Eastern Standard Time in North America. - We assume that applications translate them to other languages - as part of the normal localization process; for example, - a French application might translate 'EST' to 'HNE'. - - For zones whose times are taken from a city's longitude, use the - traditional xMT notation, e.g. 'PMT' for Paris Mean Time. - The only name like this in current use is 'GMT'. - - Use 'LMT' for local mean time of locations before the introduction - of standard time; see "Scope of the tz database". - - If there is no common English abbreviation, use numeric offsets like - -05 and +0830 that are generated by zic's %z notation. - - Use current abbreviations for older timestamps to avoid confusion. - For example, in 1910 a common English abbreviation for UT +01 - in central Europe was 'MEZ' (short for both "Middle European - Zone" and for "Mitteleuropäische Zeit" in German). Nowadays - 'CET' ("Central European Time") is more common in English, and - the database uses 'CET' even for circa-1910 timestamps as this - is less confusing for modern users and avoids the need for - determining when 'CET' supplanted 'MEZ' in common usage. - - Use a consistent style in a zone's history. For example, if a zone's - history tends to use numeric abbreviations and a particular - entry could go either way, use a numeric abbreviation. - - [The remaining guidelines predate the introduction of %z. - They are problematic as they mean tz data entries invent - notation rather than record it. These guidelines are now - deprecated and the plan is to gradually move to %z for - inhabited locations and to "-00" for uninhabited locations.] - - If there is no common English abbreviation, abbreviate the English - translation of the usual phrase used by native speakers. - If this is not available or is a phrase mentioning the country - (e.g. "Cape Verde Time"), then: - - When a country is identified with a single or principal zone, - append 'T' to the country's ISO code, e.g. 'CVT' for - Cape Verde Time. For summer time append 'ST'; - for double summer time append 'DST'; etc. - Otherwise, take the first three letters of an English place - name identifying each zone and append 'T', 'ST', etc. - as before; e.g. 'CHAST' for CHAtham Summer Time. - - Use UT (with time zone abbreviation '-00') for locations while - uninhabited. The leading '-' is a flag that the time - zone is in some sense undefined; this notation is - derived from Internet RFC 3339. - -Application writers should note that these abbreviations are ambiguous -in practice: e.g. 'CST' has a different meaning in China than -it does in the United States. In new applications, it's often better -to use numeric UT offsets like '-0600' instead of time zone -abbreviations like 'CST'; this avoids the ambiguity. - - ------ Accuracy of the tz database ----- - -The tz database is not authoritative, and it surely has errors. -Corrections are welcome and encouraged; see the file CONTRIBUTING. -Users requiring authoritative data should consult national standards -bodies and the references cited in the database's comments. - -Errors in the tz database arise from many sources: - - * The tz database predicts future timestamps, and current predictions - will be incorrect after future governments change the rules. - For example, if today someone schedules a meeting for 13:00 next - October 1, Casablanca time, and tomorrow Morocco changes its - daylight saving rules, software can mess up after the rule change - if it blithely relies on conversions made before the change. - - * The pre-1970 entries in this database cover only a tiny sliver of how - clocks actually behaved; the vast majority of the necessary - information was lost or never recorded. Thousands more zones would - be needed if the tz database's scope were extended to cover even - just the known or guessed history of standard time; for example, - the current single entry for France would need to split into dozens - of entries, perhaps hundreds. And in most of the world even this - approach would be misleading due to widespread disagreement or - indifference about what times should be observed. In her 2015 book - "The Global Transformation of Time, 1870-1950", Vanessa Ogle writes - "Outside of Europe and North America there was no system of time - zones at all, often not even a stable landscape of mean times, - prior to the middle decades of the twentieth century". See: - Timothy Shenk, Booked: A Global History of Time. Dissent 2015-12-17 - https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa... - - * Most of the pre-1970 data entries come from unreliable sources, often - astrology books that lack citations and whose compilers evidently - invented entries when the true facts were unknown, without - reporting which entries were known and which were invented. - These books often contradict each other or give implausible entries, - and on the rare occasions when they are checked they are - typically found to be incorrect. - - * For the UK the tz database relies on years of first-class work done by - Joseph Myers and others; see <https://www.polyomino.org.uk/british-time/>. - Other countries are not done nearly as well. - - * Sometimes, different people in the same city would maintain clocks - that differed significantly. Railway time was used by railroad - companies (which did not always agree with each other), - church-clock time was used for birth certificates, etc. - Often this was merely common practice, but sometimes it was set by law. - For example, from 1891 to 1911 the UT offset in France was legally - 0:09:21 outside train stations and 0:04:21 inside. - - * Although a named location in the tz database stands for the - containing region, its pre-1970 data entries are often accurate for - only a small subset of that region. For example, Europe/London - stands for the United Kingdom, but its pre-1847 times are valid - only for locations that have London's exact meridian, and its 1847 - transition to GMT is known to be valid only for the L&NW and the - Caledonian railways. - - * The tz database does not record the earliest time for which a zone's - data entries are thereafter valid for every location in the region. - For example, Europe/London is valid for all locations in its - region after GMT was made the standard time, but the date of - standardization (1880-08-02) is not in the tz database, other than - in commentary. For many zones the earliest time of validity is - unknown. - - * The tz database does not record a region's boundaries, and in many - cases the boundaries are not known. For example, the zone - America/Kentucky/Louisville represents a region around the city of - Louisville, the boundaries of which are unclear. - - * Changes that are modeled as instantaneous transitions in the tz - database were often spread out over hours, days, or even decades. - - * Even if the time is specified by law, locations sometimes - deliberately flout the law. - - * Early timekeeping practices, even assuming perfect clocks, were - often not specified to the accuracy that the tz database requires. - - * Sometimes historical timekeeping was specified more precisely - than what the tz database can handle. For example, from 1909 to - 1937 Netherlands clocks were legally UT +00:19:32.13, but the tz - database cannot represent the fractional second. - - * Even when all the timestamp transitions recorded by the tz database - are correct, the tz rules that generate them may not faithfully - reflect the historical rules. For example, from 1922 until World - War II the UK moved clocks forward the day following the third - Saturday in April unless that was Easter, in which case it moved - clocks forward the previous Sunday. Because the tz database has no - way to specify Easter, these exceptional years are entered as - separate tz Rule lines, even though the legal rules did not change. - - * The tz database models pre-standard time using the proleptic Gregorian - calendar and local mean time (LMT), but many people used other - calendars and other timescales. For example, the Roman Empire used - the Julian calendar, and had 12 varying-length daytime hours with a - non-hour-based system at night. - - * Early clocks were less reliable, and data entries do not represent - clock error. - - * The tz database assumes Universal Time (UT) as an origin, even - though UT is not standardized for older timestamps. In the tz - database commentary, UT denotes a family of time standards that - includes Coordinated Universal Time (UTC) along with other variants - such as UT1 and GMT, with days starting at midnight. Although UT - equals UTC for modern timestamps, UTC was not defined until 1960, - so commentary uses the more-general abbreviation UT for timestamps - that might predate 1960. Since UT, UT1, etc. disagree slightly, - and since pre-1972 UTC seconds varied in length, interpretation of - older timestamps can be problematic when subsecond accuracy is - needed. - - * Civil time was not based on atomic time before 1972, and we don't - know the history of earth's rotation accurately enough to map SI - seconds to historical solar time to more than about one-hour - accuracy. See: Stephenson FR, Morrison LV, Hohenkerk CY. - Measurement of the Earth's rotation: 720 BC to AD 2015. - Proc Royal Soc A. 2016 Dec 7;472:20160404. - http://dx.doi.org/10.1098/rspa.2016.0404 - Also see: Espenak F. Uncertainty in Delta T (ΔT). - https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html - - * The relationship between POSIX time (that is, UTC but ignoring leap - seconds) and UTC is not agreed upon after 1972. Although the POSIX - clock officially stops during an inserted leap second, at least one - proposed standard has it jumping back a second instead; and in - practice POSIX clocks more typically either progress glacially during - a leap second, or are slightly slowed while near a leap second. - - * The tz database does not represent how uncertain its information is. - Ideally it would contain information about when data entries are - incomplete or dicey. Partial temporal knowledge is a field of - active research, though, and it's not clear how to apply it here. - -In short, many, perhaps most, of the tz database's pre-1970 and future -timestamps are either wrong or misleading. Any attempt to pass the -tz database off as the definition of time should be unacceptable to -anybody who cares about the facts. In particular, the tz database's -LMT offsets should not be considered meaningful, and should not prompt -creation of zones merely because two locations differ in LMT or -transitioned to standard time at different dates. - - ------ Time and date functions ----- - -The tz code contains time and date functions that are upwards -compatible with those of POSIX. - -POSIX has the following properties and limitations. - -* In POSIX, time display in a process is controlled by the - environment variable TZ. Unfortunately, the POSIX TZ string takes - a form that is hard to describe and is error-prone in practice. - Also, POSIX TZ strings can't deal with other (for example, Israeli) - daylight saving time rules, or situations where more than two - time zone abbreviations are used in an area. - - The POSIX TZ string takes the following form: - - stdoffset[dst[offset][,date[/time],date[/time]]] - - where: - - std and dst - are 3 or more characters specifying the standard - and daylight saving time (DST) zone names. - Starting with POSIX.1-2001, std and dst may also be - in a quoted form like "<UTC+10>"; this allows - "+" and "-" in the names. - offset - is of the form '[+-]hh:[mm[:ss]]' and specifies the - offset west of UT. 'hh' may be a single digit; 0<=hh<=24. - The default DST offset is one hour ahead of standard time. - date[/time],date[/time] - specifies the beginning and end of DST. If this is absent, - the system supplies its own rules for DST, and these can - differ from year to year; typically US DST rules are used. - time - takes the form 'hh:[mm[:ss]]' and defaults to 02:00. - This is the same format as the offset, except that a - leading '+' or '-' is not allowed. - date - takes one of the following forms: - Jn (1<=n<=365) - origin-1 day number not counting February 29 - n (0<=n<=365) - origin-0 day number counting February 29 if present - Mm.n.d (0[Sunday]<=d<=6[Saturday], 1<=n<=5, 1<=m<=12) - for the dth day of week n of month m of the year, - where week 1 is the first week in which day d appears, - and '5' stands for the last week in which day d appears - (which may be either the 4th or 5th week). - Typically, this is the only useful form; - the n and Jn forms are rarely used. - - Here is an example POSIX TZ string for New Zealand after 2007. - It says that standard time (NZST) is 12 hours ahead of UTC, - and that daylight saving time (NZDT) is observed from September's - last Sunday at 02:00 until April's first Sunday at 03:00: - - TZ='NZST-12NZDT,M9.5.0,M4.1.0/3' - - This POSIX TZ string is hard to remember, and mishandles some - timestamps before 2008. With this package you can use this - instead: - - TZ='Pacific/Auckland' - -* POSIX does not define the exact meaning of TZ values like "EST5EDT". - Typically the current US DST rules are used to interpret such values, - but this means that the US DST rules are compiled into each program - that does time conversion. This means that when US time conversion - rules change (as in the United States in 1987), all programs that - do time conversion must be recompiled to ensure proper results. - -* The TZ environment variable is process-global, which makes it hard - to write efficient, thread-safe applications that need access - to multiple time zones. - -* In POSIX, there's no tamper-proof way for a process to learn the - system's best idea of local wall clock. (This is important for - applications that an administrator wants used only at certain times - - without regard to whether the user has fiddled the "TZ" environment - variable. While an administrator can "do everything in UTC" to get - around the problem, doing so is inconvenient and precludes handling - daylight saving time shifts - as might be required to limit phone - calls to off-peak hours.) - -* POSIX provides no convenient and efficient way to determine the UT - offset and time zone abbreviation of arbitrary timestamps, - particularly for time zone settings that do not fit into the - POSIX model. - -* POSIX requires that systems ignore leap seconds. - -* The tz code attempts to support all the time_t implementations - allowed by POSIX. The time_t type represents a nonnegative count of - seconds since 1970-01-01 00:00:00 UTC, ignoring leap seconds. - In practice, time_t is usually a signed 64- or 32-bit integer; 32-bit - signed time_t values stop working after 2038-01-19 03:14:07 UTC, so - new implementations these days typically use a signed 64-bit integer. - Unsigned 32-bit integers are used on one or two platforms, - and 36-bit and 40-bit integers are also used occasionally. - Although earlier POSIX versions allowed time_t to be a - floating-point type, this was not supported by any practical - systems, and POSIX.1-2013 and the tz code both require time_t - to be an integer type. - -These are the extensions that have been made to the POSIX functions: - -* The "TZ" environment variable is used in generating the name of a file - from which time zone information is read (or is interpreted a la - POSIX); "TZ" is no longer constrained to be a three-letter time zone - name followed by a number of hours and an optional three-letter - daylight time zone name. The daylight saving time rules to be used - for a particular time zone are encoded in the time zone file; - the format of the file allows U.S., Australian, and other rules to be - encoded, and allows for situations where more than two time zone - abbreviations are used. - - It was recognized that allowing the "TZ" environment variable to - take on values such as "America/New_York" might cause "old" programs - (that expect "TZ" to have a certain form) to operate incorrectly; - consideration was given to using some other environment variable - (for example, "TIMEZONE") to hold the string used to generate the - time zone information file name. In the end, however, it was decided - to continue using "TZ": it is widely used for time zone purposes; - separately maintaining both "TZ" and "TIMEZONE" seemed a nuisance; - and systems where "new" forms of "TZ" might cause problems can simply - use TZ values such as "EST5EDT" which can be used both by - "new" programs (a la POSIX) and "old" programs (as zone names and - offsets). - -* The code supports platforms with a UT offset member in struct tm, - e.g., tm_gmtoff. - -* The code supports platforms with a time zone abbreviation member in - struct tm, e.g., tm_zone. - -* Since the "TZ" environment variable can now be used to control time - conversion, the "daylight" and "timezone" variables are no longer - needed. (These variables are defined and set by "tzset"; however, their - values will not be used by "localtime.") - -* Functions tzalloc, tzfree, localtime_rz, and mktime_z for - more-efficient thread-safe applications that need to use - multiple time zones. The tzalloc and tzfree functions - allocate and free objects of type timezone_t, and localtime_rz - and mktime_z are like localtime_r and mktime with an extra - timezone_t argument. The functions were inspired by NetBSD. - -* A function "tzsetwall" has been added to arrange for the system's - best approximation to local wall clock time to be delivered by - subsequent calls to "localtime." Source code for portable - applications that "must" run on local wall clock time should call - "tzsetwall();" if such code is moved to "old" systems that don't - provide tzsetwall, you won't be able to generate an executable program. - (These time zone functions also arrange for local wall clock time to be - used if tzset is called - directly or indirectly - and there's no "TZ" - environment variable; portable applications should not, however, rely - on this behavior since it's not the way SVR2 systems behave.) - -* Negative time_t values are supported, on systems where time_t is signed. - -* These functions can account for leap seconds, thanks to Bradley White. - -Points of interest to folks with other systems: - -* Code compatible with this package is already part of many platforms, - including GNU/Linux, Android, the BSDs, Chromium OS, Cygwin, AIX, iOS, - BlackBery 10, macOS, Microsoft Windows, OpenVMS, and Solaris. - On such hosts, the primary use of this package - is to update obsolete time zone rule tables. - To do this, you may need to compile the time zone compiler - 'zic' supplied with this package instead of using the system 'zic', - since the format of zic's input is occasionally extended, - and a platform may still be shipping an older zic. - -* The UNIX Version 7 "timezone" function is not present in this package; - it's impossible to reliably map timezone's arguments (a "minutes west - of GMT" value and a "daylight saving time in effect" flag) to a - time zone abbreviation, and we refuse to guess. - Programs that in the past used the timezone function may now examine - localtime(&clock)->tm_zone (if TM_ZONE is defined) or - tzname[localtime(&clock)->tm_isdst] (if HAVE_TZNAME is defined) - to learn the correct time zone abbreviation to use. - -* The 4.2BSD gettimeofday function is not used in this package. - This formerly let users obtain the current UTC offset and DST flag, - but this functionality was removed in later versions of BSD. - -* In SVR2, time conversion fails for near-minimum or near-maximum - time_t values when doing conversions for places that don't use UT. - This package takes care to do these conversions correctly. - A comment in the source code tells how to get compatibly wrong - results. - -The functions that are conditionally compiled if STD_INSPIRED is defined -should, at this point, be looked on primarily as food for thought. They are -not in any sense "standard compatible" - some are not, in fact, specified in -*any* standard. They do, however, represent responses of various authors to -standardization proposals. - -Other time conversion proposals, in particular the one developed by folks at -Hewlett Packard, offer a wider selection of functions that provide capabilities -beyond those provided here. The absence of such functions from this package -is not meant to discourage the development, standardization, or use of such -functions. Rather, their absence reflects the decision to make this package -contain valid extensions to POSIX, to ensure its broad acceptability. If -more powerful time conversion functions can be standardized, so much the -better. - - ------ Interface stability ----- - -The tz code and data supply the following interfaces: - - * A set of zone names as per "Names of time zone rules" above. - - * Library functions described in "Time and date functions" above. - - * The programs tzselect, zdump, and zic, documented in their man pages. - - * The format of zic input files, documented in the zic man page. - - * The format of zic output files, documented in the tzfile man page. - - * The format of zone table files, documented in zone1970.tab. - - * The format of the country code file, documented in iso3166.tab. - - * The version number of the code and data, as the first line of - the text file 'version' in each release. - -Interface changes in a release attempt to preserve compatibility with -recent releases. For example, tz data files typically do not rely on -recently-added zic features, so that users can run older zic versions -to process newer data files. The tz-link.htm file describes how -releases are tagged and distributed. - -Interfaces not listed above are less stable. For example, users -should not rely on particular UT offsets or abbreviations for -timestamps, as data entries are often based on guesswork and these -guesses may be corrected or improved. - - ------ Calendrical issues ----- - -Calendrical issues are a bit out of scope for a time zone database, -but they indicate the sort of problems that we would run into if we -extended the time zone database further into the past. An excellent -resource in this area is Nachum Dershowitz and Edward M. Reingold, -Calendrical Calculations: Third Edition, Cambridge University Press (2008) -<https://www.cs.tau.ac.il/~nachum/calendar-book/third-edition/>. -Other information and sources are given below. They sometimes disagree. - - -France - -Gregorian calendar adopted 1582-12-20. -French Revolutionary calendar used 1793-11-24 through 1805-12-31, -and (in Paris only) 1871-05-06 through 1871-05-23. - - -Russia - -From Chris Carrier (1996-12-02): -On 1929-10-01 the Soviet Union instituted an "Eternal Calendar" -with 30-day months plus 5 holidays, with a 5-day week. -On 1931-12-01 it changed to a 6-day week; in 1934 it reverted to the -Gregorian calendar while retaining the 6-day week; on 1940-06-27 it -reverted to the 7-day week. With the 6-day week the usual days -off were the 6th, 12th, 18th, 24th and 30th of the month. -(Source: Evitiar Zerubavel, _The Seven Day Circle_) - - -Mark Brader reported a similar story in "The Book of Calendars", edited -by Frank Parise (1982, Facts on File, ISBN 0-8719-6467-8), page 377. But: - -From: Petteri Sulonen (via Usenet) -Date: 14 Jan 1999 00:00:00 GMT -... - -If your source is correct, how come documents between 1929 and 1940 were -still dated using the conventional, Gregorian calendar? - -I can post a scan of a document dated December 1, 1934, signed by -Yenukidze, the secretary, on behalf of Kalinin, the President of the -Executive Committee of the Supreme Soviet, if you like. - - - -Sweden (and Finland) - -From: Mark Brader -Subject: Re: Gregorian reform - a part of locale? -<news:1996Jul6.012937.29190@sq.com> -Date: 1996-07-06 - -In 1700, Denmark made the transition from Julian to Gregorian. Sweden -decided to *start* a transition in 1700 as well, but rather than have one of -those unsightly calendar gaps :-), they simply decreed that the next leap -year after 1696 would be in 1744 - putting the whole country on a calendar -different from both Julian and Gregorian for a period of 40 years. - -However, in 1704 something went wrong and the plan was not carried through; -they did, after all, have a leap year that year. And one in 1708. In 1712 -they gave it up and went back to Julian, putting 30 days in February that -year!... - -Then in 1753, Sweden made the transition to Gregorian in the usual manner, -getting there only 13 years behind the original schedule. - -(A previous posting of this story was challenged, and Swedish readers -produced the following references to support it: "Tideräkning och historia" -by Natanael Beckman (1924) and "Tid, en bok om tideräkning och -kalenderväsen" by Lars-Olof Lodén (1968). - - -Grotefend's data - -From: "Michael Palmer" [with one obvious typo fixed] -Subject: Re: Gregorian Calendar (was Re: Another FHC related question -Newsgroups: soc.genealogy.german -Date: Tue, 9 Feb 1999 02:32:48 -800 -... - -The following is a(n incomplete) listing, arranged chronologically, of -European states, with the date they converted from the Julian to the -Gregorian calendar: - -04/15 Oct 1582 - Italy (with exceptions), Spain, Portugal, Poland (Roman - Catholics and Danzig only) -09/20 Dec 1582 - France, Lorraine - -21 Dec 1582/ - 01 Jan 1583 - Holland, Brabant, Flanders, Hennegau -10/21 Feb 1583 - bishopric of Liege (Lüttich) -13/24 Feb 1583 - bishopric of Augsburg -04/15 Oct 1583 - electorate of Trier -05/16 Oct 1583 - Bavaria, bishoprics of Freising, Eichstedt, Regensburg, - Salzburg, Brixen -13/24 Oct 1583 - Austrian Oberelsaß and Breisgau -20/31 Oct 1583 - bishopric of Basel -02/13 Nov 1583 - duchy of Jülich-Berg -02/13 Nov 1583 - electorate and city of Köln -04/15 Nov 1583 - bishopric of Würzburg -11/22 Nov 1583 - electorate of Mainz -16/27 Nov 1583 - bishopric of Strassburg and the margraviate of Baden -17/28 Nov 1583 - bishopric of Münster and duchy of Cleve -14/25 Dec 1583 - Steiermark - -06/17 Jan 1584 - Austria and Bohemia -11/22 Jan 1584 - Lucerne, Uri, Schwyz, Zug, Freiburg, Solothurn -12/23 Jan 1584 - Silesia and the Lausitz -22 Jan/ - 02 Feb 1584 - Hungary (legally on 21 Oct 1587) - Jun 1584 - Unterwalden -01/12 Jul 1584 - duchy of Westfalen - -16/27 Jun 1585 - bishopric of Paderborn - -14/25 Dec 1590 - Transylvania - -22 Aug/ - 02 Sep 1612 - duchy of Prussia - -13/24 Dec 1614 - Pfalz-Neuburg - - 1617 - duchy of Kurland (reverted to the Julian calendar in - 1796) - - 1624 - bishopric of Osnabrück - - 1630 - bishopric of Minden - -15/26 Mar 1631 - bishopric of Hildesheim - - 1655 - Kanton Wallis - -05/16 Feb 1682 - city of Strassburg - -18 Feb/ - 01 Mar 1700 - Protestant Germany (including Swedish possessions in - Germany), Denmark, Norway -30 Jun/ - 12 Jul 1700 - Gelderland, Zutphen -10 Nov/ - 12 Dec 1700 - Utrecht, Overijssel - -31 Dec 1700/ - 12 Jan 1701 - Friesland, Groningen, Zürich, Bern, Basel, Geneva, - Turgau, and Schaffhausen - - 1724 - Glarus, Appenzell, and the city of St. Gallen - -01 Jan 1750 - Pisa and Florence - -02/14 Sep 1752 - Great Britain - -17 Feb/ - 01 Mar 1753 - Sweden - -1760-1812 - Graubünden - -The Russian empire (including Finland and the Baltic states) did not -convert to the Gregorian calendar until the Soviet revolution of 1917. - -Source: H. Grotefend, _Taschenbuch der Zeitrechnung des deutschen -Mittelalters und der Neuzeit_, herausgegeben von Dr. O. Grotefend -(Hannover: Hahnsche Buchhandlung, 1941), pp. 26-28. - - ------ Time and time zones on other planets ----- - -Some people's work schedules use Mars time. Jet Propulsion Laboratory -(JPL) coordinators have kept Mars time on and off at least since 1997 -for the Mars Pathfinder mission. Some of their family members have -also adapted to Mars time. Dozens of special Mars watches were built -for JPL workers who kept Mars time during the Mars Exploration -Rovers mission (2004). These timepieces look like normal Seikos and -Citizens but use Mars seconds rather than terrestrial seconds. - -A Mars solar day is called a "sol" and has a mean period equal to -about 24 hours 39 minutes 35.244 seconds in terrestrial time. It is -divided into a conventional 24-hour clock, so each Mars second equals -about 1.02749125 terrestrial seconds. - -The prime meridian of Mars goes through the center of the crater -Airy-0, named in honor of the British astronomer who built the -Greenwich telescope that defines Earth's prime meridian. Mean solar -time on the Mars prime meridian is called Mars Coordinated Time (MTC). - -Each landed mission on Mars has adopted a different reference for -solar time keeping, so there is no real standard for Mars time zones. -For example, the Mars Exploration Rover project (2004) defined two -time zones "Local Solar Time A" and "Local Solar Time B" for its two -missions, each zone designed so that its time equals local true solar -time at approximately the middle of the nominal mission. Such a "time -zone" is not particularly suited for any application other than the -mission itself. - -Many calendars have been proposed for Mars, but none have achieved -wide acceptance. Astronomers often use Mars Sol Date (MSD) which is a -sequential count of Mars solar days elapsed since about 1873-12-29 -12:00 GMT. - -In our solar system, Mars is the planet with time and calendar most -like Earth's. On other planets, Sun-based time and calendars would -work quite differently. For example, although Mercury's sidereal -rotation period is 58.646 Earth days, Mercury revolves around the Sun -so rapidly that an observer on Mercury's equator would see a sunrise -only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a Mercury -day. Venus is more complicated, partly because its rotation is -slightly retrograde: its year is 1.92 of its days. Gas giants like -Jupiter are trickier still, as their polar and equatorial regions -rotate at different rates, so that the length of a day depends on -latitude. This effect is most pronounced on Neptune, where the day is -about 12 hours at the poles and 18 hours at the equator. - -Although the tz database does not support time on other planets, it is -documented here in the hopes that support will be added eventually. - -Sources: - -Michael Allison and Robert Schmunk, -"Technical Notes on Mars Solar Time as Adopted by the Mars24 Sunclock" -<https://www.giss.nasa.gov/tools/mars24/help/notes.html> (2012-08-08). - -Jia-Rui Chong, "Workdays Fit for a Martian", Los Angeles Times -<http://articles.latimes.com/2004/jan/14/science/sci-marstime14> -(2004-01-14), pp A1, A20-A21. - -Tom Chmielewski, "Jet Lag Is Worse on Mars", The Atlantic (2015-02-26) -<https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-m...> - -Matt Williams, "How long is a day on the other planets of the solar -system?" <https://www.universetoday.com/37481/days-of-the-planets/> -(2017-04-27). - ------ - -This file is in the public domain, so clarified as of 2009-05-17 by -Arthur David Olson. - ------ -Local Variables: -coding: utf-8 -End: diff --git a/calendars b/calendars new file mode 100644 index 0000000..8bc7062 --- /dev/null +++ b/calendars @@ -0,0 +1,173 @@ +----- Calendrical issues ----- + +As mentioned in Theory.html, although calendrical issues are out of +scope for tzdb, they indicate the sort of problems that we would run +into if we extended tzdb further into the past. The following +information and sources go beyond Theory.html's brief discussion. +They sometimes disagree. + + +France + +Gregorian calendar adopted 1582-12-20. +French Revolutionary calendar used 1793-11-24 through 1805-12-31, +and (in Paris only) 1871-05-06 through 1871-05-23. + + +Russia + +From Chris Carrier (1996-12-02): +On 1929-10-01 the Soviet Union instituted an "Eternal Calendar" +with 30-day months plus 5 holidays, with a 5-day week. +On 1931-12-01 it changed to a 6-day week; in 1934 it reverted to the +Gregorian calendar while retaining the 6-day week; on 1940-06-27 it +reverted to the 7-day week. With the 6-day week the usual days +off were the 6th, 12th, 18th, 24th and 30th of the month. +(Source: Evitiar Zerubavel, _The Seven Day Circle_) + + +Mark Brader reported a similar story in "The Book of Calendars", edited +by Frank Parise (1982, Facts on File, ISBN 0-8719-6467-8), page 377. But: + +From: Petteri Sulonen (via Usenet) +Date: 14 Jan 1999 00:00:00 GMT +... + +If your source is correct, how come documents between 1929 and 1940 were +still dated using the conventional, Gregorian calendar? + +I can post a scan of a document dated December 1, 1934, signed by +Yenukidze, the secretary, on behalf of Kalinin, the President of the +Executive Committee of the Supreme Soviet, if you like. + + + +Sweden (and Finland) + +From: Mark Brader +Subject: Re: Gregorian reform - a part of locale? +<news:1996Jul6.012937.29190@sq.com> +Date: 1996-07-06 + +In 1700, Denmark made the transition from Julian to Gregorian. Sweden +decided to *start* a transition in 1700 as well, but rather than have one of +those unsightly calendar gaps :-), they simply decreed that the next leap +year after 1696 would be in 1744 - putting the whole country on a calendar +different from both Julian and Gregorian for a period of 40 years. + +However, in 1704 something went wrong and the plan was not carried through; +they did, after all, have a leap year that year. And one in 1708. In 1712 +they gave it up and went back to Julian, putting 30 days in February that +year!... + +Then in 1753, Sweden made the transition to Gregorian in the usual manner, +getting there only 13 years behind the original schedule. + +(A previous posting of this story was challenged, and Swedish readers +produced the following references to support it: "Tideräkning och historia" +by Natanael Beckman (1924) and "Tid, en bok om tideräkning och +kalenderväsen" by Lars-Olof Lodén (1968). + + +Grotefend's data + +From: "Michael Palmer" [with one obvious typo fixed] +Subject: Re: Gregorian Calendar (was Re: Another FHC related question +Newsgroups: soc.genealogy.german +Date: Tue, 9 Feb 1999 02:32:48 -800 +... + +The following is a(n incomplete) listing, arranged chronologically, of +European states, with the date they converted from the Julian to the +Gregorian calendar: + +04/15 Oct 1582 - Italy (with exceptions), Spain, Portugal, Poland (Roman + Catholics and Danzig only) +09/20 Dec 1582 - France, Lorraine + +21 Dec 1582/ + 01 Jan 1583 - Holland, Brabant, Flanders, Hennegau +10/21 Feb 1583 - bishopric of Liege (Lüttich) +13/24 Feb 1583 - bishopric of Augsburg +04/15 Oct 1583 - electorate of Trier +05/16 Oct 1583 - Bavaria, bishoprics of Freising, Eichstedt, Regensburg, + Salzburg, Brixen +13/24 Oct 1583 - Austrian Oberelsaß and Breisgau +20/31 Oct 1583 - bishopric of Basel +02/13 Nov 1583 - duchy of Jülich-Berg +02/13 Nov 1583 - electorate and city of Köln +04/15 Nov 1583 - bishopric of Würzburg +11/22 Nov 1583 - electorate of Mainz +16/27 Nov 1583 - bishopric of Strassburg and the margraviate of Baden +17/28 Nov 1583 - bishopric of Münster and duchy of Cleve +14/25 Dec 1583 - Steiermark + +06/17 Jan 1584 - Austria and Bohemia +11/22 Jan 1584 - Lucerne, Uri, Schwyz, Zug, Freiburg, Solothurn +12/23 Jan 1584 - Silesia and the Lausitz +22 Jan/ + 02 Feb 1584 - Hungary (legally on 21 Oct 1587) + Jun 1584 - Unterwalden +01/12 Jul 1584 - duchy of Westfalen + +16/27 Jun 1585 - bishopric of Paderborn + +14/25 Dec 1590 - Transylvania + +22 Aug/ + 02 Sep 1612 - duchy of Prussia + +13/24 Dec 1614 - Pfalz-Neuburg + + 1617 - duchy of Kurland (reverted to the Julian calendar in + 1796) + + 1624 - bishopric of Osnabrück + + 1630 - bishopric of Minden + +15/26 Mar 1631 - bishopric of Hildesheim + + 1655 - Kanton Wallis + +05/16 Feb 1682 - city of Strassburg + +18 Feb/ + 01 Mar 1700 - Protestant Germany (including Swedish possessions in + Germany), Denmark, Norway +30 Jun/ + 12 Jul 1700 - Gelderland, Zutphen +10 Nov/ + 12 Dec 1700 - Utrecht, Overijssel + +31 Dec 1700/ + 12 Jan 1701 - Friesland, Groningen, Zürich, Bern, Basel, Geneva, + Turgau, and Schaffhausen + + 1724 - Glarus, Appenzell, and the city of St. Gallen + +01 Jan 1750 - Pisa and Florence + +02/14 Sep 1752 - Great Britain + +17 Feb/ + 01 Mar 1753 - Sweden + +1760-1812 - Graubünden + +The Russian empire (including Finland and the Baltic states) did not +convert to the Gregorian calendar until the Soviet revolution of 1917. + +Source: H. Grotefend, _Taschenbuch der Zeitrechnung des deutschen +Mittelalters und der Neuzeit_, herausgegeben von Dr. O. Grotefend +(Hannover: Hahnsche Buchhandlung, 1941), pp. 26-28. + +----- + +This file is in the public domain, so clarified as of 2009-05-17 by +Arthur David Olson. + +----- +Local Variables: +coding: utf-8 +End: diff --git a/theory.html b/theory.html new file mode 100644 index 0000000..965135d --- /dev/null +++ b/theory.html @@ -0,0 +1,1034 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Theory and pragmatics of the tz code and data</title> + <meta charset="UTF-8"> +</head> + +<!-- The somewhat-unusal indenting style in this file is intended to + shrink the output of the shell command 'diff Theory Theory.html', + where 'Theory' was the plain text file that this file is derived + from. The 'Theory' file used leading white space to indent, and + when possible that indentation is preserved here. Eventually we + may stop doing this and remove this comment. --> + +<body> + <h1>Theory and pragmatics of the tz code and data</h1> + <h3>Outline</h3> + <nav> + <ul> + <li><a href="#scope">Scope of the tz database</a></li> + <li><a href="#naming">Names of time zone rules</a></li> + <li><a href="#abbreviations">Time zone abbreviations</a></li> + <li><a href="#accuracy">Accuracy of the tz database</a></li> + <li><a href="#functions">Time and date functions</a></li> + <li><a href="#stability">Interface stability</a></li> + <li><a href="#calendar">Calendrical issues</a></li> + <li><a href="#planets">Time and time zones on other planets</a></li> + </ul> + </nav> + + + <section> + <h2 id="scope">Scope of the tz database</h2> +<p> +The tz database attempts to record the history and predicted future of +all computer-based clocks that track civil time. To represent this +data, the world is partitioned into regions whose clocks all agree +about timestamps that occur after the somewhat-arbitrary cutoff point +of the POSIX Epoch (1970-01-01 00:00:00 UTC). For each such region, +the database records all known clock transitions, and labels the region +with a notable location. Although 1970 is a somewhat-arbitrary +cutoff, there are significant challenges to moving the cutoff earlier +even by a decade or two, due to the wide variety of local practices +before computer timekeeping became prevalent. +</p> + +<p> +Clock transitions before 1970 are recorded for each such location, +because most systems support timestamps before 1970 and could +misbehave if data entries were omitted for pre-1970 transitions. +However, the database is not designed for and does not suffice for +applications requiring accurate handling of all past times everywhere, +as it would take far too much effort and guesswork to record all +details of pre-1970 civil timekeeping. +</p> + +<p> +As described below, reference source code for using the tz database is +also available. The tz code is upwards compatible with POSIX, an +international standard for UNIX-like systems. As of this writing, the +current edition of POSIX is: + <a href="http://pubs.opengroup.org/onlinepubs/9699919799/"> + The Open Group Base Specifications Issue 7</a>, + IEEE Std 1003.1-2008, 2016 Edition. +</p> + </section> + + + + <section> + <h2 id="naming">Names of time zone rules</h2> +<p> +Each of the database's time zone rules has a unique name. +Inexperienced users are not expected to select these names unaided. +Distributors should provide documentation and/or a simple selection +interface that explains the names; for one example, see the 'tzselect' +program in the tz code. The +<a href="http://cldr.unicode.org/">Unicode Common Locale Data +Repository</a> contains data that may be useful for other +selection interfaces. +</p> + +<p> +The time zone rule naming conventions attempt to strike a balance +among the following goals: +</p> +<ul> + <li> + Uniquely identify every region where clocks have agreed since 1970. + This is essential for the intended use: static clocks keeping local + civil time. + </li> + <li> + Indicate to experts where that region is. + </li> + <li> + Be robust in the presence of political changes. For example, names + of countries are ordinarily not used, to avoid incompatibilities + when countries change their name (e.g. Zaire→Congo) or when + locations change countries (e.g. Hong Kong from UK colony to + China). + </li> + <li> + Be portable to a wide variety of implementations. + </li> + <li> + Use a consistent naming conventions over the entire world. + </li> +</ul> +<p> +Names normally have the +form <var>AREA</var><code>/</code><var>LOCATION</var>, +where <var>AREA</var> is the name of a continent or ocean, +and <var>LOCATION</var> is the name of a specific +location within that region. North and South America share the same +area, '<code>America</code>'. Typical names are +'<code>Africa/Cairo</code>', '<code>America/New_York</code>', and +'<code>Pacific/Honolulu</code>'. +</p> + +<p> +Here are the general rules used for choosing location names, +in decreasing order of importance: +</p> +<ul> + <li> + Use only valid POSIX file name components (i.e., the parts of + names other than '<code>/</code>'). Do not use the file name + components '<code>.</code>' and '<code>..</code>'. + Within a file name component, + use only ASCII letters, '<code>.</code>', + '<code>-</code>' and '<code>_</code>'. Do not use + digits, as that might create an ambiguity with POSIX + TZ strings. A file name component must not exceed 14 + characters or start with '<code>-</code>'. E.g., + prefer '<code>Brunei</code>' to + '<code>Bandar_Seri_Begawan</code>'. Exceptions: see + the discussion + of legacy names below. + </li> + <li> + A name must not be empty, or contain '<code>//</code>', or + start or end with '<code>/</code>'. + </li> + <li> + Do not use names that differ only in case. Although the reference + implementation is case-sensitive, some other implementations + are not, and they would mishandle names differing only in case. + </li> + <li> + If one name <var>A</var> is an initial prefix of another + name <var>AB</var> (ignoring case), then <var>B</var> + must not start with '<code>/</code>', as a + regular file cannot have + the same name as a directory in POSIX. For example, + '<code>America/New_York</code>' precludes + '<code>America/New_York/Bronx</code>'. + </li> + <li> + Uninhabited regions like the North Pole and Bouvet Island + do not need locations, since local time is not defined there. + </li> + <li> + There should typically be at least one name for each ISO 3166-1 + officially assigned two-letter code for an inhabited country + or territory. + </li> + <li> + If all the clocks in a region have agreed since 1970, + don't bother to include more than one location + even if subregions' clocks disagreed before 1970. + Otherwise these tables would become annoyingly large. + </li> + <li> + If a name is ambiguous, use a less ambiguous alternative; + e.g. many cities are named San José and Georgetown, so + prefer '<code>Costa_Rica</code>' to '<code>San_Jose</code>' and '<code>Guyana</code>' to '<code>Georgetown</code>'. + </li> + <li> + Keep locations compact. Use cities or small islands, not countries + or regions, so that any future time zone changes do not split + locations into different time zones. E.g. prefer + '<code>Paris</code>' to '<code>France</code>', since + France has had multiple time zones. + </li> + <li> + Use mainstream English spelling, e.g. prefer + '<code>Rome</code>' to '<code>Roma</code>', and prefer + '<code>Athens</code>' to the Greek + '<code>Αθήνα</code>' or the Romanized + '<code>Athína</code>'. + The POSIX file name restrictions encourage this rule. + </li> + <li> + Use the most populous among locations in a zone, + e.g. prefer '<code>Shanghai</code>' to + '<code>Beijing</code>'. Among locations with + similar populations, pick the best-known location, + e.g. prefer '<code>Rome</code>' to '<code>Milan</code>'. + </li> + <li> + Use the singular form, e.g. prefer '<code>Canary</code>' to '<code>Canaries</code>'. + </li> + <li> + Omit common suffixes like '<code>_Islands</code>' and + '<code>_City</code>', unless that would lead to + ambiguity. E.g. prefer '<code>Cayman</code>' to + '<code>Cayman_Islands</code>' and + '<code>Guatemala</code>' to + '<code>Guatemala_City</code>', but prefer + '<code>Mexico_City</code>' to '<code>Mexico</code>' + because the country + of Mexico has several time zones. + </li> + <li> + Use '<code>_</code>' to represent a space. + </li> + <li> + Omit '<code>.</code>' from abbreviations in names, e.g. prefer + '<code>St_Helena</code>' to '<code>St._Helena</code>'. + </li> + <li> + Do not change established names if they only marginally + violate the above rules. For example, don't change + the existing name '<code>Rome</code>' to + '<code>Milan</code>' merely because + Milan's population has grown to be somewhat greater + than Rome's. + </li> + <li> + If a name is changed, put its old spelling in the + '<code>backward</code>' file. + This means old spellings will continue to work. + </li> +</ul> + +<p> +The file '<code>zone1970.tab</code>' lists geographical locations used +to name time +zone rules. It is intended to be an exhaustive list of names for +geographic regions as described above; this is a subset of the names +in the data. Although a '<code>zone1970.tab</code>' location's longitude +corresponds to its LMT offset with one hour for every 15 degrees east +longitude, this relationship is not exact. +</p> + +<p> +Older versions of this package used a different naming scheme, +and these older names are still supported. +See the file '<code>backward</code>' for most of these older names +(e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>'). +The other old-fashioned names still supported are +'<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and '<code>EET</code>' (see the file '<code>europe</code>'). +</p> + +<p> +Older versions of this package defined legacy names that are +incompatible with the first rule of location names, but which are +still supported. These legacy names are mostly defined in the file +'<code>etcetera</code>'. Also, the file '<code>backward</code>' defines the legacy names +'<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', and the file '<code>northamerica</code>' defines the +legacy names '<code>EST5EDT</code>', '<code>CST6CDT</code>', '<code>MST7MDT</code>', and '<code>PST8PDT</code>'. +</p> + +<p> +Excluding '<code>backward</code>' should not affect the other data. If +'<code>backward</code>' is excluded, excluding '<code>etcetera</code>' should not affect the +remaining data. +</p> + + + </section> + <section> + <h2 id="abbreviations">Time zone abbreviations</h2> +<p> +When this package is installed, it generates time zone abbreviations +like '<code>EST</code>' to be compatible with human tradition and POSIX. +Here are the general rules used for choosing time zone abbreviations, +in decreasing order of importance: +<ul> + <li> + Use three or more characters that are ASCII alphanumerics or + '<code>+</code>' or '<code>-</code>'. + Previous editions of this database also used characters like + '<code> </code>' and '<code>?</code>', but these + characters have a special meaning to + the shell and cause commands like + '<code>set `date`</code>' + to have unexpected effects. + Previous editions of this rule required upper-case letters, + but the Congressman who introduced Chamorro Standard Time + preferred "ChST", so lower-case letters are now allowed. + Also, POSIX from 2001 on relaxed the rule to allow + '<code>-</code>', '<code>+</code>', + and alphanumeric characters from the portable character set + in the current locale. In practice ASCII alphanumerics and + '<code>+</code>' and '<code>-</code>' are safe in all locales. + + In other words, in the C locale the POSIX extended regular + expression <code>[-+[:alnum:]]{3,}</code> should match + the abbreviation. + This guarantees that all abbreviations could have been + specified by a POSIX TZ string. + </li> + <li> + Use abbreviations that are in common use among English-speakers, + e.g. 'EST' for Eastern Standard Time in North America. + We assume that applications translate them to other languages + as part of the normal localization process; for example, + a French application might translate 'EST' to 'HNE'. + </li> + <li> + For zones whose times are taken from a city's longitude, use the + traditional <var>x</var>MT notation, e.g. 'PMT' for + Paris Mean Time. + The only name like this in current use is 'GMT'. + </li> + <li> + Use 'LMT' for local mean time of locations before the introduction + of standard time; see "<a href="#scope">Scope of the + tz database</a>". + </li> + <li> + If there is no common English abbreviation, use numeric offsets like + <code>-</code>05 and <code>+</code>0830 that are + generated by zic's <code>%z</code> notation. + </li> + <li> + Use current abbreviations for older timestamps to avoid confusion. + For example, in 1910 a common English abbreviation for UT +01 + in central Europe was 'MEZ' (short for both "Middle European + Zone" and for "Mitteleuropäische Zeit" in German). Nowadays + 'CET' ("Central European Time") is more common in English, and + the database uses 'CET' even for circa-1910 timestamps as this + is less confusing for modern users and avoids the need for + determining when 'CET' supplanted 'MEZ' in common usage. + </li> + <li> + Use a consistent style in a zone's history. For example, if a zone's + history tends to use numeric abbreviations and a particular + entry could go either way, use a numeric abbreviation. + </li> +</ul> + [The remaining guidelines predate the introduction of <code>%z</code>. + They are problematic as they mean tz data entries invent + notation rather than record it. These guidelines are now + deprecated and the plan is to gradually move to <code>%z</code> for + inhabited locations and to "<code>-</code>00" for uninhabited locations.] +<ul> + <li> + If there is no common English abbreviation, abbreviate the English + translation of the usual phrase used by native speakers. + If this is not available or is a phrase mentioning the country + (e.g. "Cape Verde Time"), then: + <ul> + <li> + When a country is identified with a single or principal zone, + append 'T' to the country's ISO code, e.g. 'CVT' for + Cape Verde Time. For summer time append 'ST'; + for double summer time append 'DST'; etc. + </li> + <li> + Otherwise, take the first three letters of an English place + name identifying each zone and append 'T', 'ST', etc. + as before; e.g. 'CHAST' for CHAtham Summer Time. + </li> + </ul> + </li> + <li> + Use UT (with time zone abbreviation '<code>-</code>00') for + locations while uninhabited. The leading + '<code>-</code>' is a flag that the time + zone is in some sense undefined; this notation is + derived from Internet RFC 3339. + </li> +</ul> +<p> +Application writers should note that these abbreviations are ambiguous +in practice: e.g. 'CST' has a different meaning in China than +it does in the United States. In new applications, it's often better +to use numeric UT offsets like '<code>-</code>0600' instead of time zone +abbreviations like 'CST'; this avoids the ambiguity. +</p> + </section> + + + <section> + <h2 id="accuracy">Accuracy of the tz database</h2> +<p> +The tz database is not authoritative, and it surely has errors. +Corrections are welcome and encouraged; see the file CONTRIBUTING. +Users requiring authoritative data should consult national standards +bodies and the references cited in the database's comments. +</p> + +<p> +Errors in the tz database arise from many sources: +</p> +<ul> + <li> + The tz database predicts future timestamps, and current predictions + will be incorrect after future governments change the rules. + For example, if today someone schedules a meeting for 13:00 next + October 1, Casablanca time, and tomorrow Morocco changes its + daylight saving rules, software can mess up after the rule change + if it blithely relies on conversions made before the change. + </li> + <li> + The pre-1970 entries in this database cover only a tiny sliver of how + clocks actually behaved; the vast majority of the necessary + information was lost or never recorded. Thousands more zones would + be needed if the tz database's scope were extended to cover even + just the known or guessed history of standard time; for example, + the current single entry for France would need to split into dozens + of entries, perhaps hundreds. And in most of the world even this + approach would be misleading due to widespread disagreement or + indifference about what times should be observed. In her 2015 book + <cite>The Global Transformation of Time, 1870-1950</cite>, Vanessa Ogle writes + "Outside of Europe and North America there was no system of time + zones at all, often not even a stable landscape of mean times, + prior to the middle decades of the twentieth century". See: + Timothy Shenk, <a + href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked: + A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. + </li> + <li> + Most of the pre-1970 data entries come from unreliable sources, often + astrology books that lack citations and whose compilers evidently + invented entries when the true facts were unknown, without + reporting which entries were known and which were invented. + These books often contradict each other or give implausible entries, + and on the rare occasions when they are checked they are + typically found to be incorrect. + </li> + <li> + For the UK the tz database relies on years of first-class work done by + Joseph Myers and others; see + "<a href="https://www.polyomino.org.uk/british-time/">History of + legal time in Britain</a>". + Other countries are not done nearly as well. + </li> + <li> + Sometimes, different people in the same city would maintain clocks + that differed significantly. Railway time was used by railroad + companies (which did not always agree with each other), + church-clock time was used for birth certificates, etc. + Often this was merely common practice, but sometimes it was set by law. + For example, from 1891 to 1911 the UT offset in France was legally + 0:09:21 outside train stations and 0:04:21 inside. + </li> + <li> + Although a named location in the tz database stands for the + containing region, its pre-1970 data entries are often accurate for + only a small subset of that region. For example, <code>Europe/London</code> + stands for the United Kingdom, but its pre-1847 times are valid + only for locations that have London's exact meridian, and its 1847 + transition to GMT is known to be valid only for the L&NW and the + Caledonian railways. + </li> + <li> + The tz database does not record the earliest time for which a zone's + data entries are thereafter valid for every location in the region. + For example, <code>Europe/London</code> is valid for all locations in its + region after GMT was made the standard time, but the date of + standardization (1880-08-02) is not in the tz database, other than + in commentary. For many zones the earliest time of validity is + unknown. + </li> + <li> + The tz database does not record a region's boundaries, and in many + cases the boundaries are not known. For example, the zone + <code>America/Kentucky/Louisville</code> represents a region around + the city of + Louisville, the boundaries of which are unclear. + </li> + <li> + Changes that are modeled as instantaneous transitions in the tz + database were often spread out over hours, days, or even decades. + </li> + <li> + Even if the time is specified by law, locations sometimes + deliberately flout the law. + </li> + <li> + Early timekeeping practices, even assuming perfect clocks, were + often not specified to the accuracy that the tz database requires. + </li> + <li> + Sometimes historical timekeeping was specified more precisely + than what the tz database can handle. For example, from 1909 to + 1937 Netherlands clocks were legally UT +00:19:32.13, but the tz + database cannot represent the fractional second. + </li> + <li> + Even when all the timestamp transitions recorded by the tz database + are correct, the tz rules that generate them may not faithfully + reflect the historical rules. For example, from 1922 until World + War II the UK moved clocks forward the day following the third + Saturday in April unless that was Easter, in which case it moved + clocks forward the previous Sunday. Because the tz database has no + way to specify Easter, these exceptional years are entered as + separate tz Rule lines, even though the legal rules did not change. + </li> + <li> + The tz database models pre-standard time using the proleptic Gregorian + calendar and local mean time (LMT), but many people used other + calendars and other timescales. For example, the Roman Empire used + the Julian calendar, and had 12 varying-length daytime hours with a + non-hour-based system at night. + </li> + <li> + Early clocks were less reliable, and data entries do not represent + clock error. + </li> + <li> + The tz database assumes Universal Time (UT) as an origin, even + though UT is not standardized for older timestamps. In the tz + database commentary, UT denotes a family of time standards that + includes Coordinated Universal Time (UTC) along with other variants + such as UT1 and GMT, with days starting at midnight. Although UT + equals UTC for modern timestamps, UTC was not defined until 1960, + so commentary uses the more-general abbreviation UT for timestamps + that might predate 1960. Since UT, UT1, etc. disagree slightly, + and since pre-1972 UTC seconds varied in length, interpretation of + older timestamps can be problematic when subsecond accuracy is + needed. + </li> + <li> + Civil time was not based on atomic time before 1972, and we don't + know the history of earth's rotation accurately enough to map SI + seconds to historical solar time to more than about one-hour + accuracy. See: Stephenson FR, Morrison LV, Hohenkerk CY. + <a href="http://dx.doi.org/10.1098/rspa.2016.0404">Measurement + of the Earth's rotation: 720 BC to AD 2015</a>. + <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404. + Also see: Espenak F. <a + href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty + in Delta T (ΔT)</a>. + </li> + <li> + The relationship between POSIX time (that is, UTC but ignoring leap + seconds) and UTC is not agreed upon after 1972. Although the POSIX + clock officially stops during an inserted leap second, at least one + proposed standard has it jumping back a second instead; and in + practice POSIX clocks more typically either progress glacially during + a leap second, or are slightly slowed while near a leap second. + </li> + <li> + The tz database does not represent how uncertain its information is. + Ideally it would contain information about when data entries are + incomplete or dicey. Partial temporal knowledge is a field of + active research, though, and it's not clear how to apply it here. + </li> +</ul> +<p> +In short, many, perhaps most, of the tz database's pre-1970 and future +timestamps are either wrong or misleading. Any attempt to pass the +tz database off as the definition of time should be unacceptable to +anybody who cares about the facts. In particular, the tz database's +LMT offsets should not be considered meaningful, and should not prompt +creation of zones merely because two locations differ in LMT or +transitioned to standard time at different dates. +</p> + </section> + + + <section> + <h2 id="functions">Time and date functions</h2> +<p> +The tz code contains time and date functions that are upwards +compatible with those of POSIX. +</p> + +<p> +POSIX has the following properties and limitations. +</p> +<ul> + <li> + <p> + In POSIX, time display in a process is controlled by the + environment variable TZ. Unfortunately, the POSIX TZ string takes + a form that is hard to describe and is error-prone in practice. + Also, POSIX TZ strings can't deal with other (for example, Israeli) + daylight saving time rules, or situations where more than two + time zone abbreviations are used in an area. + </p> + <p> + The POSIX TZ string takes the following form: + </p> + <p> + <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>]]] + </p> + <p> + where: + <dl> + <dt><var>std</var> and <var>dst</var></dt><dd> + are 3 or more characters specifying the standard + and daylight saving time (DST) zone names. + Starting with POSIX.1-2001, <var>std</var> + and <var>dst</var> may also be + in a quoted form like '<code><UTC+10></code>'; this allows + "<code>+</code>" and "<code>-</code>" in the names. + </dd> + <dt><var>offset</var></dt><dd> + is of the form + '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' + and specifies the offset west of UT. '<var>hh</var>' + may be a single digit; 0≤<var>hh</var>≤24. + The default DST offset is one hour ahead of standard time. + </dd> + <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> + specifies the beginning and end of DST. If this is absent, + the system supplies its own rules for DST, and these can + differ from year to year; typically US DST rules are used. + </dd> + <dt><var>time</var></dt><dd> + takes the form + '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]' + and defaults to 02:00. + This is the same format as the offset, except that a + leading '<code>+</code>' or '<code>-</code>' is not allowed. + </dd> + <dt><var>date</var></dt><dd> + takes one of the following forms: + <dl> + <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> + origin-1 day number not counting February 29 + </dd> + <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> + origin-0 day number counting February 29 if present + </dd> + <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> + for the <var>d</var>th day of + week <var>n</var> of month <var>m</var> of the + year, where week 1 is the first week in which + day <var>d</var> appears, and '<code>5</code>' + stands for the last week in which + day <var>d</var> appears + (which may be either the 4th or 5th week). + Typically, this is the only useful form; + the <var>n</var> + and <code>J</code><var>n</var> forms are + rarely used. + </dd> +</dl> +</dd> +</dl> + Here is an example POSIX TZ string for New Zealand after 2007. + It says that standard time (NZST) is 12 hours ahead of UTC, + and that daylight saving time (NZDT) is observed from September's + last Sunday at 02:00 until April's first Sunday at 03:00: + + <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> + + This POSIX TZ string is hard to remember, and mishandles some + timestamps before 2008. With this package you can use this + instead: + + <pre><code>TZ='Pacific/Auckland'</code></pre> + </li> + <li> + POSIX does not define the exact meaning of TZ values like + "<code>EST5EDT</code>". + Typically the current US DST rules are used to interpret such values, + but this means that the US DST rules are compiled into each program + that does time conversion. This means that when US time conversion + rules change (as in the United States in 1987), all programs that + do time conversion must be recompiled to ensure proper results. + </li> + <li> + The TZ environment variable is process-global, which makes it hard + to write efficient, thread-safe applications that need access + to multiple time zones. + </li> + <li> + In POSIX, there's no tamper-proof way for a process to learn the + system's best idea of local wall clock. (This is important for + applications that an administrator wants used only at certain + times – + without regard to whether the user has fiddled the TZ environment + variable. While an administrator can "do everything in UTC" to get + around the problem, doing so is inconvenient and precludes handling + daylight saving time shifts - as might be required to limit phone + calls to off-peak hours.) + </li> + <li> + POSIX provides no convenient and efficient way to determine the UT + offset and time zone abbreviation of arbitrary timestamps, + particularly for time zone settings that do not fit into the + POSIX model. + </li> + <li> + POSIX requires that systems ignore leap seconds. + </li> + <li> + The tz code attempts to support all the <code>time_t</code> + implementations allowed by POSIX. The <code>time_t</code> + type represents a nonnegative count of + seconds since 1970-01-01 00:00:00 UTC, ignoring leap seconds. + In practice, <code>time_t</code> is usually a signed 64- or + 32-bit integer; 32-bit signed <code>time_t</code> values stop + working after 2038-01-19 03:14:07 UTC, so + new implementations these days typically use a signed 64-bit integer. + Unsigned 32-bit integers are used on one or two platforms, + and 36-bit and 40-bit integers are also used occasionally. + Although earlier POSIX versions allowed <code>time_t</code> to be a + floating-point type, this was not supported by any practical + systems, and POSIX.1-2013 and the tz code both + require <code>time_t</code> + to be an integer type. + </li> +</ul> +<p> +These are the extensions that have been made to the POSIX functions: +</p> +<ul> + <li> + <p> + The TZ environment variable is used in generating the name of a file + from which time zone information is read (or is interpreted a la + POSIX); TZ is no longer constrained to be a three-letter time zone + name followed by a number of hours and an optional three-letter + daylight time zone name. The daylight saving time rules to be used + for a particular time zone are encoded in the time zone file; + the format of the file allows U.S., Australian, and other rules to be + encoded, and allows for situations where more than two time zone + abbreviations are used. + </p> + <p> + It was recognized that allowing the TZ environment variable to + take on values such as '<code>America/New_York</code>' might + cause "old" programs + (that expect TZ to have a certain form) to operate incorrectly; + consideration was given to using some other environment variable + (for example, TIMEZONE) to hold the string used to generate the + time zone information file name. In the end, however, it was decided + to continue using TZ: it is widely used for time zone purposes; + separately maintaining both TZ and TIMEZONE seemed a nuisance; + and systems where "new" forms of TZ might cause problems can simply + use TZ values such as "<code>EST5EDT</code>" which can be used both by + "new" programs (a la POSIX) and "old" programs (as zone names and + offsets). + </p> +</li> +<li> + The code supports platforms with a UT offset member + in <code>struct tm</code>, + e.g., <code>tm_gmtoff</code>. +</li> +<li> + The code supports platforms with a time zone abbreviation member in + <code>struct tm</code>, e.g., <code>tm_zone</code>. +</li> +<li> + Since the TZ environment variable can now be used to control time + conversion, the <code>daylight</code> + and <code>timezone</code> variables are no longer needed. + (These variables are defined and set by <code>tzset</code>; + however, their values will not be used + by <code>localtime</code>.) +</li> +<li> + Functions <code>tzalloc</code>, <code>tzfree</code>, + <code>localtime_rz</code>, and <code>mktime_z</code> for + more-efficient thread-safe applications that need to use + multiple time zones. The <code>tzalloc</code> + and <code>tzfree</code> functions allocate and free objects of + type <code>timezone_t</code>, and <code>localtime_rz</code> + and <code>mktime_z</code> are like <code>localtime_r</code> + and <code>mktime</code> with an extra + <code>timezone_t</code> argument. The functions were inspired + by NetBSD. +</li> +<li> + A function <code>tzsetwall</code> has been added to arrange + for the system's + best approximation to local wall clock time to be delivered by + subsequent calls to <code>localtime</code>. Source code for portable + applications that "must" run on local wall clock time should call + <code>tzsetwall</code>; if such code is moved to "old" systems that don't + provide tzsetwall, you won't be able to generate an executable program. + (These time zone functions also arrange for local wall clock time to be + used if tzset is called – directly or indirectly – + and there's no TZ + environment variable; portable applications should not, however, rely + on this behavior since it's not the way SVR2 systems behave.) +</li> +<li> + Negative <code>time_t</code> values are supported, on systems + where <code>time_t</code> is signed. +</li> +<li> + These functions can account for leap seconds, thanks to Bradley White. +</li> +</ul> +<p> +Points of interest to folks with other systems: +</p> +<ul> + <li> + Code compatible with this package is already part of many platforms, + including GNU/Linux, Android, the BSDs, Chromium OS, Cygwin, AIX, iOS, + BlackBery 10, macOS, Microsoft Windows, OpenVMS, and Solaris. + On such hosts, the primary use of this package + is to update obsolete time zone rule tables. + To do this, you may need to compile the time zone compiler + '<code>zic</code>' supplied with this package instead of using + the system '<code>zic</code>', since the format + of <code>zic</code>'s input is occasionally extended, and a + platform may still be shipping an older <code>zic</code>. + </li> + <li> + The UNIX Version 7 <code>timezone</code> function is not + present in this package; + it's impossible to reliably map timezone's arguments (a "minutes west + of GMT" value and a "daylight saving time in effect" flag) to a + time zone abbreviation, and we refuse to guess. + Programs that in the past used the timezone function may now examine + <code>localtime(&clock)->tm_zone</code> + (if <code>TM_ZONE</code> is defined) or + <code>tzname[localtime(&clock)->tm_isdst]</code> + (if <code>HAVE_TZNAME</code> is defined) + to learn the correct time zone abbreviation to use. + </li> + <li> + The 4.2BSD <code>gettimeofday</code> function is not used in + this package. + This formerly let users obtain the current UTC offset and DST flag, + but this functionality was removed in later versions of BSD. + </li> + <li> + In SVR2, time conversion fails for near-minimum or near-maximum + <code>time_t</code> values when doing conversions for places + that don't use UT. + This package takes care to do these conversions correctly. + A comment in the source code tells how to get compatibly wrong + results. + </li> +</ul> +<p> +The functions that are conditionally compiled +if <code>STD_INSPIRED</code> is defined +should, at this point, be looked on primarily as food for thought. They are +not in any sense "standard compatible" – some are not, in fact, +specified in <em>any</em> standard. They do, however, represent responses of +various authors to +standardization proposals. +</p> + +<p> +Other time conversion proposals, in particular the one developed by folks at +Hewlett Packard, offer a wider selection of functions that provide capabilities +beyond those provided here. The absence of such functions from this package +is not meant to discourage the development, standardization, or use of such +functions. Rather, their absence reflects the decision to make this package +contain valid extensions to POSIX, to ensure its broad acceptability. If +more powerful time conversion functions can be standardized, so much the +better. +</p> + </section> + + + <section> + <h2 id="stability">Interface stability</h2> +<p> +The tz code and data supply the following interfaces: +</p> +<ul> + <li> + A set of zone names as per "<a href="#naming">Names of time zone + rules</a>" above. + </li> + <li> + Library functions described in "<a href="#functions">Time and date + functions</a>" above. + </li> + <li> + The programs <code>tzselect</code>, <code>zdump</code>, + and <code>zic</code>, documented in their man pages. + </li> + <li> + The format of <code>zic</code> input files, documented in + the <code>zic</code> man page. + </li> + <li> + The format of <code>zic</code> output files, documented in + the <code>tzfile</code> man page. + </li> + <li> + The format of zone table files, documented in <code>zone1970.tab</code>. + </li> + <li> + The format of the country code file, documented in <code>iso3166.tab</code>. + </li> + <li> + The version number of the code and data, as the first line of + the text file '<code>version</code>' in each release. + </li> +</ul> +<p> +Interface changes in a release attempt to preserve compatibility with +recent releases. For example, tz data files typically do not rely on +recently-added <code>zic</code> features, so that users can run +older <code>zic</code> versions to process newer data +files. <a href="tz-link.htm">Sources for time zone and daylight +saving time data</a> describes how +releases are tagged and distributed. +</p> + +<p> +Interfaces not listed above are less stable. For example, users +should not rely on particular UT offsets or abbreviations for +timestamps, as data entries are often based on guesswork and these +guesses may be corrected or improved. +</p> + </section> + + + <section> + <h2 id="calendar">Calendrical issues</h2> +<p> +Calendrical issues are a bit out of scope for a time zone database, +but they indicate the sort of problems that we would run into if we +extended the time zone database further into the past. An excellent +resource in this area is Nachum Dershowitz and Edward M. Reingold, +<cite><a href="https://www.cs.tau.ac.il/~nachum/calendar-book/third-edition/">Calendrical +Calculations: Third Edition</a></cite>, Cambridge University Press (2008). +Other information and sources are given in the file '<samp>calendars</samp>' +in the tz distribution. They sometimes disagree. +</p> + </section> + + + <section> + <h2 id="planets">Time and time zones on other planets</h2> +<p> +Some people's work schedules use Mars time. Jet Propulsion Laboratory +(JPL) coordinators have kept Mars time on and off at least since 1997 +for the Mars Pathfinder mission. Some of their family members have +also adapted to Mars time. Dozens of special Mars watches were built +for JPL workers who kept Mars time during the Mars Exploration +Rovers mission (2004). These timepieces look like normal Seikos and +Citizens but use Mars seconds rather than terrestrial seconds. +</p> + +<p> +A Mars solar day is called a "sol" and has a mean period equal to +about 24 hours 39 minutes 35.244 seconds in terrestrial time. It is +divided into a conventional 24-hour clock, so each Mars second equals +about 1.02749125 terrestrial seconds. +</p> + +<p> +The prime meridian of Mars goes through the center of the crater +Airy-0, named in honor of the British astronomer who built the +Greenwich telescope that defines Earth's prime meridian. Mean solar +time on the Mars prime meridian is called Mars Coordinated Time (MTC). +</p> + +<p> +Each landed mission on Mars has adopted a different reference for +solar time keeping, so there is no real standard for Mars time zones. +For example, the Mars Exploration Rover project (2004) defined two +time zones "Local Solar Time A" and "Local Solar Time B" for its two +missions, each zone designed so that its time equals local true solar +time at approximately the middle of the nominal mission. Such a "time +zone" is not particularly suited for any application other than the +mission itself. +</p> + +<p> +Many calendars have been proposed for Mars, but none have achieved +wide acceptance. Astronomers often use Mars Sol Date (MSD) which is a +sequential count of Mars solar days elapsed since about 1873-12-29 +12:00 GMT. +</p> + +<p> +In our solar system, Mars is the planet with time and calendar most +like Earth's. On other planets, Sun-based time and calendars would +work quite differently. For example, although Mercury's sidereal +rotation period is 58.646 Earth days, Mercury revolves around the Sun +so rapidly that an observer on Mercury's equator would see a sunrise +only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a Mercury +day. Venus is more complicated, partly because its rotation is +slightly retrograde: its year is 1.92 of its days. Gas giants like +Jupiter are trickier still, as their polar and equatorial regions +rotate at different rates, so that the length of a day depends on +latitude. This effect is most pronounced on Neptune, where the day is +about 12 hours at the poles and 18 hours at the equator. +</p> + +<p> +Although the tz database does not support time on other planets, it is +documented here in the hopes that support will be added eventually. +</p> + +<p> +Sources: +</p> +<ul> + <li> +Michael Allison and Robert Schmunk, +"<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical +Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" +(2012-08-08). + </li> + <li> +Jia-Rui Chong, +"<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays +Fit for a Martian</a>", Los Angeles Times +(2004-01-14), pp A1, A20-A21. + </li> + <li> +Tom Chmielewski, +"<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet +Lag Is Worse on Mars</a>", The Atlantic (2015-02-26) + </li> + <li> +Matt Williams, +"<a href="https://www.universetoday.com/37481/days-of-the-planets/">How +long is a day on the other planets of the solar system?</a>" +(2017-04-27). + </li> +</ul> + </section> + + <footer> + <hr> +This file is in the public domain, so clarified as of 2009-05-17 by +Arthur David Olson. + </footer> +</body> +</html> diff --git a/tz-link.htm b/tz-link.htm index 09edf0b..03259d2 100644 --- a/tz-link.htm +++ b/tz-link.htm @@ -214,7 +214,9 @@ Studio Code</a>. For further information about updates, please see <a href="https://tools.ietf.org/html/rfc6557">Procedures for Maintaining the Time Zone Database</a> (Internet <abbr -title="Request For Comments">RFC</abbr> 6557).</p> +title="Request For Comments">RFC</abbr> 6557). More detail can be +found in <a href="theory.html">Theory and pragmatics of the tz code and data</a>. +</p> <h2 id="commentary">Commentary on the <code><abbr>tz</abbr></code> database</h2> <ul> <li>The article @@ -915,6 +917,7 @@ is called "<abbr>GMT</abbr>".</li> </ul> <h2 id="see-also">See also</h2> <ul> +<li><a href="theory.html">Theory and pragmatics of the tz code and data</a></li> <li><a href="tz-art.htm">Time and the Arts</a></li> </ul> <hr> diff --git a/zone1970.tab b/zone1970.tab index 2bcdc64..8b828e6 100644 --- a/zone1970.tab +++ b/zone1970.tab @@ -2,7 +2,7 @@ # # This file is in the public domain. # -# From Paul Eggert (2014-07-31): +# From Paul Eggert (2017-10-01): # This file contains a table where each row stands for a zone where # civil time stamps have agreed since 1970. Columns are separated by # a single tab. Lines beginning with '#' are comments. All text uses @@ -15,7 +15,7 @@ # either +-DDMM+-DDDMM or +-DDMMSS+-DDDMMSS, # first latitude (+ is north), then longitude (+ is east). # 3. Zone name used in value of TZ environment variable. -# Please see the 'Theory' file for how zone names are chosen. +# Please see the theory.html file for how zone names are chosen. # If multiple zones overlap a country, each has a row in the # table, with each column 1 containing the country code. # 4. Comments; present if and only if a country has multiple zones. -- 2.7.4