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