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