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 off earth</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 and <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>.
64 Applications that also deal with past timestamps in the mountain time
65 zone can choose from over a dozen timezones, such as
66 <code>America/Boise</code>, <code>America/Edmonton</code>, and
67 <code>America/Hermosillo</code>, each of which currently uses mountain
68 time but differs from other timezones for some timestamps after 1970.
72 Clock transitions before 1970 are recorded for location-based timezones,
73 because most systems support timestamps before 1970 and could
74 misbehave if data entries were omitted for pre-1970 transitions.
75 However, the database is not designed for and does not suffice for
76 applications requiring accurate handling of all past times everywhere,
77 as it would take far too much effort and guesswork to record all
78 details of pre-1970 civil timekeeping.
79 Although some information outside the scope of the database is
80 collected in a file <code>backzone</code> that is distributed along
81 with the database proper, this file is less reliable and does not
82 necessarily follow database guidelines.
86 As described below, reference source code for using the
87 <code><abbr>tz</abbr></code> database is also available.
88 The <code><abbr>tz</abbr></code> code is upwards compatible with <a
89 href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international
91 href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems.
92 As of this writing, the current edition of POSIX is: <a
93 href="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open
94 Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018
96 Because the database's scope encompasses real-world changes to civil
97 timekeeping, its model for describing time is more complex than the
98 standard and daylight saving times supported by POSIX.
99 A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
100 have more than two changes per year, these changes need not merely
101 flip back and forth between two alternatives, and the rules themselves
103 Whether and when a timezone changes its clock,
104 and even the timezone's notional base offset from <abbr>UTC</abbr>,
106 It does not always make sense to talk about a timezone's
107 "base offset", which is not necessarily a single number.
113 <h2 id="naming">Timezone identifiers</h2>
115 Each timezone has a name that uniquely identifies the timezone.
116 Inexperienced users are not expected to select these names unaided.
117 Distributors should provide documentation and/or a simple selection
118 interface that explains each name via a map or via descriptive text like
119 "Czech Republic" instead of the timezone name "<code>Europe/Prague</code>".
120 If geolocation information is available, a selection interface can
121 locate the user on a timezone map or prioritize names that are
122 geographically close. For an example selection interface, see the
123 <code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.
124 The <a href="https://cldr.unicode.org">Unicode Common Locale Data
125 Repository</a> contains data that may be useful for other selection
126 interfaces; it maps timezone names like <code>Europe/Prague</code> to
127 locale-dependent strings like "Prague", "Praha", "Прага", and "布拉格".
131 The naming conventions attempt to strike a balance
132 among the following goals:
137 Uniquely identify every timezone where clocks have agreed since 1970.
138 This is essential for the intended use: static clocks keeping local
142 Indicate to experts where the timezone's clocks typically are.
145 Be robust in the presence of political changes.
146 For example, names are typically not tied to countries, to avoid
147 incompatibilities when countries change their name (e.g.,
148 Swaziland→Eswatini) or when locations change countries (e.g., Hong
149 Kong from UK colony to China).
150 There is no requirement that every country or national
151 capital must have a timezone name.
154 Be portable to a wide variety of implementations.
157 Use a consistent naming conventions over the entire world.
162 Names normally have the form
163 <var>AREA</var><code>/</code><var>LOCATION</var>, where
164 <var>AREA</var> is a continent or ocean, and
165 <var>LOCATION</var> is a specific location within the area.
166 North and South America share the same area, '<code>America</code>'.
167 Typical names are '<code>Africa/Cairo</code>',
168 '<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
169 Some names are further qualified to help avoid confusion; for example,
170 '<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
171 Indiana from other Petersburgs in America.
175 Here are the general guidelines used for
176 choosing timezone names,
177 in decreasing order of importance:
182 Use only valid POSIX file name components (i.e., the parts of
183 names other than '<code>/</code>').
184 Do not use the file name components '<code>.</code>' and
186 Within a file name component, use only <a
187 href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters,
188 '<code>.</code>', '<code>-</code>' and '<code>_</code>'.
189 Do not use digits, as that might create an ambiguity with <a
190 href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX
191 <code>TZ</code> strings</a>.
192 A file name component must not exceed 14 characters or start with
194 E.g., prefer <code>America/Noronha</code> to
195 <code>America/Fernando_de_Noronha</code>.
196 Exceptions: see the discussion of legacy names below.
199 A name must not be empty, or contain '<code>//</code>', or
200 start or end with '<code>/</code>'.
203 Do not use names that differ only in case.
204 Although the reference implementation is case-sensitive, some
205 other implementations are not, and they would mishandle names
206 differing only in case.
209 If one name <var>A</var> is an initial prefix of another
210 name <var>AB</var> (ignoring case), then <var>B</var> must not
211 start with '<code>/</code>', as a regular file cannot have the
212 same name as a directory in POSIX.
213 For example, <code>America/New_York</code> precludes
214 <code>America/New_York/Bronx</code>.
217 Uninhabited regions like the North Pole and Bouvet Island
218 do not need locations, since local time is not defined there.
221 If all the clocks in a timezone have agreed since 1970,
222 do not bother to include more than one timezone
223 even if some of the clocks disagreed before 1970.
224 Otherwise these tables would become annoyingly large.
227 If boundaries between regions are fluid, such as during a war or
228 insurrection, do not bother to create a new timezone merely
229 because of yet another boundary change. This helps prevent table
230 bloat and simplifies maintenance.
233 If a name is ambiguous, use a less ambiguous alternative;
234 e.g., many cities are named San José and Georgetown, so
235 prefer <code>America/Costa_Rica</code> to
236 <code>America/San_Jose</code> and <code>America/Guyana</code>
237 to <code>America/Georgetown</code>.
240 Keep locations compact.
241 Use cities or small islands, not countries or regions, so that any
242 future changes do not split individual locations into different
244 E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
246 <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France
247 has had multiple time zones</a>.
250 Use mainstream English spelling, e.g., prefer
251 <code>Europe/Rome</code> to <code>Europa/Roma</code>, and
252 prefer <code>Europe/Athens</code> to the Greek
253 <code>Ευρώπη/Αθήνα</code> or the Romanized
254 <code>Evrópi/Athína</code>.
255 The POSIX file name restrictions encourage this guideline.
258 Use the most populous among locations in a region,
259 e.g., prefer <code>Asia/Shanghai</code> to
260 <code>Asia/Beijing</code>.
261 Among locations with similar populations, pick the best-known
262 location, e.g., prefer <code>Europe/Rome</code> to
263 <code>Europe/Milan</code>.
266 Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
267 <code>Atlantic/Canaries</code>.
270 Omit common suffixes like '<code>_Islands</code>' and
271 '<code>_City</code>', unless that would lead to ambiguity.
272 E.g., prefer <code>America/Cayman</code> to
273 <code>America/Cayman_Islands</code> and
274 <code>America/Guatemala</code> to
275 <code>America/Guatemala_City</code>, but prefer
276 <code>America/Mexico_City</code> to
277 <code>America/Mexico</code>
278 because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the
279 country of Mexico has several time zones</a>.
282 Use '<code>_</code>' to represent a space.
285 Omit '<code>.</code>' from abbreviations in names.
286 E.g., prefer <code>Atlantic/St_Helena</code> to
287 <code>Atlantic/St._Helena</code>.
290 Do not change established names if they only marginally violate
291 the above guidelines.
292 For example, do not change the existing name <code>Europe/Rome</code> to
293 <code>Europe/Milan</code> merely because Milan's population has grown
294 to be somewhat greater than Rome's.
297 If a name is changed, put its old spelling in the
298 '<code>backward</code>' file as a link to the new spelling.
299 This means old spellings will continue to work.
300 Ordinarily a name change should occur only in the rare case when
301 a location's consensus English-language spelling changes; for example,
302 in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code>
303 due to long-time widespread use of the new city name instead of the old.
308 Guidelines have evolved with time, and names following old versions of
309 these guidelines might not follow the current version. When guidelines
310 have changed, old names continue to be supported. Guideline changes
311 have included the following:
316 Older versions of this package used a different naming scheme.
317 See the file '<code>backward</code>' for most of these older names
318 (e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>').
319 The other old-fashioned names still supported are
320 '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and
321 '<code>EET</code>' (see the file '<code>europe</code>').
325 Older versions of this package defined legacy names that are
326 incompatible with the first guideline of location names, but which are
328 These legacy names are mostly defined in the file
329 '<code>etcetera</code>'.
330 Also, the file '<code>backward</code>' defines the legacy names
331 '<code>Etc/GMT0</code>', '<code>Etc/GMT-0</code>', '<code>Etc/GMT+0</code>',
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>Etc/UTC</code>,
380 used by functions like <code>gmtime</code> to obtain leap
381 second information on platforms that support leap seconds.
382 Another <code>etcetera</code> name, <code>GMT</code>,
383 is used by older code releases.
388 <h2 id="abbreviations">Time zone abbreviations</h2>
390 When this package is installed, it generates time zone abbreviations
391 like '<code>EST</code>' to be compatible with human tradition and POSIX.
392 Here are the general guidelines used for choosing time zone abbreviations,
393 in decreasing order of importance:
398 Use three to six characters that are ASCII alphanumerics or
399 '<code>+</code>' or '<code>-</code>'.
400 Previous editions of this database also used characters like
401 space and '<code>?</code>', but these characters have a
402 special meaning to the
403 <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a>
404 and cause commands like
405 '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a>
406 `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>'
407 to have unexpected effects.
408 Previous editions of this guideline required upper-case letters, but the
409 Congressman who introduced
410 <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro
411 Standard Time</a> preferred "ChST", so lower-case letters are now
413 Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>',
414 '<code>+</code>', and alphanumeric characters from the portable
415 character set in the current locale.
416 In practice ASCII alphanumerics and '<code>+</code>' and
417 '<code>-</code>' are safe in all locales.
420 In other words, in the C locale the POSIX extended regular
421 expression <code>[-+[:alnum:]]{3,6}</code> should match the
423 This guarantees that all abbreviations could have been specified by a
424 POSIX <code>TZ</code> string.
428 Use abbreviations that are in common use among English-speakers,
429 e.g., 'EST' for Eastern Standard Time in North America.
430 We assume that applications translate them to other languages
431 as part of the normal localization process; for example,
432 a French application might translate 'EST' to 'HNE'.
435 <small>These abbreviations (for standard/daylight/etc. time) are:
436 ACST/ACDT Australian Central,
437 AST/ADT/APT/AWT/ADDT Atlantic,
438 AEST/AEDT Australian Eastern,
439 AHST/AHDT Alaska-Hawaii,
441 AWST/AWDT Australian Western,
443 CAT/CAST Central Africa,
444 CET/CEST/CEMT Central European,
446 CST/CDT/CWT/CPT Central [North America],
448 GMT/BST/IST/BDST Greenwich,
450 EST/EDT/EWT/EPT Eastern [North America],
451 EET/EEST Eastern European,
453 HST/HDT/HWT/HPT Hawaii,
454 HKT/HKST/HKWT Hong Kong,
460 MET/MEST Middle European (a backward-compatibility alias for
463 MST/MDT/MWT/MPT Mountain,
464 NST/NDT/NWT/NPT/NDDT Newfoundland,
465 NST/NDT/NWT/NPT Nome,
466 NZMT/NZST New Zealand through 1945,
467 NZST/NZDT New Zealand 1946–present,
469 PST/PDT/PWT/PPT Pacific,
474 WAT/WAST West Africa,
475 WET/WEST/WEMT Western European,
476 WIB Waktu Indonesia Barat,
477 WIT Waktu Indonesia Timur,
478 WITA Waktu Indonesia Tengah,
479 YST/YDT/YWT/YPT/YDDT Yukon</small>.
484 For times taken from a city's longitude, use the
485 traditional <var>x</var>MT notation.
486 The only abbreviation like this in current use is '<abbr>GMT</abbr>'.
487 The others are for timestamps before 1960,
488 except that Monrovia Mean Time persisted until 1972.
489 Typically, numeric abbreviations (e.g., '<code>-</code>004430' for
490 MMT) would cause trouble here, as the numeric strings would exceed
491 the POSIX length limit.
495 <small>These abbreviations are:
496 AMT Asunción, Athens;
497 BMT Baghdad, Bangkok, Batavia, Bermuda, Bern, Bogotá,
499 CMT Calamarca, Caracas, Chisinau, Colón, Córdoba;
505 HMT Havana, Helsinki, Horta, Howrah;
506 IMT Irkutsk, Istanbul;
508 KMT Kaunas, Kyiv, Kingston;
509 LMT Lima, Lisbon, local;
510 MMT Macassar, Madras, Malé, Managua, Minsk, Monrovia, Montevideo,
513 PMT Paramaribo, Paris, Perm, Pontianak, Prague;
517 RMT Rangoon, Riga, Rome;
520 SMT Santiago, Simferopol, Singapore, Stanley;
527 <small>A few abbreviations also follow the pattern that
528 <abbr>GMT</abbr>/<abbr>BST</abbr> established for time in the UK.
530 BMT/BST for Bermuda 1890–1930,
531 CMT/BST for Calamarca Mean Time and Bolivian Summer Time
533 DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time
535 MMT/MST/MDST for Moscow 1880–1919, and
536 RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926.
541 Use '<abbr>LMT</abbr>' for local mean time of locations before the
542 introduction of standard time; see "<a href="#scope">Scope of the
543 <code><abbr>tz</abbr></code> database</a>".
546 If there is no common English abbreviation, use numeric offsets like
547 <code>-</code>05 and <code>+</code>0530 that are generated
548 by <code>zic</code>'s <code>%z</code> notation.
551 Use current abbreviations for older timestamps to avoid confusion.
552 For example, in 1910 a common English abbreviation for time
553 in central Europe was 'MEZ' (short for both "Middle European
554 Zone" and for "Mitteleuropäische Zeit" in German).
555 Nowadays 'CET' ("Central European Time") is more common in
556 English, and the database uses 'CET' even for circa-1910
557 timestamps as this is less confusing for modern users and avoids
558 the need for determining when 'CET' supplanted 'MEZ' in common
562 Use a consistent style in a timezone's history.
563 For example, if a history tends to use numeric
564 abbreviations and a particular entry could go either way, use a
565 numeric abbreviation.
569 <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a>
570 (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
571 locations while uninhabited.
572 The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
573 some sense undefined; this notation is derived
574 from <a href="https://datatracker.ietf.org/doc/html/rfc3339">Internet
575 <abbr title="Request For Comments">RFC</abbr> 3339</a>.
580 Application writers should note that these abbreviations are ambiguous
581 in practice: e.g., 'CST' means one thing in China and something else
582 in North America, and 'IST' can refer to time in India, Ireland or
584 To avoid ambiguity, use numeric <abbr>UT</abbr> offsets like
585 '<code>-</code>0600' instead of time zone abbreviations like 'CST'.
590 <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
592 The <code><abbr>tz</abbr></code> database is not authoritative, and it
594 Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
595 Users requiring authoritative data should consult national standards
596 bodies and the references cited in the database's comments.
600 Errors in the <code><abbr>tz</abbr></code> database arise from many sources:
605 The <code><abbr>tz</abbr></code> database predicts future
606 timestamps, and current predictions
607 will be incorrect after future governments change the rules.
608 For example, if today someone schedules a meeting for 13:00 next
609 October 1, Casablanca time, and tomorrow Morocco changes its
610 daylight saving rules, software can mess up after the rule change
611 if it blithely relies on conversions made before the change.
614 The pre-1970 entries in this database cover only a tiny sliver of how
615 clocks actually behaved; the vast majority of the necessary
616 information was lost or never recorded.
617 Thousands more timezones would be needed if
618 the <code><abbr>tz</abbr></code> database's scope were extended to
619 cover even just the known or guessed history of standard time; for
620 example, the current single entry for France would need to split
621 into dozens of entries, perhaps hundreds.
622 And in most of the world even this approach would be misleading
623 due to widespread disagreement or indifference about what times
627 href="https://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The
628 Global Transformation of Time, 1870–1950</a></cite>,
630 "Outside of Europe and North America there was no system of time
631 zones at all, often not even a stable landscape of mean times,
632 prior to the middle decades of the twentieth century".
633 See: Timothy Shenk, <a
634 href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked:
635 A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17.
638 Most of the pre-1970 data entries come from unreliable sources, often
639 astrology books that lack citations and whose compilers evidently
640 invented entries when the true facts were unknown, without
641 reporting which entries were known and which were invented.
642 These books often contradict each other or give implausible entries,
643 and on the rare occasions when they are checked they are
644 typically found to be incorrect.
647 For the UK the <code><abbr>tz</abbr></code> database relies on
648 years of first-class work done by
649 Joseph Myers and others; see
650 "<a href="https://www.polyomino.org.uk/british-time/">History of
651 legal time in Britain</a>".
652 Other countries are not done nearly as well.
655 Sometimes, different people in the same city maintain clocks
656 that differ significantly.
657 Historically, railway time was used by railroad companies (which
659 agree with each other), church-clock time was used for birth
661 More recently, competing political groups might disagree about
662 clock settings. Often this is merely common practice, but
663 sometimes it is set by law.
664 For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France
665 was legally <abbr>UT</abbr> +00:09:21 outside train stations and
666 <abbr>UT</abbr> +00:04:21 inside. Other examples include
667 Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and
671 Although a named location in the <code><abbr>tz</abbr></code>
672 database stands for the containing region, its pre-1970 data
673 entries are often accurate for only a small subset of that region.
674 For example, <code>Europe/London</code> stands for the United
675 Kingdom, but its pre-1847 times are valid only for locations that
676 have London's exact meridian, and its 1847 transition
677 to <abbr>GMT</abbr> is known to be valid only for the L&NW and
678 the Caledonian railways.
681 The <code><abbr>tz</abbr></code> database does not record the
682 earliest time for which a timezone's
683 data entries are thereafter valid for every location in the region.
684 For example, <code>Europe/London</code> is valid for all locations
685 in its region after <abbr>GMT</abbr> was made the standard time,
686 but the date of standardization (1880-08-02) is not in the
687 <code><abbr>tz</abbr></code> database, other than in commentary.
688 For many timezones the earliest time of
692 The <code><abbr>tz</abbr></code> database does not record a
693 region's boundaries, and in many cases the boundaries are not known.
694 For example, the timezone
695 <code>America/Kentucky/Louisville</code> represents a region
696 around the city of Louisville, the boundaries of which are
700 Changes that are modeled as instantaneous transitions in the
701 <code><abbr>tz</abbr></code>
702 database were often spread out over hours, days, or even decades.
705 Even if the time is specified by law, locations sometimes
706 deliberately flout the law.
709 Early timekeeping practices, even assuming perfect clocks, were
710 often not specified to the accuracy that the
711 <code><abbr>tz</abbr></code> database requires.
714 The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
715 However, on 1911-03-11 at 00:00, some public-facing French clocks
716 were changed by stopping them for a few minutes to effect a transition.
717 The <code><abbr>tz</abbr></code> database models this via a
718 backward transition; the relevant French legislation does not
719 specify exactly how the transition was to occur.
722 Sometimes historical timekeeping was specified more precisely
723 than what the <code><abbr>tz</abbr></code> code can handle.
724 For example, from 1880 to 1916 clocks in Ireland observed Dublin Mean
725 Time (estimated to be <abbr>UT</abbr>
726 −00:25:21.1); although the <code><abbr>tz</abbr></code>
727 source data can represent the .1 second, TZif files and the code cannot.
728 In practice these old specifications were rarely if ever
729 implemented to subsecond precision.
732 Even when all the timestamp transitions recorded by the
733 <code><abbr>tz</abbr></code> database are correct, the
734 <code><abbr>tz</abbr></code> rules that generate them may not
735 faithfully reflect the historical rules.
736 For example, from 1922 until World War II the UK moved clocks
737 forward the day following the third Saturday in April unless that
738 was Easter, in which case it moved clocks forward the previous
740 Because the <code><abbr>tz</abbr></code> database has no
741 way to specify Easter, these exceptional years are entered as
742 separate <code><abbr>tz</abbr> Rule</code> lines, even though the
743 legal rules did not change.
744 When transitions are known but the historical rules behind them are not,
745 the database contains <code>Zone</code> and <code>Rule</code>
746 entries that are intended to represent only the generated
747 transitions, not any underlying historical rules; however, this
748 intent is recorded at best only in commentary.
751 The <code><abbr>tz</abbr></code> database models time
753 href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic
754 Gregorian calendar</a> with days containing 24 equal-length hours
755 numbered 00 through 23, except when clock transitions occur.
756 Pre-standard time is modeled as local mean time.
757 However, historically many people used other calendars and other timescales.
758 For example, the Roman Empire used
759 the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian
761 and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman
762 timekeeping</a> had twelve varying-length daytime hours with a
763 non-hour-based system at night.
764 And even today, some local practices diverge from the Gregorian
765 calendar with 24-hour days. These divergences range from
766 relatively minor, such as Japanese bars giving times like "24:30" for the
767 wee hours of the morning, to more-significant differences such as <a
768 href="https://www.pri.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the
769 east African practice of starting the day at dawn</a>, renumbering
770 the Western 06:00 to be 12:00. These practices are largely outside
771 the scope of the <code><abbr>tz</abbr></code> code and data, which
772 provide only limited support for date and time localization
773 such as that required by POSIX.
774 If <abbr>DST</abbr> is not used a different time zone
775 can often do the trick; for example, in Kenya a <code>TZ</code> setting
776 like <code><-03>3</code> or <code>America/Cayenne</code> starts
777 the day six hours later than <code>Africa/Nairobi</code> does.
780 Early clocks were less reliable, and data entries do not represent
784 The <code><abbr>tz</abbr></code> database assumes Universal Time
785 (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not
786 standardized for older timestamps.
787 In the <code><abbr>tz</abbr></code> database commentary,
788 <abbr>UT</abbr> denotes a family of time standards that includes
789 Coordinated Universal Time (<abbr>UTC</abbr>) along with other
790 variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>,
791 with days starting at midnight.
792 Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern
793 timestamps, <abbr>UTC</abbr> was not defined until 1960, so
794 commentary uses the more general abbreviation <abbr>UT</abbr> for
795 timestamps that might predate 1960.
796 Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly,
797 and since pre-1972 <abbr>UTC</abbr> seconds varied in length,
798 interpretation of older timestamps can be problematic when
799 subsecond accuracy is needed.
802 Civil time was not based on atomic time before 1972, and we do not
804 <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's
805 rotation</a> accurately enough to map <a
806 href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr
807 title="International System of Units">SI</abbr></a> seconds to
808 historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a>
809 to more than about one-hour accuracy.
810 See: Stephenson FR, Morrison LV, Hohenkerk CY.
811 <a href="https://dx.doi.org/10.1098/rspa.2016.0404">Measurement of
812 the Earth's rotation: 720 BC to AD 2015</a>.
813 <cite>Proc Royal Soc A</cite>. 2016;472:20160404.
814 Also see: Espenak F. <a
815 href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty
819 The relationship between POSIX time (that is, <abbr>UTC</abbr> but
820 ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap
821 seconds</a>) and <abbr>UTC</abbr> is not agreed upon.
822 This affects time stamps during the leap second era (1972–2035).
824 clock officially stops during an inserted leap second, at least one
825 proposed standard has it jumping back a second instead; and in
826 practice POSIX clocks more typically either progress glacially during
827 a leap second, or are slightly slowed while near a leap second.
830 The <code><abbr>tz</abbr></code> database does not represent how
831 uncertain its information is.
832 Ideally it would contain information about when data entries are
834 Partial temporal knowledge is a field of active research, though,
835 and it is not clear how to apply it here.
840 In short, many, perhaps most, of the <code><abbr>tz</abbr></code>
841 database's pre-1970 and future timestamps are either wrong or
843 Any attempt to pass the
844 <code><abbr>tz</abbr></code> database off as the definition of time
845 should be unacceptable to anybody who cares about the facts.
846 In particular, the <code><abbr>tz</abbr></code> database's
847 <abbr>LMT</abbr> offsets should not be considered meaningful, and
848 should not prompt creation of timezones
849 merely because two locations
850 differ in <abbr>LMT</abbr> or transitioned to standard time at
856 <h2 id="functions">Time and date functions</h2>
858 The <code><abbr>tz</abbr></code> code contains time and date functions
859 that are upwards compatible with those of POSIX.
860 Code compatible with this package is already
861 <a href="tz-link.html#tzdb">part of many platforms</a>, where the
862 primary use of this package is to update obsolete time-related files.
863 To do this, you may need to compile the time zone compiler
864 '<code>zic</code>' supplied with this package instead of using the
865 system '<code>zic</code>', since the format of <code>zic</code>'s
866 input is occasionally extended, and a platform may still be shipping
867 an older <code>zic</code>.
870 <h3 id="POSIX">POSIX properties and limitations</h3>
874 In POSIX, time display in a process is controlled by the
875 environment variable <code>TZ</code>.
876 Unfortunately, the POSIX
877 <code>TZ</code> string takes a form that is hard to describe and
878 is error-prone in practice.
879 Also, POSIX <code>TZ</code> strings cannot deal with daylight
880 saving time rules not based on the Gregorian calendar (as in
881 Morocco), or with situations where more than two time zone
882 abbreviations or <abbr>UT</abbr> offsets are used in an area.
886 The POSIX <code>TZ</code> string takes the following form:
890 <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>]]]
898 <dt><var>std</var> and <var>dst</var></dt><dd>
899 are 3 or more characters specifying the standard
900 and daylight saving time (<abbr>DST</abbr>) zone abbreviations.
901 Starting with POSIX.1-2001, <var>std</var> and <var>dst</var>
902 may also be in a quoted form like '<code><+09></code>';
903 this allows "<code>+</code>" and "<code>-</code>" in the names.
905 <dt><var>offset</var></dt><dd>
907 '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>'
908 and specifies the offset west of <abbr>UT</abbr>.
909 '<var>hh</var>' may be a single digit;
910 0≤<var>hh</var>≤24.
911 The default <abbr>DST</abbr> offset is one hour ahead of
914 <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
915 specifies the beginning and end of <abbr>DST</abbr>.
916 If this is absent, the system supplies its own ruleset
917 for <abbr>DST</abbr>, typically current <abbr>US</abbr>
918 <abbr>DST</abbr> rules.
920 <dt><var>time</var></dt><dd>
922 '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
923 and defaults to 02:00.
924 This is the same format as the offset, except that a
925 leading '<code>+</code>' or '<code>-</code>' is not allowed.
927 <dt><var>date</var></dt><dd>
928 takes one of the following forms:
930 <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd>
931 origin-1 day number not counting February 29
933 <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd>
934 origin-0 day number counting February 29 if present
936 <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
937 (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5,
938 1≤<var>m</var>≤12)</dt><dd>
939 for the <var>d</var>th day of week <var>n</var> of
940 month <var>m</var> of the year, where week 1 is the first
941 week in which day <var>d</var> appears, and
942 '<code>5</code>' stands for the last week in which
943 day <var>d</var> appears (which may be either the 4th or
945 Typically, this is the only useful form; the <var>n</var>
946 and <code>J</code><var>n</var> forms are rarely used.
953 Here is an example POSIX <code>TZ</code> string for New
955 It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead
956 of <abbr>UT</abbr>, and that daylight saving time
957 (<abbr>NZDT</abbr>) is observed from September's last Sunday at
958 02:00 until April's first Sunday at 03:00:
961 <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
964 This POSIX <code>TZ</code> string is hard to remember, and
965 mishandles some timestamps before 2008.
966 With this package you can use this instead:
969 <pre><code>TZ='Pacific/Auckland'</code></pre>
972 POSIX does not define the <abbr>DST</abbr> transitions
973 for <code>TZ</code> values like
974 "<code>EST5EDT</code>".
975 Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
976 were used to interpret such values, but this meant that the
977 <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
978 time conversion package, and when
979 <abbr>US</abbr> time conversion rules changed (as in the United
980 States in 1987 and again in 2007), all packages that
981 interpreted <code>TZ</code> values had to be updated
982 to ensure proper results.
985 The <code>TZ</code> environment variable is process-global, which
986 makes it hard to write efficient, thread-safe applications that
987 need access to multiple timezones.
990 In POSIX, there is no tamper-proof way for a process to learn the
991 system's best idea of local (wall clock) time.
992 This is important for applications that an administrator wants
993 used only at certain times – without regard to whether the
995 <code>TZ</code> environment variable.
996 While an administrator can "do everything in <abbr>UT</abbr>" to
997 get around the problem, doing so is inconvenient and precludes
998 handling daylight saving time shifts – as might be required to
999 limit phone calls to off-peak hours.
1002 POSIX provides no convenient and efficient way to determine
1003 the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary
1004 timestamps, particularly for timezones
1005 that do not fit into the POSIX model.
1008 POSIX requires that <code>time_t</code> clock counts exclude leap
1012 The <code><abbr>tz</abbr></code> code attempts to support all the
1013 <code>time_t</code> implementations allowed by POSIX.
1014 The <code>time_t</code> type represents a nonnegative count of seconds
1015 since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds.
1016 In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1017 integer; 32-bit signed <code>time_t</code> values stop working after
1018 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these
1019 days typically use a signed 64-bit integer.
1020 Unsigned 32-bit integers are used on one or two platforms, and 36-bit
1021 and 40-bit integers are also used occasionally.
1022 Although earlier POSIX versions allowed <code>time_t</code> to be a
1023 floating-point type, this was not supported by any practical system,
1024 and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both
1025 require <code>time_t</code> to be an integer type.
1029 <h3 id="POSIX-extensions">Extensions to POSIX in the
1030 <code><abbr>tz</abbr></code> code</h3>
1034 The <code>TZ</code> environment variable is used in generating
1035 the name of a file from which time-related information is read
1036 (or is interpreted à la POSIX); <code>TZ</code> is no longer
1037 constrained to be a string containing abbreviations
1038 and numeric data as described <a href="#POSIX">above</a>.
1039 The file's format is <dfn><abbr>TZif</abbr></dfn>,
1040 a timezone information format that contains binary data; see
1041 <a href="https://datatracker.ietf.org/doc/html/8536">Internet
1042 <abbr>RFC</abbr> 8536</a>.
1043 The daylight saving time rules to be used for a
1044 particular timezone are encoded in the
1045 <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
1046 Australian, and other rules to be encoded, and
1047 allows for situations where more than two time zone
1048 abbreviations are used.
1051 It was recognized that allowing the <code>TZ</code> environment
1052 variable to take on values such as '<code>America/New_York</code>'
1053 might cause "old" programs (that expect <code>TZ</code> to have a
1054 certain form) to operate incorrectly; consideration was given to using
1055 some other environment variable (for example, <code>TIMEZONE</code>)
1056 to hold the string used to generate the <abbr>TZif</abbr> file's name.
1057 In the end, however, it was decided to continue using
1058 <code>TZ</code>: it is widely used for time zone purposes;
1059 separately maintaining both <code>TZ</code>
1060 and <code>TIMEZONE</code> seemed a nuisance; and systems where
1061 "new" forms of <code>TZ</code> might cause problems can simply
1062 use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1063 can be used by "new" programs as well as by "old" programs that
1064 assume pre-POSIX <code>TZ</code> values.
1068 The code supports platforms with a <abbr>UT</abbr> offset member
1069 in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>,
1070 or with a time zone abbreviation member in
1071 <code>struct tm</code>, e.g., <code>tm_zone</code>. As noted
1072 in <a href="https://austingroupbugs.net/view.php?id=1533">Austin
1073 Group defect 1533</a>, a future version of POSIX is planned to
1074 require <code>tm_gmtoff</code> and <code>tm_zone</code>.
1077 Functions <code>tzalloc</code>, <code>tzfree</code>,
1078 <code>localtime_rz</code>, and <code>mktime_z</code> for
1079 more-efficient thread-safe applications that need to use multiple
1081 The <code>tzalloc</code> and <code>tzfree</code> functions
1082 allocate and free objects of type <code>timezone_t</code>,
1083 and <code>localtime_rz</code> and <code>mktime_z</code> are
1084 like <code>localtime_r</code> and <code>mktime</code> with an
1085 extra <code>timezone_t</code> argument.
1086 The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>.
1089 Negative <code>time_t</code> values are supported, on systems
1090 where <code>time_t</code> is signed.
1093 These functions can account for leap seconds;
1094 see <a href="#leapsec">Leap seconds</a> below.
1098 <h3 id="vestigial">POSIX features no longer needed</h3>
1100 POSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a>
1101 define some <a href="https://en.wikipedia.org/wiki/API"><abbr
1102 title="application programming interface">API</abbr>s</a> that are vestigial:
1103 they are not needed, and are relics of a too-simple model that does
1104 not suffice to handle many real-world timestamps.
1105 Although the <code><abbr>tz</abbr></code> code supports these
1106 vestigial <abbr>API</abbr>s for backwards compatibility, they should
1107 be avoided in portable applications.
1108 The vestigial <abbr>API</abbr>s are:
1112 The POSIX <code>tzname</code> variable does not suffice and is no
1114 To get a timestamp's time zone abbreviation, consult
1115 the <code>tm_zone</code> member if available; otherwise,
1116 use <code>strftime</code>'s <code>"%Z"</code> conversion
1120 The POSIX <code>daylight</code> and <code>timezone</code>
1121 variables do not suffice and are no longer needed.
1122 To get a timestamp's <abbr>UT</abbr> offset, consult
1123 the <code>tm_gmtoff</code> member if available; otherwise,
1124 subtract values returned by <code>localtime</code>
1125 and <code>gmtime</code> using the rules of the Gregorian calendar,
1126 or use <code>strftime</code>'s <code>"%z"</code> conversion
1127 specification if a string like <code>"+0900"</code> suffices.
1130 The <code>tm_isdst</code> member is almost never needed and most of
1131 its uses should be discouraged in favor of the abovementioned
1133 Although it can still be used in arguments to
1134 <code>mktime</code> to disambiguate timestamps near
1135 a <abbr>DST</abbr> transition when the clock jumps back on
1136 platforms lacking <code>tm_gmtoff</code>, this
1137 disambiguation does not work when standard time itself jumps back,
1138 which can occur when a location changes to a time zone with a
1139 lesser <abbr>UT</abbr> offset.
1143 <h3 id="other-portability">Other portability notes</h3>
1146 The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition
1147 UNIX</a> <code>timezone</code> function is not present in this
1148 package; it is impossible to reliably map <code>timezone</code>'s
1149 arguments (a "minutes west of <abbr>GMT</abbr>" value and a
1150 "daylight saving time in effect" flag) to a time zone
1151 abbreviation, and we refuse to guess.
1152 Programs that in the past used the <code>timezone</code> function
1153 may now examine <code>localtime(&clock)->tm_zone</code>
1154 (if <code>TM_ZONE</code> is defined) or
1155 <code>tzname[localtime(&clock)->tm_isdst]</code>
1156 (if <code>HAVE_TZNAME</code> is nonzero) to learn the correct time
1157 zone abbreviation to use.
1161 href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a>
1162 <code>gettimeofday</code> function is not
1163 used in this package.
1164 This formerly let users obtain the current <abbr>UTC</abbr> offset
1165 and <abbr>DST</abbr> flag, but this functionality was removed in
1166 later versions of <abbr>BSD</abbr>.
1169 In <abbr>SVR2</abbr>, time conversion fails for near-minimum or
1170 near-maximum <code>time_t</code> values when doing conversions
1171 for places that do not use <abbr>UT</abbr>.
1172 This package takes care to do these conversions correctly.
1173 A comment in the source code tells how to get compatibly wrong
1177 The functions that are conditionally compiled
1178 if <code>STD_INSPIRED</code> is nonzero should, at this point, be
1179 looked on primarily as food for thought.
1180 They are not in any sense "standard compatible" – some are
1181 not, in fact, specified in <em>any</em> standard.
1182 They do, however, represent responses of various authors to
1183 standardization proposals.
1186 Other time conversion proposals, in particular those supported by the
1187 <a href="https://howardhinnant.github.io/date/tz.html">Time Zone
1188 Database Parser</a>, offer a wider selection of functions
1189 that provide capabilities beyond those provided here.
1190 The absence of such functions from this package is not meant to
1191 discourage the development, standardization, or use of such
1193 Rather, their absence reflects the decision to make this package
1194 contain valid extensions to POSIX, to ensure its broad
1196 If more powerful time conversion functions can be standardized, so
1203 <h2 id="stability">Interface stability</h2>
1205 The <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1210 A set of timezone names as per
1211 "<a href="#naming">Timezone identifiers</a>" above.
1214 Library functions described in "<a href="#functions">Time and date
1215 functions</a>" above.
1218 The programs <code>tzselect</code>, <code>zdump</code>,
1219 and <code>zic</code>, documented in their man pages.
1222 The format of <code>zic</code> input files, documented in
1223 the <code>zic</code> man page.
1226 The format of <code>zic</code> output files, documented in
1227 the <code>tzfile</code> man page.
1230 The format of zone table files, documented in <code>zone1970.tab</code>.
1233 The format of the country code file, documented in <code>iso3166.tab</code>.
1236 The version number of the code and data, as the first line of
1237 the text file '<code>version</code>' in each release.
1242 Interface changes in a release attempt to preserve compatibility with
1244 For example, <code><abbr>tz</abbr></code> data files typically do not
1245 rely on recently added <code>zic</code> features, so that users can
1246 run older <code>zic</code> versions to process newer data files.
1247 <a href="tz-link.html#download">Downloading
1248 the <code><abbr>tz</abbr></code> database</a> describes how releases
1249 are tagged and distributed.
1253 Interfaces not listed above are less stable.
1254 For example, users should not rely on particular <abbr>UT</abbr>
1255 offsets or abbreviations for timestamps, as data entries are often
1256 based on guesswork and these guesses may be corrected or improved.
1260 Timezone boundaries are not part of the stable interface.
1261 For example, even though the <samp>Asia/Bangkok</samp> timezone
1262 currently includes Chang Mai, Hanoi, and Phnom Penh, this is not part
1263 of the stable interface and the timezone can split at any time.
1264 If a calendar application records a future event in some location other
1265 than Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record,
1266 the application should be robust in the presence of timezone splits
1267 between now and the future time.
1272 <h2 id="leapsec">Leap seconds</h2>
1274 Leap seconds were introduced in 1972 to accommodate the
1275 difference between atomic time and the less regular rotation of the earth.
1276 Unfortunately they caused so many problems with civil
1277 timekeeping that they
1278 are <a href="https://www.bipm.org/en/cgpm-2022/resolution-4">planned
1279 to be discontinued by 2035</a>, with some as-yet-undetermined
1280 mechanism replacing them, perhaps after the year 2135.
1281 Despite their impending obsolescence, a record of leap seconds is still
1282 needed to resolve timestamps from 1972 through 2035.
1286 The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1287 thanks to code contributed by Bradley White.
1288 However, the leap second support of this package is rarely used directly
1289 because POSIX requires leap seconds to be excluded and many
1290 software packages would mishandle leap seconds if they were present.
1291 Instead, leap seconds are more commonly handled by occasionally adjusting
1292 the operating system kernel clock as described in
1293 <a href="tz-link.html#precision">Precision timekeeping</a>,
1294 and this package by default installs a <samp>leapseconds</samp> file
1296 <a href="https://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a>
1297 software that adjusts the kernel clock.
1298 However, kernel-clock twiddling approximates UTC only roughly,
1299 and systems needing more precise UTC can use this package's leap
1300 second support directly.
1304 The directly supported mechanism assumes that <code>time_t</code>
1305 counts of seconds since the POSIX epoch normally include leap seconds,
1306 as opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1307 This modified timescale is converted to <abbr>UTC</abbr>
1308 at the same point that time zone and <abbr>DST</abbr>
1309 adjustments are applied –
1310 namely, at calls to <code>localtime</code> and analogous functions –
1311 and the process is driven by leap second information
1312 stored in alternate versions of the <abbr>TZif</abbr> files.
1313 Because a leap second adjustment may be needed even
1314 if no time zone correction is desired,
1315 calls to <code>gmtime</code>-like functions
1316 also need to consult a <abbr>TZif</abbr> file,
1317 conventionally named <samp><abbr>Etc/UTC</abbr></samp>
1318 (<samp><abbr>GMT</abbr></samp> in previous versions),
1319 to see whether leap second corrections are needed.
1320 To convert an application's <code>time_t</code> timestamps to or from
1321 POSIX <code>time_t</code> timestamps (for use when, say,
1322 embedding or interpreting timestamps in portable
1323 <a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1325 the application can call the utility functions
1326 <code>time2posix</code> and <code>posix2time</code>
1327 included with this package.
1331 If the POSIX-compatible <abbr>TZif</abbr> file set is installed
1332 in a directory whose basename is <samp>zoneinfo</samp>, the
1333 leap-second-aware file set is by default installed in a separate
1334 directory <samp>zoneinfo-leaps</samp>.
1335 Although each process can have its own time zone by setting
1336 its <code>TZ</code> environment variable, there is no support for some
1337 processes being leap-second aware while other processes are
1338 POSIX-compatible; the leap-second choice is system-wide.
1339 So if you configure your kernel to count leap seconds, you should also
1340 discard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp>
1341 to <samp>zoneinfo</samp>.
1342 Alternatively, you can install just one set of <abbr>TZif</abbr> files
1343 in the first place; see the <code>REDO</code> variable in this package's
1344 <a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>.
1349 <h2 id="calendar">Calendrical issues</h2>
1351 Calendrical issues are a bit out of scope for a time zone database,
1352 but they indicate the sort of problems that we would run into if we
1353 extended the time zone database further into the past.
1354 An excellent resource in this area is Edward M. Reingold
1355 and Nachum Dershowitz, <cite><a
1356 href="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical
1357 Calculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018).
1358 Other information and sources are given in the file '<code>calendars</code>'
1359 in the <code><abbr>tz</abbr></code> distribution.
1360 They sometimes disagree.
1365 <h2 id="planets">Time and time zones off Earth</h2>
1367 The European Space Agency is <a
1368 href='https://www.esa.int/Applications/Navigation/Telling_time_on_the_Moon'>considering</a>
1369 the establishment of a reference timescale for the Moon, which has
1370 days roughly equivalent to 29.5 Earth days, and where relativistic
1371 effects cause clocks to tick slightly faster than on Earth.
1375 Some people's work schedules have used
1376 <a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>.
1377 Jet Propulsion Laboratory (JPL) coordinators kept Mars time on
1379 <a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars
1380 Pathfinder</a> mission (1997).
1381 Some of their family members also adapted to Mars time.
1382 Dozens of special Mars watches were built for JPL workers who kept
1383 Mars time during the
1384 <a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars
1385 Exploration Rovers (MER)</a> mission (2004–2018).
1386 These timepieces looked like normal Seikos and Citizens but were adjusted
1387 to use Mars seconds rather than terrestrial seconds, although
1388 unfortunately the adjusted watches were unreliable and appear to have
1389 had only limited use.
1393 A Mars solar day is called a "sol" and has a mean period equal to
1394 about 24 hours 39 minutes 35.244 seconds in terrestrial time.
1395 It is divided into a conventional 24-hour clock, so each Mars second
1396 equals about 1.02749125 terrestrial seconds.
1397 (One MER worker noted, "If I am working Mars hours, and Mars hours are
1398 2.5% more than Earth hours, shouldn't I get an extra 2.5% pay raise?")
1402 The <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime
1403 meridian</a> of Mars goes through the center of the crater
1404 <a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in
1405 honor of the British astronomer who built the Greenwich telescope that
1406 defines Earth's prime meridian.
1407 Mean solar time on the Mars prime meridian is
1408 called Mars Coordinated Time (<abbr>MTC</abbr>).
1412 Each landed mission on Mars has adopted a different reference for
1413 solar timekeeping, so there is no real standard for Mars time zones.
1414 For example, the MER mission defined two time zones "Local
1415 Solar Time A" and "Local Solar Time B" for its two missions, each zone
1416 designed so that its time equals local true solar time at
1417 approximately the middle of the nominal mission.
1418 The A and B zones differ enough so that an MER worker assigned to
1419 the A zone might suffer "Mars lag" when switching to work in the B zone.
1420 Such a "time zone" is not particularly suited for any application
1421 other than the mission itself.
1425 Many calendars have been proposed for Mars, but none have achieved
1427 Astronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a
1428 sequential count of Mars solar days elapsed since about 1873-12-29
1429 12:00 <abbr>GMT</abbr>.
1433 In our solar system, Mars is the planet with time and calendar most
1435 On other planets, Sun-based time and calendars would work quite
1437 For example, although Mercury's
1438 <a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal
1439 rotation period</a> is 58.646 Earth days, Mercury revolves around the
1440 Sun so rapidly that an observer on Mercury's equator would see a
1441 sunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a
1443 Venus is more complicated, partly because its rotation is slightly
1444 <a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>:
1445 its year is 1.92 of its days.
1446 Gas giants like Jupiter are trickier still, as their polar and
1447 equatorial regions rotate at different rates, so that the length of a
1448 day depends on latitude.
1449 This effect is most pronounced on Neptune, where the day is about 12
1450 hours at the poles and 18 hours at the equator.
1454 Although the <code><abbr>tz</abbr></code> database does not support
1455 time on other planets, it is documented here in the hopes that support
1456 will be added eventually.
1460 Sources for time on other planets:
1465 Michael Allison and Robert Schmunk,
1466 "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical
1467 Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>"
1472 <em><a href="https://mitpress.mit.edu/books/making-time-mars">Making
1473 Time on Mars</a></em>, MIT Press (March 2020), ISBN 978-0262043854.
1477 "<a href="https://www.latimes.com/archives/la-xpm-2004-jan-14-sci-marstime14-story.html">Workdays
1478 Fit for a Martian</a>", <cite>Los Angeles Times</cite>
1479 (2004-01-14), pp A1, A20–A21.
1483 "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet
1484 Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26)
1488 "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How
1489 long is a day on the other planets of the solar system?</a>"
1497 This file is in the public domain, so clarified as of 2009-05-17 by