libc/time/theory.html

1.4Schristos<!DOCTYPE html>
1.1Schristos<html lang="en">
1.1Schristos<head>
1.1Schristos  <title>Theory and pragmatics of the tz code and data</title>
1.1Schristos  <meta charset="UTF-8">
1.4Schristos  <style>
1.4Schristos    pre {margin-left: 2em; white-space: pre-wrap;}
1.4Schristos  </style>
1.1Schristos</head>
1.1Schristos
1.1Schristos<body>
1.3Schristos<h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>
1.1Schristos  <h3>Outline</h3>
1.1Schristos  <nav>
1.1Schristos    <ul>
1.3Schristos      <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>
1.3Schristos	  database</a></li>
1.7Schristos      <li><a href="#naming">Timezone identifiers</a></li>
1.1Schristos      <li><a href="#abbreviations">Time zone abbreviations</a></li>
1.3Schristos      <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code>
1.3Schristos	  database</a></li>
1.1Schristos      <li><a href="#functions">Time and date functions</a></li>
1.1Schristos      <li><a href="#stability">Interface stability</a></li>
1.9Schristos      <li><a href="#leapsec">Leap seconds</a></li>
1.1Schristos      <li><a href="#calendar">Calendrical issues</a></li>
1.18Schristos      <li><a href="#planets">Time and time zones off earth</a></li>
1.1Schristos    </ul>
1.1Schristos  </nav>
1.1Schristos
1.3Schristos<section>
1.3Schristos  <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>
1.1Schristos<p>
1.3SchristosThe <a
1.3Schristoshref="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code>
1.3Schristosdatabase</a> attempts to record the history and predicted future of
1.10Schristoscivil time scales.
1.3SchristosIt organizes <a href="tz-link.html">time zone and daylight saving time
1.3Schristosdata</a> by partitioning the world into <a
1.4Schristoshref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a>
1.3Schristoswhose clocks all agree about timestamps that occur after the <a
1.3Schristoshref="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a>
1.3Schristos(1970-01-01 00:00:00 <a
1.3Schristoshref="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr
1.3Schristostitle="Coordinated Universal Time">UTC</abbr></a>).
1.3SchristosAlthough 1970 is a somewhat-arbitrary cutoff, there are significant
1.3Schristoschallenges to moving the cutoff earlier even by a decade or two, due
1.3Schristosto the wide variety of local practices before computer timekeeping
1.3Schristosbecame prevalent.
1.12SchristosMost timezones correspond to a notable location and the database
1.12Schristosrecords all known clock transitions for that location;
1.12Schristossome timezones correspond instead to a fixed <abbr>UTC</abbr> offset.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.4SchristosEach timezone typically corresponds to a geographical region that is
1.4Schristossmaller than a traditional time zone, because clocks in a timezone
1.4Schristosall agree after 1970 whereas a traditional time zone merely
1.4Schristosspecifies current standard time. For example, applications that deal
1.4Schristoswith current and future timestamps in the traditional North
1.4SchristosAmerican mountain time zone can choose from the timezones
1.4Schristos<code>America/Denver</code> which observes US-style daylight saving
1.12Schristostime (<abbr>DST</abbr>),
1.12Schristosand <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>.
1.4SchristosApplications that also deal with past timestamps in the mountain time
1.4Schristoszone can choose from over a dozen timezones, such as
1.4Schristos<code>America/Boise</code>, <code>America/Edmonton</code>, and
1.4Schristos<code>America/Hermosillo</code>, each of which currently uses mountain
1.4Schristostime but differs from other timezones for some timestamps after 1970.
1.4Schristos</p>
1.4Schristos
1.4Schristos<p>
1.12SchristosClock transitions before 1970 are recorded for location-based timezones,
1.1Schristosbecause most systems support timestamps before 1970 and could
1.1Schristosmisbehave if data entries were omitted for pre-1970 transitions.
1.1SchristosHowever, the database is not designed for and does not suffice for
1.1Schristosapplications requiring accurate handling of all past times everywhere,
1.1Schristosas it would take far too much effort and guesswork to record all
1.1Schristosdetails of pre-1970 civil timekeeping.
1.3SchristosAlthough some information outside the scope of the database is
1.2Schristoscollected in a file <code>backzone</code> that is distributed along
1.2Schristoswith the database proper, this file is less reliable and does not
1.2Schristosnecessarily follow database guidelines.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.3SchristosAs described below, reference source code for using the
1.3Schristos<code><abbr>tz</abbr></code> database is also available.
1.3SchristosThe <code><abbr>tz</abbr></code> code is upwards compatible with <a
1.3Schristoshref="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international
1.3Schristosstandard for <a
1.3Schristoshref="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems.
1.3SchristosAs of this writing, the current edition of POSIX is: <a
1.8Schristoshref="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open
1.3SchristosGroup Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018
1.3SchristosEdition.
1.3SchristosBecause the database's scope encompasses real-world changes to civil
1.3Schristostimekeeping, its model for describing time is more complex than the
1.3Schristosstandard and daylight saving times supported by POSIX.
1.4SchristosA <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
1.3Schristoshave more than two changes per year, these changes need not merely
1.3Schristosflip back and forth between two alternatives, and the rules themselves
1.3Schristoscan change at times.
1.9SchristosWhether and when a timezone changes its clock,
1.9Schristosand even the timezone's notional base offset from <abbr>UTC</abbr>,
1.9Schristosare variable.
1.4SchristosIt does not always make sense to talk about a timezone's
1.4Schristos"base offset", which is not necessarily a single number.
1.1Schristos</p>
1.1Schristos
1.3Schristos</section>
1.1Schristos
1.3Schristos<section>
1.7Schristos  <h2 id="naming">Timezone identifiers</h2>
1.1Schristos<p>
1.7SchristosEach timezone has a name that uniquely identifies the timezone.
1.1SchristosInexperienced users are not expected to select these names unaided.
1.1SchristosDistributors should provide documentation and/or a simple selection
1.4Schristosinterface that explains each name via a map or via descriptive text like
1.10Schristos"Czech Republic" instead of the timezone name "<code>Europe/Prague</code>".
1.4SchristosIf geolocation information is available, a selection interface can
1.4Schristoslocate the user on a timezone map or prioritize names that are
1.4Schristosgeographically close. For an example selection interface, see the
1.3Schristos<code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.
1.15SchristosThe <a href="https://cldr.unicode.org">Unicode Common Locale Data
1.3SchristosRepository</a> contains data that may be useful for other selection
1.10Schristosinterfaces; it maps timezone names like <code>Europe/Prague</code> to
1.10Schristoslocale-dependent strings like "Prague", "Praha", "Прага", and "布拉格".
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.3SchristosThe naming conventions attempt to strike a balance
1.1Schristosamong the following goals:
1.1Schristos</p>
1.3Schristos
1.1Schristos<ul>
1.1Schristos  <li>
1.4Schristos    Uniquely identify every timezone where clocks have agreed since 1970.
1.3Schristos    This is essential for the intended use: static clocks keeping local
1.3Schristos    civil time.
1.1Schristos  </li>
1.1Schristos  <li>
1.4Schristos    Indicate to experts where the timezone's clocks typically are.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Be robust in the presence of political changes.
1.7Schristos    For example, names are typically not tied to countries, to avoid
1.3Schristos    incompatibilities when countries change their name (e.g.,
1.7Schristos    Swaziland&rarr;Eswatini) or when locations change countries (e.g., Hong
1.3Schristos    Kong from UK colony to China).
1.7Schristos    There is no requirement that every country or national
1.7Schristos    capital must have a timezone name.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Be portable to a wide variety of implementations.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Use a consistent naming conventions over the entire world.
1.1Schristos  </li>
1.1Schristos</ul>
1.3Schristos
1.1Schristos<p>
1.3SchristosNames normally have the form
1.3Schristos<var>AREA</var><code>/</code><var>LOCATION</var>, where
1.4Schristos<var>AREA</var> is a continent or ocean, and
1.4Schristos<var>LOCATION</var> is a specific location within the area.
1.3SchristosNorth and South America share the same area, '<code>America</code>'.
1.3SchristosTypical names are '<code>Africa/Cairo</code>',
1.3Schristos'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
1.3SchristosSome names are further qualified to help avoid confusion; for example,
1.3Schristos'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
1.3SchristosIndiana from other Petersburgs in America.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.3SchristosHere are the general guidelines used for
1.4Schristoschoosing timezone names,
1.1Schristosin decreasing order of importance:
1.1Schristos</p>
1.3Schristos
1.1Schristos<ul>
1.1Schristos  <li>
1.3Schristos    Use only valid POSIX file name components (i.e., the parts of
1.3Schristos    names other than '<code>/</code>').
1.3Schristos    Do not use the file name components '<code>.</code>' and
1.3Schristos    '<code>..</code>'.
1.3Schristos    Within a file name component, use only <a
1.3Schristos    href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters,
1.3Schristos    '<code>.</code>', '<code>-</code>' and '<code>_</code>'.
1.3Schristos    Do not use digits, as that might create an ambiguity with <a
1.8Schristos    href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX
1.3Schristos    <code>TZ</code> strings</a>.
1.3Schristos    A file name component must not exceed 14 characters or start with
1.3Schristos    '<code>-</code>'.
1.12Schristos    E.g., prefer <code>America/Noronha</code> to
1.12Schristos    <code>America/Fernando_de_Noronha</code>.
1.3Schristos    Exceptions: see the discussion of legacy names below.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    A name must not be empty, or contain '<code>//</code>', or
1.3Schristos    start or end with '<code>/</code>'.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Do not use names that differ only in case.
1.3Schristos    Although the reference implementation is case-sensitive, some
1.3Schristos    other implementations are not, and they would mishandle names
1.3Schristos    differing only in case.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    If one name <var>A</var> is an initial prefix of another
1.3Schristos    name <var>AB</var> (ignoring case), then <var>B</var> must not
1.3Schristos    start with '<code>/</code>', as a regular file cannot have the
1.3Schristos    same name as a directory in POSIX.
1.3Schristos    For example, <code>America/New_York</code> precludes
1.3Schristos    <code>America/New_York/Bronx</code>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Uninhabited regions like the North Pole and Bouvet Island
1.3Schristos    do not need locations, since local time is not defined there.
1.1Schristos  </li>
1.1Schristos  <li>
1.4Schristos    If all the clocks in a timezone have agreed since 1970,
1.4Schristos    do not bother to include more than one timezone
1.4Schristos    even if some of the clocks disagreed before 1970.
1.3Schristos    Otherwise these tables would become annoyingly large.
1.1Schristos  </li>
1.1Schristos  <li>
1.7Schristos    If boundaries between regions are fluid, such as during a war or
1.7Schristos    insurrection, do not bother to create a new timezone merely
1.7Schristos    because of yet another boundary change. This helps prevent table
1.7Schristos    bloat and simplifies maintenance.
1.7Schristos  </li>
1.7Schristos  <li>
1.3Schristos    If a name is ambiguous, use a less ambiguous alternative;
1.3Schristos    e.g., many cities are named San José and Georgetown, so
1.3Schristos    prefer <code>America/Costa_Rica</code> to
1.3Schristos    <code>America/San_Jose</code> and <code>America/Guyana</code>
1.3Schristos    to <code>America/Georgetown</code>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Keep locations compact.
1.3Schristos    Use cities or small islands, not countries or regions, so that any
1.3Schristos    future changes do not split individual locations into different
1.4Schristos    timezones.
1.3Schristos    E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
1.3Schristos    since
1.3Schristos    <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France
1.3Schristos    has had multiple time zones</a>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Use mainstream English spelling, e.g., prefer
1.4Schristos    <code>Europe/Rome</code> to <code>Europa/Roma</code>, and
1.3Schristos    prefer <code>Europe/Athens</code> to the Greek
1.4Schristos    <code>Ευρώπη/Αθήνα</code> or the Romanized
1.4Schristos    <code>Evrópi/Athína</code>.
1.3Schristos    The POSIX file name restrictions encourage this guideline.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Use the most populous among locations in a region,
1.3Schristos    e.g., prefer <code>Asia/Shanghai</code> to
1.3Schristos    <code>Asia/Beijing</code>.
1.3Schristos    Among locations with similar populations, pick the best-known
1.3Schristos    location, e.g., prefer <code>Europe/Rome</code> to
1.3Schristos    <code>Europe/Milan</code>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
1.3Schristos    <code>Atlantic/Canaries</code>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Omit common suffixes like '<code>_Islands</code>' and
1.3Schristos    '<code>_City</code>', unless that would lead to ambiguity.
1.3Schristos    E.g., prefer <code>America/Cayman</code> to
1.3Schristos    <code>America/Cayman_Islands</code> and
1.3Schristos    <code>America/Guatemala</code> to
1.3Schristos    <code>America/Guatemala_City</code>, but prefer
1.3Schristos    <code>America/Mexico_City</code> to
1.3Schristos    <code>America/Mexico</code>
1.3Schristos    because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the
1.3Schristos    country of Mexico has several time zones</a>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Use '<code>_</code>' to represent a space.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Omit '<code>.</code>' from abbreviations in names.
1.3Schristos    E.g., prefer <code>Atlantic/St_Helena</code> to
1.3Schristos    <code>Atlantic/St._Helena</code>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Do not change established names if they only marginally violate
1.3Schristos    the above guidelines.
1.3Schristos    For example, do not change the existing name <code>Europe/Rome</code> to
1.3Schristos    <code>Europe/Milan</code> merely because Milan's population has grown
1.3Schristos    to be somewhat greater than Rome's.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    If a name is changed, put its old spelling in the
1.13Schristos    '<code>backward</code>' file as a link to the new spelling.
1.3Schristos    This means old spellings will continue to work.
1.9Schristos    Ordinarily a name change should occur only in the rare case when
1.9Schristos    a location's consensus English-language spelling changes; for example,
1.9Schristos    in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code>
1.9Schristos    due to long-time widespread use of the new city name instead of the old.
1.1Schristos  </li>
1.1Schristos</ul>
1.1Schristos
1.1Schristos<p>
1.7SchristosGuidelines have evolved with time, and names following old versions of
1.8Schristosthese guidelines might not follow the current version. When guidelines
1.7Schristoshave changed, old names continue to be supported. Guideline changes
1.7Schristoshave included the following:
1.1Schristos</p>
1.1Schristos
1.7Schristos<ul>
1.7Schristos<li>
1.7SchristosOlder versions of this package used a different naming scheme.
1.1SchristosSee the file '<code>backward</code>' for most of these older names
1.1Schristos(e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>').
1.1SchristosThe other old-fashioned names still supported are
1.3Schristos'<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and
1.3Schristos'<code>EET</code>' (see the file '<code>europe</code>').
1.7Schristos</li>
1.1Schristos
1.7Schristos<li>
1.1SchristosOlder versions of this package defined legacy names that are
1.3Schristosincompatible with the first guideline of location names, but which are
1.3Schristosstill supported.
1.3SchristosThese legacy names are mostly defined in the file
1.3Schristos'<code>etcetera</code>'.
1.3SchristosAlso, the file '<code>backward</code>' defines the legacy names
1.16Schristos'<code>Etc/GMT0</code>', '<code>Etc/GMT-0</code>', '<code>Etc/GMT+0</code>',
1.3Schristos'<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>',
1.3Schristosand the file '<code>northamerica</code>' defines the legacy names
1.3Schristos'<code>EST5EDT</code>', '<code>CST6CDT</code>',
1.3Schristos'<code>MST7MDT</code>', and '<code>PST8PDT</code>'.
1.7Schristos</li>
1.7Schristos
1.7Schristos<li>
1.8SchristosOlder versions of these guidelines said that
1.7Schristosthere should typically be at least one name for each <a
1.7Schristoshref="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr
1.7Schristostitle="International Organization for Standardization">ISO</abbr>
1.7Schristos3166-1</a> officially assigned two-letter code for an inhabited
1.7Schristoscountry or territory.
1.7SchristosThis old guideline has been dropped, as it was not needed to handle
1.7Schristostimestamps correctly and it increased maintenance burden.
1.7Schristos</li>
1.7Schristos</ul>
1.7Schristos
1.7Schristos<p>
1.13SchristosThe file <code>zone1970.tab</code> lists geographical locations used
1.7Schristosto name timezones.
1.7SchristosIt is intended to be an exhaustive list of names for geographic
1.7Schristosregions as described above; this is a subset of the timezones in the data.
1.13SchristosAlthough a <code>zone1970.tab</code> location's
1.7Schristos<a href="https://en.wikipedia.org/wiki/Longitude">longitude</a>
1.7Schristoscorresponds to
1.7Schristosits <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean
1.7Schristostime (<abbr>LMT</abbr>)</a> offset with one hour for every 15&deg;
1.7Schristoseast longitude, this relationship is not exact.
1.13SchristosThe backward-compatibility file <code>zone.tab</code> is similar
1.13Schristosbut conforms to the older-version guidelines related to <abbr>ISO</abbr> 3166-1;
1.13Schristosit lists only one country code per entry and unlike <code>zone1970.tab</code>
1.13Schristosit can list names defined in <code>backward</code>.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.13SchristosThe database defines each timezone name to be a zone, or a link to a zone.
1.13SchristosThe source file <code>backward</code> defines links for backward
1.13Schristoscompatibility; it does not define zones.
1.13SchristosAlthough <code>backward</code> was originally designed to be optional,
1.13Schristosnowadays distributions typically use it
1.13Schristosand no great weight should be attached to whether a link
1.13Schristosis defined in <code>backward</code> or in some other file.
1.13SchristosThe source file <code>etcetera</code> defines names that may be useful
1.13Schristoson platforms that do not support POSIX-style <code>TZ</code> strings;
1.13Schristosno other source file other than <code>backward</code>
1.13Schristoscontains links to its zones.
1.14SchristosOne of <code>etcetera</code>'s names is <code>Etc/UTC</code>,
1.13Schristosused by functions like <code>gmtime</code> to obtain leap
1.13Schristossecond information on platforms that support leap seconds.
1.14SchristosAnother <code>etcetera</code> name, <code>GMT</code>,
1.14Schristosis used by older code releases.
1.1Schristos</p>
1.3Schristos</section>
1.1Schristos
1.3Schristos<section>
1.3Schristos  <h2 id="abbreviations">Time zone abbreviations</h2>
1.1Schristos<p>
1.1SchristosWhen this package is installed, it generates time zone abbreviations
1.1Schristoslike '<code>EST</code>' to be compatible with human tradition and POSIX.
1.3SchristosHere are the general guidelines used for choosing time zone abbreviations,
1.1Schristosin decreasing order of importance:
1.3Schristos</p>
1.3Schristos
1.1Schristos<ul>
1.1Schristos  <li>
1.3Schristos    Use three to six characters that are ASCII alphanumerics or
1.3Schristos    '<code>+</code>' or '<code>-</code>'.
1.3Schristos    Previous editions of this database also used characters like
1.3Schristos    space and '<code>?</code>', but these characters have a
1.3Schristos    special meaning to the
1.3Schristos    <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a>
1.3Schristos    and cause commands like
1.8Schristos    '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a>
1.8Schristos    `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>'
1.3Schristos    to have unexpected effects.
1.3Schristos    Previous editions of this guideline required upper-case letters, but the
1.3Schristos    Congressman who introduced
1.3Schristos    <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro
1.3Schristos    Standard Time</a> preferred "ChST", so lower-case letters are now
1.3Schristos    allowed.
1.3Schristos    Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>',
1.3Schristos    '<code>+</code>', and alphanumeric characters from the portable
1.3Schristos    character set in the current locale.
1.3Schristos    In practice ASCII alphanumerics and '<code>+</code>' and
1.3Schristos    '<code>-</code>' are safe in all locales.
1.3Schristos
1.3Schristos    <p>
1.3Schristos    In other words, in the C locale the POSIX extended regular
1.3Schristos    expression <code>[-+[:alnum:]]{3,6}</code> should match the
1.3Schristos    abbreviation.
1.3Schristos    This guarantees that all abbreviations could have been specified by a
1.3Schristos    POSIX <code>TZ</code> string.
1.3Schristos    </p>
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Use abbreviations that are in common use among English-speakers,
1.3Schristos    e.g., 'EST' for Eastern Standard Time in North America.
1.3Schristos    We assume that applications translate them to other languages
1.3Schristos    as part of the normal localization process; for example,
1.3Schristos    a French application might translate 'EST' to 'HNE'.
1.3Schristos
1.3Schristos    <p>
1.3Schristos    <small>These abbreviations (for standard/daylight/etc. time) are:
1.3Schristos      ACST/ACDT Australian Central,
1.3Schristos      AST/ADT/APT/AWT/ADDT Atlantic,
1.3Schristos      AEST/AEDT Australian Eastern,
1.3Schristos      AHST/AHDT Alaska-Hawaii,
1.3Schristos      AKST/AKDT Alaska,
1.3Schristos      AWST/AWDT Australian Western,
1.3Schristos      BST/BDT Bering,
1.3Schristos      CAT/CAST Central Africa,
1.3Schristos      CET/CEST/CEMT Central European,
1.3Schristos      ChST Chamorro,
1.18Schristos      CST/CDT/CWT/CPT Central [North America],
1.3Schristos      CST/CDT China,
1.3Schristos      GMT/BST/IST/BDST Greenwich,
1.3Schristos      EAT East Africa,
1.18Schristos      EST/EDT/EWT/EPT Eastern [North America],
1.3Schristos      EET/EEST Eastern European,
1.6Schristos      GST/GDT Guam,
1.5Schristos      HST/HDT/HWT/HPT Hawaii,
1.9Schristos      HKT/HKST/HKWT Hong Kong,
1.3Schristos      IST India,
1.3Schristos      IST/GMT Irish,
1.3Schristos      IST/IDT/IDDT Israel,
1.3Schristos      JST/JDT Japan,
1.3Schristos      KST/KDT Korea,
1.3Schristos      MET/MEST Middle European (a backward-compatibility alias for
1.3Schristos	Central European),
1.3Schristos      MSK/MSD Moscow,
1.18Schristos      MST/MDT/MWT/MPT Mountain,
1.3Schristos      NST/NDT/NWT/NPT/NDDT Newfoundland,
1.3Schristos      NST/NDT/NWT/NPT Nome,
1.3Schristos      NZMT/NZST New Zealand through 1945,
1.3Schristos      NZST/NZDT New Zealand 1946&ndash;present,
1.3Schristos      PKT/PKST Pakistan,
1.18Schristos      PST/PDT/PWT/PPT Pacific,
1.4Schristos      PST/PDT Philippine,
1.3Schristos      SAST South Africa,
1.3Schristos      SST Samoa,
1.14Schristos      UTC Universal,
1.3Schristos      WAT/WAST West Africa,
1.3Schristos      WET/WEST/WEMT Western European,
1.3Schristos      WIB Waktu Indonesia Barat,
1.3Schristos      WIT Waktu Indonesia Timur,
1.3Schristos      WITA Waktu Indonesia Tengah,
1.3Schristos      YST/YDT/YWT/YPT/YDDT Yukon</small>.
1.3Schristos    </p>
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    <p>
1.3Schristos    For times taken from a city's longitude, use the
1.3Schristos    traditional <var>x</var>MT notation.
1.3Schristos    The only abbreviation like this in current use is '<abbr>GMT</abbr>'.
1.3Schristos    The others are for timestamps before 1960,
1.3Schristos    except that Monrovia Mean Time persisted until 1972.
1.3Schristos    Typically, numeric abbreviations (e.g., '<code>-</code>004430' for
1.3Schristos    MMT) would cause trouble here, as the numeric strings would exceed
1.3Schristos    the POSIX length limit.
1.3Schristos    </p>
1.3Schristos
1.3Schristos    <p>
1.3Schristos    <small>These abbreviations are:
1.12Schristos      AMT Asunción, Athens;
1.18Schristos      BMT Baghdad, Bangkok, Batavia, Bermuda, Bern, Bogotá,
1.11Schristos        Brussels, Bucharest;
1.12Schristos      CMT Calamarca, Caracas, Chisinau, Colón, Córdoba;
1.3Schristos      DMT Dublin/Dunsink;
1.3Schristos      EMT Easter;
1.3Schristos      FFMT Fort-de-France;
1.3Schristos      FMT Funchal;
1.3Schristos      GMT Greenwich;
1.3Schristos      HMT Havana, Helsinki, Horta, Howrah;
1.3Schristos      IMT Irkutsk, Istanbul;
1.3Schristos      JMT Jerusalem;
1.14Schristos      KMT Kaunas, Kyiv, Kingston;
1.18Schristos      LMT Lima, Lisbon, local;
1.3Schristos      MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo,
1.3Schristos	Moratuwa, Moscow;
1.3Schristos      PLMT Phù Liễn;
1.3Schristos      PMT Paramaribo, Paris, Perm, Pontianak, Prague;
1.3Schristos      PMMT Port Moresby;
1.18Schristos      PPMT Port-au-Prince;
1.3Schristos      QMT Quito;
1.3Schristos      RMT Rangoon, Riga, Rome;
1.3Schristos      SDMT Santo Domingo;
1.3Schristos      SJMT San José;
1.3Schristos      SMT Santiago, Simferopol, Singapore, Stanley;
1.3Schristos      TBMT Tbilisi;
1.3Schristos      TMT Tallinn, Tehran;
1.18Schristos      WMT Warsaw.</small>
1.3Schristos    </p>
1.3Schristos
1.3Schristos    <p>
1.3Schristos    <small>A few abbreviations also follow the pattern that
1.4Schristos    <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK.
1.3Schristos    They are:
1.11Schristos      BMT/BST for Bermuda 1890&ndash;1930,
1.3Schristos      CMT/BST for Calamarca Mean Time and Bolivian Summer Time
1.3Schristos	1890&ndash;1932,
1.3Schristos      DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time
1.3Schristos	1880&ndash;1916,
1.3Schristos      MMT/MST/MDST for Moscow 1880&ndash;1919, and
1.3Schristos      RMT/LST for Riga Mean Time and Latvian Summer time 1880&ndash;1926.
1.12Schristos    </small>
1.3Schristos    </p>
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Use '<abbr>LMT</abbr>' for local mean time of locations before the
1.3Schristos    introduction of standard time; see "<a href="#scope">Scope of the
1.3Schristos    <code><abbr>tz</abbr></code> database</a>".
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    If there is no common English abbreviation, use numeric offsets like
1.4Schristos    <code>-</code>05 and <code>+</code>0530 that are generated
1.3Schristos    by <code>zic</code>'s <code>%z</code> notation.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Use current abbreviations for older timestamps to avoid confusion.
1.3Schristos    For example, in 1910 a common English abbreviation for time
1.3Schristos    in central Europe was 'MEZ' (short for both "Middle European
1.3Schristos    Zone" and for "Mitteleuropäische Zeit" in German).
1.3Schristos    Nowadays 'CET' ("Central European Time") is more common in
1.3Schristos    English, and the database uses 'CET' even for circa-1910
1.3Schristos    timestamps as this is less confusing for modern users and avoids
1.3Schristos    the need for determining when 'CET' supplanted 'MEZ' in common
1.3Schristos    usage.
1.3Schristos  </li>
1.3Schristos  <li>
1.4Schristos    Use a consistent style in a timezone's history.
1.4Schristos    For example, if a history tends to use numeric
1.3Schristos    abbreviations and a particular entry could go either way, use a
1.3Schristos    numeric abbreviation.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Use
1.3Schristos    <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a>
1.3Schristos    (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
1.3Schristos    locations while uninhabited.
1.3Schristos    The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
1.3Schristos    some sense undefined; this notation is derived
1.15Schristos    from <a href="https://datatracker.ietf.org/doc/html/rfc3339">Internet
1.4Schristos    <abbr title="Request For Comments">RFC</abbr> 3339</a>.
1.1Schristos  </li>
1.1Schristos</ul>
1.3Schristos
1.1Schristos<p>
1.1SchristosApplication writers should note that these abbreviations are ambiguous
1.2Schristosin practice: e.g., 'CST' means one thing in China and something else
1.2Schristosin North America, and 'IST' can refer to time in India, Ireland or
1.3SchristosIsrael.
1.3SchristosTo avoid ambiguity, use numeric <abbr>UT</abbr> offsets like
1.2Schristos'<code>-</code>0600' instead of time zone abbreviations like 'CST'.
1.1Schristos</p>
1.3Schristos</section>
1.1Schristos
1.3Schristos<section>
1.3Schristos  <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
1.1Schristos<p>
1.3SchristosThe <code><abbr>tz</abbr></code> database is not authoritative, and it
1.3Schristossurely has errors.
1.2SchristosCorrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
1.1SchristosUsers requiring authoritative data should consult national standards
1.1Schristosbodies and the references cited in the database's comments.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.3SchristosErrors in the <code><abbr>tz</abbr></code> database arise from many sources:
1.1Schristos</p>
1.3Schristos
1.1Schristos<ul>
1.1Schristos  <li>
1.3Schristos    The <code><abbr>tz</abbr></code> database predicts future
1.3Schristos    timestamps, and current predictions
1.3Schristos    will be incorrect after future governments change the rules.
1.3Schristos    For example, if today someone schedules a meeting for 13:00 next
1.3Schristos    October 1, Casablanca time, and tomorrow Morocco changes its
1.3Schristos    daylight saving rules, software can mess up after the rule change
1.3Schristos    if it blithely relies on conversions made before the change.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The pre-1970 entries in this database cover only a tiny sliver of how
1.3Schristos    clocks actually behaved; the vast majority of the necessary
1.3Schristos    information was lost or never recorded.
1.4Schristos    Thousands more timezones would be needed if
1.3Schristos    the <code><abbr>tz</abbr></code> database's scope were extended to
1.3Schristos    cover even just the known or guessed history of standard time; for
1.3Schristos    example, the current single entry for France would need to split
1.3Schristos    into dozens of entries, perhaps hundreds.
1.3Schristos    And in most of the world even this approach would be misleading
1.3Schristos    due to widespread disagreement or indifference about what times
1.3Schristos    should be observed.
1.3Schristos    In her 2015 book
1.3Schristos    <cite><a
1.15Schristos    href="https://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The
1.3Schristos    Global Transformation of Time, 1870&ndash;1950</a></cite>,
1.3Schristos    Vanessa Ogle writes
1.3Schristos    "Outside of Europe and North America there was no system of time
1.3Schristos    zones at all, often not even a stable landscape of mean times,
1.3Schristos    prior to the middle decades of the twentieth century".
1.3Schristos    See: Timothy Shenk, <a
1.3Schristoshref="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked:
1.3Schristos      A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Most of the pre-1970 data entries come from unreliable sources, often
1.3Schristos    astrology books that lack citations and whose compilers evidently
1.3Schristos    invented entries when the true facts were unknown, without
1.3Schristos    reporting which entries were known and which were invented.
1.3Schristos    These books often contradict each other or give implausible entries,
1.3Schristos    and on the rare occasions when they are checked they are
1.3Schristos    typically found to be incorrect.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    For the UK the <code><abbr>tz</abbr></code> database relies on
1.3Schristos    years of first-class work done by
1.3Schristos    Joseph Myers and others; see
1.3Schristos    "<a href="https://www.polyomino.org.uk/british-time/">History of
1.3Schristos    legal time in Britain</a>".
1.3Schristos    Other countries are not done nearly as well.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Sometimes, different people in the same city maintain clocks
1.3Schristos    that differ significantly.
1.3Schristos    Historically, railway time was used by railroad companies (which
1.3Schristos    did not always
1.3Schristos    agree with each other), church-clock time was used for birth
1.3Schristos    certificates, etc.
1.3Schristos    More recently, competing political groups might disagree about
1.3Schristos    clock settings. Often this is merely common practice, but
1.3Schristos    sometimes it is set by law.
1.3Schristos    For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France
1.3Schristos    was legally <abbr>UT</abbr> +00:09:21 outside train stations and
1.3Schristos    <abbr>UT</abbr> +00:04:21 inside. Other examples include
1.3Schristos    Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and
1.3Schristos    Ürümqi to this day.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Although a named location in the <code><abbr>tz</abbr></code>
1.3Schristos    database stands for the containing region, its pre-1970 data
1.3Schristos    entries are often accurate for only a small subset of that region.
1.3Schristos    For example, <code>Europe/London</code> stands for the United
1.3Schristos    Kingdom, but its pre-1847 times are valid only for locations that
1.3Schristos    have London's exact meridian, and its 1847 transition
1.3Schristos    to <abbr>GMT</abbr> is known to be valid only for the L&amp;NW and
1.3Schristos    the Caledonian railways.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The <code><abbr>tz</abbr></code> database does not record the
1.4Schristos    earliest time for which a timezone's
1.3Schristos    data entries are thereafter valid for every location in the region.
1.3Schristos    For example, <code>Europe/London</code> is valid for all locations
1.3Schristos    in its region after <abbr>GMT</abbr> was made the standard time,
1.3Schristos    but the date of standardization (1880-08-02) is not in the
1.3Schristos    <code><abbr>tz</abbr></code> database, other than in commentary.
1.4Schristos    For many timezones the earliest time of
1.3Schristos    validity is unknown.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The <code><abbr>tz</abbr></code> database does not record a
1.3Schristos    region's boundaries, and in many cases the boundaries are not known.
1.4Schristos    For example, the timezone
1.3Schristos    <code>America/Kentucky/Louisville</code> represents a region
1.3Schristos    around the city of Louisville, the boundaries of which are
1.3Schristos    unclear.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Changes that are modeled as instantaneous transitions in the
1.3Schristos    <code><abbr>tz</abbr></code>
1.3Schristos    database were often spread out over hours, days, or even decades.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Even if the time is specified by law, locations sometimes
1.3Schristos    deliberately flout the law.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Early timekeeping practices, even assuming perfect clocks, were
1.3Schristos    often not specified to the accuracy that the
1.3Schristos    <code><abbr>tz</abbr></code> database requires.
1.3Schristos  </li>
1.3Schristos  <li>
1.10Schristos    The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
1.10Schristos    However, on 1911-03-11 at 00:00, some public-facing French clocks
1.10Schristos    were changed by stopping them for a few minutes to effect a transition.
1.10Schristos    The <code><abbr>tz</abbr></code> database models this via a
1.10Schristos    backward transition; the relevant French legislation does not
1.10Schristos    specify exactly how the transition was to occur.
1.10Schristos  </li>
1.10Schristos  <li>
1.3Schristos    Sometimes historical timekeeping was specified more precisely
1.3Schristos    than what the <code><abbr>tz</abbr></code> code can handle.
1.12Schristos    For example, from 1880 to 1916 clocks in Ireland observed Dublin Mean
1.3Schristos    Time (estimated to be <abbr>UT</abbr>
1.14Schristos    &minus;00:25:21.1); although the <code><abbr>tz</abbr></code>
1.14Schristos    source data can represent the .1 second, TZif files and the code cannot.
1.3Schristos    In practice these old specifications were rarely if ever
1.3Schristos    implemented to subsecond precision.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Even when all the timestamp transitions recorded by the
1.3Schristos    <code><abbr>tz</abbr></code> database are correct, the
1.3Schristos    <code><abbr>tz</abbr></code> rules that generate them may not
1.3Schristos    faithfully reflect the historical rules.
1.3Schristos    For example, from 1922 until World War II the UK moved clocks
1.3Schristos    forward the day following the third Saturday in April unless that
1.3Schristos    was Easter, in which case it moved clocks forward the previous
1.3Schristos    Sunday.
1.3Schristos    Because the <code><abbr>tz</abbr></code> database has no
1.3Schristos    way to specify Easter, these exceptional years are entered as
1.3Schristos    separate <code><abbr>tz</abbr> Rule</code> lines, even though the
1.3Schristos    legal rules did not change.
1.4Schristos    When transitions are known but the historical rules behind them are not,
1.4Schristos    the database contains <code>Zone</code> and <code>Rule</code>
1.4Schristos    entries that are intended to represent only the generated
1.4Schristos    transitions, not any underlying historical rules; however, this
1.4Schristos    intent is recorded at best only in commentary.
1.3Schristos  </li>
1.3Schristos  <li>
1.4Schristos    The <code><abbr>tz</abbr></code> database models time
1.3Schristos    using the <a
1.3Schristos    href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic
1.4Schristos    Gregorian calendar</a> with days containing 24 equal-length hours
1.4Schristos    numbered 00 through 23, except when clock transitions occur.
1.4Schristos    Pre-standard time is modeled as local mean time.
1.4Schristos    However, historically many people used other calendars and other timescales.
1.3Schristos    For example, the Roman Empire used
1.3Schristos    the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian
1.3Schristos    calendar</a>,
1.3Schristos    and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman
1.3Schristos    timekeeping</a> had twelve varying-length daytime hours with a
1.3Schristos    non-hour-based system at night.
1.4Schristos    And even today, some local practices diverge from the Gregorian
1.4Schristos    calendar with 24-hour days. These divergences range from
1.4Schristos    relatively minor, such as Japanese bars giving times like "24:30" for the
1.4Schristos    wee hours of the morning, to more-significant differences such as <a
1.4Schristos    href="https://www.pri.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the
1.4Schristos    east African practice of starting the day at dawn</a>, renumbering
1.4Schristos    the Western 06:00 to be 12:00. These practices are largely outside
1.4Schristos    the scope of the <code><abbr>tz</abbr></code> code and data, which
1.4Schristos    provide only limited support for date and time localization
1.12Schristos    such as that required by POSIX.
1.12Schristos    If <abbr>DST</abbr> is not used a different time zone
1.4Schristos    can often do the trick; for example, in Kenya a <code>TZ</code> setting
1.4Schristos    like <code>&lt;-03&gt;3</code> or <code>America/Cayenne</code> starts
1.4Schristos    the day six hours later than <code>Africa/Nairobi</code> does.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Early clocks were less reliable, and data entries do not represent
1.3Schristos    clock error.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The <code><abbr>tz</abbr></code> database assumes Universal Time
1.3Schristos    (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not
1.3Schristos    standardized for older timestamps.
1.3Schristos    In the <code><abbr>tz</abbr></code> database commentary,
1.3Schristos    <abbr>UT</abbr> denotes a family of time standards that includes
1.3Schristos    Coordinated Universal Time (<abbr>UTC</abbr>) along with other
1.3Schristos    variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>,
1.3Schristos    with days starting at midnight.
1.3Schristos    Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern
1.3Schristos    timestamps, <abbr>UTC</abbr> was not defined until 1960, so
1.18Schristos    commentary uses the more general abbreviation <abbr>UT</abbr> for
1.3Schristos    timestamps that might predate 1960.
1.3Schristos    Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly,
1.3Schristos    and since pre-1972 <abbr>UTC</abbr> seconds varied in length,
1.3Schristos    interpretation of older timestamps can be problematic when
1.3Schristos    subsecond accuracy is needed.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Civil time was not based on atomic time before 1972, and we do not
1.3Schristos    know the history of
1.3Schristos    <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's
1.3Schristos    rotation</a> accurately enough to map <a
1.3Schristos    href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr
1.3Schristos    title="International System of Units">SI</abbr></a> seconds to
1.3Schristos    historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a>
1.3Schristos    to more than about one-hour accuracy.
1.3Schristos    See: Stephenson FR, Morrison LV, Hohenkerk CY.
1.4Schristos    <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of
1.3Schristos    the Earth's rotation: 720 BC to AD 2015</a>.
1.15Schristos    <cite>Proc Royal Soc A</cite>. 2016;472:20160404.
1.3Schristos    Also see: Espenak F. <a
1.3Schristos    href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty
1.3Schristos    in Delta T (ΔT)</a>.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The relationship between POSIX time (that is, <abbr>UTC</abbr> but
1.3Schristos    ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap
1.18Schristos    seconds</a>) and <abbr>UTC</abbr> is not agreed upon.
1.18Schristos    This affects time stamps during the leap second era (1972&ndash;2035).
1.3Schristos    Although the POSIX
1.3Schristos    clock officially stops during an inserted leap second, at least one
1.3Schristos    proposed standard has it jumping back a second instead; and in
1.3Schristos    practice POSIX clocks more typically either progress glacially during
1.3Schristos    a leap second, or are slightly slowed while near a leap second.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The <code><abbr>tz</abbr></code> database does not represent how
1.3Schristos    uncertain its information is.
1.3Schristos    Ideally it would contain information about when data entries are
1.3Schristos    incomplete or dicey.
1.3Schristos    Partial temporal knowledge is a field of active research, though,
1.3Schristos    and it is not clear how to apply it here.
1.1Schristos  </li>
1.1Schristos</ul>
1.1Schristos
1.1Schristos<p>
1.3SchristosIn short, many, perhaps most, of the <code><abbr>tz</abbr></code>
1.3Schristosdatabase's pre-1970 and future timestamps are either wrong or
1.3Schristosmisleading.
1.3SchristosAny attempt to pass the
1.3Schristos<code><abbr>tz</abbr></code> database off as the definition of time
1.3Schristosshould be unacceptable to anybody who cares about the facts.
1.3SchristosIn particular, the <code><abbr>tz</abbr></code> database's
1.3Schristos<abbr>LMT</abbr> offsets should not be considered meaningful, and
1.4Schristosshould not prompt creation of timezones
1.3Schristosmerely because two locations
1.3Schristosdiffer in <abbr>LMT</abbr> or transitioned to standard time at
1.3Schristosdifferent dates.
1.3Schristos</p>
1.3Schristos</section>
1.3Schristos
1.3Schristos<section>
1.3Schristos  <h2 id="functions">Time and date functions</h2>
1.3Schristos<p>
1.3SchristosThe <code><abbr>tz</abbr></code> code contains time and date functions
1.3Schristosthat are upwards compatible with those of POSIX.
1.3SchristosCode compatible with this package is already
1.3Schristos<a href="tz-link.html#tzdb">part of many platforms</a>, where the
1.3Schristosprimary use of this package is to update obsolete time-related files.
1.3SchristosTo do this, you may need to compile the time zone compiler
1.3Schristos'<code>zic</code>' supplied with this package instead of using the
1.3Schristossystem '<code>zic</code>', since the format of <code>zic</code>'s
1.3Schristosinput is occasionally extended, and a platform may still be shipping
1.3Schristosan older <code>zic</code>.
1.1Schristos</p>
1.1Schristos
1.3Schristos<h3 id="POSIX">POSIX properties and limitations</h3>
1.1Schristos<ul>
1.1Schristos  <li>
1.1Schristos    <p>
1.3Schristos    In POSIX, time display in a process is controlled by the
1.3Schristos    environment variable <code>TZ</code>.
1.3Schristos    Unfortunately, the POSIX
1.3Schristos    <code>TZ</code> string takes a form that is hard to describe and
1.3Schristos    is error-prone in practice.
1.3Schristos    Also, POSIX <code>TZ</code> strings cannot deal with daylight
1.3Schristos    saving time rules not based on the Gregorian calendar (as in
1.18Schristos    Morocco), or with situations where more than two time zone
1.3Schristos    abbreviations or <abbr>UT</abbr> offsets are used in an area.
1.1Schristos    </p>
1.3Schristos
1.1Schristos    <p>
1.3Schristos    The POSIX <code>TZ</code> string takes the following form:
1.1Schristos    </p>
1.3Schristos
1.1Schristos    <p>
1.3Schristos    <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>]]]
1.1Schristos    </p>
1.3Schristos
1.1Schristos    <p>
1.3Schristos    where:
1.3Schristos    </p>
1.3Schristos
1.1Schristos    <dl>
1.1Schristos      <dt><var>std</var> and <var>dst</var></dt><dd>
1.3Schristos	are 3 or more characters specifying the standard
1.4Schristos	and daylight saving time (<abbr>DST</abbr>) zone abbreviations.
1.3Schristos	Starting with POSIX.1-2001, <var>std</var> and <var>dst</var>
1.3Schristos	may also be in a quoted form like '<code>&lt;+09&gt;</code>';
1.3Schristos	this allows "<code>+</code>" and "<code>-</code>" in the names.
1.1Schristos      </dd>
1.1Schristos      <dt><var>offset</var></dt><dd>
1.3Schristos	is of the form
1.3Schristos	'<code>[&plusmn;]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>'
1.3Schristos	and specifies the offset west of <abbr>UT</abbr>.
1.3Schristos	'<var>hh</var>' may be a single digit;
1.3Schristos	0&le;<var>hh</var>&le;24.
1.3Schristos	The default <abbr>DST</abbr> offset is one hour ahead of
1.3Schristos	standard time.
1.1Schristos      </dd>
1.1Schristos      <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
1.3Schristos	specifies the beginning and end of <abbr>DST</abbr>.
1.3Schristos	If this is absent, the system supplies its own ruleset
1.18Schristos	for <abbr>DST</abbr>, typically	current <abbr>US</abbr>
1.18Schristos	<abbr>DST</abbr> rules.
1.1Schristos      </dd>
1.1Schristos      <dt><var>time</var></dt><dd>
1.3Schristos	takes the form
1.3Schristos	'<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
1.3Schristos	and defaults to 02:00.
1.3Schristos	This is the same format as the offset, except that a
1.3Schristos	leading '<code>+</code>' or '<code>-</code>' is not allowed.
1.1Schristos      </dd>
1.1Schristos      <dt><var>date</var></dt><dd>
1.3Schristos	takes one of the following forms:
1.1Schristos	<dl>
1.1Schristos	  <dt>J<var>n</var> (1&le;<var>n</var>&le;365)</dt><dd>
1.3Schristos	    origin-1 day number not counting February 29
1.3Schristos	  </dd>
1.1Schristos	  <dt><var>n</var> (0&le;<var>n</var>&le;365)</dt><dd>
1.3Schristos	    origin-0 day number counting February 29 if present
1.3Schristos	  </dd>
1.3Schristos	  <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
1.3Schristos	    (0[Sunday]&le;<var>d</var>&le;6[Saturday], 1&le;<var>n</var>&le;5,
1.3Schristos	    1&le;<var>m</var>&le;12)</dt><dd>
1.3Schristos	    for the <var>d</var>th day of week <var>n</var> of
1.3Schristos	    month <var>m</var> of the year, where week 1 is the first
1.3Schristos	    week in which day <var>d</var> appears, and
1.3Schristos	    '<code>5</code>' stands for the last week in which
1.3Schristos	    day <var>d</var> appears (which may be either the 4th or
1.3Schristos	    5th week).
1.3Schristos	    Typically, this is the only useful form; the <var>n</var>
1.3Schristos	    and <code>J</code><var>n</var> forms are rarely used.
1.1Schristos	  </dd>
1.3Schristos	</dl>
1.3Schristos      </dd>
1.3Schristos    </dl>
1.3Schristos
1.3Schristos    <p>
1.3Schristos    Here is an example POSIX <code>TZ</code> string for New
1.3Schristos    Zealand after 2007.
1.3Schristos    It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead
1.3Schristos    of <abbr>UT</abbr>, and that daylight saving time
1.3Schristos    (<abbr>NZDT</abbr>) is observed from September's last Sunday at
1.3Schristos    02:00 until April's first Sunday at 03:00:
1.3Schristos    </p>
1.3Schristos
1.3Schristos    <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
1.3Schristos
1.3Schristos    <p>
1.3Schristos    This POSIX <code>TZ</code> string is hard to remember, and
1.3Schristos    mishandles some timestamps before 2008.
1.3Schristos    With this package you can use this instead:
1.3Schristos    </p>
1.3Schristos
1.3Schristos    <pre><code>TZ='Pacific/Auckland'</code></pre>
1.3Schristos  </li>
1.3Schristos  <li>
1.4Schristos    POSIX does not define the <abbr>DST</abbr> transitions
1.4Schristos    for <code>TZ</code> values like
1.3Schristos    "<code>EST5EDT</code>".
1.4Schristos    Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
1.4Schristos    were used to interpret such values, but this meant that the
1.4Schristos    <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
1.18Schristos    time conversion package, and when
1.4Schristos    <abbr>US</abbr> time conversion rules changed (as in the United
1.18Schristos    States in 1987 and again in 2007), all packages that
1.18Schristos    interpreted <code>TZ</code> values had to be updated
1.18Schristos    to ensure proper results.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The <code>TZ</code> environment variable is process-global, which
1.3Schristos    makes it hard to write efficient, thread-safe applications that
1.4Schristos    need access to multiple timezones.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    In POSIX, there is no tamper-proof way for a process to learn the
1.8Schristos    system's best idea of local (wall clock) time.
1.4Schristos    This is important for applications that an administrator wants
1.3Schristos    used only at certain times &ndash; without regard to whether the
1.3Schristos    user has fiddled the
1.3Schristos    <code>TZ</code> environment variable.
1.3Schristos    While an administrator can "do everything in <abbr>UT</abbr>" to
1.3Schristos    get around the problem, doing so is inconvenient and precludes
1.4Schristos    handling daylight saving time shifts &ndash; as might be required to
1.4Schristos    limit phone calls to off-peak hours.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    POSIX provides no convenient and efficient way to determine
1.3Schristos    the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary
1.4Schristos    timestamps, particularly for timezones
1.3Schristos    that do not fit into the POSIX model.
1.3Schristos  </li>
1.3Schristos  <li>
1.9Schristos    POSIX requires that <code>time_t</code> clock counts exclude leap
1.9Schristos    seconds.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The <code><abbr>tz</abbr></code> code attempts to support all the
1.3Schristos    <code>time_t</code> implementations allowed by POSIX.
1.3Schristos    The <code>time_t</code> type represents a nonnegative count of seconds
1.3Schristos    since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds.
1.3Schristos    In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1.3Schristos    integer; 32-bit signed <code>time_t</code> values stop working after
1.3Schristos    2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these
1.3Schristos    days typically use a signed 64-bit integer.
1.3Schristos    Unsigned 32-bit integers are used on one or two platforms, and 36-bit
1.3Schristos    and 40-bit integers are also used occasionally.
1.3Schristos    Although earlier POSIX versions allowed <code>time_t</code> to be a
1.4Schristos    floating-point type, this was not supported by any practical system,
1.3Schristos    and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both
1.3Schristos    require <code>time_t</code> to be an integer type.
1.1Schristos  </li>
1.1Schristos</ul>
1.3Schristos
1.3Schristos<h3 id="POSIX-extensions">Extensions to POSIX in the
1.3Schristos<code><abbr>tz</abbr></code> code</h3>
1.1Schristos<ul>
1.1Schristos  <li>
1.1Schristos    <p>
1.3Schristos    The <code>TZ</code> environment variable is used in generating
1.4Schristos    the name of a file from which time-related information is read
1.3Schristos    (or is interpreted à la POSIX); <code>TZ</code> is no longer
1.4Schristos    constrained to be a string containing abbreviations
1.4Schristos    and numeric data as described <a href="#POSIX">above</a>.
1.4Schristos    The file's format is <dfn><abbr>TZif</abbr></dfn>,
1.7Schristos    a timezone information format that contains binary data; see
1.15Schristos    <a href="https://datatracker.ietf.org/doc/html/8536">Internet
1.7Schristos    <abbr>RFC</abbr> 8536</a>.
1.3Schristos    The daylight saving time rules to be used for a
1.4Schristos    particular timezone are encoded in the
1.4Schristos    <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
1.4Schristos    Australian, and other rules to be encoded, and
1.3Schristos    allows for situations where more than two time zone
1.3Schristos    abbreviations are used.
1.1Schristos    </p>
1.1Schristos    <p>
1.3Schristos    It was recognized that allowing the <code>TZ</code> environment
1.3Schristos    variable to take on values such as '<code>America/New_York</code>'
1.3Schristos    might cause "old" programs (that expect <code>TZ</code> to have a
1.3Schristos    certain form) to operate incorrectly; consideration was given to using
1.3Schristos    some other environment variable (for example, <code>TIMEZONE</code>)
1.4Schristos    to hold the string used to generate the <abbr>TZif</abbr> file's name.
1.3Schristos    In the end, however, it was decided to continue using
1.3Schristos    <code>TZ</code>: it is widely used for time zone purposes;
1.3Schristos    separately maintaining both <code>TZ</code>
1.3Schristos    and <code>TIMEZONE</code> seemed a nuisance; and systems where
1.3Schristos    "new" forms of <code>TZ</code> might cause problems can simply
1.4Schristos    use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1.4Schristos    can be used by "new" programs as well as by "old" programs that
1.4Schristos    assume pre-POSIX <code>TZ</code> values.
1.1Schristos    </p>
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The code supports platforms with a <abbr>UT</abbr> offset member
1.15Schristos    in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>,
1.15Schristos    or with a time zone abbreviation member in
1.15Schristos    <code>struct tm</code>, e.g., <code>tm_zone</code>. As noted
1.15Schristos    in <a href="https://austingroupbugs.net/view.php?id=1533">Austin
1.15Schristos    Group defect 1533</a>, a future version of POSIX is planned to
1.15Schristos    require <code>tm_gmtoff</code> and <code>tm_zone</code>.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Functions <code>tzalloc</code>, <code>tzfree</code>,
1.3Schristos    <code>localtime_rz</code>, and <code>mktime_z</code> for
1.3Schristos    more-efficient thread-safe applications that need to use multiple
1.4Schristos    timezones.
1.3Schristos    The <code>tzalloc</code> and <code>tzfree</code> functions
1.3Schristos    allocate and free objects of type <code>timezone_t</code>,
1.3Schristos    and <code>localtime_rz</code> and <code>mktime_z</code> are
1.3Schristos    like <code>localtime_r</code> and <code>mktime</code> with an
1.3Schristos    extra <code>timezone_t</code> argument.
1.3Schristos    The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    Negative <code>time_t</code> values are supported, on systems
1.3Schristos    where <code>time_t</code> is signed.
1.3Schristos  </li>
1.3Schristos  <li>
1.9Schristos    These functions can account for leap seconds;
1.9Schristos    see <a href="#leapsec">Leap seconds</a> below.
1.3Schristos  </li>
1.1Schristos</ul>
1.3Schristos
1.3Schristos<h3 id="vestigial">POSIX features no longer needed</h3>
1.1Schristos<p>
1.3SchristosPOSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a>
1.3Schristosdefine some <a href="https://en.wikipedia.org/wiki/API"><abbr
1.3Schristostitle="application programming interface">API</abbr>s</a> that are vestigial:
1.3Schristosthey are not needed, and are relics of a too-simple model that does
1.3Schristosnot suffice to handle many real-world timestamps.
1.3SchristosAlthough the <code><abbr>tz</abbr></code> code supports these
1.3Schristosvestigial <abbr>API</abbr>s for backwards compatibility, they should
1.3Schristosbe avoided in portable applications.
1.3SchristosThe vestigial <abbr>API</abbr>s are:
1.1Schristos</p>
1.1Schristos<ul>
1.1Schristos  <li>
1.3Schristos    The POSIX <code>tzname</code> variable does not suffice and is no
1.3Schristos    longer needed.
1.3Schristos    To get a timestamp's time zone abbreviation, consult
1.3Schristos    the <code>tm_zone</code> member if available; otherwise,
1.3Schristos    use <code>strftime</code>'s <code>"%Z"</code> conversion
1.3Schristos    specification.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The POSIX <code>daylight</code> and <code>timezone</code>
1.3Schristos    variables do not suffice and are no longer needed.
1.3Schristos    To get a timestamp's <abbr>UT</abbr> offset, consult
1.3Schristos    the <code>tm_gmtoff</code> member if available; otherwise,
1.3Schristos    subtract values returned by <code>localtime</code>
1.3Schristos    and <code>gmtime</code> using the rules of the Gregorian calendar,
1.3Schristos    or use <code>strftime</code>'s <code>"%z"</code> conversion
1.3Schristos    specification if a string like <code>"+0900"</code> suffices.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The <code>tm_isdst</code> member is almost never needed and most of
1.3Schristos    its uses should be discouraged in favor of the abovementioned
1.3Schristos    <abbr>API</abbr>s.
1.3Schristos    Although it can still be used in arguments to
1.3Schristos    <code>mktime</code> to disambiguate timestamps near
1.15Schristos    a <abbr>DST</abbr> transition when the clock jumps back on
1.15Schristos    platforms lacking <code>tm_gmtoff</code>, this
1.3Schristos    disambiguation does not work when standard time itself jumps back,
1.3Schristos    which can occur when a location changes to a time zone with a
1.3Schristos    lesser <abbr>UT</abbr> offset.
1.3Schristos  </li>
1.3Schristos</ul>
1.3Schristos
1.3Schristos<h3 id="other-portability">Other portability notes</h3>
1.3Schristos<ul>
1.3Schristos  <li>
1.3Schristos    The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition
1.3Schristos    UNIX</a> <code>timezone</code> function is not present in this
1.3Schristos    package; it is impossible to reliably map <code>timezone</code>'s
1.3Schristos    arguments (a "minutes west of <abbr>GMT</abbr>" value and a
1.3Schristos    "daylight saving time in effect" flag) to a time zone
1.3Schristos    abbreviation, and we refuse to guess.
1.3Schristos    Programs that in the past used the <code>timezone</code> function
1.3Schristos    may now examine <code>localtime(&amp;clock)-&gt;tm_zone</code>
1.3Schristos    (if <code>TM_ZONE</code> is defined) or
1.3Schristos    <code>tzname[localtime(&amp;clock)-&gt;tm_isdst]</code>
1.9Schristos    (if <code>HAVE_TZNAME</code> is nonzero) to learn the correct time
1.3Schristos    zone abbreviation to use.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The <a
1.3Schristos    href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a>
1.3Schristos    <code>gettimeofday</code> function is not
1.3Schristos    used in this package.
1.3Schristos    This formerly let users obtain the current <abbr>UTC</abbr> offset
1.3Schristos    and <abbr>DST</abbr> flag, but this functionality was removed in
1.3Schristos    later versions of <abbr>BSD</abbr>.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    In <abbr>SVR2</abbr>, time conversion fails for near-minimum or
1.3Schristos    near-maximum <code>time_t</code> values when doing conversions
1.3Schristos    for places that do not use <abbr>UT</abbr>.
1.3Schristos    This package takes care to do these conversions correctly.
1.3Schristos    A comment in the source code tells how to get compatibly wrong
1.3Schristos    results.
1.3Schristos  </li>
1.3Schristos  <li>
1.3Schristos    The functions that are conditionally compiled
1.18Schristos    if <code>STD_INSPIRED</code> is nonzero should, at this point, be
1.3Schristos    looked on primarily as food for thought.
1.3Schristos    They are not in any sense "standard compatible" &ndash; some are
1.3Schristos    not, in fact, specified in <em>any</em> standard.
1.3Schristos    They do, however, represent responses of various authors to
1.3Schristos    standardization proposals.
1.3Schristos  </li>
1.3Schristos  <li>
1.4Schristos    Other time conversion proposals, in particular those supported by the
1.4Schristos    <a href="https://howardhinnant.github.io/date/tz.html">Time Zone
1.4Schristos    Database Parser</a>, offer a wider selection of functions
1.3Schristos    that provide capabilities beyond those provided here.
1.3Schristos    The absence of such functions from this package is not meant to
1.3Schristos    discourage the development, standardization, or use of such
1.3Schristos    functions.
1.3Schristos    Rather, their absence reflects the decision to make this package
1.3Schristos    contain valid extensions to POSIX, to ensure its broad
1.3Schristos    acceptability.
1.3Schristos    If more powerful time conversion functions can be standardized, so
1.3Schristos    much the better.
1.1Schristos  </li>
1.1Schristos</ul>
1.3Schristos</section>
1.1Schristos
1.3Schristos<section>
1.3Schristos  <h2 id="stability">Interface stability</h2>
1.1Schristos<p>
1.3SchristosThe <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1.1Schristos</p>
1.1Schristos
1.1Schristos<ul>
1.1Schristos  <li>
1.4Schristos    A set of timezone names as per
1.7Schristos      "<a href="#naming">Timezone identifiers</a>" above.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Library functions described in "<a href="#functions">Time and date
1.3Schristos      functions</a>" above.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    The programs <code>tzselect</code>, <code>zdump</code>,
1.3Schristos    and <code>zic</code>, documented in their man pages.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    The format of <code>zic</code> input files, documented in
1.3Schristos    the <code>zic</code> man page.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    The format of <code>zic</code> output files, documented in
1.3Schristos    the <code>tzfile</code> man page.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    The format of zone table files, documented in <code>zone1970.tab</code>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    The format of the country code file, documented in <code>iso3166.tab</code>.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    The version number of the code and data, as the first line of
1.3Schristos    the text file '<code>version</code>' in each release.
1.1Schristos  </li>
1.1Schristos</ul>
1.3Schristos
1.1Schristos<p>
1.1SchristosInterface changes in a release attempt to preserve compatibility with
1.3Schristosrecent releases.
1.3SchristosFor example, <code><abbr>tz</abbr></code> data files typically do not
1.18Schristosrely on recently added <code>zic</code> features, so that users can
1.3Schristosrun older <code>zic</code> versions to process newer data files.
1.3Schristos<a href="tz-link.html#download">Downloading
1.3Schristosthe <code><abbr>tz</abbr></code> database</a> describes how releases
1.3Schristosare tagged and distributed.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.3SchristosInterfaces not listed above are less stable.
1.3SchristosFor example, users should not rely on particular <abbr>UT</abbr>
1.3Schristosoffsets or abbreviations for timestamps, as data entries are often
1.3Schristosbased on guesswork and these guesses may be corrected or improved.
1.1Schristos</p>
1.7Schristos
1.7Schristos<p>
1.7SchristosTimezone boundaries are not part of the stable interface.
1.7SchristosFor example, even though the <samp>Asia/Bangkok</samp> timezone
1.7Schristoscurrently includes Chang Mai, Hanoi, and Phnom Penh, this is not part
1.7Schristosof the stable interface and the timezone can split at any time.
1.7SchristosIf a calendar application records a future event in some location other
1.7Schristosthan Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record,
1.7Schristosthe application should be robust in the presence of timezone splits
1.7Schristosbetween now and the future time.
1.7Schristos</p>
1.3Schristos</section>
1.1Schristos
1.3Schristos<section>
1.9Schristos  <h2 id="leapsec">Leap seconds</h2>
1.9Schristos<p>
1.18SchristosLeap seconds were introduced in 1972 to accommodate the
1.18Schristosdifference between atomic time and the less regular rotation of the earth.
1.18SchristosUnfortunately they caused so many problems with civil
1.18Schristostimekeeping that they
1.18Schristosare <a href="https://www.bipm.org/en/cgpm-2022/resolution-4">planned
1.18Schristosto be discontinued by 2035</a>, with some as-yet-undetermined
1.18Schristosmechanism replacing them, perhaps after the year 2135.
1.18SchristosDespite their impending obsolescence, a record of leap seconds is still
1.18Schristosneeded to resolve timestamps from 1972 through 2035.
1.18Schristos</p>
1.18Schristos
1.18Schristos<p>
1.9SchristosThe <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1.9Schristosthanks to code contributed by Bradley White.
1.9SchristosHowever, the leap second support of this package is rarely used directly
1.9Schristosbecause POSIX requires leap seconds to be excluded and many
1.9Schristossoftware packages would mishandle leap seconds if they were present.
1.9SchristosInstead, leap seconds are more commonly handled by occasionally adjusting
1.9Schristosthe operating system kernel clock as described in
1.9Schristos<a href="tz-link.html#precision">Precision timekeeping</a>,
1.9Schristosand this package by default installs a <samp>leapseconds</samp> file
1.9Schristoscommonly used by
1.15Schristos<a href="https://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a>
1.9Schristossoftware that adjusts the kernel clock.
1.9SchristosHowever, kernel-clock twiddling approximates UTC only roughly,
1.18Schristosand systems needing more precise UTC can use this package's leap
1.9Schristossecond support directly.
1.9Schristos</p>
1.9Schristos
1.9Schristos<p>
1.18SchristosThe directly supported mechanism assumes that <code>time_t</code>
1.9Schristoscounts of seconds since the POSIX epoch normally include leap seconds,
1.9Schristosas opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1.9SchristosThis modified timescale is converted to <abbr>UTC</abbr>
1.12Schristosat the same point that time zone and <abbr>DST</abbr>
1.12Schristosadjustments are applied &ndash;
1.9Schristosnamely, at calls to <code>localtime</code> and analogous functions &ndash;
1.9Schristosand the process is driven by leap second information
1.9Schristosstored in alternate versions of the <abbr>TZif</abbr> files.
1.9SchristosBecause a leap second adjustment may be needed even
1.9Schristosif no time zone correction is desired,
1.9Schristoscalls to <code>gmtime</code>-like functions
1.9Schristosalso need to consult a <abbr>TZif</abbr> file,
1.14Schristosconventionally named <samp><abbr>Etc/UTC</abbr></samp>
1.14Schristos(<samp><abbr>GMT</abbr></samp> in previous versions),
1.9Schristosto see whether leap second corrections are needed.
1.9SchristosTo convert an application's <code>time_t</code> timestamps to or from
1.9SchristosPOSIX <code>time_t</code> timestamps (for use when, say,
1.9Schristosembedding or interpreting timestamps in portable
1.9Schristos<a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1.9Schristosfiles),
1.9Schristosthe application can call the utility functions
1.9Schristos<code>time2posix</code> and <code>posix2time</code>
1.9Schristosincluded with this package.
1.9Schristos</p>
1.9Schristos
1.9Schristos<p>
1.9SchristosIf the POSIX-compatible <abbr>TZif</abbr> file set is installed
1.9Schristosin a directory whose basename is <samp>zoneinfo</samp>, the
1.9Schristosleap-second-aware file set is by default installed in a separate
1.9Schristosdirectory <samp>zoneinfo-leaps</samp>.
1.9SchristosAlthough each process can have its own time zone by setting
1.9Schristosits <code>TZ</code> environment variable, there is no support for some
1.9Schristosprocesses being leap-second aware while other processes are
1.9SchristosPOSIX-compatible; the leap-second choice is system-wide.
1.9SchristosSo if you configure your kernel to count leap seconds, you should also
1.9Schristosdiscard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp>
1.9Schristosto <samp>zoneinfo</samp>.
1.9SchristosAlternatively, you can install just one set of <abbr>TZif</abbr> files
1.9Schristosin the first place; see the <code>REDO</code> variable in this package's
1.9Schristos<a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>.
1.9Schristos</p>
1.9Schristos</section>
1.9Schristos
1.9Schristos<section>
1.3Schristos  <h2 id="calendar">Calendrical issues</h2>
1.1Schristos<p>
1.1SchristosCalendrical issues are a bit out of scope for a time zone database,
1.1Schristosbut they indicate the sort of problems that we would run into if we
1.3Schristosextended the time zone database further into the past.
1.3SchristosAn excellent resource in this area is Edward M. Reingold
1.3Schristosand Nachum Dershowitz, <cite><a
1.3Schristoshref="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical
1.3SchristosCalculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018).
1.3SchristosOther information and sources are given in the file '<code>calendars</code>'
1.3Schristosin the <code><abbr>tz</abbr></code> distribution.
1.3SchristosThey sometimes disagree.
1.3Schristos</p>
1.3Schristos</section>
1.3Schristos
1.3Schristos<section>
1.18Schristos  <h2 id="planets">Time and time zones off Earth</h2>
1.18Schristos<p>
1.18SchristosThe European Space Agency is <a
1.18Schristoshref='https://www.esa.int/Applications/Navigation/Telling_time_on_the_Moon'>considering</a>
1.18Schristosthe establishment of a reference timescale for the Moon, which has
1.18Schristosdays roughly equivalent to 29.5 Earth days, and where relativistic
1.18Schristoseffects cause clocks to tick slightly faster than on Earth.
1.18Schristos</p>
1.18Schristos
1.3Schristos<p>
1.10SchristosSome people's work schedules have used
1.10Schristos<a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>.
1.3SchristosJet Propulsion Laboratory (JPL) coordinators kept Mars time on
1.3Schristosand off during the
1.6Schristos<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars
1.10SchristosPathfinder</a> mission (1997).
1.3SchristosSome of their family members also adapted to Mars time.
1.3SchristosDozens of special Mars watches were built for JPL workers who kept
1.10SchristosMars time during the
1.10Schristos<a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars
1.10SchristosExploration Rovers (MER)</a> mission (2004&ndash;2018).
1.10SchristosThese timepieces looked like normal Seikos and Citizens but were adjusted
1.10Schristosto use Mars seconds rather than terrestrial seconds, although
1.10Schristosunfortunately the adjusted watches were unreliable and appear to have
1.10Schristoshad only limited use.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.1SchristosA Mars solar day is called a "sol" and has a mean period equal to
1.3Schristosabout 24 hours 39 minutes 35.244 seconds in terrestrial time.
1.3SchristosIt is divided into a conventional 24-hour clock, so each Mars second
1.3Schristosequals about 1.02749125 terrestrial seconds.
1.10Schristos(One MER worker noted, "If I am working Mars hours, and Mars hours are
1.10Schristos2.5% more than Earth hours, shouldn't I get an extra 2.5% pay raise?")
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.3SchristosThe <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime
1.3Schristosmeridian</a> of Mars goes through the center of the crater
1.3Schristos<a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in
1.3Schristoshonor of the British astronomer who built the Greenwich telescope that
1.3Schristosdefines Earth's prime meridian.
1.3SchristosMean solar time on the Mars prime meridian is
1.6Schristoscalled Mars Coordinated Time (<abbr>MTC</abbr>).
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.1SchristosEach landed mission on Mars has adopted a different reference for
1.4Schristossolar timekeeping, so there is no real standard for Mars time zones.
1.10SchristosFor example, the MER mission defined two time zones "Local
1.3SchristosSolar Time A" and "Local Solar Time B" for its two missions, each zone
1.3Schristosdesigned so that its time equals local true solar time at
1.3Schristosapproximately the middle of the nominal mission.
1.10SchristosThe A and B zones differ enough so that an MER worker assigned to
1.10Schristosthe A zone might suffer "Mars lag" when switching to work in the B zone.
1.3SchristosSuch a "time zone" is not particularly suited for any application
1.3Schristosother than the mission itself.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.1SchristosMany calendars have been proposed for Mars, but none have achieved
1.3Schristoswide acceptance.
1.3SchristosAstronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a
1.1Schristossequential count of Mars solar days elapsed since about 1873-12-29
1.3Schristos12:00 <abbr>GMT</abbr>.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.1SchristosIn our solar system, Mars is the planet with time and calendar most
1.3Schristoslike Earth's.
1.3SchristosOn other planets, Sun-based time and calendars would work quite
1.3Schristosdifferently.
1.3SchristosFor example, although Mercury's
1.3Schristos<a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal
1.3Schristosrotation period</a> is 58.646 Earth days, Mercury revolves around the
1.3SchristosSun so rapidly that an observer on Mercury's equator would see a
1.3Schristossunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a
1.3SchristosMercury day.
1.3SchristosVenus is more complicated, partly because its rotation is slightly
1.3Schristos<a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>:
1.3Schristosits year is 1.92 of its days.
1.3SchristosGas giants like Jupiter are trickier still, as their polar and
1.3Schristosequatorial regions rotate at different rates, so that the length of a
1.3Schristosday depends on latitude.
1.3SchristosThis effect is most pronounced on Neptune, where the day is about 12
1.3Schristoshours at the poles and 18 hours at the equator.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.3SchristosAlthough the <code><abbr>tz</abbr></code> database does not support
1.3Schristostime on other planets, it is documented here in the hopes that support
1.3Schristoswill be added eventually.
1.1Schristos</p>
1.1Schristos
1.1Schristos<p>
1.3SchristosSources for time on other planets:
1.1Schristos</p>
1.3Schristos
1.1Schristos<ul>
1.1Schristos  <li>
1.3Schristos    Michael Allison and Robert Schmunk,
1.3Schristos    "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical
1.3Schristos      Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>"
1.10Schristos    (2020-03-08).
1.10Schristos  </li>
1.10Schristos  <li>
1.10Schristos    Zara Mirmalek,
1.10Schristos    <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making
1.10Schristos	Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Jia-Rui Chong,
1.8Schristos    "<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays
1.3Schristos    Fit for a Martian</a>", <cite>Los Angeles Times</cite>
1.3Schristos    (2004-01-14), pp A1, A20&ndash;A21.
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Tom Chmielewski,
1.3Schristos    "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet
1.3Schristos    Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26)
1.1Schristos  </li>
1.1Schristos  <li>
1.3Schristos    Matt Williams,
1.3Schristos    "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How
1.3Schristos    long is a day on the other planets of the solar system?</a>"
1.4Schristos    (2016-01-20).
1.1Schristos  </li>
1.1Schristos</ul>
1.3Schristos</section>
1.1Schristos
1.3Schristos<footer>
1.3Schristos  <hr>
1.3Schristos  This file is in the public domain, so clarified as of 2009-05-17 by
1.3Schristos  Arthur David Olson.
1.3Schristos</footer>
1.1Schristos</body>
1.1Schristos</html>