xref: /freebsd/contrib/tzcode/theory.html (revision 967a49a21a27380ba1c545c746b4f1badabefd77)
1bc421551SDag-Erling Smørgrav<!DOCTYPE html>
2bc421551SDag-Erling Smørgrav<html lang="en">
3bc421551SDag-Erling Smørgrav<head>
4bc421551SDag-Erling Smørgrav  <title>Theory and pragmatics of the tz code and data</title>
5bc421551SDag-Erling Smørgrav  <meta charset="UTF-8">
6bc421551SDag-Erling Smørgrav  <style>
7bc421551SDag-Erling Smørgrav    pre {margin-left: 2em; white-space: pre-wrap;}
8bc421551SDag-Erling Smørgrav  </style>
9bc421551SDag-Erling Smørgrav</head>
10bc421551SDag-Erling Smørgrav
11bc421551SDag-Erling Smørgrav<body>
12bc421551SDag-Erling Smørgrav<h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>
13bc421551SDag-Erling Smørgrav  <h3>Outline</h3>
14bc421551SDag-Erling Smørgrav  <nav>
15bc421551SDag-Erling Smørgrav    <ul>
16bc421551SDag-Erling Smørgrav      <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>
17bc421551SDag-Erling Smørgrav	  database</a></li>
18bc421551SDag-Erling Smørgrav      <li><a href="#naming">Timezone identifiers</a></li>
19bc421551SDag-Erling Smørgrav      <li><a href="#abbreviations">Time zone abbreviations</a></li>
20bc421551SDag-Erling Smørgrav      <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code>
21bc421551SDag-Erling Smørgrav	  database</a></li>
22bc421551SDag-Erling Smørgrav      <li><a href="#functions">Time and date functions</a></li>
23bc421551SDag-Erling Smørgrav      <li><a href="#stability">Interface stability</a></li>
24bc421551SDag-Erling Smørgrav      <li><a href="#leapsec">Leap seconds</a></li>
25bc421551SDag-Erling Smørgrav      <li><a href="#calendar">Calendrical issues</a></li>
2675411d15SDag-Erling Smørgrav      <li><a href="#planets">Time and time zones off earth</a></li>
27bc421551SDag-Erling Smørgrav    </ul>
28bc421551SDag-Erling Smørgrav  </nav>
29bc421551SDag-Erling Smørgrav
30bc421551SDag-Erling Smørgrav<section>
31bc421551SDag-Erling Smørgrav  <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>
32bc421551SDag-Erling Smørgrav<p>
33bc421551SDag-Erling SmørgravThe <a
34bc421551SDag-Erling Smørgravhref="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code>
35bc421551SDag-Erling Smørgravdatabase</a> attempts to record the history and predicted future of
36bc421551SDag-Erling Smørgravcivil time scales.
37bc421551SDag-Erling SmørgravIt organizes <a href="tz-link.html">time zone and daylight saving time
38bc421551SDag-Erling Smørgravdata</a> by partitioning the world into <a
39bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a>
40bc421551SDag-Erling Smørgravwhose clocks all agree about timestamps that occur after the <a
41bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a>
42bc421551SDag-Erling Smørgrav(1970-01-01 00:00:00 <a
43bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr
44bc421551SDag-Erling Smørgravtitle="Coordinated Universal Time">UTC</abbr></a>).
45bc421551SDag-Erling SmørgravAlthough 1970 is a somewhat-arbitrary cutoff, there are significant
46bc421551SDag-Erling Smørgravchallenges to moving the cutoff earlier even by a decade or two, due
47bc421551SDag-Erling Smørgravto the wide variety of local practices before computer timekeeping
48bc421551SDag-Erling Smørgravbecame prevalent.
49bc421551SDag-Erling SmørgravMost timezones correspond to a notable location and the database
50bc421551SDag-Erling Smørgravrecords all known clock transitions for that location;
51bc421551SDag-Erling Smørgravsome timezones correspond instead to a fixed <abbr>UTC</abbr> offset.
52bc421551SDag-Erling Smørgrav</p>
53bc421551SDag-Erling Smørgrav
54bc421551SDag-Erling Smørgrav<p>
55bc421551SDag-Erling SmørgravEach timezone typically corresponds to a geographical region that is
56bc421551SDag-Erling Smørgravsmaller than a traditional time zone, because clocks in a timezone
57bc421551SDag-Erling Smørgravall agree after 1970 whereas a traditional time zone merely
58bc421551SDag-Erling Smørgravspecifies current standard time. For example, applications that deal
59bc421551SDag-Erling Smørgravwith current and future timestamps in the traditional North
60bc421551SDag-Erling SmørgravAmerican mountain time zone can choose from the timezones
61bc421551SDag-Erling Smørgrav<code>America/Denver</code> which observes US-style daylight saving
62bc421551SDag-Erling Smørgravtime (<abbr>DST</abbr>),
63bc421551SDag-Erling Smørgravand <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>.
64bc421551SDag-Erling SmørgravApplications that also deal with past timestamps in the mountain time
65bc421551SDag-Erling Smørgravzone can choose from over a dozen timezones, such as
66bc421551SDag-Erling Smørgrav<code>America/Boise</code>, <code>America/Edmonton</code>, and
67bc421551SDag-Erling Smørgrav<code>America/Hermosillo</code>, each of which currently uses mountain
68bc421551SDag-Erling Smørgravtime but differs from other timezones for some timestamps after 1970.
69bc421551SDag-Erling Smørgrav</p>
70bc421551SDag-Erling Smørgrav
71bc421551SDag-Erling Smørgrav<p>
72bc421551SDag-Erling SmørgravClock transitions before 1970 are recorded for location-based timezones,
73bc421551SDag-Erling Smørgravbecause most systems support timestamps before 1970 and could
74bc421551SDag-Erling Smørgravmisbehave if data entries were omitted for pre-1970 transitions.
75bc421551SDag-Erling SmørgravHowever, the database is not designed for and does not suffice for
76bc421551SDag-Erling Smørgravapplications requiring accurate handling of all past times everywhere,
77bc421551SDag-Erling Smørgravas it would take far too much effort and guesswork to record all
78bc421551SDag-Erling Smørgravdetails of pre-1970 civil timekeeping.
79bc421551SDag-Erling SmørgravAlthough some information outside the scope of the database is
80bc421551SDag-Erling Smørgravcollected in a file <code>backzone</code> that is distributed along
81bc421551SDag-Erling Smørgravwith the database proper, this file is less reliable and does not
82bc421551SDag-Erling Smørgravnecessarily follow database guidelines.
83bc421551SDag-Erling Smørgrav</p>
84bc421551SDag-Erling Smørgrav
85bc421551SDag-Erling Smørgrav<p>
86bc421551SDag-Erling SmørgravAs described below, reference source code for using the
87bc421551SDag-Erling Smørgrav<code><abbr>tz</abbr></code> database is also available.
88bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> code is upwards compatible with <a
89bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international
90bc421551SDag-Erling Smørgravstandard for <a
91bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems.
92a979394aSDag-Erling SmørgravAs of this writing, the current edition of POSIX is POSIX.1-2024,
93a979394aSDag-Erling Smørgravwhich has been published but not yet in HTML form.
94a979394aSDag-Erling SmørgravUnlike its predecessor POSIX.1-2017 (<a
95bc421551SDag-Erling Smørgravhref="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open
96bc421551SDag-Erling SmørgravGroup Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018
97a979394aSDag-Erling SmørgravEdition), POSIX.1-2024 requires support for the
98a979394aSDag-Erling Smørgrav<code><abbr>tz</abbr></code> database, which has a
99a979394aSDag-Erling Smørgravmodel for describing civil time that is more complex than the
100a979394aSDag-Erling Smørgravstandard and daylight saving times required by POSIX.1-2017.
101bc421551SDag-Erling SmørgravA <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
102bc421551SDag-Erling Smørgravhave more than two changes per year, these changes need not merely
103bc421551SDag-Erling Smørgravflip back and forth between two alternatives, and the rules themselves
104bc421551SDag-Erling Smørgravcan change at times.
105bc421551SDag-Erling SmørgravWhether and when a timezone changes its clock,
106bc421551SDag-Erling Smørgravand even the timezone's notional base offset from <abbr>UTC</abbr>,
107bc421551SDag-Erling Smørgravare variable.
108bc421551SDag-Erling SmørgravIt does not always make sense to talk about a timezone's
109bc421551SDag-Erling Smørgrav"base offset", which is not necessarily a single number.
110bc421551SDag-Erling Smørgrav</p>
111bc421551SDag-Erling Smørgrav
112bc421551SDag-Erling Smørgrav</section>
113bc421551SDag-Erling Smørgrav
114bc421551SDag-Erling Smørgrav<section>
115bc421551SDag-Erling Smørgrav  <h2 id="naming">Timezone identifiers</h2>
116bc421551SDag-Erling Smørgrav<p>
117bc421551SDag-Erling SmørgravEach timezone has a name that uniquely identifies the timezone.
118bc421551SDag-Erling SmørgravInexperienced users are not expected to select these names unaided.
119bc421551SDag-Erling SmørgravDistributors should provide documentation and/or a simple selection
120bc421551SDag-Erling Smørgravinterface that explains each name via a map or via descriptive text like
121bc421551SDag-Erling Smørgrav"Czech Republic" instead of the timezone name "<code>Europe/Prague</code>".
122bc421551SDag-Erling SmørgravIf geolocation information is available, a selection interface can
123bc421551SDag-Erling Smørgravlocate the user on a timezone map or prioritize names that are
124bc421551SDag-Erling Smørgravgeographically close. For an example selection interface, see the
125bc421551SDag-Erling Smørgrav<code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.
126*967a49a2SDag-Erling SmørgravUnicode's <a href="https://cldr.unicode.org">Common Locale Data
127*967a49a2SDag-Erling SmørgravRepository (<abbr>CLDR</abbr>)</a>
128*967a49a2SDag-Erling Smørgravcontains data that may be useful for other selection
129bc421551SDag-Erling Smørgravinterfaces; it maps timezone names like <code>Europe/Prague</code> to
130bc421551SDag-Erling Smørgravlocale-dependent strings like "Prague", "Praha", "Прага", and "布拉格".
131bc421551SDag-Erling Smørgrav</p>
132bc421551SDag-Erling Smørgrav
133bc421551SDag-Erling Smørgrav<p>
134bc421551SDag-Erling SmørgravThe naming conventions attempt to strike a balance
135bc421551SDag-Erling Smørgravamong the following goals:
136bc421551SDag-Erling Smørgrav</p>
137bc421551SDag-Erling Smørgrav
138bc421551SDag-Erling Smørgrav<ul>
139bc421551SDag-Erling Smørgrav  <li>
140bc421551SDag-Erling Smørgrav    Uniquely identify every timezone where clocks have agreed since 1970.
141bc421551SDag-Erling Smørgrav    This is essential for the intended use: static clocks keeping local
142bc421551SDag-Erling Smørgrav    civil time.
143bc421551SDag-Erling Smørgrav  </li>
144bc421551SDag-Erling Smørgrav  <li>
145bc421551SDag-Erling Smørgrav    Indicate to experts where the timezone's clocks typically are.
146bc421551SDag-Erling Smørgrav  </li>
147bc421551SDag-Erling Smørgrav  <li>
148bc421551SDag-Erling Smørgrav    Be robust in the presence of political changes.
149bc421551SDag-Erling Smørgrav    For example, names are typically not tied to countries, to avoid
150bc421551SDag-Erling Smørgrav    incompatibilities when countries change their name (e.g.,
151bc421551SDag-Erling Smørgrav    Swaziland&rarr;Eswatini) or when locations change countries (e.g., Hong
152bc421551SDag-Erling Smørgrav    Kong from UK colony to China).
153bc421551SDag-Erling Smørgrav    There is no requirement that every country or national
154bc421551SDag-Erling Smørgrav    capital must have a timezone name.
155bc421551SDag-Erling Smørgrav  </li>
156bc421551SDag-Erling Smørgrav  <li>
157bc421551SDag-Erling Smørgrav    Be portable to a wide variety of implementations.
158bc421551SDag-Erling Smørgrav  </li>
159bc421551SDag-Erling Smørgrav  <li>
160bc421551SDag-Erling Smørgrav    Use a consistent naming conventions over the entire world.
161bc421551SDag-Erling Smørgrav  </li>
162bc421551SDag-Erling Smørgrav</ul>
163bc421551SDag-Erling Smørgrav
164bc421551SDag-Erling Smørgrav<p>
165a979394aSDag-Erling SmørgravNames normally have the format
166bc421551SDag-Erling Smørgrav<var>AREA</var><code>/</code><var>LOCATION</var>, where
167bc421551SDag-Erling Smørgrav<var>AREA</var> is a continent or ocean, and
168bc421551SDag-Erling Smørgrav<var>LOCATION</var> is a specific location within the area.
169bc421551SDag-Erling SmørgravNorth and South America share the same area, '<code>America</code>'.
170bc421551SDag-Erling SmørgravTypical names are '<code>Africa/Cairo</code>',
171bc421551SDag-Erling Smørgrav'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
172bc421551SDag-Erling SmørgravSome names are further qualified to help avoid confusion; for example,
173bc421551SDag-Erling Smørgrav'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
174bc421551SDag-Erling SmørgravIndiana from other Petersburgs in America.
175bc421551SDag-Erling Smørgrav</p>
176bc421551SDag-Erling Smørgrav
177bc421551SDag-Erling Smørgrav<p>
178bc421551SDag-Erling SmørgravHere are the general guidelines used for
179bc421551SDag-Erling Smørgravchoosing timezone names,
180bc421551SDag-Erling Smørgravin decreasing order of importance:
181bc421551SDag-Erling Smørgrav</p>
182bc421551SDag-Erling Smørgrav
183bc421551SDag-Erling Smørgrav<ul>
184bc421551SDag-Erling Smørgrav  <li>
185bc421551SDag-Erling Smørgrav    Use only valid POSIX file name components (i.e., the parts of
186bc421551SDag-Erling Smørgrav    names other than '<code>/</code>').
187bc421551SDag-Erling Smørgrav    Do not use the file name components '<code>.</code>' and
188bc421551SDag-Erling Smørgrav    '<code>..</code>'.
189bc421551SDag-Erling Smørgrav    Within a file name component, use only <a
190bc421551SDag-Erling Smørgrav    href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters,
191bc421551SDag-Erling Smørgrav    '<code>.</code>', '<code>-</code>' and '<code>_</code>'.
192bc421551SDag-Erling Smørgrav    Do not use digits, as that might create an ambiguity with <a
193a979394aSDag-Erling Smørgrav    href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX's proleptic
194bc421551SDag-Erling Smørgrav    <code>TZ</code> strings</a>.
195bc421551SDag-Erling Smørgrav    A file name component must not exceed 14 characters or start with
196bc421551SDag-Erling Smørgrav    '<code>-</code>'.
197bc421551SDag-Erling Smørgrav    E.g., prefer <code>America/Noronha</code> to
198bc421551SDag-Erling Smørgrav    <code>America/Fernando_de_Noronha</code>.
199bc421551SDag-Erling Smørgrav    Exceptions: see the discussion of legacy names below.
200bc421551SDag-Erling Smørgrav  </li>
201bc421551SDag-Erling Smørgrav  <li>
202bc421551SDag-Erling Smørgrav    A name must not be empty, or contain '<code>//</code>', or
203bc421551SDag-Erling Smørgrav    start or end with '<code>/</code>'.
204*967a49a2SDag-Erling Smørgrav    Also, a name must not be '<code>Etc/Unknown</code>', as
205*967a49a2SDag-Erling Smørgrav    <abbr>CLDR</abbr> uses that string for an unknown or invalid timezone.
206bc421551SDag-Erling Smørgrav  </li>
207bc421551SDag-Erling Smørgrav  <li>
208bc421551SDag-Erling Smørgrav    Do not use names that differ only in case.
209bc421551SDag-Erling Smørgrav    Although the reference implementation is case-sensitive, some
210bc421551SDag-Erling Smørgrav    other implementations are not, and they would mishandle names
211bc421551SDag-Erling Smørgrav    differing only in case.
212bc421551SDag-Erling Smørgrav  </li>
213bc421551SDag-Erling Smørgrav  <li>
214bc421551SDag-Erling Smørgrav    If one name <var>A</var> is an initial prefix of another
215bc421551SDag-Erling Smørgrav    name <var>AB</var> (ignoring case), then <var>B</var> must not
216bc421551SDag-Erling Smørgrav    start with '<code>/</code>', as a regular file cannot have the
217bc421551SDag-Erling Smørgrav    same name as a directory in POSIX.
218bc421551SDag-Erling Smørgrav    For example, <code>America/New_York</code> precludes
219bc421551SDag-Erling Smørgrav    <code>America/New_York/Bronx</code>.
220bc421551SDag-Erling Smørgrav  </li>
221bc421551SDag-Erling Smørgrav  <li>
222bc421551SDag-Erling Smørgrav    Uninhabited regions like the North Pole and Bouvet Island
223bc421551SDag-Erling Smørgrav    do not need locations, since local time is not defined there.
224bc421551SDag-Erling Smørgrav  </li>
225bc421551SDag-Erling Smørgrav  <li>
226*967a49a2SDag-Erling Smørgrav    If all clocks in a region have agreed since 1970,
227*967a49a2SDag-Erling Smørgrav    give them just one name even if some of the clocks disagreed before 1970,
228*967a49a2SDag-Erling Smørgrav    or reside in different countries or in notable or faraway locations.
229bc421551SDag-Erling Smørgrav    Otherwise these tables would become annoyingly large.
230*967a49a2SDag-Erling Smørgrav    For example, do not create a name <code>Indian/Crozet</code>
231*967a49a2SDag-Erling Smørgrav    as a near-duplicate or alias of <code>Asia/Dubai</code>
232*967a49a2SDag-Erling Smørgrav    merely because they are different countries or territories,
233*967a49a2SDag-Erling Smørgrav    or their clocks disagreed before 1970, or the
234*967a49a2SDag-Erling Smørgrav    <a href="https://en.wikipedia.org/wiki/Crozet_Islands">Crozet Islands</a>
235*967a49a2SDag-Erling Smørgrav    are notable in their own right,
236*967a49a2SDag-Erling Smørgrav    or the Crozet Islands are not adjacent to other locations
237*967a49a2SDag-Erling Smørgrav    that use <code>Asia/Dubai</code>.
238bc421551SDag-Erling Smørgrav  </li>
239bc421551SDag-Erling Smørgrav  <li>
240bc421551SDag-Erling Smørgrav    If boundaries between regions are fluid, such as during a war or
241bc421551SDag-Erling Smørgrav    insurrection, do not bother to create a new timezone merely
242bc421551SDag-Erling Smørgrav    because of yet another boundary change. This helps prevent table
243bc421551SDag-Erling Smørgrav    bloat and simplifies maintenance.
244bc421551SDag-Erling Smørgrav  </li>
245bc421551SDag-Erling Smørgrav  <li>
246bc421551SDag-Erling Smørgrav    If a name is ambiguous, use a less ambiguous alternative;
247bc421551SDag-Erling Smørgrav    e.g., many cities are named San José and Georgetown, so
248bc421551SDag-Erling Smørgrav    prefer <code>America/Costa_Rica</code> to
249bc421551SDag-Erling Smørgrav    <code>America/San_Jose</code> and <code>America/Guyana</code>
250bc421551SDag-Erling Smørgrav    to <code>America/Georgetown</code>.
251bc421551SDag-Erling Smørgrav  </li>
252bc421551SDag-Erling Smørgrav  <li>
253bc421551SDag-Erling Smørgrav    Keep locations compact.
254bc421551SDag-Erling Smørgrav    Use cities or small islands, not countries or regions, so that any
255bc421551SDag-Erling Smørgrav    future changes do not split individual locations into different
256bc421551SDag-Erling Smørgrav    timezones.
257bc421551SDag-Erling Smørgrav    E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
258bc421551SDag-Erling Smørgrav    since
259bc421551SDag-Erling Smørgrav    <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France
260bc421551SDag-Erling Smørgrav    has had multiple time zones</a>.
261bc421551SDag-Erling Smørgrav  </li>
262bc421551SDag-Erling Smørgrav  <li>
263bc421551SDag-Erling Smørgrav    Use mainstream English spelling, e.g., prefer
264bc421551SDag-Erling Smørgrav    <code>Europe/Rome</code> to <code>Europa/Roma</code>, and
265bc421551SDag-Erling Smørgrav    prefer <code>Europe/Athens</code> to the Greek
266bc421551SDag-Erling Smørgrav    <code>Ευρώπη/Αθήνα</code> or the Romanized
267bc421551SDag-Erling Smørgrav    <code>Evrópi/Athína</code>.
268bc421551SDag-Erling Smørgrav    The POSIX file name restrictions encourage this guideline.
269bc421551SDag-Erling Smørgrav  </li>
270bc421551SDag-Erling Smørgrav  <li>
271bc421551SDag-Erling Smørgrav    Use the most populous among locations in a region,
272bc421551SDag-Erling Smørgrav    e.g., prefer <code>Asia/Shanghai</code> to
273bc421551SDag-Erling Smørgrav    <code>Asia/Beijing</code>.
274bc421551SDag-Erling Smørgrav    Among locations with similar populations, pick the best-known
275bc421551SDag-Erling Smørgrav    location, e.g., prefer <code>Europe/Rome</code> to
276bc421551SDag-Erling Smørgrav    <code>Europe/Milan</code>.
277bc421551SDag-Erling Smørgrav  </li>
278bc421551SDag-Erling Smørgrav  <li>
279bc421551SDag-Erling Smørgrav    Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
280bc421551SDag-Erling Smørgrav    <code>Atlantic/Canaries</code>.
281bc421551SDag-Erling Smørgrav  </li>
282bc421551SDag-Erling Smørgrav  <li>
283bc421551SDag-Erling Smørgrav    Omit common suffixes like '<code>_Islands</code>' and
284bc421551SDag-Erling Smørgrav    '<code>_City</code>', unless that would lead to ambiguity.
285bc421551SDag-Erling Smørgrav    E.g., prefer <code>America/Cayman</code> to
286bc421551SDag-Erling Smørgrav    <code>America/Cayman_Islands</code> and
287bc421551SDag-Erling Smørgrav    <code>America/Guatemala</code> to
288bc421551SDag-Erling Smørgrav    <code>America/Guatemala_City</code>, but prefer
289bc421551SDag-Erling Smørgrav    <code>America/Mexico_City</code> to
290bc421551SDag-Erling Smørgrav    <code>America/Mexico</code>
291bc421551SDag-Erling Smørgrav    because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the
292bc421551SDag-Erling Smørgrav    country of Mexico has several time zones</a>.
293bc421551SDag-Erling Smørgrav  </li>
294bc421551SDag-Erling Smørgrav  <li>
295bc421551SDag-Erling Smørgrav    Use '<code>_</code>' to represent a space.
296bc421551SDag-Erling Smørgrav  </li>
297bc421551SDag-Erling Smørgrav  <li>
298bc421551SDag-Erling Smørgrav    Omit '<code>.</code>' from abbreviations in names.
299bc421551SDag-Erling Smørgrav    E.g., prefer <code>Atlantic/St_Helena</code> to
300bc421551SDag-Erling Smørgrav    <code>Atlantic/St._Helena</code>.
301bc421551SDag-Erling Smørgrav  </li>
302bc421551SDag-Erling Smørgrav  <li>
303bc421551SDag-Erling Smørgrav    Do not change established names if they only marginally violate
304bc421551SDag-Erling Smørgrav    the above guidelines.
305bc421551SDag-Erling Smørgrav    For example, do not change the existing name <code>Europe/Rome</code> to
306bc421551SDag-Erling Smørgrav    <code>Europe/Milan</code> merely because Milan's population has grown
307bc421551SDag-Erling Smørgrav    to be somewhat greater than Rome's.
308bc421551SDag-Erling Smørgrav  </li>
309bc421551SDag-Erling Smørgrav  <li>
310bc421551SDag-Erling Smørgrav    If a name is changed, put its old spelling in the
311bc421551SDag-Erling Smørgrav    '<code>backward</code>' file as a link to the new spelling.
312bc421551SDag-Erling Smørgrav    This means old spellings will continue to work.
313bc421551SDag-Erling Smørgrav    Ordinarily a name change should occur only in the rare case when
314bc421551SDag-Erling Smørgrav    a location's consensus English-language spelling changes; for example,
315bc421551SDag-Erling Smørgrav    in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code>
316bc421551SDag-Erling Smørgrav    due to long-time widespread use of the new city name instead of the old.
317bc421551SDag-Erling Smørgrav  </li>
318bc421551SDag-Erling Smørgrav</ul>
319bc421551SDag-Erling Smørgrav
320bc421551SDag-Erling Smørgrav<p>
321bc421551SDag-Erling SmørgravGuidelines have evolved with time, and names following old versions of
322bc421551SDag-Erling Smørgravthese guidelines might not follow the current version. When guidelines
323bc421551SDag-Erling Smørgravhave changed, old names continue to be supported. Guideline changes
324bc421551SDag-Erling Smørgravhave included the following:
325bc421551SDag-Erling Smørgrav</p>
326bc421551SDag-Erling Smørgrav
327bc421551SDag-Erling Smørgrav<ul>
328bc421551SDag-Erling Smørgrav<li>
329bc421551SDag-Erling SmørgravOlder versions of this package used a different naming scheme.
330bc421551SDag-Erling SmørgravSee the file '<code>backward</code>' for most of these older names
331bc421551SDag-Erling Smørgrav(e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>').
332bc421551SDag-Erling SmørgravThe other old-fashioned names still supported are
333bc421551SDag-Erling Smørgrav'<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and
334bc421551SDag-Erling Smørgrav'<code>EET</code>' (see the file '<code>europe</code>').
335bc421551SDag-Erling Smørgrav</li>
336bc421551SDag-Erling Smørgrav
337bc421551SDag-Erling Smørgrav<li>
338bc421551SDag-Erling SmørgravOlder versions of this package defined legacy names that are
339bc421551SDag-Erling Smørgravincompatible with the first guideline of location names, but which are
340bc421551SDag-Erling Smørgravstill supported.
341bc421551SDag-Erling SmørgravThese legacy names are mostly defined in the file
342bc421551SDag-Erling Smørgrav'<code>etcetera</code>'.
343bc421551SDag-Erling SmørgravAlso, the file '<code>backward</code>' defines the legacy names
344bc421551SDag-Erling Smørgrav'<code>Etc/GMT0</code>', '<code>Etc/GMT-0</code>', '<code>Etc/GMT+0</code>',
345bc421551SDag-Erling Smørgrav'<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>',
346bc421551SDag-Erling Smørgravand the file '<code>northamerica</code>' defines the legacy names
347bc421551SDag-Erling Smørgrav'<code>EST5EDT</code>', '<code>CST6CDT</code>',
348bc421551SDag-Erling Smørgrav'<code>MST7MDT</code>', and '<code>PST8PDT</code>'.
349bc421551SDag-Erling Smørgrav</li>
350bc421551SDag-Erling Smørgrav
351bc421551SDag-Erling Smørgrav<li>
352bc421551SDag-Erling SmørgravOlder versions of these guidelines said that
353bc421551SDag-Erling Smørgravthere should typically be at least one name for each <a
354bc421551SDag-Erling Smørgravhref="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr
355bc421551SDag-Erling Smørgravtitle="International Organization for Standardization">ISO</abbr>
356bc421551SDag-Erling Smørgrav3166-1</a> officially assigned two-letter code for an inhabited
357bc421551SDag-Erling Smørgravcountry or territory.
358bc421551SDag-Erling SmørgravThis old guideline has been dropped, as it was not needed to handle
359bc421551SDag-Erling Smørgravtimestamps correctly and it increased maintenance burden.
360bc421551SDag-Erling Smørgrav</li>
361bc421551SDag-Erling Smørgrav</ul>
362bc421551SDag-Erling Smørgrav
363bc421551SDag-Erling Smørgrav<p>
364bc421551SDag-Erling SmørgravThe file <code>zone1970.tab</code> lists geographical locations used
365bc421551SDag-Erling Smørgravto name timezones.
366bc421551SDag-Erling SmørgravIt is intended to be an exhaustive list of names for geographic
367bc421551SDag-Erling Smørgravregions as described above; this is a subset of the timezones in the data.
368bc421551SDag-Erling SmørgravAlthough a <code>zone1970.tab</code> location's
369bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Longitude">longitude</a>
370bc421551SDag-Erling Smørgravcorresponds to
371bc421551SDag-Erling Smørgravits <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean
372bc421551SDag-Erling Smørgravtime (<abbr>LMT</abbr>)</a> offset with one hour for every 15&deg;
373bc421551SDag-Erling Smørgraveast longitude, this relationship is not exact.
374bc421551SDag-Erling SmørgravThe backward-compatibility file <code>zone.tab</code> is similar
375bc421551SDag-Erling Smørgravbut conforms to the older-version guidelines related to <abbr>ISO</abbr> 3166-1;
376bc421551SDag-Erling Smørgravit lists only one country code per entry and unlike <code>zone1970.tab</code>
377bc421551SDag-Erling Smørgravit can list names defined in <code>backward</code>.
37846c59934SDag-Erling SmørgravApplications that process only timestamps from now on can instead use the file
37946c59934SDag-Erling Smørgrav<code>zonenow.tab</code>, which partitions the world more coarsely,
38046c59934SDag-Erling Smørgravinto regions where clocks agree now and in the predicted future;
38146c59934SDag-Erling Smørgravthis file is smaller and simpler than <code>zone1970.tab</code>
38246c59934SDag-Erling Smørgravand <code>zone.tab</code>.
383bc421551SDag-Erling Smørgrav</p>
384bc421551SDag-Erling Smørgrav
385bc421551SDag-Erling Smørgrav<p>
386bc421551SDag-Erling SmørgravThe database defines each timezone name to be a zone, or a link to a zone.
387bc421551SDag-Erling SmørgravThe source file <code>backward</code> defines links for backward
388bc421551SDag-Erling Smørgravcompatibility; it does not define zones.
389bc421551SDag-Erling SmørgravAlthough <code>backward</code> was originally designed to be optional,
390bc421551SDag-Erling Smørgravnowadays distributions typically use it
391bc421551SDag-Erling Smørgravand no great weight should be attached to whether a link
392bc421551SDag-Erling Smørgravis defined in <code>backward</code> or in some other file.
393bc421551SDag-Erling SmørgravThe source file <code>etcetera</code> defines names that may be useful
394a979394aSDag-Erling Smørgravon platforms that do not support proleptic <code>TZ</code> strings
395a979394aSDag-Erling Smørgravlike <code>&lt;+08&gt;-8</code>;
396bc421551SDag-Erling Smørgravno other source file other than <code>backward</code>
397bc421551SDag-Erling Smørgravcontains links to its zones.
398bc421551SDag-Erling SmørgravOne of <code>etcetera</code>'s names is <code>Etc/UTC</code>,
399bc421551SDag-Erling Smørgravused by functions like <code>gmtime</code> to obtain leap
400bc421551SDag-Erling Smørgravsecond information on platforms that support leap seconds.
401bc421551SDag-Erling SmørgravAnother <code>etcetera</code> name, <code>GMT</code>,
402bc421551SDag-Erling Smørgravis used by older code releases.
403bc421551SDag-Erling Smørgrav</p>
404bc421551SDag-Erling Smørgrav</section>
405bc421551SDag-Erling Smørgrav
406bc421551SDag-Erling Smørgrav<section>
407bc421551SDag-Erling Smørgrav  <h2 id="abbreviations">Time zone abbreviations</h2>
408bc421551SDag-Erling Smørgrav<p>
409bc421551SDag-Erling SmørgravWhen this package is installed, it generates time zone abbreviations
410bc421551SDag-Erling Smørgravlike '<code>EST</code>' to be compatible with human tradition and POSIX.
411bc421551SDag-Erling SmørgravHere are the general guidelines used for choosing time zone abbreviations,
412bc421551SDag-Erling Smørgravin decreasing order of importance:
413bc421551SDag-Erling Smørgrav</p>
414bc421551SDag-Erling Smørgrav
415bc421551SDag-Erling Smørgrav<ul>
416bc421551SDag-Erling Smørgrav  <li>
417bc421551SDag-Erling Smørgrav    Use three to six characters that are ASCII alphanumerics or
418bc421551SDag-Erling Smørgrav    '<code>+</code>' or '<code>-</code>'.
419bc421551SDag-Erling Smørgrav    Previous editions of this database also used characters like
420bc421551SDag-Erling Smørgrav    space and '<code>?</code>', but these characters have a
421bc421551SDag-Erling Smørgrav    special meaning to the
422bc421551SDag-Erling Smørgrav    <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a>
423bc421551SDag-Erling Smørgrav    and cause commands like
424bc421551SDag-Erling Smørgrav    '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a>
425bc421551SDag-Erling Smørgrav    `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>'
426bc421551SDag-Erling Smørgrav    to have unexpected effects.
427bc421551SDag-Erling Smørgrav    Previous editions of this guideline required upper-case letters, but the
428bc421551SDag-Erling Smørgrav    Congressman who introduced
429bc421551SDag-Erling Smørgrav    <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro
430bc421551SDag-Erling Smørgrav    Standard Time</a> preferred "ChST", so lower-case letters are now
431bc421551SDag-Erling Smørgrav    allowed.
432bc421551SDag-Erling Smørgrav    Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>',
433bc421551SDag-Erling Smørgrav    '<code>+</code>', and alphanumeric characters from the portable
434bc421551SDag-Erling Smørgrav    character set in the current locale.
435bc421551SDag-Erling Smørgrav    In practice ASCII alphanumerics and '<code>+</code>' and
436bc421551SDag-Erling Smørgrav    '<code>-</code>' are safe in all locales.
437bc421551SDag-Erling Smørgrav
438bc421551SDag-Erling Smørgrav    <p>
439bc421551SDag-Erling Smørgrav    In other words, in the C locale the POSIX extended regular
440bc421551SDag-Erling Smørgrav    expression <code>[-+[:alnum:]]{3,6}</code> should match the
441bc421551SDag-Erling Smørgrav    abbreviation.
442a979394aSDag-Erling Smørgrav    This guarantees that all abbreviations could have been specified
443a979394aSDag-Erling Smørgrav    explicitly by a POSIX proleptic <code>TZ</code> string.
444bc421551SDag-Erling Smørgrav    </p>
445bc421551SDag-Erling Smørgrav  </li>
446bc421551SDag-Erling Smørgrav  <li>
447bc421551SDag-Erling Smørgrav    Use abbreviations that are in common use among English-speakers,
448bc421551SDag-Erling Smørgrav    e.g., 'EST' for Eastern Standard Time in North America.
449bc421551SDag-Erling Smørgrav    We assume that applications translate them to other languages
450bc421551SDag-Erling Smørgrav    as part of the normal localization process; for example,
451bc421551SDag-Erling Smørgrav    a French application might translate 'EST' to 'HNE'.
452bc421551SDag-Erling Smørgrav
453bc421551SDag-Erling Smørgrav    <p>
454bc421551SDag-Erling Smørgrav    <small>These abbreviations (for standard/daylight/etc. time) are:
455bc421551SDag-Erling Smørgrav      ACST/ACDT Australian Central,
456bc421551SDag-Erling Smørgrav      AST/ADT/APT/AWT/ADDT Atlantic,
457bc421551SDag-Erling Smørgrav      AEST/AEDT Australian Eastern,
458bc421551SDag-Erling Smørgrav      AHST/AHDT Alaska-Hawaii,
459bc421551SDag-Erling Smørgrav      AKST/AKDT Alaska,
460bc421551SDag-Erling Smørgrav      AWST/AWDT Australian Western,
461bc421551SDag-Erling Smørgrav      BST/BDT Bering,
462bc421551SDag-Erling Smørgrav      CAT/CAST Central Africa,
463bc421551SDag-Erling Smørgrav      CET/CEST/CEMT Central European,
464bc421551SDag-Erling Smørgrav      ChST Chamorro,
46575411d15SDag-Erling Smørgrav      CST/CDT/CWT/CPT Central [North America],
466bc421551SDag-Erling Smørgrav      CST/CDT China,
467bc421551SDag-Erling Smørgrav      GMT/BST/IST/BDST Greenwich,
468bc421551SDag-Erling Smørgrav      EAT East Africa,
46975411d15SDag-Erling Smørgrav      EST/EDT/EWT/EPT Eastern [North America],
470bc421551SDag-Erling Smørgrav      EET/EEST Eastern European,
471bc421551SDag-Erling Smørgrav      GST/GDT Guam,
472bc421551SDag-Erling Smørgrav      HST/HDT/HWT/HPT Hawaii,
473bc421551SDag-Erling Smørgrav      HKT/HKST/HKWT Hong Kong,
474bc421551SDag-Erling Smørgrav      IST India,
475bc421551SDag-Erling Smørgrav      IST/GMT Irish,
476bc421551SDag-Erling Smørgrav      IST/IDT/IDDT Israel,
477bc421551SDag-Erling Smørgrav      JST/JDT Japan,
478bc421551SDag-Erling Smørgrav      KST/KDT Korea,
479bc421551SDag-Erling Smørgrav      MET/MEST Middle European (a backward-compatibility alias for
480bc421551SDag-Erling Smørgrav	Central European),
481bc421551SDag-Erling Smørgrav      MSK/MSD Moscow,
48275411d15SDag-Erling Smørgrav      MST/MDT/MWT/MPT Mountain,
483bc421551SDag-Erling Smørgrav      NST/NDT/NWT/NPT/NDDT Newfoundland,
484bc421551SDag-Erling Smørgrav      NST/NDT/NWT/NPT Nome,
485bc421551SDag-Erling Smørgrav      NZMT/NZST New Zealand through 1945,
486bc421551SDag-Erling Smørgrav      NZST/NZDT New Zealand 1946&ndash;present,
487bc421551SDag-Erling Smørgrav      PKT/PKST Pakistan,
48875411d15SDag-Erling Smørgrav      PST/PDT/PWT/PPT Pacific,
489bc421551SDag-Erling Smørgrav      PST/PDT Philippine,
490bc421551SDag-Erling Smørgrav      SAST South Africa,
491bc421551SDag-Erling Smørgrav      SST Samoa,
492bc421551SDag-Erling Smørgrav      UTC Universal,
493bc421551SDag-Erling Smørgrav      WAT/WAST West Africa,
494bc421551SDag-Erling Smørgrav      WET/WEST/WEMT Western European,
495bc421551SDag-Erling Smørgrav      WIB Waktu Indonesia Barat,
496bc421551SDag-Erling Smørgrav      WIT Waktu Indonesia Timur,
497bc421551SDag-Erling Smørgrav      WITA Waktu Indonesia Tengah,
498bc421551SDag-Erling Smørgrav      YST/YDT/YWT/YPT/YDDT Yukon</small>.
499bc421551SDag-Erling Smørgrav    </p>
500bc421551SDag-Erling Smørgrav  </li>
501bc421551SDag-Erling Smørgrav  <li>
502bc421551SDag-Erling Smørgrav    <p>
503bc421551SDag-Erling Smørgrav    For times taken from a city's longitude, use the
504bc421551SDag-Erling Smørgrav    traditional <var>x</var>MT notation.
505bc421551SDag-Erling Smørgrav    The only abbreviation like this in current use is '<abbr>GMT</abbr>'.
506bc421551SDag-Erling Smørgrav    The others are for timestamps before 1960,
507bc421551SDag-Erling Smørgrav    except that Monrovia Mean Time persisted until 1972.
508bc421551SDag-Erling Smørgrav    Typically, numeric abbreviations (e.g., '<code>-</code>004430' for
509bc421551SDag-Erling Smørgrav    MMT) would cause trouble here, as the numeric strings would exceed
510bc421551SDag-Erling Smørgrav    the POSIX length limit.
511bc421551SDag-Erling Smørgrav    </p>
512bc421551SDag-Erling Smørgrav
513bc421551SDag-Erling Smørgrav    <p>
514bc421551SDag-Erling Smørgrav    <small>These abbreviations are:
515bc421551SDag-Erling Smørgrav      AMT Asunción, Athens;
51675411d15SDag-Erling Smørgrav      BMT Baghdad, Bangkok, Batavia, Bermuda, Bern, Bogotá,
517bc421551SDag-Erling Smørgrav        Brussels, Bucharest;
518bc421551SDag-Erling Smørgrav      CMT Calamarca, Caracas, Chisinau, Colón, Córdoba;
519bc421551SDag-Erling Smørgrav      DMT Dublin/Dunsink;
520bc421551SDag-Erling Smørgrav      EMT Easter;
521bc421551SDag-Erling Smørgrav      FFMT Fort-de-France;
522bc421551SDag-Erling Smørgrav      FMT Funchal;
523bc421551SDag-Erling Smørgrav      GMT Greenwich;
524bc421551SDag-Erling Smørgrav      HMT Havana, Helsinki, Horta, Howrah;
525bc421551SDag-Erling Smørgrav      IMT Irkutsk, Istanbul;
526bc421551SDag-Erling Smørgrav      JMT Jerusalem;
527bc421551SDag-Erling Smørgrav      KMT Kaunas, Kyiv, Kingston;
52875411d15SDag-Erling Smørgrav      LMT Lima, Lisbon, local;
529bc421551SDag-Erling Smørgrav      MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo,
530bc421551SDag-Erling Smørgrav	Moratuwa, Moscow;
531bc421551SDag-Erling Smørgrav      PLMT Phù Liễn;
532bc421551SDag-Erling Smørgrav      PMT Paramaribo, Paris, Perm, Pontianak, Prague;
533bc421551SDag-Erling Smørgrav      PMMT Port Moresby;
53475411d15SDag-Erling Smørgrav      PPMT Port-au-Prince;
535bc421551SDag-Erling Smørgrav      QMT Quito;
536bc421551SDag-Erling Smørgrav      RMT Rangoon, Riga, Rome;
537bc421551SDag-Erling Smørgrav      SDMT Santo Domingo;
538bc421551SDag-Erling Smørgrav      SJMT San José;
539bc421551SDag-Erling Smørgrav      SMT Santiago, Simferopol, Singapore, Stanley;
540bc421551SDag-Erling Smørgrav      TBMT Tbilisi;
541bc421551SDag-Erling Smørgrav      TMT Tallinn, Tehran;
54275411d15SDag-Erling Smørgrav      WMT Warsaw.</small>
543bc421551SDag-Erling Smørgrav    </p>
544bc421551SDag-Erling Smørgrav
545bc421551SDag-Erling Smørgrav    <p>
546bc421551SDag-Erling Smørgrav    <small>A few abbreviations also follow the pattern that
547bc421551SDag-Erling Smørgrav    <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK.
548bc421551SDag-Erling Smørgrav    They are:
549bc421551SDag-Erling Smørgrav      BMT/BST for Bermuda 1890&ndash;1930,
550bc421551SDag-Erling Smørgrav      CMT/BST for Calamarca Mean Time and Bolivian Summer Time
551bc421551SDag-Erling Smørgrav	1890&ndash;1932,
552bc421551SDag-Erling Smørgrav      DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time
553bc421551SDag-Erling Smørgrav	1880&ndash;1916,
554bc421551SDag-Erling Smørgrav      MMT/MST/MDST for Moscow 1880&ndash;1919, and
555bc421551SDag-Erling Smørgrav      RMT/LST for Riga Mean Time and Latvian Summer time 1880&ndash;1926.
556bc421551SDag-Erling Smørgrav    </small>
557bc421551SDag-Erling Smørgrav    </p>
558bc421551SDag-Erling Smørgrav  </li>
559bc421551SDag-Erling Smørgrav  <li>
560bc421551SDag-Erling Smørgrav    Use '<abbr>LMT</abbr>' for local mean time of locations before the
561bc421551SDag-Erling Smørgrav    introduction of standard time; see "<a href="#scope">Scope of the
562bc421551SDag-Erling Smørgrav    <code><abbr>tz</abbr></code> database</a>".
563bc421551SDag-Erling Smørgrav  </li>
564bc421551SDag-Erling Smørgrav  <li>
565bc421551SDag-Erling Smørgrav    If there is no common English abbreviation, use numeric offsets like
566bc421551SDag-Erling Smørgrav    <code>-</code>05 and <code>+</code>0530 that are generated
567bc421551SDag-Erling Smørgrav    by <code>zic</code>'s <code>%z</code> notation.
568bc421551SDag-Erling Smørgrav  </li>
569bc421551SDag-Erling Smørgrav  <li>
570bc421551SDag-Erling Smørgrav    Use current abbreviations for older timestamps to avoid confusion.
571bc421551SDag-Erling Smørgrav    For example, in 1910 a common English abbreviation for time
572bc421551SDag-Erling Smørgrav    in central Europe was 'MEZ' (short for both "Middle European
573bc421551SDag-Erling Smørgrav    Zone" and for "Mitteleuropäische Zeit" in German).
574bc421551SDag-Erling Smørgrav    Nowadays 'CET' ("Central European Time") is more common in
575bc421551SDag-Erling Smørgrav    English, and the database uses 'CET' even for circa-1910
576bc421551SDag-Erling Smørgrav    timestamps as this is less confusing for modern users and avoids
577bc421551SDag-Erling Smørgrav    the need for determining when 'CET' supplanted 'MEZ' in common
578bc421551SDag-Erling Smørgrav    usage.
579bc421551SDag-Erling Smørgrav  </li>
580bc421551SDag-Erling Smørgrav  <li>
581bc421551SDag-Erling Smørgrav    Use a consistent style in a timezone's history.
582bc421551SDag-Erling Smørgrav    For example, if a history tends to use numeric
583bc421551SDag-Erling Smørgrav    abbreviations and a particular entry could go either way, use a
584bc421551SDag-Erling Smørgrav    numeric abbreviation.
585bc421551SDag-Erling Smørgrav  </li>
586bc421551SDag-Erling Smørgrav  <li>
587bc421551SDag-Erling Smørgrav    Use
588bc421551SDag-Erling Smørgrav    <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a>
589bc421551SDag-Erling Smørgrav    (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
590bc421551SDag-Erling Smørgrav    locations while uninhabited.
591bc421551SDag-Erling Smørgrav    The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
592bc421551SDag-Erling Smørgrav    some sense undefined; this notation is derived
593*967a49a2SDag-Erling Smørgrav    from <a href="https://www.rfc-editor.org/rfc/rfc3339">Internet
594bc421551SDag-Erling Smørgrav    <abbr title="Request For Comments">RFC</abbr> 3339</a>.
595a979394aSDag-Erling Smørgrav    (The abbreviation 'Z' that
596*967a49a2SDag-Erling Smørgrav    <a href="https://www.rfc-editor.org/rfc/rfc9557">Internet
597a979394aSDag-Erling Smørgrav    <abbr>RFC</abbr> 9557</a> uses for this concept
598a979394aSDag-Erling Smørgrav    would violate the POSIX requirement
599a979394aSDag-Erling Smørgrav    of at least three characters in an abbreviation.)
600bc421551SDag-Erling Smørgrav  </li>
601bc421551SDag-Erling Smørgrav</ul>
602bc421551SDag-Erling Smørgrav
603bc421551SDag-Erling Smørgrav<p>
604bc421551SDag-Erling SmørgravApplication writers should note that these abbreviations are ambiguous
605bc421551SDag-Erling Smørgravin practice: e.g., 'CST' means one thing in China and something else
606bc421551SDag-Erling Smørgravin North America, and 'IST' can refer to time in India, Ireland or
607bc421551SDag-Erling SmørgravIsrael.
608bc421551SDag-Erling SmørgravTo avoid ambiguity, use numeric <abbr>UT</abbr> offsets like
609bc421551SDag-Erling Smørgrav'<code>-</code>0600' instead of time zone abbreviations like 'CST'.
610bc421551SDag-Erling Smørgrav</p>
611bc421551SDag-Erling Smørgrav</section>
612bc421551SDag-Erling Smørgrav
613bc421551SDag-Erling Smørgrav<section>
614bc421551SDag-Erling Smørgrav  <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
615bc421551SDag-Erling Smørgrav<p>
616bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> database is not authoritative, and it
617bc421551SDag-Erling Smørgravsurely has errors.
618bc421551SDag-Erling SmørgravCorrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
619bc421551SDag-Erling SmørgravUsers requiring authoritative data should consult national standards
620bc421551SDag-Erling Smørgravbodies and the references cited in the database's comments.
621bc421551SDag-Erling Smørgrav</p>
622bc421551SDag-Erling Smørgrav
623bc421551SDag-Erling Smørgrav<p>
624bc421551SDag-Erling SmørgravErrors in the <code><abbr>tz</abbr></code> database arise from many sources:
625bc421551SDag-Erling Smørgrav</p>
626bc421551SDag-Erling Smørgrav
627bc421551SDag-Erling Smørgrav<ul>
628bc421551SDag-Erling Smørgrav  <li>
629bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> database predicts future
630bc421551SDag-Erling Smørgrav    timestamps, and current predictions
631bc421551SDag-Erling Smørgrav    will be incorrect after future governments change the rules.
632bc421551SDag-Erling Smørgrav    For example, if today someone schedules a meeting for 13:00 next
633bc421551SDag-Erling Smørgrav    October 1, Casablanca time, and tomorrow Morocco changes its
634bc421551SDag-Erling Smørgrav    daylight saving rules, software can mess up after the rule change
635bc421551SDag-Erling Smørgrav    if it blithely relies on conversions made before the change.
636bc421551SDag-Erling Smørgrav  </li>
637bc421551SDag-Erling Smørgrav  <li>
638bc421551SDag-Erling Smørgrav    The pre-1970 entries in this database cover only a tiny sliver of how
639bc421551SDag-Erling Smørgrav    clocks actually behaved; the vast majority of the necessary
640bc421551SDag-Erling Smørgrav    information was lost or never recorded.
641bc421551SDag-Erling Smørgrav    Thousands more timezones would be needed if
642bc421551SDag-Erling Smørgrav    the <code><abbr>tz</abbr></code> database's scope were extended to
643bc421551SDag-Erling Smørgrav    cover even just the known or guessed history of standard time; for
644bc421551SDag-Erling Smørgrav    example, the current single entry for France would need to split
645bc421551SDag-Erling Smørgrav    into dozens of entries, perhaps hundreds.
646bc421551SDag-Erling Smørgrav    And in most of the world even this approach would be misleading
647bc421551SDag-Erling Smørgrav    due to widespread disagreement or indifference about what times
648bc421551SDag-Erling Smørgrav    should be observed.
649bc421551SDag-Erling Smørgrav    In her 2015 book
650bc421551SDag-Erling Smørgrav    <cite><a
651bc421551SDag-Erling Smørgrav    href="https://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The
652bc421551SDag-Erling Smørgrav    Global Transformation of Time, 1870&ndash;1950</a></cite>,
653bc421551SDag-Erling Smørgrav    Vanessa Ogle writes
654bc421551SDag-Erling Smørgrav    "Outside of Europe and North America there was no system of time
655bc421551SDag-Erling Smørgrav    zones at all, often not even a stable landscape of mean times,
656bc421551SDag-Erling Smørgrav    prior to the middle decades of the twentieth century".
657bc421551SDag-Erling Smørgrav    See: Timothy Shenk, <a
658bc421551SDag-Erling Smørgravhref="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked:
659bc421551SDag-Erling Smørgrav      A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17.
660bc421551SDag-Erling Smørgrav  </li>
661bc421551SDag-Erling Smørgrav  <li>
662bc421551SDag-Erling Smørgrav    Most of the pre-1970 data entries come from unreliable sources, often
663bc421551SDag-Erling Smørgrav    astrology books that lack citations and whose compilers evidently
664bc421551SDag-Erling Smørgrav    invented entries when the true facts were unknown, without
665bc421551SDag-Erling Smørgrav    reporting which entries were known and which were invented.
666bc421551SDag-Erling Smørgrav    These books often contradict each other or give implausible entries,
667bc421551SDag-Erling Smørgrav    and on the rare occasions when they are checked they are
668bc421551SDag-Erling Smørgrav    typically found to be incorrect.
669bc421551SDag-Erling Smørgrav  </li>
670bc421551SDag-Erling Smørgrav  <li>
671bc421551SDag-Erling Smørgrav    For the UK the <code><abbr>tz</abbr></code> database relies on
672bc421551SDag-Erling Smørgrav    years of first-class work done by
673bc421551SDag-Erling Smørgrav    Joseph Myers and others; see
674bc421551SDag-Erling Smørgrav    "<a href="https://www.polyomino.org.uk/british-time/">History of
675bc421551SDag-Erling Smørgrav    legal time in Britain</a>".
676bc421551SDag-Erling Smørgrav    Other countries are not done nearly as well.
677bc421551SDag-Erling Smørgrav  </li>
678bc421551SDag-Erling Smørgrav  <li>
679bc421551SDag-Erling Smørgrav    Sometimes, different people in the same city maintain clocks
680bc421551SDag-Erling Smørgrav    that differ significantly.
681bc421551SDag-Erling Smørgrav    Historically, railway time was used by railroad companies (which
682bc421551SDag-Erling Smørgrav    did not always
683bc421551SDag-Erling Smørgrav    agree with each other), church-clock time was used for birth
684bc421551SDag-Erling Smørgrav    certificates, etc.
685bc421551SDag-Erling Smørgrav    More recently, competing political groups might disagree about
686bc421551SDag-Erling Smørgrav    clock settings. Often this is merely common practice, but
687bc421551SDag-Erling Smørgrav    sometimes it is set by law.
688bc421551SDag-Erling Smørgrav    For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France
689bc421551SDag-Erling Smørgrav    was legally <abbr>UT</abbr> +00:09:21 outside train stations and
690bc421551SDag-Erling Smørgrav    <abbr>UT</abbr> +00:04:21 inside. Other examples include
691bc421551SDag-Erling Smørgrav    Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and
692bc421551SDag-Erling Smørgrav    Ürümqi to this day.
693bc421551SDag-Erling Smørgrav  </li>
694bc421551SDag-Erling Smørgrav  <li>
695bc421551SDag-Erling Smørgrav    Although a named location in the <code><abbr>tz</abbr></code>
696bc421551SDag-Erling Smørgrav    database stands for the containing region, its pre-1970 data
697bc421551SDag-Erling Smørgrav    entries are often accurate for only a small subset of that region.
698bc421551SDag-Erling Smørgrav    For example, <code>Europe/London</code> stands for the United
699bc421551SDag-Erling Smørgrav    Kingdom, but its pre-1847 times are valid only for locations that
700bc421551SDag-Erling Smørgrav    have London's exact meridian, and its 1847 transition
701bc421551SDag-Erling Smørgrav    to <abbr>GMT</abbr> is known to be valid only for the L&amp;NW and
702bc421551SDag-Erling Smørgrav    the Caledonian railways.
703bc421551SDag-Erling Smørgrav  </li>
704bc421551SDag-Erling Smørgrav  <li>
705bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> database does not record the
706bc421551SDag-Erling Smørgrav    earliest time for which a timezone's
707bc421551SDag-Erling Smørgrav    data entries are thereafter valid for every location in the region.
708bc421551SDag-Erling Smørgrav    For example, <code>Europe/London</code> is valid for all locations
709bc421551SDag-Erling Smørgrav    in its region after <abbr>GMT</abbr> was made the standard time,
710bc421551SDag-Erling Smørgrav    but the date of standardization (1880-08-02) is not in the
711bc421551SDag-Erling Smørgrav    <code><abbr>tz</abbr></code> database, other than in commentary.
712bc421551SDag-Erling Smørgrav    For many timezones the earliest time of
713bc421551SDag-Erling Smørgrav    validity is unknown.
714bc421551SDag-Erling Smørgrav  </li>
715bc421551SDag-Erling Smørgrav  <li>
716bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> database does not record a
717bc421551SDag-Erling Smørgrav    region's boundaries, and in many cases the boundaries are not known.
718bc421551SDag-Erling Smørgrav    For example, the timezone
719bc421551SDag-Erling Smørgrav    <code>America/Kentucky/Louisville</code> represents a region
720bc421551SDag-Erling Smørgrav    around the city of Louisville, the boundaries of which are
721bc421551SDag-Erling Smørgrav    unclear.
722bc421551SDag-Erling Smørgrav  </li>
723bc421551SDag-Erling Smørgrav  <li>
724bc421551SDag-Erling Smørgrav    Changes that are modeled as instantaneous transitions in the
725bc421551SDag-Erling Smørgrav    <code><abbr>tz</abbr></code>
726bc421551SDag-Erling Smørgrav    database were often spread out over hours, days, or even decades.
727bc421551SDag-Erling Smørgrav  </li>
728bc421551SDag-Erling Smørgrav  <li>
729bc421551SDag-Erling Smørgrav    Even if the time is specified by law, locations sometimes
730bc421551SDag-Erling Smørgrav    deliberately flout the law.
731bc421551SDag-Erling Smørgrav  </li>
732bc421551SDag-Erling Smørgrav  <li>
733bc421551SDag-Erling Smørgrav    Early timekeeping practices, even assuming perfect clocks, were
734bc421551SDag-Erling Smørgrav    often not specified to the accuracy that the
735bc421551SDag-Erling Smørgrav    <code><abbr>tz</abbr></code> database requires.
736bc421551SDag-Erling Smørgrav  </li>
737bc421551SDag-Erling Smørgrav  <li>
738bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
739bc421551SDag-Erling Smørgrav    However, on 1911-03-11 at 00:00, some public-facing French clocks
740bc421551SDag-Erling Smørgrav    were changed by stopping them for a few minutes to effect a transition.
741bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> database models this via a
742bc421551SDag-Erling Smørgrav    backward transition; the relevant French legislation does not
743bc421551SDag-Erling Smørgrav    specify exactly how the transition was to occur.
744bc421551SDag-Erling Smørgrav  </li>
745bc421551SDag-Erling Smørgrav  <li>
746bc421551SDag-Erling Smørgrav    Sometimes historical timekeeping was specified more precisely
747bc421551SDag-Erling Smørgrav    than what the <code><abbr>tz</abbr></code> code can handle.
748bc421551SDag-Erling Smørgrav    For example, from 1880 to 1916 clocks in Ireland observed Dublin Mean
749bc421551SDag-Erling Smørgrav    Time (estimated to be <abbr>UT</abbr>
750bc421551SDag-Erling Smørgrav    &minus;00:25:21.1); although the <code><abbr>tz</abbr></code>
751bc421551SDag-Erling Smørgrav    source data can represent the .1 second, TZif files and the code cannot.
752bc421551SDag-Erling Smørgrav    In practice these old specifications were rarely if ever
753bc421551SDag-Erling Smørgrav    implemented to subsecond precision.
754bc421551SDag-Erling Smørgrav  </li>
755bc421551SDag-Erling Smørgrav  <li>
756bc421551SDag-Erling Smørgrav    Even when all the timestamp transitions recorded by the
757bc421551SDag-Erling Smørgrav    <code><abbr>tz</abbr></code> database are correct, the
758bc421551SDag-Erling Smørgrav    <code><abbr>tz</abbr></code> rules that generate them may not
759bc421551SDag-Erling Smørgrav    faithfully reflect the historical rules.
760bc421551SDag-Erling Smørgrav    For example, from 1922 until World War II the UK moved clocks
761bc421551SDag-Erling Smørgrav    forward the day following the third Saturday in April unless that
762bc421551SDag-Erling Smørgrav    was Easter, in which case it moved clocks forward the previous
763bc421551SDag-Erling Smørgrav    Sunday.
764bc421551SDag-Erling Smørgrav    Because the <code><abbr>tz</abbr></code> database has no
765bc421551SDag-Erling Smørgrav    way to specify Easter, these exceptional years are entered as
766bc421551SDag-Erling Smørgrav    separate <code><abbr>tz</abbr> Rule</code> lines, even though the
767bc421551SDag-Erling Smørgrav    legal rules did not change.
768bc421551SDag-Erling Smørgrav    When transitions are known but the historical rules behind them are not,
769bc421551SDag-Erling Smørgrav    the database contains <code>Zone</code> and <code>Rule</code>
770bc421551SDag-Erling Smørgrav    entries that are intended to represent only the generated
771bc421551SDag-Erling Smørgrav    transitions, not any underlying historical rules; however, this
772bc421551SDag-Erling Smørgrav    intent is recorded at best only in commentary.
773bc421551SDag-Erling Smørgrav  </li>
774bc421551SDag-Erling Smørgrav  <li>
775bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> database models time
776bc421551SDag-Erling Smørgrav    using the <a
777bc421551SDag-Erling Smørgrav    href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic
778bc421551SDag-Erling Smørgrav    Gregorian calendar</a> with days containing 24 equal-length hours
779bc421551SDag-Erling Smørgrav    numbered 00 through 23, except when clock transitions occur.
780bc421551SDag-Erling Smørgrav    Pre-standard time is modeled as local mean time.
781bc421551SDag-Erling Smørgrav    However, historically many people used other calendars and other timescales.
782bc421551SDag-Erling Smørgrav    For example, the Roman Empire used
783bc421551SDag-Erling Smørgrav    the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian
784bc421551SDag-Erling Smørgrav    calendar</a>,
785bc421551SDag-Erling Smørgrav    and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman
786bc421551SDag-Erling Smørgrav    timekeeping</a> had twelve varying-length daytime hours with a
787bc421551SDag-Erling Smørgrav    non-hour-based system at night.
788bc421551SDag-Erling Smørgrav    And even today, some local practices diverge from the Gregorian
789bc421551SDag-Erling Smørgrav    calendar with 24-hour days. These divergences range from
790bc421551SDag-Erling Smørgrav    relatively minor, such as Japanese bars giving times like "24:30" for the
791bc421551SDag-Erling Smørgrav    wee hours of the morning, to more-significant differences such as <a
79246c59934SDag-Erling Smørgrav    href="https://theworld.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the
793bc421551SDag-Erling Smørgrav    east African practice of starting the day at dawn</a>, renumbering
794bc421551SDag-Erling Smørgrav    the Western 06:00 to be 12:00. These practices are largely outside
795bc421551SDag-Erling Smørgrav    the scope of the <code><abbr>tz</abbr></code> code and data, which
796bc421551SDag-Erling Smørgrav    provide only limited support for date and time localization
797a979394aSDag-Erling Smørgrav    such as that required by POSIX.
798bc421551SDag-Erling Smørgrav    If <abbr>DST</abbr> is not used a different time zone
799bc421551SDag-Erling Smørgrav    can often do the trick; for example, in Kenya a <code>TZ</code> setting
800bc421551SDag-Erling Smørgrav    like <code>&lt;-03&gt;3</code> or <code>America/Cayenne</code> starts
801bc421551SDag-Erling Smørgrav    the day six hours later than <code>Africa/Nairobi</code> does.
802bc421551SDag-Erling Smørgrav  </li>
803bc421551SDag-Erling Smørgrav  <li>
804bc421551SDag-Erling Smørgrav    Early clocks were less reliable, and data entries do not represent
805bc421551SDag-Erling Smørgrav    clock error.
806bc421551SDag-Erling Smørgrav  </li>
807bc421551SDag-Erling Smørgrav  <li>
808bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> database assumes Universal Time
809bc421551SDag-Erling Smørgrav    (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not
810bc421551SDag-Erling Smørgrav    standardized for older timestamps.
811bc421551SDag-Erling Smørgrav    In the <code><abbr>tz</abbr></code> database commentary,
812bc421551SDag-Erling Smørgrav    <abbr>UT</abbr> denotes a family of time standards that includes
813bc421551SDag-Erling Smørgrav    Coordinated Universal Time (<abbr>UTC</abbr>) along with other
814bc421551SDag-Erling Smørgrav    variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>,
815bc421551SDag-Erling Smørgrav    with days starting at midnight.
816bc421551SDag-Erling Smørgrav    Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern
817bc421551SDag-Erling Smørgrav    timestamps, <abbr>UTC</abbr> was not defined until 1960, so
81875411d15SDag-Erling Smørgrav    commentary uses the more general abbreviation <abbr>UT</abbr> for
819bc421551SDag-Erling Smørgrav    timestamps that might predate 1960.
820bc421551SDag-Erling Smørgrav    Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly,
821bc421551SDag-Erling Smørgrav    and since pre-1972 <abbr>UTC</abbr> seconds varied in length,
822bc421551SDag-Erling Smørgrav    interpretation of older timestamps can be problematic when
823bc421551SDag-Erling Smørgrav    subsecond accuracy is needed.
824bc421551SDag-Erling Smørgrav  </li>
825bc421551SDag-Erling Smørgrav  <li>
826bc421551SDag-Erling Smørgrav    Civil time was not based on atomic time before 1972, and we do not
827bc421551SDag-Erling Smørgrav    know the history of
828bc421551SDag-Erling Smørgrav    <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's
829bc421551SDag-Erling Smørgrav    rotation</a> accurately enough to map <a
830bc421551SDag-Erling Smørgrav    href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr
831bc421551SDag-Erling Smørgrav    title="International System of Units">SI</abbr></a> seconds to
832bc421551SDag-Erling Smørgrav    historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a>
833bc421551SDag-Erling Smørgrav    to more than about one-hour accuracy.
834bc421551SDag-Erling Smørgrav    See: Stephenson FR, Morrison LV, Hohenkerk CY.
835bc421551SDag-Erling Smørgrav    <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of
836bc421551SDag-Erling Smørgrav    the Earth's rotation: 720 BC to AD 2015</a>.
837bc421551SDag-Erling Smørgrav    <cite>Proc Royal Soc A</cite>. 2016;472:20160404.
838bc421551SDag-Erling Smørgrav    Also see: Espenak F. <a
839bc421551SDag-Erling Smørgrav    href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty
840bc421551SDag-Erling Smørgrav    in Delta T (ΔT)</a>.
841bc421551SDag-Erling Smørgrav  </li>
842bc421551SDag-Erling Smørgrav  <li>
843bc421551SDag-Erling Smørgrav    The relationship between POSIX time (that is, <abbr>UTC</abbr> but
844bc421551SDag-Erling Smørgrav    ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap
84575411d15SDag-Erling Smørgrav    seconds</a>) and <abbr>UTC</abbr> is not agreed upon.
84675411d15SDag-Erling Smørgrav    This affects time stamps during the leap second era (1972&ndash;2035).
847bc421551SDag-Erling Smørgrav    Although the POSIX
848bc421551SDag-Erling Smørgrav    clock officially stops during an inserted leap second, at least one
849bc421551SDag-Erling Smørgrav    proposed standard has it jumping back a second instead; and in
850bc421551SDag-Erling Smørgrav    practice POSIX clocks more typically either progress glacially during
851bc421551SDag-Erling Smørgrav    a leap second, or are slightly slowed while near a leap second.
852bc421551SDag-Erling Smørgrav  </li>
853bc421551SDag-Erling Smørgrav  <li>
854bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> database does not represent how
855bc421551SDag-Erling Smørgrav    uncertain its information is.
856bc421551SDag-Erling Smørgrav    Ideally it would contain information about when data entries are
857bc421551SDag-Erling Smørgrav    incomplete or dicey.
858bc421551SDag-Erling Smørgrav    Partial temporal knowledge is a field of active research, though,
859bc421551SDag-Erling Smørgrav    and it is not clear how to apply it here.
860bc421551SDag-Erling Smørgrav  </li>
861bc421551SDag-Erling Smørgrav</ul>
862bc421551SDag-Erling Smørgrav
863bc421551SDag-Erling Smørgrav<p>
864bc421551SDag-Erling SmørgravIn short, many, perhaps most, of the <code><abbr>tz</abbr></code>
865bc421551SDag-Erling Smørgravdatabase's pre-1970 and future timestamps are either wrong or
866bc421551SDag-Erling Smørgravmisleading.
867bc421551SDag-Erling SmørgravAny attempt to pass the
868bc421551SDag-Erling Smørgrav<code><abbr>tz</abbr></code> database off as the definition of time
869bc421551SDag-Erling Smørgravshould be unacceptable to anybody who cares about the facts.
870bc421551SDag-Erling SmørgravIn particular, the <code><abbr>tz</abbr></code> database's
871bc421551SDag-Erling Smørgrav<abbr>LMT</abbr> offsets should not be considered meaningful, and
872bc421551SDag-Erling Smørgravshould not prompt creation of timezones
873bc421551SDag-Erling Smørgravmerely because two locations
874bc421551SDag-Erling Smørgravdiffer in <abbr>LMT</abbr> or transitioned to standard time at
875bc421551SDag-Erling Smørgravdifferent dates.
876bc421551SDag-Erling Smørgrav</p>
877bc421551SDag-Erling Smørgrav</section>
878bc421551SDag-Erling Smørgrav
879bc421551SDag-Erling Smørgrav<section>
880bc421551SDag-Erling Smørgrav  <h2 id="functions">Time and date functions</h2>
881bc421551SDag-Erling Smørgrav<p>
882bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> code contains time and date functions
883bc421551SDag-Erling Smørgravthat are upwards compatible with those of POSIX.
884bc421551SDag-Erling SmørgravCode compatible with this package is already
885bc421551SDag-Erling Smørgrav<a href="tz-link.html#tzdb">part of many platforms</a>, where the
886bc421551SDag-Erling Smørgravprimary use of this package is to update obsolete time-related files.
887bc421551SDag-Erling SmørgravTo do this, you may need to compile the time zone compiler
888a979394aSDag-Erling Smørgrav<code>zic</code> supplied with this package instead of using the
889a979394aSDag-Erling Smørgravsystem <code>zic</code>, since the format of <code>zic</code>'s
890bc421551SDag-Erling Smørgravinput is occasionally extended, and a platform may still be shipping
891bc421551SDag-Erling Smørgravan older <code>zic</code>.
892bc421551SDag-Erling Smørgrav</p>
893bc421551SDag-Erling Smørgrav
894a979394aSDag-Erling Smørgrav<p>
895a979394aSDag-Erling SmørgravIn POSIX, time display in a process is controlled by the
896a979394aSDag-Erling Smørgravenvironment variable <code>TZ</code>, which can have two forms:
897a979394aSDag-Erling Smørgrav</p>
898bc421551SDag-Erling Smørgrav<ul>
899bc421551SDag-Erling Smørgrav  <li>
900a979394aSDag-Erling Smørgrav    A <dfn>proleptic <code>TZ</code></dfn> value
901a979394aSDag-Erling Smørgrav    like <code>CET-1CEST,M3.5.0,M10.5.0/3</code> uses a complex
902a979394aSDag-Erling Smørgrav    notation that specifies a single standard time along with daylight
903a979394aSDag-Erling Smørgrav    saving rules that apply to all years past, present, and future.
904a979394aSDag-Erling Smørgrav  </li>
905a979394aSDag-Erling Smørgrav  <li>
906a979394aSDag-Erling Smørgrav    A <dfn>geographical <code>TZ</code></dfn> value
907a979394aSDag-Erling Smørgrav    like <code>Europe/Berlin</code> names a location that stands for
908a979394aSDag-Erling Smørgrav    civil time near that location, which can have more than
909a979394aSDag-Erling Smørgrav    one standard time and more than one set of daylight saving rules,
910a979394aSDag-Erling Smørgrav    to record timekeeping practice more accurately.
911a979394aSDag-Erling Smørgrav    These names are defined by the <code><abbr>tz</abbr></code> database.
912a979394aSDag-Erling Smørgrav  </li>
913a979394aSDag-Erling Smørgrav</ul>
914a979394aSDag-Erling Smørgrav
915a979394aSDag-Erling Smørgrav<h3 id="POSIX.1-2017">POSIX.1-2017 properties and limitations</h3>
916bc421551SDag-Erling Smørgrav<p>
917a979394aSDag-Erling SmørgravSome platforms support only the features required by POSIX.1-2017,
918a979394aSDag-Erling Smørgravand have not yet upgraded to POSIX.1-2024.
919a979394aSDag-Erling SmørgravCode intended to be portable to these platforms must deal
920a979394aSDag-Erling Smørgravwith problems that were fixed in later POSIX editions.
921a979394aSDag-Erling Smørgrav</p>
922a979394aSDag-Erling Smørgrav
923a979394aSDag-Erling Smørgrav<ul>
924a979394aSDag-Erling Smørgrav  <li>
925a979394aSDag-Erling Smørgrav    POSIX.1-2017 does not require support for geographical <code>TZ</code>,
926a979394aSDag-Erling Smørgrav    and there is no convenient and efficient way to determine
927a979394aSDag-Erling Smørgrav    the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary
928a979394aSDag-Erling Smørgrav    timestamps, particularly for timezones
929a979394aSDag-Erling Smørgrav    that do not fit into the POSIX model.
930a979394aSDag-Erling Smørgrav  </li>
931a979394aSDag-Erling Smørgrav  <li>
932a979394aSDag-Erling Smørgrav    <p>
933a979394aSDag-Erling Smørgrav    The proleptic <code>TZ</code> string,
934a979394aSDag-Erling Smørgrav    which is all that POSIX.1-2017 requires,
935a979394aSDag-Erling Smørgrav    has a format that is hard to describe and is error-prone in practice.
936a979394aSDag-Erling Smørgrav    Also, proleptic <code>TZ</code> strings cannot deal with daylight
937bc421551SDag-Erling Smørgrav    saving time rules not based on the Gregorian calendar (as in
93875411d15SDag-Erling Smørgrav    Morocco), or with situations where more than two time zone
939bc421551SDag-Erling Smørgrav    abbreviations or <abbr>UT</abbr> offsets are used in an area.
940bc421551SDag-Erling Smørgrav    </p>
941bc421551SDag-Erling Smørgrav
942bc421551SDag-Erling Smørgrav    <p>
943a979394aSDag-Erling Smørgrav    A proleptic <code>TZ</code> string has the following format:
944bc421551SDag-Erling Smørgrav    </p>
945bc421551SDag-Erling Smørgrav
946bc421551SDag-Erling Smørgrav    <p>
947bc421551SDag-Erling Smørgrav    <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>]]]
948bc421551SDag-Erling Smørgrav    </p>
949bc421551SDag-Erling Smørgrav
950bc421551SDag-Erling Smørgrav    <p>
951bc421551SDag-Erling Smørgrav    where:
952bc421551SDag-Erling Smørgrav    </p>
953bc421551SDag-Erling Smørgrav
954bc421551SDag-Erling Smørgrav    <dl>
955bc421551SDag-Erling Smørgrav      <dt><var>std</var> and <var>dst</var></dt><dd>
956bc421551SDag-Erling Smørgrav	are 3 or more characters specifying the standard
957bc421551SDag-Erling Smørgrav	and daylight saving time (<abbr>DST</abbr>) zone abbreviations.
958bc421551SDag-Erling Smørgrav	Starting with POSIX.1-2001, <var>std</var> and <var>dst</var>
959bc421551SDag-Erling Smørgrav	may also be in a quoted form like '<code>&lt;+09&gt;</code>';
960bc421551SDag-Erling Smørgrav	this allows "<code>+</code>" and "<code>-</code>" in the names.
961bc421551SDag-Erling Smørgrav      </dd>
962bc421551SDag-Erling Smørgrav      <dt><var>offset</var></dt><dd>
963bc421551SDag-Erling Smørgrav	is of the form
964bc421551SDag-Erling Smørgrav	'<code>[&plusmn;]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>'
965bc421551SDag-Erling Smørgrav	and specifies the offset west of <abbr>UT</abbr>.
966bc421551SDag-Erling Smørgrav	'<var>hh</var>' may be a single digit;
967bc421551SDag-Erling Smørgrav	0&le;<var>hh</var>&le;24.
968bc421551SDag-Erling Smørgrav	The default <abbr>DST</abbr> offset is one hour ahead of
969bc421551SDag-Erling Smørgrav	standard time.
970bc421551SDag-Erling Smørgrav      </dd>
971bc421551SDag-Erling Smørgrav      <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
972bc421551SDag-Erling Smørgrav	specifies the beginning and end of <abbr>DST</abbr>.
973bc421551SDag-Erling Smørgrav	If this is absent, the system supplies its own ruleset
97475411d15SDag-Erling Smørgrav	for <abbr>DST</abbr>, typically	current <abbr>US</abbr>
97575411d15SDag-Erling Smørgrav	<abbr>DST</abbr> rules.
976bc421551SDag-Erling Smørgrav      </dd>
977bc421551SDag-Erling Smørgrav      <dt><var>time</var></dt><dd>
978bc421551SDag-Erling Smørgrav	takes the form
979bc421551SDag-Erling Smørgrav	'<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
980bc421551SDag-Erling Smørgrav	and defaults to 02:00.
981bc421551SDag-Erling Smørgrav	This is the same format as the offset, except that a
982bc421551SDag-Erling Smørgrav	leading '<code>+</code>' or '<code>-</code>' is not allowed.
983bc421551SDag-Erling Smørgrav      </dd>
984bc421551SDag-Erling Smørgrav      <dt><var>date</var></dt><dd>
985bc421551SDag-Erling Smørgrav	takes one of the following forms:
986bc421551SDag-Erling Smørgrav	<dl>
987bc421551SDag-Erling Smørgrav	  <dt>J<var>n</var> (1&le;<var>n</var>&le;365)</dt><dd>
988bc421551SDag-Erling Smørgrav	    origin-1 day number not counting February 29
989bc421551SDag-Erling Smørgrav	  </dd>
990bc421551SDag-Erling Smørgrav	  <dt><var>n</var> (0&le;<var>n</var>&le;365)</dt><dd>
991bc421551SDag-Erling Smørgrav	    origin-0 day number counting February 29 if present
992bc421551SDag-Erling Smørgrav	  </dd>
993bc421551SDag-Erling Smørgrav	  <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
994bc421551SDag-Erling Smørgrav	    (0[Sunday]&le;<var>d</var>&le;6[Saturday], 1&le;<var>n</var>&le;5,
995bc421551SDag-Erling Smørgrav	    1&le;<var>m</var>&le;12)</dt><dd>
996bc421551SDag-Erling Smørgrav	    for the <var>d</var>th day of week <var>n</var> of
997bc421551SDag-Erling Smørgrav	    month <var>m</var> of the year, where week 1 is the first
998bc421551SDag-Erling Smørgrav	    week in which day <var>d</var> appears, and
999bc421551SDag-Erling Smørgrav	    '<code>5</code>' stands for the last week in which
1000bc421551SDag-Erling Smørgrav	    day <var>d</var> appears (which may be either the 4th or
1001bc421551SDag-Erling Smørgrav	    5th week).
1002bc421551SDag-Erling Smørgrav	    Typically, this is the only useful form; the <var>n</var>
1003bc421551SDag-Erling Smørgrav	    and <code>J</code><var>n</var> forms are rarely used.
1004bc421551SDag-Erling Smørgrav	  </dd>
1005bc421551SDag-Erling Smørgrav	</dl>
1006bc421551SDag-Erling Smørgrav      </dd>
1007bc421551SDag-Erling Smørgrav    </dl>
1008bc421551SDag-Erling Smørgrav
1009bc421551SDag-Erling Smørgrav    <p>
1010a979394aSDag-Erling Smørgrav    Here is an example proleptic <code>TZ</code> string for New
1011bc421551SDag-Erling Smørgrav    Zealand after 2007.
1012bc421551SDag-Erling Smørgrav    It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead
1013bc421551SDag-Erling Smørgrav    of <abbr>UT</abbr>, and that daylight saving time
1014bc421551SDag-Erling Smørgrav    (<abbr>NZDT</abbr>) is observed from September's last Sunday at
1015bc421551SDag-Erling Smørgrav    02:00 until April's first Sunday at 03:00:
1016bc421551SDag-Erling Smørgrav    </p>
1017bc421551SDag-Erling Smørgrav
1018bc421551SDag-Erling Smørgrav    <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
1019bc421551SDag-Erling Smørgrav
1020bc421551SDag-Erling Smørgrav    <p>
1021a979394aSDag-Erling Smørgrav    This proleptic <code>TZ</code> string is hard to remember, and
1022bc421551SDag-Erling Smørgrav    mishandles some timestamps before 2008.
1023a979394aSDag-Erling Smørgrav    With this package you can use a geographical <code>TZ</code> instead:
1024bc421551SDag-Erling Smørgrav    </p>
1025bc421551SDag-Erling Smørgrav
1026bc421551SDag-Erling Smørgrav    <pre><code>TZ='Pacific/Auckland'</code></pre>
1027bc421551SDag-Erling Smørgrav  </li>
1028a979394aSDag-Erling Smørgrav</ul>
1029a979394aSDag-Erling Smørgrav
1030a979394aSDag-Erling Smørgrav<p>
1031a979394aSDag-Erling SmørgravPOSIX.1-2017 also has the limitations of POSIX.1-2024,
1032a979394aSDag-Erling Smørgravdiscussed in the next section.
1033a979394aSDag-Erling Smørgrav</p>
1034a979394aSDag-Erling Smørgrav
1035a979394aSDag-Erling Smørgrav<h3 id="POSIX.1-2024">POSIX.1-2024 properties and limitations</h3>
1036a979394aSDag-Erling Smørgrav<p>
1037a979394aSDag-Erling SmørgravPOSIX.1-2024 extends POSIX.1-2017 in the following significant ways:
1038a979394aSDag-Erling Smørgrav</p>
1039a979394aSDag-Erling Smørgrav<ul>
1040bc421551SDag-Erling Smørgrav  <li>
1041a979394aSDag-Erling Smørgrav    POSIX.1-2024 requires support for geographical <code>TZ</code>.
1042a979394aSDag-Erling Smørgrav    Earlier POSIX editions require support only for proleptic <code>TZ</code>.
1043bc421551SDag-Erling Smørgrav  </li>
1044bc421551SDag-Erling Smørgrav  <li>
1045a979394aSDag-Erling Smørgrav    POSIX.1-2024 requires <code>struct tm</code>
1046a979394aSDag-Erling Smørgrav    to have a <abbr>UT</abbr> offset member <code>tm_gmtoff</code>
1047a979394aSDag-Erling Smørgrav    and a time zone abbreviation member <code>tm_zone</code>.
1048a979394aSDag-Erling Smørgrav    Earlier POSIX editions lack this requirement.
1049a979394aSDag-Erling Smørgrav  </li>
1050a979394aSDag-Erling Smørgrav  <li>
1051a979394aSDag-Erling Smørgrav    DST transition times can range from &minus;167:59:59
1052a979394aSDag-Erling Smørgrav    to 167:59:59 instead of merely from 00:00:00 to 24:59:59.
1053a979394aSDag-Erling Smørgrav    This allows for proleptic TZ strings
1054a979394aSDag-Erling Smørgrav    like <code>"&lt;-02&gt;2&lt;-01&gt;,M3.5.0/-1,M10.5.0/0"</code>
1055a979394aSDag-Erling Smørgrav    where the transition time &minus;1:00 means 23:00 the previous day.
1056a979394aSDag-Erling Smørgrav  </li>
1057a979394aSDag-Erling Smørgrav</ul>
1058a979394aSDag-Erling Smørgrav<p>
1059a979394aSDag-Erling SmørgravHowever POSIX.1-2024, like earlier POSIX editions, has some limitations:
1060a979394aSDag-Erling Smørgrav<ul>
1061a979394aSDag-Erling Smørgrav  <li>
1062bc421551SDag-Erling Smørgrav    The <code>TZ</code> environment variable is process-global, which
1063bc421551SDag-Erling Smørgrav    makes it hard to write efficient, thread-safe applications that
1064bc421551SDag-Erling Smørgrav    need access to multiple timezones.
1065bc421551SDag-Erling Smørgrav  </li>
1066bc421551SDag-Erling Smørgrav  <li>
1067bc421551SDag-Erling Smørgrav    In POSIX, there is no tamper-proof way for a process to learn the
1068bc421551SDag-Erling Smørgrav    system's best idea of local (wall clock) time.
1069bc421551SDag-Erling Smørgrav    This is important for applications that an administrator wants
1070bc421551SDag-Erling Smørgrav    used only at certain times &ndash; without regard to whether the
1071bc421551SDag-Erling Smørgrav    user has fiddled the
1072bc421551SDag-Erling Smørgrav    <code>TZ</code> environment variable.
1073bc421551SDag-Erling Smørgrav    While an administrator can "do everything in <abbr>UT</abbr>" to
1074bc421551SDag-Erling Smørgrav    get around the problem, doing so is inconvenient and precludes
1075bc421551SDag-Erling Smørgrav    handling daylight saving time shifts &ndash; as might be required to
1076bc421551SDag-Erling Smørgrav    limit phone calls to off-peak hours.
1077bc421551SDag-Erling Smørgrav  </li>
1078bc421551SDag-Erling Smørgrav  <li>
1079bc421551SDag-Erling Smørgrav    POSIX requires that <code>time_t</code> clock counts exclude leap
1080bc421551SDag-Erling Smørgrav    seconds.
1081bc421551SDag-Erling Smørgrav  </li>
1082bc421551SDag-Erling Smørgrav  <li>
1083a979394aSDag-Erling Smørgrav    POSIX does not define the <abbr>DST</abbr> transitions
1084a979394aSDag-Erling Smørgrav    for <code>TZ</code> values like
1085a979394aSDag-Erling Smørgrav    "<code>EST5EDT</code>".
1086a979394aSDag-Erling Smørgrav    Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
1087a979394aSDag-Erling Smørgrav    were used to interpret such values, but this meant that the
1088a979394aSDag-Erling Smørgrav    <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
1089a979394aSDag-Erling Smørgrav    time conversion package, and when
1090a979394aSDag-Erling Smørgrav    <abbr>US</abbr> time conversion rules changed (as in the United
1091a979394aSDag-Erling Smørgrav    States in 1987 and again in 2007), all packages that
1092a979394aSDag-Erling Smørgrav    interpreted <code>TZ</code> values had to be updated
1093a979394aSDag-Erling Smørgrav    to ensure proper results.
1094a979394aSDag-Erling Smørgrav  </li>
1095a979394aSDag-Erling Smørgrav</ul>
1096a979394aSDag-Erling Smørgrav
1097a979394aSDag-Erling Smørgrav<h3 id="POSIX-extensions">Extensions to POSIX in the
1098a979394aSDag-Erling Smørgrav<code><abbr>tz</abbr></code> code</h3>
1099a979394aSDag-Erling Smørgrav<p>
1100a979394aSDag-Erling Smørgrav  The <code><abbr>tz</abbr></code> code defines some properties
1101a979394aSDag-Erling Smørgrav  left unspecified by POSIX, and attempts to support some
1102a979394aSDag-Erling Smørgrav  extensions to POSIX.
1103a979394aSDag-Erling Smørgrav</p>
1104a979394aSDag-Erling Smørgrav
1105a979394aSDag-Erling Smørgrav<ul>
1106a979394aSDag-Erling Smørgrav  <li>
1107bc421551SDag-Erling Smørgrav    The <code><abbr>tz</abbr></code> code attempts to support all the
1108bc421551SDag-Erling Smørgrav    <code>time_t</code> implementations allowed by POSIX.
1109bc421551SDag-Erling Smørgrav    The <code>time_t</code> type represents a nonnegative count of seconds
1110bc421551SDag-Erling Smørgrav    since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds.
1111bc421551SDag-Erling Smørgrav    In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1112bc421551SDag-Erling Smørgrav    integer; 32-bit signed <code>time_t</code> values stop working after
1113bc421551SDag-Erling Smørgrav    2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these
1114bc421551SDag-Erling Smørgrav    days typically use a signed 64-bit integer.
1115bc421551SDag-Erling Smørgrav    Unsigned 32-bit integers are used on one or two platforms, and 36-bit
1116bc421551SDag-Erling Smørgrav    and 40-bit integers are also used occasionally.
1117bc421551SDag-Erling Smørgrav    Although earlier POSIX versions allowed <code>time_t</code> to be a
1118bc421551SDag-Erling Smørgrav    floating-point type, this was not supported by any practical system,
1119a979394aSDag-Erling Smørgrav    and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both
1120bc421551SDag-Erling Smørgrav    require <code>time_t</code> to be an integer type.
1121bc421551SDag-Erling Smørgrav  </li>
1122bc421551SDag-Erling Smørgrav  <li>
1123bc421551SDag-Erling Smørgrav    <p>
1124a979394aSDag-Erling Smørgrav    If the <code>TZ</code> environment variable uses the geographical format,
1125a979394aSDag-Erling Smørgrav    it is used in generating
1126a979394aSDag-Erling Smørgrav    the name of a file from which time-related information is read.
1127bc421551SDag-Erling Smørgrav    The file's format is <dfn><abbr>TZif</abbr></dfn>,
1128bc421551SDag-Erling Smørgrav    a timezone information format that contains binary data; see
1129*967a49a2SDag-Erling Smørgrav    <a href="https://www.rfc-editor.org/rfc/9636">Internet
1130*967a49a2SDag-Erling Smørgrav    <abbr>RFC</abbr> 9636</a>.
1131bc421551SDag-Erling Smørgrav    The daylight saving time rules to be used for a
1132bc421551SDag-Erling Smørgrav    particular timezone are encoded in the
1133bc421551SDag-Erling Smørgrav    <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
1134bc421551SDag-Erling Smørgrav    Australian, and other rules to be encoded, and
1135bc421551SDag-Erling Smørgrav    allows for situations where more than two time zone
1136bc421551SDag-Erling Smørgrav    abbreviations are used.
1137bc421551SDag-Erling Smørgrav    </p>
1138bc421551SDag-Erling Smørgrav    <p>
1139a979394aSDag-Erling Smørgrav    When the <code><abbr>tz</abbr></code> code was developed in the 1980s,
1140a979394aSDag-Erling Smørgrav    it was recognized that allowing the <code>TZ</code> environment
1141bc421551SDag-Erling Smørgrav    variable to take on values such as '<code>America/New_York</code>'
1142bc421551SDag-Erling Smørgrav    might cause "old" programs (that expect <code>TZ</code> to have a
1143a979394aSDag-Erling Smørgrav    certain format) to operate incorrectly; consideration was given to using
1144bc421551SDag-Erling Smørgrav    some other environment variable (for example, <code>TIMEZONE</code>)
1145bc421551SDag-Erling Smørgrav    to hold the string used to generate the <abbr>TZif</abbr> file's name.
1146bc421551SDag-Erling Smørgrav    In the end, however, it was decided to continue using
1147bc421551SDag-Erling Smørgrav    <code>TZ</code>: it is widely used for time zone purposes;
1148bc421551SDag-Erling Smørgrav    separately maintaining both <code>TZ</code>
1149bc421551SDag-Erling Smørgrav    and <code>TIMEZONE</code> seemed a nuisance; and systems where
1150bc421551SDag-Erling Smørgrav    "new" forms of <code>TZ</code> might cause problems can simply
1151bc421551SDag-Erling Smørgrav    use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1152bc421551SDag-Erling Smørgrav    can be used by "new" programs as well as by "old" programs that
1153bc421551SDag-Erling Smørgrav    assume pre-POSIX <code>TZ</code> values.
1154bc421551SDag-Erling Smørgrav    </p>
1155bc421551SDag-Erling Smørgrav  </li>
1156bc421551SDag-Erling Smørgrav  <li>
1157bc421551SDag-Erling Smørgrav    Functions <code>tzalloc</code>, <code>tzfree</code>,
1158bc421551SDag-Erling Smørgrav    <code>localtime_rz</code>, and <code>mktime_z</code> for
1159bc421551SDag-Erling Smørgrav    more-efficient thread-safe applications that need to use multiple
1160bc421551SDag-Erling Smørgrav    timezones.
1161bc421551SDag-Erling Smørgrav    The <code>tzalloc</code> and <code>tzfree</code> functions
1162bc421551SDag-Erling Smørgrav    allocate and free objects of type <code>timezone_t</code>,
1163bc421551SDag-Erling Smørgrav    and <code>localtime_rz</code> and <code>mktime_z</code> are
1164bc421551SDag-Erling Smørgrav    like <code>localtime_r</code> and <code>mktime</code> with an
1165bc421551SDag-Erling Smørgrav    extra <code>timezone_t</code> argument.
1166a979394aSDag-Erling Smørgrav    The functions were inspired by <a href="https://netbsd.org">NetBSD</a>.
1167bc421551SDag-Erling Smørgrav  </li>
1168bc421551SDag-Erling Smørgrav  <li>
1169bc421551SDag-Erling Smørgrav    Negative <code>time_t</code> values are supported, on systems
1170bc421551SDag-Erling Smørgrav    where <code>time_t</code> is signed.
1171bc421551SDag-Erling Smørgrav  </li>
1172bc421551SDag-Erling Smørgrav  <li>
1173bc421551SDag-Erling Smørgrav    These functions can account for leap seconds;
1174bc421551SDag-Erling Smørgrav    see <a href="#leapsec">Leap seconds</a> below.
1175bc421551SDag-Erling Smørgrav  </li>
1176bc421551SDag-Erling Smørgrav</ul>
1177bc421551SDag-Erling Smørgrav
1178bc421551SDag-Erling Smørgrav<h3 id="vestigial">POSIX features no longer needed</h3>
1179bc421551SDag-Erling Smørgrav<p>
1180bc421551SDag-Erling SmørgravPOSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a>
1181bc421551SDag-Erling Smørgravdefine some <a href="https://en.wikipedia.org/wiki/API"><abbr
1182bc421551SDag-Erling Smørgravtitle="application programming interface">API</abbr>s</a> that are vestigial:
1183bc421551SDag-Erling Smørgravthey are not needed, and are relics of a too-simple model that does
1184bc421551SDag-Erling Smørgravnot suffice to handle many real-world timestamps.
1185bc421551SDag-Erling SmørgravAlthough the <code><abbr>tz</abbr></code> code supports these
1186bc421551SDag-Erling Smørgravvestigial <abbr>API</abbr>s for backwards compatibility, they should
1187bc421551SDag-Erling Smørgravbe avoided in portable applications.
1188bc421551SDag-Erling SmørgravThe vestigial <abbr>API</abbr>s are:
1189bc421551SDag-Erling Smørgrav</p>
1190bc421551SDag-Erling Smørgrav<ul>
1191bc421551SDag-Erling Smørgrav  <li>
1192bc421551SDag-Erling Smørgrav    The POSIX <code>tzname</code> variable does not suffice and is no
1193bc421551SDag-Erling Smørgrav    longer needed.
1194a979394aSDag-Erling Smørgrav    It is planned to be removed in a future edition of POSIX.
1195bc421551SDag-Erling Smørgrav    To get a timestamp's time zone abbreviation, consult
1196bc421551SDag-Erling Smørgrav    the <code>tm_zone</code> member if available; otherwise,
1197bc421551SDag-Erling Smørgrav    use <code>strftime</code>'s <code>"%Z"</code> conversion
1198bc421551SDag-Erling Smørgrav    specification.
1199bc421551SDag-Erling Smørgrav  </li>
1200bc421551SDag-Erling Smørgrav  <li>
1201bc421551SDag-Erling Smørgrav    The POSIX <code>daylight</code> and <code>timezone</code>
1202bc421551SDag-Erling Smørgrav    variables do not suffice and are no longer needed.
1203a979394aSDag-Erling Smørgrav    They are planned to be removed in a future edition of POSIX.
1204bc421551SDag-Erling Smørgrav    To get a timestamp's <abbr>UT</abbr> offset, consult
1205bc421551SDag-Erling Smørgrav    the <code>tm_gmtoff</code> member if available; otherwise,
1206bc421551SDag-Erling Smørgrav    subtract values returned by <code>localtime</code>
1207bc421551SDag-Erling Smørgrav    and <code>gmtime</code> using the rules of the Gregorian calendar,
1208bc421551SDag-Erling Smørgrav    or use <code>strftime</code>'s <code>"%z"</code> conversion
1209bc421551SDag-Erling Smørgrav    specification if a string like <code>"+0900"</code> suffices.
1210bc421551SDag-Erling Smørgrav  </li>
1211bc421551SDag-Erling Smørgrav  <li>
1212bc421551SDag-Erling Smørgrav    The <code>tm_isdst</code> member is almost never needed and most of
1213bc421551SDag-Erling Smørgrav    its uses should be discouraged in favor of the abovementioned
1214bc421551SDag-Erling Smørgrav    <abbr>API</abbr>s.
1215*967a49a2SDag-Erling Smørgrav    It was intended as an index into the <code>tzname</code> variable,
1216*967a49a2SDag-Erling Smørgrav    but as mentioned previously that usage is obsolete.
1217bc421551SDag-Erling Smørgrav    Although it can still be used in arguments to
1218bc421551SDag-Erling Smørgrav    <code>mktime</code> to disambiguate timestamps near
1219bc421551SDag-Erling Smørgrav    a <abbr>DST</abbr> transition when the clock jumps back on
1220bc421551SDag-Erling Smørgrav    platforms lacking <code>tm_gmtoff</code>, this
1221*967a49a2SDag-Erling Smørgrav    disambiguation works only for proleptic <code>TZ</code> strings;
1222*967a49a2SDag-Erling Smørgrav    it does not work in general for geographical timezones,
1223*967a49a2SDag-Erling Smørgrav    such as when a location changes to a time zone with a
1224bc421551SDag-Erling Smørgrav    lesser <abbr>UT</abbr> offset.
1225bc421551SDag-Erling Smørgrav  </li>
1226bc421551SDag-Erling Smørgrav</ul>
1227bc421551SDag-Erling Smørgrav
1228bc421551SDag-Erling Smørgrav<h3 id="other-portability">Other portability notes</h3>
1229bc421551SDag-Erling Smørgrav<ul>
1230bc421551SDag-Erling Smørgrav  <li>
1231bc421551SDag-Erling Smørgrav    The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition
1232bc421551SDag-Erling Smørgrav    UNIX</a> <code>timezone</code> function is not present in this
1233bc421551SDag-Erling Smørgrav    package; it is impossible to reliably map <code>timezone</code>'s
1234bc421551SDag-Erling Smørgrav    arguments (a "minutes west of <abbr>GMT</abbr>" value and a
1235bc421551SDag-Erling Smørgrav    "daylight saving time in effect" flag) to a time zone
1236bc421551SDag-Erling Smørgrav    abbreviation, and we refuse to guess.
1237bc421551SDag-Erling Smørgrav    Programs that in the past used the <code>timezone</code> function
1238bc421551SDag-Erling Smørgrav    may now examine <code>localtime(&amp;clock)-&gt;tm_zone</code>
1239bc421551SDag-Erling Smørgrav    (if <code>TM_ZONE</code> is defined) or
1240*967a49a2SDag-Erling Smørgrav    use <code>strftime</code> with a <code>%Z</code> conversion specification
1241*967a49a2SDag-Erling Smørgrav    to learn the correct time
1242bc421551SDag-Erling Smørgrav    zone abbreviation to use.
1243bc421551SDag-Erling Smørgrav  </li>
1244bc421551SDag-Erling Smørgrav  <li>
1245bc421551SDag-Erling Smørgrav    The <a
1246bc421551SDag-Erling Smørgrav    href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a>
1247bc421551SDag-Erling Smørgrav    <code>gettimeofday</code> function is not
1248bc421551SDag-Erling Smørgrav    used in this package.
1249bc421551SDag-Erling Smørgrav    This formerly let users obtain the current <abbr>UTC</abbr> offset
1250bc421551SDag-Erling Smørgrav    and <abbr>DST</abbr> flag, but this functionality was removed in
1251bc421551SDag-Erling Smørgrav    later versions of <abbr>BSD</abbr>.
1252bc421551SDag-Erling Smørgrav  </li>
1253bc421551SDag-Erling Smørgrav  <li>
1254bc421551SDag-Erling Smørgrav    In <abbr>SVR2</abbr>, time conversion fails for near-minimum or
1255bc421551SDag-Erling Smørgrav    near-maximum <code>time_t</code> values when doing conversions
1256bc421551SDag-Erling Smørgrav    for places that do not use <abbr>UT</abbr>.
1257bc421551SDag-Erling Smørgrav    This package takes care to do these conversions correctly.
1258bc421551SDag-Erling Smørgrav    A comment in the source code tells how to get compatibly wrong
1259bc421551SDag-Erling Smørgrav    results.
1260bc421551SDag-Erling Smørgrav  </li>
1261bc421551SDag-Erling Smørgrav  <li>
1262bc421551SDag-Erling Smørgrav    The functions that are conditionally compiled
126375411d15SDag-Erling Smørgrav    if <code>STD_INSPIRED</code> is nonzero should, at this point, be
1264bc421551SDag-Erling Smørgrav    looked on primarily as food for thought.
1265bc421551SDag-Erling Smørgrav    They are not in any sense "standard compatible" &ndash; some are
1266bc421551SDag-Erling Smørgrav    not, in fact, specified in <em>any</em> standard.
1267bc421551SDag-Erling Smørgrav    They do, however, represent responses of various authors to
1268bc421551SDag-Erling Smørgrav    standardization proposals.
1269bc421551SDag-Erling Smørgrav  </li>
1270bc421551SDag-Erling Smørgrav  <li>
1271bc421551SDag-Erling Smørgrav    Other time conversion proposals, in particular those supported by the
1272bc421551SDag-Erling Smørgrav    <a href="https://howardhinnant.github.io/date/tz.html">Time Zone
1273bc421551SDag-Erling Smørgrav    Database Parser</a>, offer a wider selection of functions
1274bc421551SDag-Erling Smørgrav    that provide capabilities beyond those provided here.
1275bc421551SDag-Erling Smørgrav    The absence of such functions from this package is not meant to
1276bc421551SDag-Erling Smørgrav    discourage the development, standardization, or use of such
1277bc421551SDag-Erling Smørgrav    functions.
1278bc421551SDag-Erling Smørgrav    Rather, their absence reflects the decision to make this package
1279bc421551SDag-Erling Smørgrav    contain valid extensions to POSIX, to ensure its broad
1280bc421551SDag-Erling Smørgrav    acceptability.
1281bc421551SDag-Erling Smørgrav    If more powerful time conversion functions can be standardized, so
1282bc421551SDag-Erling Smørgrav    much the better.
1283bc421551SDag-Erling Smørgrav  </li>
1284bc421551SDag-Erling Smørgrav</ul>
1285bc421551SDag-Erling Smørgrav</section>
1286bc421551SDag-Erling Smørgrav
1287bc421551SDag-Erling Smørgrav<section>
1288bc421551SDag-Erling Smørgrav  <h2 id="stability">Interface stability</h2>
1289bc421551SDag-Erling Smørgrav<p>
1290bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1291bc421551SDag-Erling Smørgrav</p>
1292bc421551SDag-Erling Smørgrav
1293bc421551SDag-Erling Smørgrav<ul>
1294bc421551SDag-Erling Smørgrav  <li>
1295bc421551SDag-Erling Smørgrav    A set of timezone names as per
1296bc421551SDag-Erling Smørgrav      "<a href="#naming">Timezone identifiers</a>" above.
1297bc421551SDag-Erling Smørgrav  </li>
1298bc421551SDag-Erling Smørgrav  <li>
1299bc421551SDag-Erling Smørgrav    Library functions described in "<a href="#functions">Time and date
1300bc421551SDag-Erling Smørgrav      functions</a>" above.
1301bc421551SDag-Erling Smørgrav  </li>
1302bc421551SDag-Erling Smørgrav  <li>
1303bc421551SDag-Erling Smørgrav    The programs <code>tzselect</code>, <code>zdump</code>,
1304bc421551SDag-Erling Smørgrav    and <code>zic</code>, documented in their man pages.
1305bc421551SDag-Erling Smørgrav  </li>
1306bc421551SDag-Erling Smørgrav  <li>
1307bc421551SDag-Erling Smørgrav    The format of <code>zic</code> input files, documented in
1308bc421551SDag-Erling Smørgrav    the <code>zic</code> man page.
1309bc421551SDag-Erling Smørgrav  </li>
1310bc421551SDag-Erling Smørgrav  <li>
1311bc421551SDag-Erling Smørgrav    The format of <code>zic</code> output files, documented in
1312bc421551SDag-Erling Smørgrav    the <code>tzfile</code> man page.
1313bc421551SDag-Erling Smørgrav  </li>
1314bc421551SDag-Erling Smørgrav  <li>
1315bc421551SDag-Erling Smørgrav    The format of zone table files, documented in <code>zone1970.tab</code>.
1316bc421551SDag-Erling Smørgrav  </li>
1317bc421551SDag-Erling Smørgrav  <li>
1318bc421551SDag-Erling Smørgrav    The format of the country code file, documented in <code>iso3166.tab</code>.
1319bc421551SDag-Erling Smørgrav  </li>
1320bc421551SDag-Erling Smørgrav  <li>
1321bc421551SDag-Erling Smørgrav    The version number of the code and data, as the first line of
1322bc421551SDag-Erling Smørgrav    the text file '<code>version</code>' in each release.
1323bc421551SDag-Erling Smørgrav  </li>
1324bc421551SDag-Erling Smørgrav</ul>
1325bc421551SDag-Erling Smørgrav
1326bc421551SDag-Erling Smørgrav<p>
1327bc421551SDag-Erling SmørgravInterface changes in a release attempt to preserve compatibility with
1328bc421551SDag-Erling Smørgravrecent releases.
1329bc421551SDag-Erling SmørgravFor example, <code><abbr>tz</abbr></code> data files typically do not
133075411d15SDag-Erling Smørgravrely on recently added <code>zic</code> features, so that users can
1331bc421551SDag-Erling Smørgravrun older <code>zic</code> versions to process newer data files.
1332bc421551SDag-Erling Smørgrav<a href="tz-link.html#download">Downloading
1333bc421551SDag-Erling Smørgravthe <code><abbr>tz</abbr></code> database</a> describes how releases
1334bc421551SDag-Erling Smørgravare tagged and distributed.
1335bc421551SDag-Erling Smørgrav</p>
1336bc421551SDag-Erling Smørgrav
1337bc421551SDag-Erling Smørgrav<p>
1338bc421551SDag-Erling SmørgravInterfaces not listed above are less stable.
1339bc421551SDag-Erling SmørgravFor example, users should not rely on particular <abbr>UT</abbr>
1340bc421551SDag-Erling Smørgravoffsets or abbreviations for timestamps, as data entries are often
1341bc421551SDag-Erling Smørgravbased on guesswork and these guesses may be corrected or improved.
1342bc421551SDag-Erling Smørgrav</p>
1343bc421551SDag-Erling Smørgrav
1344bc421551SDag-Erling Smørgrav<p>
1345bc421551SDag-Erling SmørgravTimezone boundaries are not part of the stable interface.
1346bc421551SDag-Erling SmørgravFor example, even though the <samp>Asia/Bangkok</samp> timezone
1347bc421551SDag-Erling Smørgravcurrently includes Chang Mai, Hanoi, and Phnom Penh, this is not part
1348bc421551SDag-Erling Smørgravof the stable interface and the timezone can split at any time.
1349bc421551SDag-Erling SmørgravIf a calendar application records a future event in some location other
1350bc421551SDag-Erling Smørgravthan Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record,
1351bc421551SDag-Erling Smørgravthe application should be robust in the presence of timezone splits
1352bc421551SDag-Erling Smørgravbetween now and the future time.
1353bc421551SDag-Erling Smørgrav</p>
1354bc421551SDag-Erling Smørgrav</section>
1355bc421551SDag-Erling Smørgrav
1356bc421551SDag-Erling Smørgrav<section>
1357bc421551SDag-Erling Smørgrav  <h2 id="leapsec">Leap seconds</h2>
1358bc421551SDag-Erling Smørgrav<p>
135975411d15SDag-Erling SmørgravLeap seconds were introduced in 1972 to accommodate the
136075411d15SDag-Erling Smørgravdifference between atomic time and the less regular rotation of the earth.
1361a979394aSDag-Erling SmørgravUnfortunately they have caused so many problems with civil
1362a979394aSDag-Erling Smørgravtimekeeping that there are
1363a979394aSDag-Erling Smørgrav<a href="https://www.bipm.org/en/cgpm-2022/resolution-4">plans
1364a979394aSDag-Erling Smørgravto discontinue them by 2035</a>.
1365a979394aSDag-Erling SmørgravEven if these plans come to fruition, a record of leap seconds will still be
1366a979394aSDag-Erling Smørgravneeded to resolve timestamps from 1972 through 2035,
1367a979394aSDag-Erling Smørgravand there may also be a need to record whatever mechanism replaces them.
136875411d15SDag-Erling Smørgrav</p>
136975411d15SDag-Erling Smørgrav
137075411d15SDag-Erling Smørgrav<p>
1371bc421551SDag-Erling SmørgravThe <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1372bc421551SDag-Erling Smørgravthanks to code contributed by Bradley White.
1373bc421551SDag-Erling SmørgravHowever, the leap second support of this package is rarely used directly
1374bc421551SDag-Erling Smørgravbecause POSIX requires leap seconds to be excluded and many
1375bc421551SDag-Erling Smørgravsoftware packages would mishandle leap seconds if they were present.
1376bc421551SDag-Erling SmørgravInstead, leap seconds are more commonly handled by occasionally adjusting
1377bc421551SDag-Erling Smørgravthe operating system kernel clock as described in
1378bc421551SDag-Erling Smørgrav<a href="tz-link.html#precision">Precision timekeeping</a>,
1379bc421551SDag-Erling Smørgravand this package by default installs a <samp>leapseconds</samp> file
1380bc421551SDag-Erling Smørgravcommonly used by
1381bc421551SDag-Erling Smørgrav<a href="https://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a>
1382bc421551SDag-Erling Smørgravsoftware that adjusts the kernel clock.
1383bc421551SDag-Erling SmørgravHowever, kernel-clock twiddling approximates UTC only roughly,
138475411d15SDag-Erling Smørgravand systems needing more precise UTC can use this package's leap
1385bc421551SDag-Erling Smørgravsecond support directly.
1386bc421551SDag-Erling Smørgrav</p>
1387bc421551SDag-Erling Smørgrav
1388bc421551SDag-Erling Smørgrav<p>
138975411d15SDag-Erling SmørgravThe directly supported mechanism assumes that <code>time_t</code>
1390bc421551SDag-Erling Smørgravcounts of seconds since the POSIX epoch normally include leap seconds,
1391bc421551SDag-Erling Smørgravas opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1392bc421551SDag-Erling SmørgravThis modified timescale is converted to <abbr>UTC</abbr>
1393bc421551SDag-Erling Smørgravat the same point that time zone and <abbr>DST</abbr>
1394bc421551SDag-Erling Smørgravadjustments are applied &ndash;
1395bc421551SDag-Erling Smørgravnamely, at calls to <code>localtime</code> and analogous functions &ndash;
1396bc421551SDag-Erling Smørgravand the process is driven by leap second information
1397bc421551SDag-Erling Smørgravstored in alternate versions of the <abbr>TZif</abbr> files.
1398bc421551SDag-Erling SmørgravBecause a leap second adjustment may be needed even
1399bc421551SDag-Erling Smørgravif no time zone correction is desired,
1400bc421551SDag-Erling Smørgravcalls to <code>gmtime</code>-like functions
1401bc421551SDag-Erling Smørgravalso need to consult a <abbr>TZif</abbr> file,
1402bc421551SDag-Erling Smørgravconventionally named <samp><abbr>Etc/UTC</abbr></samp>
1403bc421551SDag-Erling Smørgrav(<samp><abbr>GMT</abbr></samp> in previous versions),
1404bc421551SDag-Erling Smørgravto see whether leap second corrections are needed.
1405bc421551SDag-Erling SmørgravTo convert an application's <code>time_t</code> timestamps to or from
1406bc421551SDag-Erling SmørgravPOSIX <code>time_t</code> timestamps (for use when, say,
1407bc421551SDag-Erling Smørgravembedding or interpreting timestamps in portable
1408bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1409bc421551SDag-Erling Smørgravfiles),
1410bc421551SDag-Erling Smørgravthe application can call the utility functions
1411bc421551SDag-Erling Smørgrav<code>time2posix</code> and <code>posix2time</code>
1412bc421551SDag-Erling Smørgravincluded with this package.
1413bc421551SDag-Erling Smørgrav</p>
1414bc421551SDag-Erling Smørgrav
1415bc421551SDag-Erling Smørgrav<p>
1416bc421551SDag-Erling SmørgravIf the POSIX-compatible <abbr>TZif</abbr> file set is installed
1417bc421551SDag-Erling Smørgravin a directory whose basename is <samp>zoneinfo</samp>, the
1418bc421551SDag-Erling Smørgravleap-second-aware file set is by default installed in a separate
1419bc421551SDag-Erling Smørgravdirectory <samp>zoneinfo-leaps</samp>.
1420bc421551SDag-Erling SmørgravAlthough each process can have its own time zone by setting
1421bc421551SDag-Erling Smørgravits <code>TZ</code> environment variable, there is no support for some
1422bc421551SDag-Erling Smørgravprocesses being leap-second aware while other processes are
1423bc421551SDag-Erling SmørgravPOSIX-compatible; the leap-second choice is system-wide.
1424bc421551SDag-Erling SmørgravSo if you configure your kernel to count leap seconds, you should also
1425bc421551SDag-Erling Smørgravdiscard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp>
1426bc421551SDag-Erling Smørgravto <samp>zoneinfo</samp>.
1427bc421551SDag-Erling SmørgravAlternatively, you can install just one set of <abbr>TZif</abbr> files
1428bc421551SDag-Erling Smørgravin the first place; see the <code>REDO</code> variable in this package's
1429bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>.
1430bc421551SDag-Erling Smørgrav</p>
1431bc421551SDag-Erling Smørgrav</section>
1432bc421551SDag-Erling Smørgrav
1433bc421551SDag-Erling Smørgrav<section>
1434bc421551SDag-Erling Smørgrav  <h2 id="calendar">Calendrical issues</h2>
1435bc421551SDag-Erling Smørgrav<p>
1436bc421551SDag-Erling SmørgravCalendrical issues are a bit out of scope for a time zone database,
1437bc421551SDag-Erling Smørgravbut they indicate the sort of problems that we would run into if we
1438bc421551SDag-Erling Smørgravextended the time zone database further into the past.
1439bc421551SDag-Erling SmørgravAn excellent resource in this area is Edward M. Reingold
1440bc421551SDag-Erling Smørgravand Nachum Dershowitz, <cite><a
1441bc421551SDag-Erling Smørgravhref="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical
1442bc421551SDag-Erling SmørgravCalculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018).
1443bc421551SDag-Erling SmørgravOther information and sources are given in the file '<code>calendars</code>'
1444bc421551SDag-Erling Smørgravin the <code><abbr>tz</abbr></code> distribution.
1445bc421551SDag-Erling SmørgravThey sometimes disagree.
1446bc421551SDag-Erling Smørgrav</p>
1447bc421551SDag-Erling Smørgrav</section>
1448bc421551SDag-Erling Smørgrav
1449bc421551SDag-Erling Smørgrav<section>
145075411d15SDag-Erling Smørgrav  <h2 id="planets">Time and time zones off Earth</h2>
145175411d15SDag-Erling Smørgrav<p>
145275411d15SDag-Erling SmørgravThe European Space Agency is <a
145375411d15SDag-Erling Smørgravhref='https://www.esa.int/Applications/Navigation/Telling_time_on_the_Moon'>considering</a>
145475411d15SDag-Erling Smørgravthe establishment of a reference timescale for the Moon, which has
145575411d15SDag-Erling Smørgravdays roughly equivalent to 29.5 Earth days, and where relativistic
145675411d15SDag-Erling Smørgraveffects cause clocks to tick slightly faster than on Earth.
1457a979394aSDag-Erling SmørgravAlso, <abbr title="National Aeronautics and Space Administration">NASA</abbr>
1458a979394aSDag-Erling Smørgravhas been <a
1459a979394aSDag-Erling Smørgravhref='https://www.whitehouse.gov/wp-content/uploads/2024/04/Celestial-Time-Standardization-Policy.pdf'>ordered</a>
1460a979394aSDag-Erling Smørgravto consider the establishment of Coordinated Lunar Time (<abbr>LTC</abbr>).
1461a979394aSDag-Erling SmørgravIt is not yet known whether the US and European efforts will result in
1462a979394aSDag-Erling Smørgravmultiple timescales on the Moon.
146375411d15SDag-Erling Smørgrav</p>
146475411d15SDag-Erling Smørgrav
1465bc421551SDag-Erling Smørgrav<p>
1466bc421551SDag-Erling SmørgravSome people's work schedules have used
1467bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>.
1468bc421551SDag-Erling SmørgravJet Propulsion Laboratory (JPL) coordinators kept Mars time on
1469bc421551SDag-Erling Smørgravand off during the
1470bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars
1471bc421551SDag-Erling SmørgravPathfinder</a> mission (1997).
1472bc421551SDag-Erling SmørgravSome of their family members also adapted to Mars time.
1473bc421551SDag-Erling SmørgravDozens of special Mars watches were built for JPL workers who kept
1474bc421551SDag-Erling SmørgravMars time during the
1475bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars
1476bc421551SDag-Erling SmørgravExploration Rovers (MER)</a> mission (2004&ndash;2018).
1477bc421551SDag-Erling SmørgravThese timepieces looked like normal Seikos and Citizens but were adjusted
1478bc421551SDag-Erling Smørgravto use Mars seconds rather than terrestrial seconds, although
1479bc421551SDag-Erling Smørgravunfortunately the adjusted watches were unreliable and appear to have
1480bc421551SDag-Erling Smørgravhad only limited use.
1481bc421551SDag-Erling Smørgrav</p>
1482bc421551SDag-Erling Smørgrav
1483bc421551SDag-Erling Smørgrav<p>
1484bc421551SDag-Erling SmørgravA Mars solar day is called a "sol" and has a mean period equal to
1485bc421551SDag-Erling Smørgravabout 24 hours 39 minutes 35.244 seconds in terrestrial time.
1486bc421551SDag-Erling SmørgravIt is divided into a conventional 24-hour clock, so each Mars second
1487bc421551SDag-Erling Smørgravequals about 1.02749125 terrestrial seconds.
1488bc421551SDag-Erling Smørgrav(One MER worker noted, "If I am working Mars hours, and Mars hours are
1489bc421551SDag-Erling Smørgrav2.5% more than Earth hours, shouldn't I get an extra 2.5% pay raise?")
1490bc421551SDag-Erling Smørgrav</p>
1491bc421551SDag-Erling Smørgrav
1492bc421551SDag-Erling Smørgrav<p>
1493bc421551SDag-Erling SmørgravThe <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime
1494bc421551SDag-Erling Smørgravmeridian</a> of Mars goes through the center of the crater
1495bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in
1496bc421551SDag-Erling Smørgravhonor of the British astronomer who built the Greenwich telescope that
1497bc421551SDag-Erling Smørgravdefines Earth's prime meridian.
1498bc421551SDag-Erling SmørgravMean solar time on the Mars prime meridian is
1499bc421551SDag-Erling Smørgravcalled Mars Coordinated Time (<abbr>MTC</abbr>).
1500bc421551SDag-Erling Smørgrav</p>
1501bc421551SDag-Erling Smørgrav
1502bc421551SDag-Erling Smørgrav<p>
1503bc421551SDag-Erling SmørgravEach landed mission on Mars has adopted a different reference for
1504bc421551SDag-Erling Smørgravsolar timekeeping, so there is no real standard for Mars time zones.
1505bc421551SDag-Erling SmørgravFor example, the MER mission defined two time zones "Local
1506bc421551SDag-Erling SmørgravSolar Time A" and "Local Solar Time B" for its two missions, each zone
1507bc421551SDag-Erling Smørgravdesigned so that its time equals local true solar time at
1508bc421551SDag-Erling Smørgravapproximately the middle of the nominal mission.
1509bc421551SDag-Erling SmørgravThe A and B zones differ enough so that an MER worker assigned to
1510bc421551SDag-Erling Smørgravthe A zone might suffer "Mars lag" when switching to work in the B zone.
1511bc421551SDag-Erling SmørgravSuch a "time zone" is not particularly suited for any application
1512bc421551SDag-Erling Smørgravother than the mission itself.
1513bc421551SDag-Erling Smørgrav</p>
1514bc421551SDag-Erling Smørgrav
1515bc421551SDag-Erling Smørgrav<p>
1516bc421551SDag-Erling SmørgravMany calendars have been proposed for Mars, but none have achieved
1517bc421551SDag-Erling Smørgravwide acceptance.
1518bc421551SDag-Erling SmørgravAstronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a
1519bc421551SDag-Erling Smørgravsequential count of Mars solar days elapsed since about 1873-12-29
1520bc421551SDag-Erling Smørgrav12:00 <abbr>GMT</abbr>.
1521bc421551SDag-Erling Smørgrav</p>
1522bc421551SDag-Erling Smørgrav
1523bc421551SDag-Erling Smørgrav<p>
1524bc421551SDag-Erling SmørgravIn our solar system, Mars is the planet with time and calendar most
1525bc421551SDag-Erling Smørgravlike Earth's.
1526bc421551SDag-Erling SmørgravOn other planets, Sun-based time and calendars would work quite
1527bc421551SDag-Erling Smørgravdifferently.
1528bc421551SDag-Erling SmørgravFor example, although Mercury's
1529bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal
1530bc421551SDag-Erling Smørgravrotation period</a> is 58.646 Earth days, Mercury revolves around the
1531bc421551SDag-Erling SmørgravSun so rapidly that an observer on Mercury's equator would see a
1532bc421551SDag-Erling Smørgravsunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a
1533bc421551SDag-Erling SmørgravMercury day.
1534bc421551SDag-Erling SmørgravVenus is more complicated, partly because its rotation is slightly
1535bc421551SDag-Erling Smørgrav<a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>:
1536bc421551SDag-Erling Smørgravits year is 1.92 of its days.
1537bc421551SDag-Erling SmørgravGas giants like Jupiter are trickier still, as their polar and
1538bc421551SDag-Erling Smørgravequatorial regions rotate at different rates, so that the length of a
1539bc421551SDag-Erling Smørgravday depends on latitude.
1540bc421551SDag-Erling SmørgravThis effect is most pronounced on Neptune, where the day is about 12
1541bc421551SDag-Erling Smørgravhours at the poles and 18 hours at the equator.
1542bc421551SDag-Erling Smørgrav</p>
1543bc421551SDag-Erling Smørgrav
1544bc421551SDag-Erling Smørgrav<p>
1545bc421551SDag-Erling SmørgravAlthough the <code><abbr>tz</abbr></code> database does not support
1546bc421551SDag-Erling Smørgravtime on other planets, it is documented here in the hopes that support
1547bc421551SDag-Erling Smørgravwill be added eventually.
1548bc421551SDag-Erling Smørgrav</p>
1549bc421551SDag-Erling Smørgrav
1550bc421551SDag-Erling Smørgrav<p>
1551bc421551SDag-Erling SmørgravSources for time on other planets:
1552bc421551SDag-Erling Smørgrav</p>
1553bc421551SDag-Erling Smørgrav
1554bc421551SDag-Erling Smørgrav<ul>
1555bc421551SDag-Erling Smørgrav  <li>
1556bc421551SDag-Erling Smørgrav    Michael Allison and Robert Schmunk,
1557bc421551SDag-Erling Smørgrav    "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical
1558bc421551SDag-Erling Smørgrav      Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>"
1559bc421551SDag-Erling Smørgrav    (2020-03-08).
1560bc421551SDag-Erling Smørgrav  </li>
1561bc421551SDag-Erling Smørgrav  <li>
1562bc421551SDag-Erling Smørgrav    Zara Mirmalek,
1563bc421551SDag-Erling Smørgrav    <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making
1564bc421551SDag-Erling Smørgrav	Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854.
1565bc421551SDag-Erling Smørgrav  </li>
1566bc421551SDag-Erling Smørgrav  <li>
1567bc421551SDag-Erling Smørgrav    Jia-Rui Chong,
1568bc421551SDag-Erling Smørgrav    "<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays
1569bc421551SDag-Erling Smørgrav    Fit for a Martian</a>", <cite>Los Angeles Times</cite>
1570bc421551SDag-Erling Smørgrav    (2004-01-14), pp A1, A20&ndash;A21.
1571bc421551SDag-Erling Smørgrav  </li>
1572bc421551SDag-Erling Smørgrav  <li>
1573bc421551SDag-Erling Smørgrav    Tom Chmielewski,
1574bc421551SDag-Erling Smørgrav    "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet
1575bc421551SDag-Erling Smørgrav    Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26)
1576bc421551SDag-Erling Smørgrav  </li>
1577bc421551SDag-Erling Smørgrav  <li>
1578bc421551SDag-Erling Smørgrav    Matt Williams,
1579bc421551SDag-Erling Smørgrav    "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How
1580bc421551SDag-Erling Smørgrav    long is a day on the other planets of the solar system?</a>"
1581bc421551SDag-Erling Smørgrav    (2016-01-20).
1582bc421551SDag-Erling Smørgrav  </li>
1583bc421551SDag-Erling Smørgrav</ul>
1584bc421551SDag-Erling Smørgrav</section>
1585bc421551SDag-Erling Smørgrav
1586bc421551SDag-Erling Smørgrav<footer>
1587bc421551SDag-Erling Smørgrav  <hr>
1588bc421551SDag-Erling Smørgrav  This file is in the public domain, so clarified as of 2009-05-17 by
1589bc421551SDag-Erling Smørgrav  Arthur David Olson.
1590bc421551SDag-Erling Smørgrav</footer>
1591bc421551SDag-Erling Smørgrav</body>
1592bc421551SDag-Erling Smørgrav</html>
1593