Branch: Tag:


2017-11-17 18:07:36 by Henrik Grubbström (Grubba) <>

Updated to 2017c.

1: + <!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=""> +  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="">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&rarr;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></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></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="">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="">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&amp;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="">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="">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>&lt;UTC+10&gt;</code>'; this allows +  "<code>+</code>" and "<code>-</code>" in the names. +  </dd> +  <dt><var>offset</var></dt><dd> +  is of the form +  '<code>[&plusmn;]<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&le;<var>hh</var>&le;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&le;<var>n</var>&le;365)</dt><dd> +  origin-1 day number not counting February 29 +  </dd> +  <dt><var>n</var> (0&le;<var>n</var>&le;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]&le;<var>d</var>&le;6[Saturday], 1&le;<var>n</var>&le;5, 1&le;<var>m</var>&le;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 &ndash; +  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 &ndash; directly or indirectly &ndash; +  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(&amp;clock)-&gt;tm_zone</code> +  (if <code>TM_ZONE</code> is defined) or +  <code>tzname[localtime(&amp;clock)-&gt;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" &ndash; 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></code>. +  </li> +  <li> +  The format of the country code file, documented in <code></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="">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="">Technical + Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" + (2012-08-08). +  </li> +  <li> + Jia-Rui Chong, + "<a href="">Workdays + Fit for a Martian</a>", Los Angeles Times + (2004-01-14), pp A1, A20-A21. +  </li> +  <li> + Tom Chmielewski, + "<a href="">Jet + Lag Is Worse on Mars</a>", The Atlantic (2015-02-26) +  </li> +  <li> + Matt Williams, + "<a href="">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>   Newline at end of file added.