4 <title>How to Read the tz Database</title>
7 pre {margin-left: 2em; white-space: pre-wrap;}
8 pre.td {margin-left: 0;}
9 td {text-align: center;}
10 table {border: 1px outset;}
11 th, td {border: 1px inset;}
12 table.rule {border: none; margin: auto;}
13 td.footnote {text-align: left;}
17 <h2>How to Read the <a href="https://en.wikipedia.org/wiki/Tz_database">tz
18 Database</a> Source Files</h2>
19 <h3>by Bill Seymour</h3>
20 <p>This guide uses the <code>America/Chicago</code> and
21 <code>Pacific/Honolulu</code> zones as examples of how to infer
22 times of day from the <a href="tz-link.html">tz database</a>
23 source files. It might be helpful, but not absolutely necessary,
24 for the reader to have already downloaded the
25 latest release of the database and become familiar with the basic layout
26 of the data files. The format is explained in the “man
27 page” for the zic compiler, <code>zic.8.txt</code>, in
28 the <code>code</code> subdirectory.
29 Although this guide covers many of the common cases, it is not a
30 complete summary of what zic accepts; the man page is the
31 authoritative reference.</p>
33 <p>We’ll begin by talking about the rules for changing between standard
34 and daylight saving time since we’ll need that information when we talk
37 <p>First, let’s consider the special daylight saving time rules
38 for Chicago (from the <code>northamerica</code> file in
39 the <code>data</code> subdirectory):</p>
43 <th colspan="6">From the Source File</th>
48 <tr><td style="border:none;text-align:left">
50 #Rule NAME FROM TO - IN ON AT SAVE LETTER
51 Rule Chicago 1920 only - Jun 13 2:00 1:00 D
52 Rule Chicago 1920 1921 - Oct lastSun 2:00 0 S
53 Rule Chicago 1921 only - Mar lastSun 2:00 1:00 D
54 Rule Chicago 1922 1966 - Apr lastSun 2:00 1:00 D
55 Rule Chicago 1922 1954 - Sep lastSun 2:00 0 S
56 Rule Chicago 1955 1966 - Oct lastSun 2:00 0 S
58 </td></tr></table></td>
61 <th colspan="6">Reformatted a Bit</th>
66 <th colspan="2">On</th>
71 <td colspan="2">1920 only</td>
72 <td colspan="2">June 13<small><sup>th</sup></small></td>
73 <td rowspan="6">02:00 local</td>
74 <td>go to daylight saving time</td>
79 <td rowspan="5">last Sunday</td>
81 <td>return to standard time</td>
84 <td colspan="2">1921 only</td>
86 <td rowspan="2">go to daylight saving time</td>
89 <td rowspan="2">1922</td>
96 <td rowspan="2">return to standard time</td>
105 <p>The <code>FROM</code> and <code>TO</code> columns, respectively, specify the
106 first and last calendar years defining a contiguous range over which a specific
107 Rule line is to apply. The keyword <code>only</code> can be used in the
108 <code>TO</code> field to repeat the value of the <code>FROM</code> field in the
109 event that a rule should only apply to a single year. Often, the keyword
110 <code>max</code> is used to extend a rule’s application into the
111 indefinite future; it is a platform-agnostic stand-in for the largest
114 <p>The next column, <code>-</code>, is reserved; for compatibility with earlier
115 releases, it always contains a hyphen, which acts as a kind of null value.
116 Prior to the 2020b release, it was called the <code>TYPE</code> field, though
117 it had not been used in the main data since the 2000e release.
118 An obsolescent supplementary file used the
119 field as a proof-of-concept to allow <code>zic</code> to apply a given Rule
120 line only to certain “types” of years within the specified range as
121 dictated by the output of a separate script, such as: only years which would
122 have a US presidential election, or only years which wouldn’t.
124 <p>The <code>SAVE</code> column contains the local (wall clock) offset from
126 This is usually either zero for standard time or one hour for daylight
127 saving time; but there’s no reason, in principle, why it can’t
128 take on other values.
130 <p>The <code>LETTER</code> (sometimes called <code>LETTER/S</code>)
131 column can contain a variable
132 part of the usual abbreviation of the time zone’s name, or it can just
133 be a hyphen if there’s no variable part. For example, the abbreviation
134 used in the central time zone will be either “CST” or
135 “CDT”. The variable part is ‘S’ or ‘D’;
136 and, sure enough, that’s just what we find in
137 the <code>LETTER</code> column
138 in the <code>Chicago</code> rules. More about this when we talk about
139 “Zone” lines.
141 <p>One important thing to notice is that “Rule” lines
142 want at once to be both <i>transitions</i> and <i>steady states</i>:
144 <li>On the one hand, they represent transitions between standard and
145 daylight saving time; and any number of Rule lines can be in effect
146 during a given period (which will always be a non-empty set of
147 contiguous calendar years).</li>
148 <li>On the other hand, the <code>SAVE</code> and <code>LETTER</code>
149 columns contain state that exists between transitions. More about this
150 when we talk about the US rules.</li>
153 <p>In the example above, the transition to daylight saving time
154 happened on the 13<small><sup>th</sup></small> of June in 1920, and on
155 the last Sunday in March in 1921; but the return to standard time
156 happened on the last Sunday in October in both of those
157 years. Similarly, the rule for changing to daylight saving time was
158 the same from 1922 to 1966; but the rule for returning to standard
159 time changed in 1955. Got it?</p>
161 <p>OK, now for the somewhat more interesting “US” rules:</p>
165 <th colspan="6">From the Source File</th>
170 <tr><td style="border:none;text-align:left">
172 #Rule NAME FROM TO - IN ON AT SAVE LETTER/S
173 Rule US 1918 1919 - Mar lastSun 2:00 1:00 D
174 Rule US 1918 1919 - Oct lastSun 2:00 0 S
175 Rule US 1942 only - Feb 9 2:00 1:00 W # War
176 Rule US 1945 only - Aug 14 23:00u 1:00 P # Peace
177 Rule US 1945 only - Sep 30 2:00 0 S
178 Rule US 1967 2006 - Oct lastSun 2:00 0 S
179 Rule US 1967 1973 - Apr lastSun 2:00 1:00 D
180 Rule US 1974 only - Jan 6 2:00 1:00 D
181 Rule US 1975 only - Feb 23 2:00 1:00 D
182 Rule US 1976 1986 - Apr lastSun 2:00 1:00 D
183 Rule US 1987 2006 - Apr Sun>=1 2:00 1:00 D
184 Rule US 2007 max - Mar Sun>=8 2:00 1:00 D
185 Rule US 2007 max - Nov Sun>=1 2:00 0 S
187 </td></tr></table></td>
190 <th colspan="6">Reformatted a Bit</th>
195 <th colspan="2">On</th>
200 <td rowspan="2">1918</td>
201 <td rowspan="2">1919</td>
202 <td rowspan="2">last Sunday</td>
204 <td rowspan="3">02:00 local</td>
205 <td>go to daylight saving time</td>
209 <td>return to standard time</td>
212 <td colspan="2">1942 only</td>
213 <td colspan="2">February 9<small><sup>th</sup></small></td>
214 <td>go to “war time”</td>
217 <td colspan="2" rowspan="2">1945 only</td>
218 <td colspan="2">August 14<small><sup>th</sup></small></td>
219 <td>23:00 <a href="https://en.wikipedia.org/wiki/Universal_Time">UT</a></td>
221 rename “war time” to “peace<br>time;”
222 clocks don’t change
226 <td colspan="2">September 30<small><sup>th</sup></small></td>
227 <td rowspan="9">02:00 local</td>
228 <td rowspan="2">return to standard time</td>
231 <td rowspan="2">1967</td>
233 <td rowspan="2">last Sunday</td>
239 <td rowspan="6">go to daylight saving time</td>
242 <td colspan="2">1974 only</td>
243 <td colspan="2">January 6<small><sup>th</sup></small></td>
246 <td colspan="2">1975 only</td>
247 <td colspan="2">February 23<small><sup>rd</sup></small></td>
253 <td rowspan="2">in April</td>
258 <td>first Sunday</td>
261 <td rowspan="2">2007</td>
262 <td rowspan="2">present</td>
263 <td colspan="2">second Sunday in March</td>
266 <td colspan="2">first Sunday in November</td>
267 <td>return to standard time</td>
271 <p>There are two interesting things to note here.</p>
273 <p>First, the time that something happens (in the <code>AT</code>
274 column) is not necessarily the local (wall clock) time. The time can be
275 suffixed with ‘s’ (for “standard”) to mean
276 local standard time, different from local (wall clock) time when observing
277 daylight saving time; or it can be suffixed with ‘g’,
278 ‘u’, or ‘z’, all three of which mean the
280 <a href="https://en.wikipedia.org/wiki/Prime_Meridian">prime meridian</a>.
281 ‘g’ stands for “<a
282 href="https://en.wikipedia.org/wiki/Greenwich_Mean_Time">GMT</a>”;
283 ‘u’ stands for “<a
284 href="https://en.wikipedia.org/wiki/Universal_Time">UT</a>” or “<a
285 href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a>”
286 (whichever was official at the time); ‘z’ stands for the
287 <a href="https://en.wikipedia.org/wiki/Nautical_time">nautical time zone</a>
288 Z (a.k.a. “Zulu” which, in turn, stands for ‘Z’).
289 The time can also be suffixed with ‘w’ meaning local (wall
290 clock) time; but it usually isn’t because that’s the
293 <p>Second, the day in the <code>ON</code> column, in addition to
294 “<code>lastSun</code>” or a particular day of the month,
295 can have the form, “<code>Sun>=</code><i>x</i>” or
296 “<code>Sun<=</code><i>x</i>,” where <i>x</i> is a day
297 of the month. For example, “<code>Sun>=8</code>” means
298 “the first Sunday on or after the eighth of the month,” in
299 other words, the second Sunday of the month. Furthermore, although
300 there are no examples above, the weekday needn’t be
301 “<code>Sun</code>” in either form, but can be the usual
302 three-character English abbreviation for any day of the week.</p>
304 <p>And the US rules give us more examples of a couple of things
305 already mentioned:</p>
308 <li>The rules for changing to and from daylight saving time are
309 actually <i>different sets</i> of rules; and the two sets can change
310 independently. Consider, for example, that the rule for the return to
311 standard time stayed the same from 1967 to 2006; but the rule for the
312 transition to daylight saving time changed several times in the same
313 period. There can also be periods, 1946 to 1966 for example, when no
314 rule from this group is in effect, and so either no transition
315 happened in those years, or some other rule is in effect (perhaps a
316 state or other more local rule).</li>
318 <li>The <code>SAVE</code> and <code>LETTER</code> columns
319 contain <i>steady state</i>, not transitions. Consider, for example,
320 the transition from “war time” to “peace time”
321 that happened on August 14, 1945. The “1:00” in
322 the <code>SAVE</code> column is <i>not</i> an instruction to advance
323 the clock an hour. It means that clocks should <i>be</i> one hour
324 ahead of standard time, which they already are because of the previous
325 rule, so there should be no change.</li>
329 <p>OK, now let’s look at a Zone record:</p>
333 <th colspan="5">From the Source File</th>
338 <tr><td style="border:none;text-align:left">
340 #Zone NAME STDOFF RULES FORMAT [UNTIL]
341 Zone America/Chicago -5:50:36 - LMT 1883 Nov 18 12:09:24
343 -6:00 Chicago C%sT 1936 Mar 1 2:00
344 -5:00 - EST 1936 Nov 15 2:00
345 -6:00 Chicago C%sT 1942
347 -6:00 Chicago C%sT 1967
350 </td></tr></table></td>
353 <th colspan="5">Columns Renamed</th>
356 <th rowspan="2">Standard Offset<br>
357 from <a href="https://en.wikipedia.org/wiki/Prime_Meridian">Prime
359 <th rowspan="2">Daylight<br>Saving Time</th>
360 <th rowspan="2">Abbreviation(s)</th>
361 <th colspan="2">Ending at Local Time</th>
368 <td>−5:50:36</td>
369 <td>not observed</td>
375 <td rowspan="2">−6:00:00</td>
377 <td rowspan="2">CST or CDT</td>
382 <td>Chicago rules</td>
384 <td rowspan="2">02:00:00</td>
387 <td>−5:00:00</td>
388 <td>not observed</td>
393 <td rowspan="4">−6:00:00</td>
394 <td>Chicago rules</td>
397 <td rowspan="3">00:00:00</td>
401 <td>CST, CWT or CPT</td>
405 <td>Chicago rules</td>
406 <td rowspan="2">CST or CDT</td>
411 <td colspan="2">—</td>
415 <p>There are a couple of interesting differences between Zones and Rules.</p>
417 <p>First, and somewhat trivially, whereas Rules are considered to
418 contain one or more records, a Zone is considered to be a single
419 record with zero or more <i>continuation lines</i>. Thus, the keyword,
420 “<code>Zone</code>,” and the zone name are not
421 repeated. The last line is the one without anything in
422 the <code>[UNTIL]</code> column.</p>
424 <p>Second, and more fundamentally, each line of a Zone represents a
425 steady state, not a transition between states. The state exists from
426 the date and time in the previous line’s <code>[UNTIL]</code>
427 column up to the date and time in the current
428 line’s <code>[UNTIL]</code> column. In other words, the date and
429 time in the <code>[UNTIL]</code> column is the instant that separates
430 this state from the next. Where that would be ambiguous because
431 we’re setting our clocks back, the <code>[UNTIL]</code> column
432 specifies the first occurrence of the instant. The state specified by
433 the last line, the one without anything in the <code>[UNTIL]</code>
434 column, continues to the present.</p>
436 <p>The first line typically specifies the mean solar time observed
437 before the introduction of standard time. Since there’s no line before
438 that, it has no beginning. <code>8-) </code> For some places near the <a
439 href="https://en.wikipedia.org/wiki/International_Date_Line">International
440 Date Line</a>, the first <i>two</i> lines will show solar times
441 differing by 24 hours; this corresponds to a movement of the Date
442 Line. For example:</p>
445 #Zone NAME STDOFF RULES FORMAT [UNTIL]
446 Zone America/Juneau 15:02:19 - LMT 1867 Oct 18
450 <p>When Alaska was purchased from Russia in 1867, the Date Line moved
451 from the Alaska/Canada border to the Bering Strait; and the time in
452 Alaska was then 24 hours earlier than it had
453 been. <code><aside></code>(6 October in the Julian calendar,
454 which Russia was still using then for religious reasons, was followed
455 by <i>a second instance of the same day with a different name</i>, 18
456 October in the Gregorian calendar. Isn’t civil time
457 wonderful? <code>8-)</code>)<code></aside></code></p>
459 <p>The abbreviation, “LMT” stands for “local mean
460 time”, which is an invention of
461 the <a href="https://en.wikipedia.org/wiki/Tz_database">tz
462 database</a> and was probably never actually used during the
463 period. Furthermore, the value is almost certainly wrong except in the
464 archetypal place after which the zone is named. (The tz database
465 usually doesn’t provide a separate Zone record for places where
466 nothing significant happened after 1970.)</p>
468 <p>The <code>RULES</code> column tells us whether daylight saving time is being observed:
470 <li>A hyphen, a kind of null value, means that we have not set our
471 clocks ahead of standard time.</li>
473 <li>An amount of time (usually but not necessarily “1:00”
474 meaning one hour) means that we have set our clocks ahead by that
477 <li>Some alphabetic string means that we <i>might have</i> set our
478 clocks ahead; and we need to check the rule the name of which is the
479 given alphabetic string.</li>
482 <p>An example of a specific amount of time is:</p>
484 #Zone NAME STDOFF RULES FORMAT [UNTIL]
485 Zone Pacific/Honolulu ... 1933 Apr 30 2:00
486 -10:30 1:00 HDT 1933 May 21 12:00
490 <p>Hawaii tried daylight saving time for three weeks in 1933 and
491 decided they didn’t like it. <code>8-) </code>Note that
492 the <code>STDOFF</code> column always contains the standard time
493 offset, so the local (wall clock) time during this period was GMT −
494 10:30 + 1:00 = GMT − 9:30.</p>
496 <p>The <code>FORMAT</code> column specifies the usual abbreviation of
497 the time zone name. It should have one of four forms:</p>
500 <li>a time zone abbreviation that is a string of three or more
501 characters that are either ASCII alphanumerics,
502 “<code>+</code>”, or “<code>-</code>”</li>
504 <li>the string “%z”, in which case the
505 “<code>%z</code>” will be replaced by a numeric time zone
508 <li>a pair of time zone abbreviations separated by a slash
509 (‘<code>/</code>’), in which case the first string is the
510 abbreviation for the standard time name and the second string is the
511 abbreviation for the daylight saving time name</li>
513 <li>a string containing “<code>%s</code>”, in which case
514 the “<code>%s</code>” will be replaced by the text in the
515 appropriate Rule’s <code>LETTER</code> column, and the resulting
516 string should be a time zone abbreviation</li>
519 <p>The last two make sense only if there’s a named rule in effect.</p>
521 <p>An example of a slash is:</p>
523 #Zone NAME STDOFF RULES FORMAT [UNTIL]
524 Zone Europe/London ... 1996
528 <p>The current time in the UK is called either Greenwich mean time or
529 British summer time.</p>
531 <p>One wrinkle, not fully explained in <code>zic.8.txt</code>, is what
532 happens when switching to a named rule. To what values should
533 the <code>SAVE</code> and <code>LETTER</code> data be initialized?</p>
536 <li>If at least one transition has happened, use
537 the <code>SAVE</code> and <code>LETTER</code> data from the most
540 <li>If switching to a named rule before any transition has happened,
541 assume standard time (<code>SAVE</code> zero), and use
542 the <code>LETTER</code> data from the earliest transition with
543 a <code>SAVE</code> of zero.
547 <p>And three last things about the <code>FORMAT</code> column:</p>
550 <li>The <a href="https://en.wikipedia.org/wiki/Tz_database">tz
551 database</a> gives abbreviations for time zones
552 in popular English-language usage. For
553 example, the last line in
554 <code>Zone</code> <code>Pacific/Honolulu</code> (shown below) gives
555 “HST” for “Hawaii standard time” even though the
556 <a href="https://www.law.cornell.edu/uscode/text/15/263">legal</a>
557 name for that time zone is “Hawaii-Aleutian standard time.”
558 This author has read that there are also some places in Australia where
559 popular time zone names differ from the legal ones.
561 <li>No attempt is made to <a
562 href="https://en.wikipedia.org/wiki/Internationalization_and_localization">localize</a>
563 the abbreviations. They are intended to be the values returned through the
564 <code>"%Z"</code> format specifier to
565 <a href="https://en.wikipedia.org/wiki/C_(programming_language)">C</a>’s
566 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.html"><code>strftime</code></a>
568 <a href="https://kirste.userpage.fu-berlin.de/chemnet/use/info/libc/libc_19.html#SEC324">“C” locale</a>.
570 <li>If there is no generally accepted abbreviation for a time zone,
571 a numeric offset is used instead, e.g., <code>+07</code> for 7 hours
572 ahead of Greenwich. By convention, <code>-00</code> is used in a
573 zone while uninhabited, where the offset is zero but in some sense
574 the true offset is undefined.
577 <p>As a final example, here’s the complete history for Hawaii:</p>
581 <th colspan="6">Relevant Excerpts from the US Rules</th>
586 <tr><td style="border:none;text-align:left">
588 #Rule NAME FROM TO - IN ON AT SAVE LETTER/S
589 Rule US 1918 1919 - Oct lastSun 2:00 0 S
590 Rule US 1942 only - Feb 9 2:00 1:00 W # War
591 Rule US 1945 only - Aug 14 23:00u 1:00 P # Peace
592 Rule US 1945 only - Sep lastSun 2:00 0 S
594 </td></tr></table></td>
597 <th colspan="6">The Zone Record</th>
602 <tr><td style="border:none;text-align:left">
604 #Zone NAME STDOFF RULES FORMAT [UNTIL]
605 Zone Pacific/Honolulu -10:31:26 - LMT 1896 Jan 13 12:00
606 -10:30 - HST 1933 Apr 30 2:00
607 -10:30 1:00 HDT 1933 May 21 2:00
608 -10:30 US H%sT 1947 Jun 8 2:00
611 </td></tr></table></td>
614 <th colspan="6">What We Infer</th>
617 <th rowspan="2">Wall-Clock<br>Offset from<br>Prime Meridian</th>
618 <th rowspan="2">Adjust<br>Clocks</th>
619 <th colspan="2">Time Zone</th>
620 <th colspan="2">Ending at Local Time</th>
629 <td>−10:31:26</td>
632 <td>local mean time</td>
637 <td>−10:30</td>
640 <td>Hawaii standard time</td>
648 <td>Hawaii daylight time</td>
653 <td>−10:30¹</td>
654 <td>−1:00¹</td>
656 <td>Hawaii standard time</td>
661 <td rowspan="2">−9:30</td>
664 <td>Hawaii war time</td>
671 <td>Hawaii peace time</td>
673 <td rowspan="2">02:00</td>
676 <td>−10:30</td>
678 <td rowspan="2">HST</td>
679 <td rowspan="2">Hawaii standard time</td>
683 <td>−10:00³</td>
685 <td colspan="2">—</td>
688 <td colspan="6" class="footnote">
689 ¹Switching to US rules…most recent transition (in 1919) was to standard time
693 <td colspan="6" class="footnote">
694 ²23:00 <a href="https://en.wikipedia.org/wiki/Universal_Time">UT</a>
695 + (−9:30) = 13:30 local
699 <td colspan="6" class="footnote">
700 ³Since <a href="https://en.wikipedia.org/wiki/ISO_8601">1947–06–08T12:30Z</a>,
701 the civil time in Hawaii has been
702 <a href="https://en.wikipedia.org/wiki/Universal_Time">UT</a>/<a href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a>
703 − 10:00 year-round.
708 <p>There will be a short quiz later. <code>8-)</code></p>
712 This web page is in the public domain, so clarified as of
713 2015-10-20 by Bill Seymour.
715 All suggestions and corrections will be welcome; all flames will be amusing.
716 Mail to was at pobox dot com.
projects / FreeBSD / FreeBSD.git / blob