4 <title>Theory and pragmatics of the tz code and data</title>
7 pre {margin-left: 2em; white-space: pre-wrap;}
12 <h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>
16 <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>
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>
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>
31 <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>
34 href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code>
35 database</a> attempts to record the history and predicted future of
37 It organizes <a href="tz-link.html">time zone and daylight saving time
38 data</a> by partitioning the world into <a
39 href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"><dfn>timezones</dfn></a>
40 whose clocks all agree about timestamps that occur after the <a
41 href="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a>
42 (1970-01-01 00:00:00 <a
43 href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr
44 title="Coordinated Universal Time">UTC</abbr></a>).
45 Although 1970 is a somewhat-arbitrary cutoff, there are significant
46 challenges to moving the cutoff earlier even by a decade or two, due
47 to the wide variety of local practices before computer timekeeping
49 Most timezones correspond to a notable location and the database
50 records all known clock transitions for that location;
51 some timezones correspond instead to a fixed <abbr>UTC</abbr> offset.
55 Each timezone typically corresponds to a geographical region that is
56 smaller than a traditional time zone, because clocks in a timezone
57 all agree after 1970 whereas a traditional time zone merely
58 specifies current standard time. For example, applications that deal
59 with current and future timestamps in the traditional North
60 American mountain time zone can choose from the timezones
61 <code>America/Denver</code> which observes US-style daylight saving
62 time (<abbr>DST</abbr>),
63 <code>America/Mazatlan</code> which observes Mexican-style <abbr>DST</abbr>,
64 and <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>.
65 Applications that also deal with past timestamps in the mountain time
66 zone can choose from over a dozen timezones, such as
67 <code>America/Boise</code>, <code>America/Edmonton</code>, and
68 <code>America/Hermosillo</code>, each of which currently uses mountain
69 time but differs from other timezones for some timestamps after 1970.
73 Clock transitions before 1970 are recorded for location-based timezones,
74 because most systems support timestamps before 1970 and could
75 misbehave if data entries were omitted for pre-1970 transitions.
76 However, the database is not designed for and does not suffice for
77 applications requiring accurate handling of all past times everywhere,
78 as it would take far too much effort and guesswork to record all
79 details of pre-1970 civil timekeeping.
80 Although some information outside the scope of the database is
81 collected in a file <code>backzone</code> that is distributed along
82 with the database proper, this file is less reliable and does not
83 necessarily follow database guidelines.
87 As described below, reference source code for using the
88 <code><abbr>tz</abbr></code> database is also available.
89 The <code><abbr>tz</abbr></code> code is upwards compatible with <a
90 href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international
92 href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems.
93 As of this writing, the current edition of POSIX is: <a
94 href="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open
95 Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018
97 Because the database's scope encompasses real-world changes to civil
98 timekeeping, its model for describing time is more complex than the
99 standard and daylight saving times supported by POSIX.
100 A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
101 have more than two changes per year, these changes need not merely
102 flip back and forth between two alternatives, and the rules themselves
104 Whether and when a timezone changes its clock,
105 and even the timezone's notional base offset from <abbr>UTC</abbr>,
107 It does not always make sense to talk about a timezone's
108 "base offset", which is not necessarily a single number.
114 <h2 id="naming">Timezone identifiers</h2>
116 Each timezone has a name that uniquely identifies the timezone.
117 Inexperienced users are not expected to select these names unaided.
118 Distributors should provide documentation and/or a simple selection
119 interface that explains each name via a map or via descriptive text like
120 "Czech Republic" instead of the timezone name "<code>Europe/Prague</code>".
121 If geolocation information is available, a selection interface can
122 locate the user on a timezone map or prioritize names that are
123 geographically close. For an example selection interface, see the
124 <code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.
125 The <a href="http://cldr.unicode.org">Unicode Common Locale Data
126 Repository</a> contains data that may be useful for other selection
127 interfaces; it maps timezone names like <code>Europe/Prague</code> to
128 locale-dependent strings like "Prague", "Praha", "Прага", and "布拉格".
132 The naming conventions attempt to strike a balance
133 among the following goals:
138 Uniquely identify every timezone where clocks have agreed since 1970.
139 This is essential for the intended use: static clocks keeping local
143 Indicate to experts where the timezone's clocks typically are.
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→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.
155 Be portable to a wide variety of implementations.
158 Use a consistent naming conventions over the entire world.
163 Names 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.
167 North and South America share the same area, '<code>America</code>'.
168 Typical names are '<code>Africa/Cairo</code>',
169 '<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
170 Some names are further qualified to help avoid confusion; for example,
171 '<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
172 Indiana from other Petersburgs in America.
176 Here are the general guidelines used for
177 choosing timezone names,
178 in decreasing order of importance:
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
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
195 E.g., prefer <code>America/Noronha</code> to
196 <code>America/Fernando_de_Noronha</code>.
197 Exceptions: see the discussion of legacy names below.
200 A name must not be empty, or contain '<code>//</code>', or
201 start or end with '<code>/</code>'.
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.
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>.
218 Uninhabited regions like the North Pole and Bouvet Island
219 do not need locations, since local time is not defined there.
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.
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.
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>.
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
245 E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
247 <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France
248 has had multiple time zones</a>.
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.
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>.
267 Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
268 <code>Atlantic/Canaries</code>.
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>.
283 Use '<code>_</code>' to represent a space.
286 Omit '<code>.</code>' from abbreviations in names.
287 E.g., prefer <code>Atlantic/St_Helena</code> to
288 <code>Atlantic/St._Helena</code>.
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.
298 If a name is changed, put its old spelling in the
299 '<code>backward</code>' file as a link to the new spelling.
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.
309 Guidelines have evolved with time, and names following old versions of
310 these guidelines might not follow the current version. When guidelines
311 have changed, old names continue to be supported. Guideline changes
312 have included the following:
317 Older versions of this package used a different naming scheme.
318 See 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>').
320 The 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>').
326 Older versions of this package defined legacy names that are
327 incompatible with the first guideline of location names, but which are
329 These legacy names are mostly defined in the file
330 '<code>etcetera</code>'.
331 Also, the file '<code>backward</code>' defines the legacy names
332 '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>',
333 and the file '<code>northamerica</code>' defines the legacy names
334 '<code>EST5EDT</code>', '<code>CST6CDT</code>',
335 '<code>MST7MDT</code>', and '<code>PST8PDT</code>'.
339 Older versions of these guidelines said that
340 there should typically be at least one name for each <a
341 href="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr
342 title="International Organization for Standardization">ISO</abbr>
343 3166-1</a> officially assigned two-letter code for an inhabited
344 country or territory.
345 This old guideline has been dropped, as it was not needed to handle
346 timestamps correctly and it increased maintenance burden.
351 The file <code>zone1970.tab</code> lists geographical locations used
353 It is intended to be an exhaustive list of names for geographic
354 regions as described above; this is a subset of the timezones in the data.
355 Although a <code>zone1970.tab</code> location's
356 <a href="https://en.wikipedia.org/wiki/Longitude">longitude</a>
358 its <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean
359 time (<abbr>LMT</abbr>)</a> offset with one hour for every 15°
360 east longitude, this relationship is not exact.
361 The backward-compatibility file <code>zone.tab</code> is similar
362 but conforms to the older-version guidelines related to <abbr>ISO</abbr> 3166-1;
363 it lists only one country code per entry and unlike <code>zone1970.tab</code>
364 it can list names defined in <code>backward</code>.
368 The database defines each timezone name to be a zone, or a link to a zone.
369 The source file <code>backward</code> defines links for backward
370 compatibility; it does not define zones.
371 Although <code>backward</code> was originally designed to be optional,
372 nowadays distributions typically use it
373 and no great weight should be attached to whether a link
374 is defined in <code>backward</code> or in some other file.
375 The source file <code>etcetera</code> defines names that may be useful
376 on platforms that do not support POSIX-style <code>TZ</code> strings;
377 no other source file other than <code>backward</code>
378 contains links to its zones.
379 One of <code>etcetera</code>'s names is <code>GMT</code>,
380 used by functions like <code>gmtime</code> to obtain leap
381 second information on platforms that support leap seconds.
386 <h2 id="abbreviations">Time zone abbreviations</h2>
388 When this package is installed, it generates time zone abbreviations
389 like '<code>EST</code>' to be compatible with human tradition and POSIX.
390 Here are the general guidelines used for choosing time zone abbreviations,
391 in decreasing order of importance:
396 Use three to six characters that are ASCII alphanumerics or
397 '<code>+</code>' or '<code>-</code>'.
398 Previous editions of this database also used characters like
399 space and '<code>?</code>', but these characters have a
400 special meaning to the
401 <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a>
402 and cause commands like
403 '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a>
404 `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>'
405 to have unexpected effects.
406 Previous editions of this guideline required upper-case letters, but the
407 Congressman who introduced
408 <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro
409 Standard Time</a> preferred "ChST", so lower-case letters are now
411 Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>',
412 '<code>+</code>', and alphanumeric characters from the portable
413 character set in the current locale.
414 In practice ASCII alphanumerics and '<code>+</code>' and
415 '<code>-</code>' are safe in all locales.
418 In other words, in the C locale the POSIX extended regular
419 expression <code>[-+[:alnum:]]{3,6}</code> should match the
421 This guarantees that all abbreviations could have been specified by a
422 POSIX <code>TZ</code> string.
426 Use abbreviations that are in common use among English-speakers,
427 e.g., 'EST' for Eastern Standard Time in North America.
428 We assume that applications translate them to other languages
429 as part of the normal localization process; for example,
430 a French application might translate 'EST' to 'HNE'.
433 <small>These abbreviations (for standard/daylight/etc. time) are:
434 ACST/ACDT Australian Central,
435 AST/ADT/APT/AWT/ADDT Atlantic,
436 AEST/AEDT Australian Eastern,
437 AHST/AHDT Alaska-Hawaii,
439 AWST/AWDT Australian Western,
441 CAT/CAST Central Africa,
442 CET/CEST/CEMT Central European,
444 CST/CDT/CWT/CPT/CDDT Central [North America],
446 GMT/BST/IST/BDST Greenwich,
448 EST/EDT/EWT/EPT/EDDT Eastern [North America],
449 EET/EEST Eastern European,
451 HST/HDT/HWT/HPT Hawaii,
452 HKT/HKST/HKWT Hong Kong,
458 MET/MEST Middle European (a backward-compatibility alias for
461 MST/MDT/MWT/MPT/MDDT Mountain,
462 NST/NDT/NWT/NPT/NDDT Newfoundland,
463 NST/NDT/NWT/NPT Nome,
464 NZMT/NZST New Zealand through 1945,
465 NZST/NZDT New Zealand 1946–present,
467 PST/PDT/PWT/PPT/PDDT Pacific,
471 WAT/WAST West Africa,
472 WET/WEST/WEMT Western European,
473 WIB Waktu Indonesia Barat,
474 WIT Waktu Indonesia Timur,
475 WITA Waktu Indonesia Tengah,
476 YST/YDT/YWT/YPT/YDDT Yukon</small>.
481 For times taken from a city's longitude, use the
482 traditional <var>x</var>MT notation.
483 The only abbreviation like this in current use is '<abbr>GMT</abbr>'.
484 The others are for timestamps before 1960,
485 except that Monrovia Mean Time persisted until 1972.
486 Typically, numeric abbreviations (e.g., '<code>-</code>004430' for
487 MMT) would cause trouble here, as the numeric strings would exceed
488 the POSIX length limit.
492 <small>These abbreviations are:
493 AMT Asunción, Athens;
494 BMT Baghdad, Bangkok, Batavia, Bermuda, Bern, Bogotá, Bridgetown,
496 CMT Calamarca, Caracas, Chisinau, Colón, Córdoba;
502 HMT Havana, Helsinki, Horta, Howrah;
503 IMT Irkutsk, Istanbul;
505 KMT Kaunas, Kiev, Kingston;
506 LMT Lima, Lisbon, local, Luanda;
507 MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo,
510 PMT Paramaribo, Paris, Perm, Pontianak, Prague;
513 RMT Rangoon, Riga, Rome;
516 SMT Santiago, Simferopol, Singapore, Stanley;
524 <small>A few abbreviations also follow the pattern that
525 <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK.
527 BMT/BST for Bermuda 1890–1930,
528 CMT/BST for Calamarca Mean Time and Bolivian Summer Time
530 DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time
532 MMT/MST/MDST for Moscow 1880–1919, and
533 RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926.
538 Use '<abbr>LMT</abbr>' for local mean time of locations before the
539 introduction of standard time; see "<a href="#scope">Scope of the
540 <code><abbr>tz</abbr></code> database</a>".
543 If there is no common English abbreviation, use numeric offsets like
544 <code>-</code>05 and <code>+</code>0530 that are generated
545 by <code>zic</code>'s <code>%z</code> notation.
548 Use current abbreviations for older timestamps to avoid confusion.
549 For example, in 1910 a common English abbreviation for time
550 in central Europe was 'MEZ' (short for both "Middle European
551 Zone" and for "Mitteleuropäische Zeit" in German).
552 Nowadays 'CET' ("Central European Time") is more common in
553 English, and the database uses 'CET' even for circa-1910
554 timestamps as this is less confusing for modern users and avoids
555 the need for determining when 'CET' supplanted 'MEZ' in common
559 Use a consistent style in a timezone's history.
560 For example, if a history tends to use numeric
561 abbreviations and a particular entry could go either way, use a
562 numeric abbreviation.
566 <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a>
567 (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
568 locations while uninhabited.
569 The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
570 some sense undefined; this notation is derived
571 from <a href="https://tools.ietf.org/html/rfc3339">Internet
572 <abbr title="Request For Comments">RFC</abbr> 3339</a>.
577 Application writers should note that these abbreviations are ambiguous
578 in practice: e.g., 'CST' means one thing in China and something else
579 in North America, and 'IST' can refer to time in India, Ireland or
581 To avoid ambiguity, use numeric <abbr>UT</abbr> offsets like
582 '<code>-</code>0600' instead of time zone abbreviations like 'CST'.
587 <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
589 The <code><abbr>tz</abbr></code> database is not authoritative, and it
591 Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
592 Users requiring authoritative data should consult national standards
593 bodies and the references cited in the database's comments.
597 Errors in the <code><abbr>tz</abbr></code> database arise from many sources:
602 The <code><abbr>tz</abbr></code> database predicts future
603 timestamps, and current predictions
604 will be incorrect after future governments change the rules.
605 For example, if today someone schedules a meeting for 13:00 next
606 October 1, Casablanca time, and tomorrow Morocco changes its
607 daylight saving rules, software can mess up after the rule change
608 if it blithely relies on conversions made before the change.
611 The pre-1970 entries in this database cover only a tiny sliver of how
612 clocks actually behaved; the vast majority of the necessary
613 information was lost or never recorded.
614 Thousands more timezones would be needed if
615 the <code><abbr>tz</abbr></code> database's scope were extended to
616 cover even just the known or guessed history of standard time; for
617 example, the current single entry for France would need to split
618 into dozens of entries, perhaps hundreds.
619 And in most of the world even this approach would be misleading
620 due to widespread disagreement or indifference about what times
624 href="http://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The
625 Global Transformation of Time, 1870–1950</a></cite>,
627 "Outside of Europe and North America there was no system of time
628 zones at all, often not even a stable landscape of mean times,
629 prior to the middle decades of the twentieth century".
630 See: Timothy Shenk, <a
631 href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked:
632 A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17.
635 Most of the pre-1970 data entries come from unreliable sources, often
636 astrology books that lack citations and whose compilers evidently
637 invented entries when the true facts were unknown, without
638 reporting which entries were known and which were invented.
639 These books often contradict each other or give implausible entries,
640 and on the rare occasions when they are checked they are
641 typically found to be incorrect.
644 For the UK the <code><abbr>tz</abbr></code> database relies on
645 years of first-class work done by
646 Joseph Myers and others; see
647 "<a href="https://www.polyomino.org.uk/british-time/">History of
648 legal time in Britain</a>".
649 Other countries are not done nearly as well.
652 Sometimes, different people in the same city maintain clocks
653 that differ significantly.
654 Historically, railway time was used by railroad companies (which
656 agree with each other), church-clock time was used for birth
658 More recently, competing political groups might disagree about
659 clock settings. Often this is merely common practice, but
660 sometimes it is set by law.
661 For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France
662 was legally <abbr>UT</abbr> +00:09:21 outside train stations and
663 <abbr>UT</abbr> +00:04:21 inside. Other examples include
664 Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and
668 Although a named location in the <code><abbr>tz</abbr></code>
669 database stands for the containing region, its pre-1970 data
670 entries are often accurate for only a small subset of that region.
671 For example, <code>Europe/London</code> stands for the United
672 Kingdom, but its pre-1847 times are valid only for locations that
673 have London's exact meridian, and its 1847 transition
674 to <abbr>GMT</abbr> is known to be valid only for the L&NW and
675 the Caledonian railways.
678 The <code><abbr>tz</abbr></code> database does not record the
679 earliest time for which a timezone's
680 data entries are thereafter valid for every location in the region.
681 For example, <code>Europe/London</code> is valid for all locations
682 in its region after <abbr>GMT</abbr> was made the standard time,
683 but the date of standardization (1880-08-02) is not in the
684 <code><abbr>tz</abbr></code> database, other than in commentary.
685 For many timezones the earliest time of
689 The <code><abbr>tz</abbr></code> database does not record a
690 region's boundaries, and in many cases the boundaries are not known.
691 For example, the timezone
692 <code>America/Kentucky/Louisville</code> represents a region
693 around the city of Louisville, the boundaries of which are
697 Changes that are modeled as instantaneous transitions in the
698 <code><abbr>tz</abbr></code>
699 database were often spread out over hours, days, or even decades.
702 Even if the time is specified by law, locations sometimes
703 deliberately flout the law.
706 Early timekeeping practices, even assuming perfect clocks, were
707 often not specified to the accuracy that the
708 <code><abbr>tz</abbr></code> database requires.
711 The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
712 However, on 1911-03-11 at 00:00, some public-facing French clocks
713 were changed by stopping them for a few minutes to effect a transition.
714 The <code><abbr>tz</abbr></code> database models this via a
715 backward transition; the relevant French legislation does not
716 specify exactly how the transition was to occur.
719 Sometimes historical timekeeping was specified more precisely
720 than what the <code><abbr>tz</abbr></code> code can handle.
721 For example, from 1880 to 1916 clocks in Ireland observed Dublin Mean
722 Time (estimated to be <abbr>UT</abbr>
723 −00:25:21.1), but the <code><abbr>tz</abbr></code>
724 code cannot represent the fractional second.
725 In practice these old specifications were rarely if ever
726 implemented to subsecond precision.
729 Even when all the timestamp transitions recorded by the
730 <code><abbr>tz</abbr></code> database are correct, the
731 <code><abbr>tz</abbr></code> rules that generate them may not
732 faithfully reflect the historical rules.
733 For example, from 1922 until World War II the UK moved clocks
734 forward the day following the third Saturday in April unless that
735 was Easter, in which case it moved clocks forward the previous
737 Because the <code><abbr>tz</abbr></code> database has no
738 way to specify Easter, these exceptional years are entered as
739 separate <code><abbr>tz</abbr> Rule</code> lines, even though the
740 legal rules did not change.
741 When transitions are known but the historical rules behind them are not,
742 the database contains <code>Zone</code> and <code>Rule</code>
743 entries that are intended to represent only the generated
744 transitions, not any underlying historical rules; however, this
745 intent is recorded at best only in commentary.
748 The <code><abbr>tz</abbr></code> database models time
750 href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic
751 Gregorian calendar</a> with days containing 24 equal-length hours
752 numbered 00 through 23, except when clock transitions occur.
753 Pre-standard time is modeled as local mean time.
754 However, historically many people used other calendars and other timescales.
755 For example, the Roman Empire used
756 the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian
758 and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman
759 timekeeping</a> had twelve varying-length daytime hours with a
760 non-hour-based system at night.
761 And even today, some local practices diverge from the Gregorian
762 calendar with 24-hour days. These divergences range from
763 relatively minor, such as Japanese bars giving times like "24:30" for the
764 wee hours of the morning, to more-significant differences such as <a
765 href="https://www.pri.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the
766 east African practice of starting the day at dawn</a>, renumbering
767 the Western 06:00 to be 12:00. These practices are largely outside
768 the scope of the <code><abbr>tz</abbr></code> code and data, which
769 provide only limited support for date and time localization
770 such as that required by POSIX.
771 If <abbr>DST</abbr> is not used a different time zone
772 can often do the trick; for example, in Kenya a <code>TZ</code> setting
773 like <code><-03>3</code> or <code>America/Cayenne</code> starts
774 the day six hours later than <code>Africa/Nairobi</code> does.
777 Early clocks were less reliable, and data entries do not represent
781 The <code><abbr>tz</abbr></code> database assumes Universal Time
782 (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not
783 standardized for older timestamps.
784 In the <code><abbr>tz</abbr></code> database commentary,
785 <abbr>UT</abbr> denotes a family of time standards that includes
786 Coordinated Universal Time (<abbr>UTC</abbr>) along with other
787 variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>,
788 with days starting at midnight.
789 Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern
790 timestamps, <abbr>UTC</abbr> was not defined until 1960, so
791 commentary uses the more-general abbreviation <abbr>UT</abbr> for
792 timestamps that might predate 1960.
793 Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly,
794 and since pre-1972 <abbr>UTC</abbr> seconds varied in length,
795 interpretation of older timestamps can be problematic when
796 subsecond accuracy is needed.
799 Civil time was not based on atomic time before 1972, and we do not
801 <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's
802 rotation</a> accurately enough to map <a
803 href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr
804 title="International System of Units">SI</abbr></a> seconds to
805 historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a>
806 to more than about one-hour accuracy.
807 See: Stephenson FR, Morrison LV, Hohenkerk CY.
808 <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of
809 the Earth's rotation: 720 BC to AD 2015</a>.
810 <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404.
811 Also see: Espenak F. <a
812 href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty
816 The relationship between POSIX time (that is, <abbr>UTC</abbr> but
817 ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap
818 seconds</a>) and <abbr>UTC</abbr> is not agreed upon after 1972.
820 clock officially stops during an inserted leap second, at least one
821 proposed standard has it jumping back a second instead; and in
822 practice POSIX clocks more typically either progress glacially during
823 a leap second, or are slightly slowed while near a leap second.
826 The <code><abbr>tz</abbr></code> database does not represent how
827 uncertain its information is.
828 Ideally it would contain information about when data entries are
830 Partial temporal knowledge is a field of active research, though,
831 and it is not clear how to apply it here.
836 In short, many, perhaps most, of the <code><abbr>tz</abbr></code>
837 database's pre-1970 and future timestamps are either wrong or
839 Any attempt to pass the
840 <code><abbr>tz</abbr></code> database off as the definition of time
841 should be unacceptable to anybody who cares about the facts.
842 In particular, the <code><abbr>tz</abbr></code> database's
843 <abbr>LMT</abbr> offsets should not be considered meaningful, and
844 should not prompt creation of timezones
845 merely because two locations
846 differ in <abbr>LMT</abbr> or transitioned to standard time at
852 <h2 id="functions">Time and date functions</h2>
854 The <code><abbr>tz</abbr></code> code contains time and date functions
855 that are upwards compatible with those of POSIX.
856 Code compatible with this package is already
857 <a href="tz-link.html#tzdb">part of many platforms</a>, where the
858 primary use of this package is to update obsolete time-related files.
859 To do this, you may need to compile the time zone compiler
860 '<code>zic</code>' supplied with this package instead of using the
861 system '<code>zic</code>', since the format of <code>zic</code>'s
862 input is occasionally extended, and a platform may still be shipping
863 an older <code>zic</code>.
866 <h3 id="POSIX">POSIX properties and limitations</h3>
870 In POSIX, time display in a process is controlled by the
871 environment variable <code>TZ</code>.
872 Unfortunately, the POSIX
873 <code>TZ</code> string takes a form that is hard to describe and
874 is error-prone in practice.
875 Also, POSIX <code>TZ</code> strings cannot deal with daylight
876 saving time rules not based on the Gregorian calendar (as in
877 Iran), or with situations where more than two time zone
878 abbreviations or <abbr>UT</abbr> offsets are used in an area.
882 The POSIX <code>TZ</code> string takes the following form:
886 <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>]]]
894 <dt><var>std</var> and <var>dst</var></dt><dd>
895 are 3 or more characters specifying the standard
896 and daylight saving time (<abbr>DST</abbr>) zone abbreviations.
897 Starting with POSIX.1-2001, <var>std</var> and <var>dst</var>
898 may also be in a quoted form like '<code><+09></code>';
899 this allows "<code>+</code>" and "<code>-</code>" in the names.
901 <dt><var>offset</var></dt><dd>
903 '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>'
904 and specifies the offset west of <abbr>UT</abbr>.
905 '<var>hh</var>' may be a single digit;
906 0≤<var>hh</var>≤24.
907 The default <abbr>DST</abbr> offset is one hour ahead of
910 <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
911 specifies the beginning and end of <abbr>DST</abbr>.
912 If this is absent, the system supplies its own ruleset
913 for <abbr>DST</abbr>, and its rules can differ from year to year;
914 typically <abbr>US</abbr> <abbr>DST</abbr> rules are used.
916 <dt><var>time</var></dt><dd>
918 '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
919 and defaults to 02:00.
920 This is the same format as the offset, except that a
921 leading '<code>+</code>' or '<code>-</code>' is not allowed.
923 <dt><var>date</var></dt><dd>
924 takes one of the following forms:
926 <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd>
927 origin-1 day number not counting February 29
929 <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd>
930 origin-0 day number counting February 29 if present
932 <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
933 (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5,
934 1≤<var>m</var>≤12)</dt><dd>
935 for the <var>d</var>th day of week <var>n</var> of
936 month <var>m</var> of the year, where week 1 is the first
937 week in which day <var>d</var> appears, and
938 '<code>5</code>' stands for the last week in which
939 day <var>d</var> appears (which may be either the 4th or
941 Typically, this is the only useful form; the <var>n</var>
942 and <code>J</code><var>n</var> forms are rarely used.
949 Here is an example POSIX <code>TZ</code> string for New
951 It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead
952 of <abbr>UT</abbr>, and that daylight saving time
953 (<abbr>NZDT</abbr>) is observed from September's last Sunday at
954 02:00 until April's first Sunday at 03:00:
957 <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
960 This POSIX <code>TZ</code> string is hard to remember, and
961 mishandles some timestamps before 2008.
962 With this package you can use this instead:
965 <pre><code>TZ='Pacific/Auckland'</code></pre>
968 POSIX does not define the <abbr>DST</abbr> transitions
969 for <code>TZ</code> values like
970 "<code>EST5EDT</code>".
971 Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
972 were used to interpret such values, but this meant that the
973 <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
974 program that did time conversion. This meant that when
975 <abbr>US</abbr> time conversion rules changed (as in the United
976 States in 1987), all programs that did time conversion had to be
977 recompiled to ensure proper results.
980 The <code>TZ</code> environment variable is process-global, which
981 makes it hard to write efficient, thread-safe applications that
982 need access to multiple timezones.
985 In POSIX, there is no tamper-proof way for a process to learn the
986 system's best idea of local (wall clock) time.
987 This is important for applications that an administrator wants
988 used only at certain times – without regard to whether the
990 <code>TZ</code> environment variable.
991 While an administrator can "do everything in <abbr>UT</abbr>" to
992 get around the problem, doing so is inconvenient and precludes
993 handling daylight saving time shifts – as might be required to
994 limit phone calls to off-peak hours.
997 POSIX provides no convenient and efficient way to determine
998 the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary
999 timestamps, particularly for timezones
1000 that do not fit into the POSIX model.
1003 POSIX requires that <code>time_t</code> clock counts exclude leap
1007 The <code><abbr>tz</abbr></code> code attempts to support all the
1008 <code>time_t</code> implementations allowed by POSIX.
1009 The <code>time_t</code> type represents a nonnegative count of seconds
1010 since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds.
1011 In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1012 integer; 32-bit signed <code>time_t</code> values stop working after
1013 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these
1014 days typically use a signed 64-bit integer.
1015 Unsigned 32-bit integers are used on one or two platforms, and 36-bit
1016 and 40-bit integers are also used occasionally.
1017 Although earlier POSIX versions allowed <code>time_t</code> to be a
1018 floating-point type, this was not supported by any practical system,
1019 and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both
1020 require <code>time_t</code> to be an integer type.
1024 <h3 id="POSIX-extensions">Extensions to POSIX in the
1025 <code><abbr>tz</abbr></code> code</h3>
1029 The <code>TZ</code> environment variable is used in generating
1030 the name of a file from which time-related information is read
1031 (or is interpreted à la POSIX); <code>TZ</code> is no longer
1032 constrained to be a string containing abbreviations
1033 and numeric data as described <a href="#POSIX">above</a>.
1034 The file's format is <dfn><abbr>TZif</abbr></dfn>,
1035 a timezone information format that contains binary data; see
1036 <a href="https://tools.ietf.org/html/8536">Internet
1037 <abbr>RFC</abbr> 8536</a>.
1038 The daylight saving time rules to be used for a
1039 particular timezone are encoded in the
1040 <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
1041 Australian, and other rules to be encoded, and
1042 allows for situations where more than two time zone
1043 abbreviations are used.
1046 It was recognized that allowing the <code>TZ</code> environment
1047 variable to take on values such as '<code>America/New_York</code>'
1048 might cause "old" programs (that expect <code>TZ</code> to have a
1049 certain form) to operate incorrectly; consideration was given to using
1050 some other environment variable (for example, <code>TIMEZONE</code>)
1051 to hold the string used to generate the <abbr>TZif</abbr> file's name.
1052 In the end, however, it was decided to continue using
1053 <code>TZ</code>: it is widely used for time zone purposes;
1054 separately maintaining both <code>TZ</code>
1055 and <code>TIMEZONE</code> seemed a nuisance; and systems where
1056 "new" forms of <code>TZ</code> might cause problems can simply
1057 use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1058 can be used by "new" programs as well as by "old" programs that
1059 assume pre-POSIX <code>TZ</code> values.
1063 The code supports platforms with a <abbr>UT</abbr> offset member
1064 in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>.
1067 The code supports platforms with a time zone abbreviation member in
1068 <code>struct tm</code>, e.g., <code>tm_zone</code>.
1071 Functions <code>tzalloc</code>, <code>tzfree</code>,
1072 <code>localtime_rz</code>, and <code>mktime_z</code> for
1073 more-efficient thread-safe applications that need to use multiple
1075 The <code>tzalloc</code> and <code>tzfree</code> functions
1076 allocate and free objects of type <code>timezone_t</code>,
1077 and <code>localtime_rz</code> and <code>mktime_z</code> are
1078 like <code>localtime_r</code> and <code>mktime</code> with an
1079 extra <code>timezone_t</code> argument.
1080 The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>.
1083 Negative <code>time_t</code> values are supported, on systems
1084 where <code>time_t</code> is signed.
1087 These functions can account for leap seconds;
1088 see <a href="#leapsec">Leap seconds</a> below.
1092 <h3 id="vestigial">POSIX features no longer needed</h3>
1094 POSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a>
1095 define some <a href="https://en.wikipedia.org/wiki/API"><abbr
1096 title="application programming interface">API</abbr>s</a> that are vestigial:
1097 they are not needed, and are relics of a too-simple model that does
1098 not suffice to handle many real-world timestamps.
1099 Although the <code><abbr>tz</abbr></code> code supports these
1100 vestigial <abbr>API</abbr>s for backwards compatibility, they should
1101 be avoided in portable applications.
1102 The vestigial <abbr>API</abbr>s are:
1106 The POSIX <code>tzname</code> variable does not suffice and is no
1108 To get a timestamp's time zone abbreviation, consult
1109 the <code>tm_zone</code> member if available; otherwise,
1110 use <code>strftime</code>'s <code>"%Z"</code> conversion
1114 The POSIX <code>daylight</code> and <code>timezone</code>
1115 variables do not suffice and are no longer needed.
1116 To get a timestamp's <abbr>UT</abbr> offset, consult
1117 the <code>tm_gmtoff</code> member if available; otherwise,
1118 subtract values returned by <code>localtime</code>
1119 and <code>gmtime</code> using the rules of the Gregorian calendar,
1120 or use <code>strftime</code>'s <code>"%z"</code> conversion
1121 specification if a string like <code>"+0900"</code> suffices.
1124 The <code>tm_isdst</code> member is almost never needed and most of
1125 its uses should be discouraged in favor of the abovementioned
1127 Although it can still be used in arguments to
1128 <code>mktime</code> to disambiguate timestamps near
1129 a <abbr>DST</abbr> transition when the clock jumps back, this
1130 disambiguation does not work when standard time itself jumps back,
1131 which can occur when a location changes to a time zone with a
1132 lesser <abbr>UT</abbr> offset.
1136 <h3 id="other-portability">Other portability notes</h3>
1139 The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition
1140 UNIX</a> <code>timezone</code> function is not present in this
1141 package; it is impossible to reliably map <code>timezone</code>'s
1142 arguments (a "minutes west of <abbr>GMT</abbr>" value and a
1143 "daylight saving time in effect" flag) to a time zone
1144 abbreviation, and we refuse to guess.
1145 Programs that in the past used the <code>timezone</code> function
1146 may now examine <code>localtime(&clock)->tm_zone</code>
1147 (if <code>TM_ZONE</code> is defined) or
1148 <code>tzname[localtime(&clock)->tm_isdst]</code>
1149 (if <code>HAVE_TZNAME</code> is nonzero) to learn the correct time
1150 zone abbreviation to use.
1154 href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a>
1155 <code>gettimeofday</code> function is not
1156 used in this package.
1157 This formerly let users obtain the current <abbr>UTC</abbr> offset
1158 and <abbr>DST</abbr> flag, but this functionality was removed in
1159 later versions of <abbr>BSD</abbr>.
1162 In <abbr>SVR2</abbr>, time conversion fails for near-minimum or
1163 near-maximum <code>time_t</code> values when doing conversions
1164 for places that do not use <abbr>UT</abbr>.
1165 This package takes care to do these conversions correctly.
1166 A comment in the source code tells how to get compatibly wrong
1170 The functions that are conditionally compiled
1171 if <code>STD_INSPIRED</code> is defined should, at this point, be
1172 looked on primarily as food for thought.
1173 They are not in any sense "standard compatible" – some are
1174 not, in fact, specified in <em>any</em> standard.
1175 They do, however, represent responses of various authors to
1176 standardization proposals.
1179 Other time conversion proposals, in particular those supported by the
1180 <a href="https://howardhinnant.github.io/date/tz.html">Time Zone
1181 Database Parser</a>, offer a wider selection of functions
1182 that provide capabilities beyond those provided here.
1183 The absence of such functions from this package is not meant to
1184 discourage the development, standardization, or use of such
1186 Rather, their absence reflects the decision to make this package
1187 contain valid extensions to POSIX, to ensure its broad
1189 If more powerful time conversion functions can be standardized, so
1196 <h2 id="stability">Interface stability</h2>
1198 The <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1203 A set of timezone names as per
1204 "<a href="#naming">Timezone identifiers</a>" above.
1207 Library functions described in "<a href="#functions">Time and date
1208 functions</a>" above.
1211 The programs <code>tzselect</code>, <code>zdump</code>,
1212 and <code>zic</code>, documented in their man pages.
1215 The format of <code>zic</code> input files, documented in
1216 the <code>zic</code> man page.
1219 The format of <code>zic</code> output files, documented in
1220 the <code>tzfile</code> man page.
1223 The format of zone table files, documented in <code>zone1970.tab</code>.
1226 The format of the country code file, documented in <code>iso3166.tab</code>.
1229 The version number of the code and data, as the first line of
1230 the text file '<code>version</code>' in each release.
1235 Interface changes in a release attempt to preserve compatibility with
1237 For example, <code><abbr>tz</abbr></code> data files typically do not
1238 rely on recently-added <code>zic</code> features, so that users can
1239 run older <code>zic</code> versions to process newer data files.
1240 <a href="tz-link.html#download">Downloading
1241 the <code><abbr>tz</abbr></code> database</a> describes how releases
1242 are tagged and distributed.
1246 Interfaces not listed above are less stable.
1247 For example, users should not rely on particular <abbr>UT</abbr>
1248 offsets or abbreviations for timestamps, as data entries are often
1249 based on guesswork and these guesses may be corrected or improved.
1253 Timezone boundaries are not part of the stable interface.
1254 For example, even though the <samp>Asia/Bangkok</samp> timezone
1255 currently includes Chang Mai, Hanoi, and Phnom Penh, this is not part
1256 of the stable interface and the timezone can split at any time.
1257 If a calendar application records a future event in some location other
1258 than Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record,
1259 the application should be robust in the presence of timezone splits
1260 between now and the future time.
1265 <h2 id="leapsec">Leap seconds</h2>
1267 The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1268 thanks to code contributed by Bradley White.
1269 However, the leap second support of this package is rarely used directly
1270 because POSIX requires leap seconds to be excluded and many
1271 software packages would mishandle leap seconds if they were present.
1272 Instead, leap seconds are more commonly handled by occasionally adjusting
1273 the operating system kernel clock as described in
1274 <a href="tz-link.html#precision">Precision timekeeping</a>,
1275 and this package by default installs a <samp>leapseconds</samp> file
1277 <a href="http://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a>
1278 software that adjusts the kernel clock.
1279 However, kernel-clock twiddling approximates UTC only roughly,
1280 and systems needing more-precise UTC can use this package's leap
1281 second support directly.
1285 The directly-supported mechanism assumes that <code>time_t</code>
1286 counts of seconds since the POSIX epoch normally include leap seconds,
1287 as opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1288 This modified timescale is converted to <abbr>UTC</abbr>
1289 at the same point that time zone and <abbr>DST</abbr>
1290 adjustments are applied –
1291 namely, at calls to <code>localtime</code> and analogous functions –
1292 and the process is driven by leap second information
1293 stored in alternate versions of the <abbr>TZif</abbr> files.
1294 Because a leap second adjustment may be needed even
1295 if no time zone correction is desired,
1296 calls to <code>gmtime</code>-like functions
1297 also need to consult a <abbr>TZif</abbr> file,
1298 conventionally named <samp><abbr>GMT</abbr></samp>,
1299 to see whether leap second corrections are needed.
1300 To convert an application's <code>time_t</code> timestamps to or from
1301 POSIX <code>time_t</code> timestamps (for use when, say,
1302 embedding or interpreting timestamps in portable
1303 <a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1305 the application can call the utility functions
1306 <code>time2posix</code> and <code>posix2time</code>
1307 included with this package.
1311 If the POSIX-compatible <abbr>TZif</abbr> file set is installed
1312 in a directory whose basename is <samp>zoneinfo</samp>, the
1313 leap-second-aware file set is by default installed in a separate
1314 directory <samp>zoneinfo-leaps</samp>.
1315 Although each process can have its own time zone by setting
1316 its <code>TZ</code> environment variable, there is no support for some
1317 processes being leap-second aware while other processes are
1318 POSIX-compatible; the leap-second choice is system-wide.
1319 So if you configure your kernel to count leap seconds, you should also
1320 discard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp>
1321 to <samp>zoneinfo</samp>.
1322 Alternatively, you can install just one set of <abbr>TZif</abbr> files
1323 in the first place; see the <code>REDO</code> variable in this package's
1324 <a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>.
1329 <h2 id="calendar">Calendrical issues</h2>
1331 Calendrical issues are a bit out of scope for a time zone database,
1332 but they indicate the sort of problems that we would run into if we
1333 extended the time zone database further into the past.
1334 An excellent resource in this area is Edward M. Reingold
1335 and Nachum Dershowitz, <cite><a
1336 href="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical
1337 Calculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018).
1338 Other information and sources are given in the file '<code>calendars</code>'
1339 in the <code><abbr>tz</abbr></code> distribution.
1340 They sometimes disagree.
1345 <h2 id="planets">Time and time zones on other planets</h2>
1347 Some people's work schedules have used
1348 <a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>.
1349 Jet Propulsion Laboratory (JPL) coordinators kept Mars time on
1351 <a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars
1352 Pathfinder</a> mission (1997).
1353 Some of their family members also adapted to Mars time.
1354 Dozens of special Mars watches were built for JPL workers who kept
1355 Mars time during the
1356 <a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars
1357 Exploration Rovers (MER)</a> mission (2004–2018).
1358 These timepieces looked like normal Seikos and Citizens but were adjusted
1359 to use Mars seconds rather than terrestrial seconds, although
1360 unfortunately the adjusted watches were unreliable and appear to have
1361 had only limited use.
1365 A Mars solar day is called a "sol" and has a mean period equal to
1366 about 24 hours 39 minutes 35.244 seconds in terrestrial time.
1367 It is divided into a conventional 24-hour clock, so each Mars second
1368 equals about 1.02749125 terrestrial seconds.
1369 (One MER worker noted, "If I am working Mars hours, and Mars hours are
1370 2.5% more than Earth hours, shouldn't I get an extra 2.5% pay raise?")
1374 The <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime
1375 meridian</a> of Mars goes through the center of the crater
1376 <a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in
1377 honor of the British astronomer who built the Greenwich telescope that
1378 defines Earth's prime meridian.
1379 Mean solar time on the Mars prime meridian is
1380 called Mars Coordinated Time (<abbr>MTC</abbr>).
1384 Each landed mission on Mars has adopted a different reference for
1385 solar timekeeping, so there is no real standard for Mars time zones.
1386 For example, the MER mission defined two time zones "Local
1387 Solar Time A" and "Local Solar Time B" for its two missions, each zone
1388 designed so that its time equals local true solar time at
1389 approximately the middle of the nominal mission.
1390 The A and B zones differ enough so that an MER worker assigned to
1391 the A zone might suffer "Mars lag" when switching to work in the B zone.
1392 Such a "time zone" is not particularly suited for any application
1393 other than the mission itself.
1397 Many calendars have been proposed for Mars, but none have achieved
1399 Astronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a
1400 sequential count of Mars solar days elapsed since about 1873-12-29
1401 12:00 <abbr>GMT</abbr>.
1405 In our solar system, Mars is the planet with time and calendar most
1407 On other planets, Sun-based time and calendars would work quite
1409 For example, although Mercury's
1410 <a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal
1411 rotation period</a> is 58.646 Earth days, Mercury revolves around the
1412 Sun so rapidly that an observer on Mercury's equator would see a
1413 sunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a
1415 Venus is more complicated, partly because its rotation is slightly
1416 <a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>:
1417 its year is 1.92 of its days.
1418 Gas giants like Jupiter are trickier still, as their polar and
1419 equatorial regions rotate at different rates, so that the length of a
1420 day depends on latitude.
1421 This effect is most pronounced on Neptune, where the day is about 12
1422 hours at the poles and 18 hours at the equator.
1426 Although the <code><abbr>tz</abbr></code> database does not support
1427 time on other planets, it is documented here in the hopes that support
1428 will be added eventually.
1432 Sources for time on other planets:
1437 Michael Allison and Robert Schmunk,
1438 "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical
1439 Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>"
1444 <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making
1445 Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854.
1449 "<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays
1450 Fit for a Martian</a>", <cite>Los Angeles Times</cite>
1451 (2004-01-14), pp A1, A20–A21.
1455 "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet
1456 Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26)
1460 "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How
1461 long is a day on the other planets of the solar system?</a>"
1469 This file is in the public domain, so clarified as of 2009-05-17 by