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