2 PUBLIC
"-//W3C//DTD HTML 4.01//EN"
3 "http://www.w3.org/TR/html4/strict.dtd">
5 <head><title>How to Read the tz Database
</title></head>
7 <h2>How to Read the
<a href=
"https://en.wikipedia.org/wiki/Tz_database">tz
8 Database
</a> Source Files
</h2>
9 <h3>by Bill Seymour
</h3>
10 <p>This page uses the
<code>America/Chicago
</code> and
11 <code>Pacific/Honolulu
</code> zones as examples of how to infer
12 times of day from the
<a href=
"tz-link.htm">tz database
</a>
13 source files. It might be helpful, but not absolutely necessary,
14 for the reader to have already downloaded the
15 latest release of the database and become familiar with the basic layout
16 of the data files. The format is explained in the
“man
17 page
” for the zic compiler,
<code>zic
.8.txt
</code>, in
18 the
<code>code
</code> subdirectory.
</p>
20 <p>We
’ll begin by talking about the rules for changing between standard
21 and daylight saving time since we
’ll need that information when we talk
24 <p>First, let
’s consider the special daylight saving time rules
25 for Chicago (from the
<code>northamerica
</code> file in
26 the
<code>data
</code> subdirectory):
</p>
30 <th colspan=
"6">From the Source File
</th>
33 <td colspan=
"6" align=
"center"><table><tr><td>
35 #Rule NAME FROM TO TYPE IN ON AT SAVE LETTER
36 Rule Chicago
1920 only - Jun
13 2:
00 1:
00 D
37 Rule Chicago
1920 1921 - Oct lastSun
2:
00 0 S
38 Rule Chicago
1921 only - Mar lastSun
2:
00 1:
00 D
39 Rule Chicago
1922 1966 - Apr lastSun
2:
00 1:
00 D
40 Rule Chicago
1922 1954 - Sep lastSun
2:
00 0 S
41 Rule Chicago
1955 1966 - Oct lastSun
2:
00 0 S
43 </td></tr></table></td>
46 <th colspan=
"6">Reformatted a Bit
</th>
51 <th colspan=
"2">On
</th>
56 <td colspan=
"2">1920 only
</td>
57 <td colspan=
"2">June
13<small><sup>th
</sup></small></td>
58 <td rowspan=
"6">02:
00 local
</td>
59 <td>go to daylight saving time
</td>
64 <td rowspan=
"5">last Sunday
</td>
66 <td>return to standard time
</td>
69 <td colspan=
"2">1921 only
</td>
71 <td rowspan=
"2">go to daylight saving time
</td>
74 <td rowspan=
"2">1922</td>
81 <td rowspan=
"2">return to standard time
</td>
90 <p>We
’ll basically just ignore the
<code>TYPE
</code> column.
91 In the
2007j release, the most recent as of this writing, the
92 <code>TYPE
</code> column never contains anything but a hyphen,
93 a kind of null value. (From the description in
<code>zic
.8.txt
</code>,
94 this appears to be a mechanism for removing years from a set
95 in some localizable way. It
’s used in the file,
<code>pacificnew
</code>,
96 to determine whether a given year will have a US presidential election;
97 but everything related to that use is commented out.)
99 <p>The
<code>SAVE
</code> column contains the wall clock offset from
101 This is usually either zero for standard time or one hour for daylight
102 saving time; but there
’s no reason, in principle, why it can
’t
103 take on other values.
105 <p>The
<code>LETTER
</code> (sometimes called
<code>LETTER/S
</code>)
106 column can contain a variable
107 part of the usual abbreviation of the time zone
’s name, or it can just
108 be a hyphen if there
’s no variable part. For example, the abbreviation
109 used in the central time zone will be either
“CST
” or
110 “CDT
”. The variable part is
‘S
’ or
‘D
’;
111 and, sure enough, that
’s just what we find in
112 the
<code>LETTER
</code> column
113 in the
<code>Chicago
</code> rules. More about this when we talk about
114 “Zone
” lines.
116 <p>One important thing to notice is that
“Rule
” lines
117 want at once to be both
<i>transitions
</i> and
<i>steady states
</i>:
119 <li>On the one hand, they represent transitions between standard and
120 daylight saving time; and any number of Rule lines can be in effect
121 during a given period (which will always be a non-empty set of
122 contiguous calendar years).
</li>
123 <li>On the other hand, the
<code>SAVE
</code> and
<code>LETTER
</code>
124 columns contain state that exists between transitions. More about this
125 when we talk about the US rules.
</li>
128 <p>In the example above, the transition to daylight saving time
129 happened on the
13<small><sup>th
</sup></small> of June in
1920, and on
130 the last Sunday in March in
1921; but the return to standard time
131 happened on the last Sunday in October in both of those
132 years. Similarly, the rule for changing to daylight saving time was
133 the same from
1922 to
1966; but the rule for returning to standard
134 time changed in
1955. Got it?
</p>
136 <p>OK, now for the somewhat more interesting
“US
” rules:
</p>
140 <th colspan=
"6">From the Source File
</th>
143 <td colspan=
"6" align=
"center"><table><tr><td>
145 #Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
146 Rule US
1918 1919 - Mar lastSun
2:
00 1:
00 D
147 Rule US
1918 1919 - Oct lastSun
2:
00 0 S
148 Rule US
1942 only - Feb
9 2:
00 1:
00 W # War
149 Rule US
1945 only - Aug
14 23:
00u 1:
00 P # Peace
150 Rule US
1945 only - Sep
30 2:
00 0 S
151 Rule US
1967 2006 - Oct lastSun
2:
00 0 S
152 Rule US
1967 1973 - Apr lastSun
2:
00 1:
00 D
153 Rule US
1974 only - Jan
6 2:
00 1:
00 D
154 Rule US
1975 only - Feb
23 2:
00 1:
00 D
155 Rule US
1976 1986 - Apr lastSun
2:
00 1:
00 D
156 Rule US
1987 2006 - Apr Sun
>=
1 2:
00 1:
00 D
157 Rule US
2007 max - Mar Sun
>=
8 2:
00 1:
00 D
158 Rule US
2007 max - Nov Sun
>=
1 2:
00 0 S
160 </td></tr></table></td>
163 <th colspan=
"6">Reformatted a Bit
</th>
168 <th colspan=
"2">On
</th>
173 <td rowspan=
"2">1918</td>
174 <td rowspan=
"2">1919</td>
175 <td rowspan=
"2">last Sunday
</td>
177 <td rowspan=
"3">02:
00 local
</td>
178 <td>go to daylight saving time
</td>
182 <td>return to standard time
</td>
185 <td colspan=
"2">1942 only
</td>
186 <td colspan=
"2">February
9<small><sup>th
</sup></small></td>
187 <td>go to
“war time
”</td>
190 <td colspan=
"2" rowspan=
"2">1945 only
</td>
191 <td colspan=
"2">August
14<small><sup>th
</sup></small></td>
192 <td>23:
00 <a href=
"https://en.wikipedia.org/wiki/Universal_Time">UT
</a></td>
194 rename
“war time
” to
“peace
<br>time;
”
195 clocks don
’t change
199 <td colspan=
"2">September
30<small><sup>th
</sup></small></td>
200 <td rowspan=
"9">02:
00 local
</td>
201 <td rowspan=
"2">return to standard time
</td>
204 <td rowspan=
"2">1967</td>
206 <td rowspan=
"2">last Sunday
</td>
212 <td rowspan=
"6">go to daylight saving time
</td>
215 <td colspan=
"2">1974 only
</td>
216 <td colspan=
"2">January
6<small><sup>th
</sup></small></td>
219 <td colspan=
"2">1975 only
</td>
220 <td colspan=
"2">February
23<small><sup>rd
</sup></small></td>
226 <td rowspan=
"2">in April
</td>
231 <td>first Sunday
</td>
234 <td rowspan=
"2">2007</td>
235 <td rowspan=
"2">present
</td>
236 <td colspan=
"2">second Sunday in March
</td>
239 <td colspan=
"2">first Sunday in November
</td>
240 <td>return to standard time
</td>
244 <p>There are two interesting things to note here.
</p>
246 <p>First, the time that something happens (in the
<code>AT
</code>
247 column) is not necessarily the local wall clock time. The time can be
248 suffixed with
‘s
’ (for
“standard
”) to mean
249 local standard time (different from wall clock time when observing
250 daylight saving time); or it can be suffixed with
‘g
’,
251 ‘u
’, or
‘z
’, all three of which mean the
253 <a href=
"https://en.wikipedia.org/wiki/Prime_Meridian">prime meridian
</a>.
254 ‘g
’ stands for
“<a
255 href=
"https://en.wikipedia.org/wiki/Greenwich_Mean_Time">GMT
</a>”;
256 ‘u
’ stands for
“<a
257 href=
"https://en.wikipedia.org/wiki/Universal_Time">UT
</a>” or
“<a
258 href=
"https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC
</a>”
259 (whichever was official at the time);
‘z
’ stands for the
260 <a href=
"https://en.wikipedia.org/wiki/Nautical_time">nautical time zone
</a>
261 Z (a.k.a.
“Zulu
” which, in turn, stands for
‘Z
’).
262 The time can also be suffixed with
‘w
’ meaning
“wall
263 clock time;
” but it usually isn
’t because that
’s the
266 <p>Second, the day in the
<code>ON
</code> column, in addition to
267 “<code>lastSun
</code>” or a particular day of the month,
268 can have the form,
“<code>Sun
>=
</code><i>x
</i>” or
269 “<code>Sun
<=
</code><i>x
</i>,
” where
<i>x
</i> is a day
270 of the month. For example,
“<code>Sun
>=
8</code>” means
271 “the first Sunday on or after the eighth of the month,
” in
272 other words, the second Sunday of the month. Furthermore, although
273 there are no examples above, the weekday needn
’t be
274 “<code>Sun
</code>” in either form, but can be the usual
275 three-character English abbreviation for any day of the week.
</p>
277 <p>And the US rules give us more examples of a couple of things
278 already mentioned:
</p>
281 <li>The rules for changing to and from daylight saving time are
282 actually
<i>different sets
</i> of rules; and the two sets can change
283 independently. Consider, for example, that the rule for the return to
284 standard time stayed the same from
1967 to
2006; but the rule for the
285 transition to daylight saving time changed several times in the same
286 period. There can also be periods,
1946 to
1966 for example, when no
287 rule from this group is in effect, and so either no transition
288 happened in those years, or some other rule is in effect (perhaps a
289 state or other more local rule).
</li>
291 <li>The
<code>SAVE
</code> and
<code>LETTER
</code> columns
292 contain
<i>steady state
</i>, not transitions. Consider, for example,
293 the transition from
“war time
” to
“peace time
”
294 that happened on August
14,
1945. The
“1:
00” in
295 the
<code>SAVE
</code> column is
<i>not
</i> an instruction to advance
296 the clock an hour. It means that clocks should
<i>be
</i> one hour
297 ahead of standard time, which they already are because of the previous
298 rule, so there should be no change.
</li>
302 <p>OK, now let
’s look at a Zone record:
</p>
306 <th colspan=
"5">From the Source File
</th>
309 <td colspan=
"6" align=
"center"><table><tr><td>
311 #Zone NAME GMTOFF RULES FORMAT [UNTIL]
312 Zone America/Chicago -
5:
50:
36 - LMT
1883 Nov
18 12:
09:
24
314 -
6:
00 Chicago C%sT
1936 Mar
1 2:
00
315 -
5:
00 - EST
1936 Nov
15 2:
00
316 -
6:
00 Chicago C%sT
1942
318 -
6:
00 Chicago C%sT
1967
321 </td></tr></table></td>
324 <th colspan=
"5">Columns Renamed
</th>
327 <th rowspan=
"2">Standard Offset
<br>
328 from
<a href=
"https://en.wikipedia.org/wiki/Prime_Meridian">Prime
330 <th rowspan=
"2">Daylight
<br>Saving Time
</th>
331 <th rowspan=
"2">Abbreviation(s)
</th>
332 <th colspan=
"2">Ending at Local Time
</th>
339 <td>−5:
50:
36</td>
340 <td>not observed
</td>
346 <td rowspan=
"2">−6:
00:
00</td>
348 <td rowspan=
"2">CST or CDT
</td>
353 <td>Chicago rules
</td>
355 <td rowspan=
"2">02:
00:
00</td>
358 <td>−5:
00:
00</td>
359 <td>not observed
</td>
364 <td rowspan=
"4">−6:
00:
00</td>
365 <td>Chicago rules
</td>
368 <td rowspan=
"3">00:
00:
00</td>
372 <td>CST, CWT or CPT
</td>
376 <td>Chicago rules
</td>
377 <td rowspan=
"2">CST or CDT
</td>
382 <td colspan=
"2">—</td>
386 <p>There are a couple of interesting differences between Zones and Rules.
</p>
388 <p>First, and somewhat trivially, whereas Rules are considered to
389 contain one or more records, a Zone is considered to be a single
390 record with zero or more
<i>continuation lines
</i>. Thus, the keyword,
391 “<code>Zone
</code>,
” and the zone name are not
392 repeated. The last line is the one without anything in
393 the
<code>[UNTIL]
</code> column.
</p>
395 <p>Second, and more fundamentally, each line of a Zone represents a
396 steady state, not a transition between states. The state exists from
397 the date and time in the previous line
’s
<code>[UNTIL]
</code>
398 column up to the date and time in the current
399 line
’s
<code>[UNTIL]
</code> column. In other words, the date and
400 time in the
<code>[UNTIL]
</code> column is the instant that separates
401 this state from the next. Where that would be ambiguous because
402 we
’re setting our clocks back, the
<code>[UNTIL]
</code> column
403 specifies the first occurrence of the instant. The state specified by
404 the last line, the one without anything in the
<code>[UNTIL]
</code>
405 column, continues to the present.
</p>
407 <p>The first line typically specifies the mean solar time observed
408 before the introduction of standard time. Since there
’s no line before
409 that, it has no beginning.
<code>8-)
</code> For some places near the
<a
410 href=
"https://en.wikipedia.org/wiki/International_Date_Line">International
411 Date Line
</a>, the first
<i>two
</i> lines will show solar times
412 differing by
24 hours; this corresponds to a movement of the Date
413 Line. For example:
</p>
416 #Zone NAME GMTOFF RULES FORMAT [UNTIL]
417 Zone America/Juneau
15:
02:
19 - LMT
1867 Oct
18
421 <p>When Alaska was purchased from Russia in
1867, the Date Line moved
422 from the Alaska/Canada border to the Bering Strait; and the time in
423 Alaska was then
24 hours earlier than it had
424 been.
<code><aside
></code>(
6 October in the Julian calendar,
425 which Russia was still using then for religious reasons, was followed
426 by
<i>a second instance of the same day with a different name
</i>,
18
427 October in the Gregorian calendar. Isn
’t civil time
428 wonderful?
<code>8-)
</code>)
<code></aside
></code></p>
430 <p>The abbreviation,
“LMT
” stands for
“local mean
431 time
”, which is an invention of
432 the
<a href=
"https://en.wikipedia.org/wiki/Tz_database">tz
433 database
</a> and was probably never actually used during the
434 period. Furthermore, the value is almost certainly wrong except in the
435 archetypal place after which the zone is named. (The tz database
436 usually doesn
’t provide a separate Zone record for places where
437 nothing significant happened after
1970.)
</p>
439 <p>The
<code>RULES
</code> column tells us whether daylight saving time is being observed:
441 <li>A hyphen, a kind of null value, means that we have not set our
442 clocks ahead of standard time.
</li>
444 <li>An amount of time (usually but not necessarily
“1:
00”
445 meaning one hour) means that we have set our clocks ahead by that
448 <li>Some alphabetic string means that we
<i>might have
</i> set our
449 clocks ahead; and we need to check the rule the name of which is the
450 given alphabetic string.
</li>
453 <p>An example of a specific amount of time is:
</p>
455 #Zone NAME GMTOFF RULES FORMAT [UNTIL]
456 Zone Pacific/Honolulu ...
1933 Apr
30 2:
00
457 -
10:
30 1:
00 HDT
1933 May
21 2:
00
461 <p>Hawaii tried daylight saving time for three weeks in
1933 and
462 decided they didn
’t like it.
<code>8-)
</code>Note that
463 the
<code>GMTOFF
</code> column always contains the standard time
464 offset, so the wall clock time during this period was GMT
−
465 10:
30 +
1:
00 = GMT
− 9:
30.
</p>
467 <p>The
<code>FORMAT
</code> column specifies the usual abbreviation of
468 the time zone name. It can have one of three forms:
</p>
471 <li>a string of three or more characters that are either ASCII alphanumerics,
472 “<code>+
</code>”, or
“<code>-
</code>”,
473 in which case that
’s the abbreviation
</li>
475 <li>a pair of strings separated by a slash
476 (
‘<code>/
</code>’), in which case the first string is the
477 abbreviation for the standard time name and the second string is the
478 abbreviation for the daylight saving time name
</li>
480 <li>a string containing
“<code>%s
</code>,
” in which case
481 the
“<code>%s
</code>” will be replaced by the text in the
482 appropriate Rule
’s
<code>LETTER
</code> column
</li>
485 <p>The last two make sense only if there
’s a named rule in effect.
</p>
487 <p>An example of a slash is:
</p>
489 #Zone NAME GMTOFF RULES FORMAT [UNTIL]
490 Zone Europe/London ...
1996
494 <p>The current time in the UK is called either Greenwich mean time or
495 British summer time.
</p>
497 <p>One wrinkle, not fully explained in
<code>zic
.8.txt
</code>, is what
498 happens when switching to a named rule. To what values should
499 the
<code>SAVE
</code> and
<code>LETTER
</code> data be initialized?
</p>
502 <li>If at least one transition has happened, use
503 the
<code>SAVE
</code> and
<code>LETTER
</code> data from the most
506 <li>If switching to a named rule before any transition has happened,
507 assume standard time (
<code>SAVE
</code> zero), and use
508 the
<code>LETTER
</code> data from the earliest transition with
509 a
<code>SAVE
</code> of zero.
513 <p>And three last things about the
<code>FORMAT
</code> column:
</p>
516 <li>The
<a href=
"https://en.wikipedia.org/wiki/Tz_database">tz
517 database
</a> gives abbreviations for time zone names in
<i>popular
518 usage
</i>, which is not necessarily
“correct
” by law. For
519 example, the last line in
520 <code>Zone
</code> <code>Pacific/Honolulu
</code> (shown below) gives
521 “HST
” for
“Hawaii standard time
” even though the
522 <a href=
"http://www.law.cornell.edu/uscode/html/uscode15/usc_sec_15_00000263----000-.html">legal
</a>
523 name for that time zone is
“Hawaii-Aleutian standard time.
”
524 This author has read that there are also some places in Australia where
525 popular time zone names differ from the legal ones.
527 <li>No attempt is made to
<a
528 href=
"https://en.wikipedia.org/wiki/Internationalization_and_localization">localize
</a>
529 the abbreviations. They are intended to be the values returned through the
530 <code>"%Z"</code> format specifier to
531 <a href=
"https://en.wikipedia.org/wiki/C_(programming_language)">C
</a>’s
532 <a href=
"http://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.html"><code>strftime
</code></a>
534 <a href=
"http://www.chemie.fu-berlin.de/chemnet/use/info/libc/libc_19.html#SEC324">“C
” locale
</a>.
536 <li>If there is no generally-accepted abbreviation for a time zone,
537 a numeric offset is used instead, e.g.,
<code>+
07</code> for
7 hours
538 ahead of Greenwich. By convention,
<code>-
00</code> is used in a
539 zone while uninhabited, where the offset is zero but in some sense
540 the true offset is undefined.
543 <p>As a final example, here
’s the complete history for Hawaii:
</p>
547 <th colspan=
"6">Relevant Excerpts from the US Rules
</th>
550 <td colspan=
"6" align=
"center"><table><tr><td>
552 #Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
553 Rule US
1918 1919 - Oct lastSun
2:
00 0 S
554 Rule US
1942 only - Feb
9 2:
00 1:
00 W # War
555 Rule US
1945 only - Aug
14 23:
00u 1:
00 P # Peace
556 Rule US
1945 only - Sep
30 2:
00 0 S
558 </td></tr></table></td>
561 <th colspan=
"6">The Zone Record
</th>
564 <td colspan=
"6" align=
"center"><table><tr><td>
566 #Zone NAME GMTOFF RULES FORMAT [UNTIL]
567 Zone Pacific/Honolulu -
10:
31:
26 - LMT
1900 Jan
1 12:
00
568 -
10:
30 - HST
1933 Apr
30 2:
00
569 -
10:
30 1:
00 HDT
1933 May
21 2:
00
570 -
10:
30 US H%sT
1947 Jun
8 2:
00
573 </td></tr></table></td>
576 <th colspan=
"6">What We Infer
</th>
579 <th rowspan=
"2">Wall-Clock
<br>Offset from
<br>Prime Meridian
</th>
580 <th rowspan=
"2">Adjust
<br>Clocks
</th>
581 <th colspan=
"2">Time Zone
</th>
582 <th colspan=
"2">Ending at Local Time
</th>
591 <td>−10:
31:
26</td>
594 <td>local mean time
</td>
599 <td>−10:
30</td>
602 <td>Hawaii standard time
</td>
604 <td rowspan=
"3">02:
00</td>
610 <td>Hawaii daylight time
</td>
614 <td>−10:
30¹</td>
615 <td>−1:
00¹</td>
617 <td>Hawaii standard time
</td>
621 <td rowspan=
"2">−9:
30</td>
624 <td>Hawaii war time
</td>
631 <td>Hawaii peace time
</td>
633 <td rowspan=
"2">02:
00</td>
636 <td>−10:
30</td>
638 <td rowspan=
"2">HST
</td>
639 <td rowspan=
"2">Hawaii standard time
</td>
643 <td>−10:
00³</td>
645 <td colspan=
"2">—</td>
649 ¹Switching to US rules
…most recent transition (in
1919) was to standard time
654 ²23:
00 <a href=
"https://en.wikipedia.org/wiki/Universal_Time">UT
</a>
655 + (
−9:
30) =
13:
30 local
660 ³Since
<a href=
"https://en.wikipedia.org/wiki/ISO_8601">1947–06–08T12:
30Z
</a>,
661 the civil time in Hawaii has been
662 <a href=
"https://en.wikipedia.org/wiki/Universal_Time">UT
</a>/
<a href=
"https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC
</a>
663 − 10:
00 year-round.
668 <p>There will be a short quiz later.
<code>8-)
</code></p>
672 This web page is in the public domain, so clarified as of
673 2015-
10-
20 by Bill Seymour.
675 All suggestions and corrections will be welcome; all flames will be amusing.
676 Mail to was at pobox dot com.
