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