<html>
<head><title>How to Read the tz Database</title></head>
<body>
<h2>How to Read the <a href="http://en.wikipedia.org/wiki/Zoneinfo">tz Database</a> Source Files</h2>
<h3>by Bill Seymour</h3>
<h4>This paper is in the public domain.</h4>
This paper uses the <tt>America/Chicago</tt> and <tt>Pacific/Honolulu</tt> zones as examples of how to infer
times of day from the <a href="http://www.twinsun.com/tz/tz-link.htm">tz database</a>
source files. It might be helpful, but not absolutely necessary,
for the reader to have already downloaded the database from
<nobr><tt><a href="ftp://elsie.nci.nih.gov/pub/">ftp://elsie.nci.nih.gov/pub/</a></tt></nobr>
and become familiar with the basic layout of the data files. The format is explained
in the “man page” for the zic compiler, <nobr><tt>zic.8.txt</tt>,</nobr> in the <tt>code</tt>
subdirectory.
<p>We’ll begin by talking about the rules for changing between standard
and daylight saving time since we’ll need that information when we talk
about the zones.
<p>First, let’s consider the special daylight saving time rules for Chicago
(from the <tt>northamerica</tt> file in the <tt>data</tt> subdirectory):
<p>
<table border>
<tr>
<th colspan=6>From the Source File</th>
</tr>
<tr>
<td colspan=6>
<pre>
# Rule NAME FROM TO TYPE IN ON AT SAVE LETTER
Rule Chicago 1920 only - Jun 13 2:00 1:00 D
Rule Chicago 1920 1921 - Oct lastSun 2:00 0 S
Rule Chicago 1921 only - Mar lastSun 2:00 1:00 D
Rule Chicago 1922 1966 - Apr lastSun 2:00 1:00 D
Rule Chicago 1922 1954 - Sep lastSun 2:00 0 S
Rule Chicago 1955 1966 - Oct lastSun 2:00 0 S
</pre>
</td>
</tr>
<tr>
<th colspan=6>Reformatted a Bit</th>
</tr>
<tr>
<th>From</th>
<th>To</th>
<th colspan=2>On</th>
<th>At</th>
<th>Action</th>
</tr>
<tr align=center>
<td colspan=2>1920 only</td>
<td colspan=2>June 13<small><sup>th</sup></small></td>
<td rowspan=6>02:00 local</td>
<td>go to daylight saving time</td>
</tr>
<tr align=center>
<td>1920</td>
<td>1921</td>
<td rowspan=5>last Sunday</td>
<td>in October</td>
<td>return to standard time</td>
</tr>
<tr align=center>
<td colspan=2>1921 only</td>
<td>in March</td>
<td rowspan=2>go to daylight saving time</td>
</tr>
<tr align=center>
<td rowspan=2>1922</td>
<td>1966</td>
<td>in April</td>
</tr>
<tr align=center>
<td>1954</td>
<td>in September</td>
<td rowspan=2>return to standard time</td>
</tr>
<tr align=center>
<td>1955</td>
<td>1966</td>
<td>in October</td>
</tr>
</table>
<p>We’ll basically just ignore the <tt>TYPE</tt> column.
In the 2007j release, the most recent as of this writing, the
<tt>TYPE</tt> column never contains anything but a hyphen,
a kind of null value. (From the description in <tt>zic.8.txt</tt>,
this appears to be a mechanism for removing years from a set
in some localizable way. It’s used in the file, <tt>pacificnew</tt>,
to determine whether a given year will have a US presidential election;
but everything related to that use is commented out.)
<p>The <tt>SAVE</tt> column contains the wall clock offset from local standard time.
This is usually either zero for standard time or one hour for daylight
saving time; but there’s no reason, in principle, why it can’t
take on other values.
<p>The <tt>LETTER</tt> (sometimes called <tt>LETTER/S</tt>) column can contain a variable
part of the usual abbreviation of the time zone’s name, or it can just
be a hyphen if there’s no variable part. For example, the abbreviation
used in the central time zone will be either “CST” or
“CDT”. The variable part is ‘S’ or ‘D’;
and, sure enough, that’s just what we find in the <tt>LETTER</tt> column
in the <tt>Chicago</tt> rules. More about this when we talk about
“Zone” lines.
<p>One important thing to notice is that “Rule” lines
want at once to be both <i>transitions</i> and <i>steady states</i>:
<ul>
<li>On the one hand, they represent transitions between standard and daylight saving time;
and any number of Rule lines can be in effect during a given period (which will always
be a non-empty set of contiguous calendar years).
<p>
<li>On the other hand, the <tt>SAVE</tt> and <tt>LETTER</tt> columns contain
state that exists between transitions. More about this when we talk about
the US rules.
</ul>
<p>In the example above, the transition to daylight saving time happened on the
13<small><sup>th</sup></small> of June in 1920, and on the last Sunday in March
in 1921; but the return to standard time happened on the last Sunday in October
in both of those years. Similarly, the rule for changing to daylight saving time
was the same from 1922 to 1966; but the rule for returning to standard time
changed in 1955. Got it?
<p>OK, now for the somewhat more interesting “US” rules:
<p>
<table border>
<tr>
<th colspan=6>From the Source File</th>
</tr>
<tr>
<td colspan=6>
<pre>
# Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
Rule US 1918 1919 - Mar lastSun 2:00 1:00 D
Rule US 1918 1919 - Oct lastSun 2:00 0 S
Rule US 1942 only - Feb 9 2:00 1:00 W # War
Rule US 1945 only - Aug 14 23:00u 1:00 P # Peace
Rule US 1945 only - Sep 30 2:00 0 S
Rule US 1967 2006 - Oct lastSun 2:00 0 S
Rule US 1967 1973 - Apr lastSun 2:00 1:00 D
Rule US 1974 only - Jan 6 2:00 1:00 D
Rule US 1975 only - Feb 23 2:00 1:00 D
Rule US 1976 1986 - Apr lastSun 2:00 1:00 D
Rule US 1987 2006 - Apr Sun>=1 2:00 1:00 D
Rule US 2007 max - Mar Sun>=8 2:00 1:00 D
Rule US 2007 max - Nov Sun>=1 2:00 0 S
</pre>
</td>
</tr>
<tr>
<th colspan=6>Reformatted a Bit</th>
</tr>
<tr>
<th>From</th>
<th>To</th>
<th colspan=2>On</th>
<th>At</th>
<th>Action</th>
</tr>
<tr align=center>
<td rowspan=2>1918</td>
<td rowspan=2>1919</td>
<td rowspan=2>last Sunday</td>
<td>in March</td>
<td rowspan=3>02:00 local</td>
<td>go to daylight saving time</td>
</tr>
<tr align=center>
<td>in October</td>
<td>return to standard time</td>
</tr>
<tr align=center>
<td colspan=2>1942 only</td>
<td colspan=2>February 9<small><sup>th</sup></small></td>
<td>go to “war time”</td>
</tr>
<tr align=center>
<td colspan=2 rowspan=2>1945 only</td>
<td colspan=2>August 14<small><sup>th</sup></small></td>
<td>23:00 <a href="http://en.wikipedia.org/wiki/Universal_Time">UT</a></td>
<td>
rename “war time” to “peace<br>time;” clocks don’t change
</td>
</tr>
<tr align=center>
<td colspan=2>September 30<small><sup>th</sup></small></td>
<td rowspan=9>02:00 local</td>
<td rowspan=2>return to standard time</td>
</tr>
<tr align=center>
<td rowspan=2>1967</td>
<td>2006</td>
<td rowspan=2>last Sunday</td>
<td>in October</td>
</tr>
<tr align=center>
<td>1973</td>
<td>in April</td>
<td rowspan=6>go to daylight saving time</td>
</tr>
<tr align=center>
<td colspan=2>1974 only</td>
<td colspan=2>January 6<small><sup>th</sup></small></td>
</tr>
<tr align=center>
<td colspan=2>1975 only</td>
<td colspan=2>February 23<small><sup>rd</sup></small></td>
</tr>
<tr align=center>
<td>1976</td>
<td>1986</td>
<td>last Sunday</td>
<td rowspan=2>in April</td>
</tr>
<tr align=center>
<td>1987</td>
<td>2006</td>
<td>first Sunday</td>
</tr>
<tr align=center>
<td rowspan=2>2007</td>
<td rowspan=2>present</td>
<td colspan=2>second Sunday in March</td>
</tr>
<tr align=center>
<td colspan=2>first Sunday in November</td>
<td>return to standard time</td>
</tr>
</table>
<p>There are two interesting things to note here.
<p>First, the time that something happens (in the <tt>AT</tt> column) is not necessarily
the local wall clock time. The time can be suffixed with ‘s’ (for
“standard”) to mean local standard time (different from wall clock
time when observing daylight saving time); or it can be suffixed with ‘g’,
‘u’, or ‘z’, all three of which mean the standard time at the
<a href="http://en.wikipedia.org/wiki/Prime_Meridian">prime meridan</a>. ‘g’
stands for “<a href="http://en.wikipedia.org/wiki/Greenwich_Mean_Time">GMT</a>”;
‘u’
stands for “<a href="http://en.wikipedia.org/wiki/Universal_Time">UT</a>” or
“<a href="http://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a>”
(whichever was official at the time);
‘z’ stands for the
<a href="http://aa.usno.navy.mil/graphics/TimeZoneMap2007.pdf">nautical time zone</a> Z
(a.k.a. “Zulu” which, in turn, stands for ‘Z’).
<!--<tt><rant></tt>(Don’t say “Z stands for Zulu;”
that’s <a href="http://www.urbandictionary.com/define.php?term=Bass+Ackwards">bass
ackwards</a>.)<tt></rant></tt>-->
The time can also be suffixed with
‘w’ meaning “wall clock time;” but it usually isn’t
because that’s the default.
<p>Second, the day in the <tt>ON</tt> column, in addition to “<tt>lastSun</tt>” or a particular
day of the month, can have the form, <nobr>“<tt>Sun>=</tt><i>x</i>”</nobr>
or <nobr>“<tt>Sun<=</tt><i>x</i>,”</nobr>
where <i>x</i> is a day of the month. For example, <nobr>“<tt>Sun>=8</tt>”</nobr>
means “the first Sunday on or after the eighth of the month,” in other words, the second Sunday
of the month. Furthermore, although there are no examples above, the weekday needn’t be
“<tt>Sun</tt>” in either form, but can be the usual three-character
English abbreviation for any day of the week.
<p>And the US rules give us more examples of a couple of things already mentioned:
<ul>
<li>The rules for changing to and from daylight saving time are actually <i>different sets</i>
of rules; and the two sets can change independently. Consider, for example, that the rule
for the return to standard time stayed the same from 1967 to 2006; but the rule for
the transition to daylight saving time changed several times in the same period.
There can also be periods, 1946 to 1966 for example, when no rule from this group
is in effect, and so either no transition happened in those years, or some other
rule is in effect (perhaps a state or other more local rule).
<p>
<li>The <tt>SAVE</tt> and <tt>LETTER</tt> columns contain <i>steady state</i>, not transitions.
Consider, for example, the transition from “war time” to “peace time”
that happened on August 14, 1945. The “1:00” in the <tt>SAVE</tt> column
is <i>not</i> an instruction to advance the clock an hour. It means that clocks should
<i>be</i> one hour ahead of standard time, which they already are because of the previous rule,
so there should be no change.
</ul>
<p>OK, now let’s look at a Zone record:
<p>
<table border>
<tr>
<th colspan=5>From the Source File</th>
</tr>
<tr>
<td colspan=5>
<pre>
# Zone NAME GMTOFF RULES FORMAT [UNTIL]
Zone America/Chicago -5:50:36 - LMT 1883 Nov 18 12:09:24
-6:00 US C%sT 1920
-6:00 Chicago C%sT 1936 Mar 1 2:00
-5:00 - EST 1936 Nov 15 2:00
-6:00 Chicago C%sT 1942
-6:00 US C%sT 1946
-6:00 Chicago C%sT 1967
-6:00 US C%sT
</pre>
</td>
</tr>
<tr>
<th colspan=5>Columns Renamed</th>
</tr>
<tr>
<th rowspan=2>Standard Offset<br>from <a href="http://en.wikipedia.org/wiki/Prime_Meridian">Prime Meridian</a></th>
<th rowspan=2>Daylight<br>Saving Time</th>
<th rowspan=2>Abbreviation(s)</th>
<th colspan=2>Ending at Local Time</th>
</tr>
<tr>
<th>Date</th>
<th>Time</th>
</tr>
<tr align=center>
<td>−5:50:36</td>
<td>not observed</td>
<td>LMT</td>
<td>1883-11-18</td>
<td>12:09:24</td>
</tr>
<tr align=center>
<td rowspan=2>−6:00:00</td>
<td>US rules</td>
<td rowspan=2>CST or CDT</td>
<td>1920-01-01</td>
<td>00:00:00</td>
</tr>
<tr align=center>
<td>Chicago rules</td>
<td>1936-03-01</td>
<td rowspan=2>02:00:00</td>
</tr>
<tr align=center>
<td>−5:00:00</td>
<td>not observed</td>
<td>EST</td>
<td>1936-11-15</td>
</tr>
<tr align=center>
<td rowspan=4>−6:00:00</td>
<td>Chicago rules</td>
<td>CST or CDT</td>
<td>1942-01-01</td>
<td rowspan=3>00:00:00</td>
</tr>
<tr align=center>
<td>US rules</td>
<td>CST, CWT or CPT</td>
<td>1946-01-01</td>
</tr>
<tr align=center>
<td>Chicago rules</td>
<td rowspan=2>CST or CDT</td>
<td>1967-01-01</td>
</tr>
<tr align=center>
<td>US rules</td>
<td colspan=2>—</td>
</tr>
</table>
<p>There are a couple of interesting differences between Zones and Rules.
<p>First, and somewhat trivially, whereas Rules are considered to contain one or more
records, a Zone is considered to be a single record with zero or more <i>continuation
lines</i>. Thus, the keyword, <nobr>“<tt>Zone</tt>,”</nobr> and the zone name
are not repeated. The last line is the one without anything in the <tt>[UNTIL]</tt> column.
<p>Second, and more fundamentally, each line of a Zone represents
a steady state, not a transition between states. The state exists from the date and time
in the previous line’s <tt>[UNTIL]</tt> column up to the
date and time in the current line’s <tt>[UNTIL]</tt> column. In other words,
the date and time in the <tt>[UNTIL]</tt> column is the instant that separates
this state from the next. Where that would be ambiguous because we’re
setting our clocks back, the <tt>[UNTIL]</tt> column specifies the first occurrence of
the instant. The state specified by the last line, the one without
anything in the <tt>[UNTIL]</tt> column, continues to the present.
<p>The first line typically specifies the mean solar time observed before the introduction
of standard time. Since there’s no line before that, it has no <nobr>beginning. <tt>8-) </tt></nobr>
For some places near the
<a href="http://en.wikipedia.org/wiki/International_Date_Line">International Date Line</a>,
the first <i>two</i> lines will show solar times differing by 24 hours; this corresponds to
a movement of the Date Line.
For example:
<pre>
# Zone NAME GMTOFF RULES FORMAT [UNTIL]
Zone America/Juneau 15:02:19 - LMT 1867 Oct 18
-8:57:41 - LMT ...
</pre>
When Alaska was purchased from Russia in 1867, the Date Line moved from
the Alaska/Canada border to
the Bering Strait; and the time in Alaska was then 24 hours earlier than it had been.
<nobr><tt><aside></tt>(6 October</nobr> in the Julian calendar,
which Russia was still using then for religious reasons, was followed by <i>a second instance
of the same day with a different name</i>, <nobr>18 October</nobr>
in the Gregorian calendar. Isn’t civil time
<nobr>wonderful? <tt>8-)</tt>)<tt></aside></tt></nobr>
<p>The abbreviation, “LMT,” stands for “local mean time,”
which is an invention of the <a href="http://en.wikipedia.org/wiki/Zoneinfo">tz database</a>
and was probably never actually used during the period. Furthermore, the value
is almost certainly wrong except in the archetypal place after which the zone
is named. (The tz database usually doesn’t provide a separate Zone record
for places where nothing significant happened after 1970.)
<p>The <tt>RULES</tt> column tells us whether daylight saving time is being observed:
<ul>
<li>A hyphen, a kind of null value, means that we have not set our clocks ahead of standard time.
<li>An amount of time (usually but not necessarily <nobr>“1:00”</nobr>
meaning one hour) means that we have set our clocks ahead by that amount.
<li>Some alphabetic string means that we <i>might have</i> set our clocks ahead;
and we need to check the rule the name of which is the given alphabetic string.
</ul>
An example of a specific amount of time is:
<pre>
# Zone NAME GMTOFF RULES FORMAT [UNTIL]
Zone Pacific/Honolulu ... 1933 Apr 30 2:00
-10:30 1:00 HDT 1933 May 21 2:00
...
</pre>
Hawaii tried daylight saving time for three weeks in 1933 and decided they didn’t
like <nobr>it. <tt>8-) </tt></nobr>Note that the <tt>GMTOFF</tt> column always contains
the standard time offset, so the wall clock time during this period was
<nobr>GMT − 10:30 + 1:00 = GMT − 9:30.</nobr>
<p>The <tt>FORMAT</tt> column specifies the usual abbreviation of the time zone name.
It can have one of four forms:
<ul>
<li>the string, “<tt>zzz</tt>,” which is a kind of null value (don’t ask)
<li>a single alphabetic string other than “<tt>zzz</tt>,”
in which case that’s the abbreviation
<li>a pair of strings separated by a slash <nobr>(‘<tt>/</tt>’),</nobr>
in which case the first string is the abbreviation for the standard time name
and the second string is the abbreviation for the daylight saving time name
<li>a string containing <nobr>“<tt>%s</tt>,”</nobr> in which case the
<nobr>“<tt>%s</tt>”</nobr> will be replaced by the text in the
appropriate Rule’s <nobr><tt>LETTER</tt></nobr> column
</ul>
The last two make sense only if there’s a named rule in effect.
<p>An example of a slash is:
<pre>
# Zone NAME GMTOFF RULES FORMAT [UNTIL]
Zone Europe/London ... 1996
0:00 EU GMT/BST
</pre>
The current time in the UK is called either Greenwich mean time or British summer time.
<p>One wrinkle, not fully explained in <tt>zic.8.txt</tt>, is what happens when
switching to a named rule. To what values should the <tt>SAVE</tt> and <tt>LETTER</tt>
data be initialized?
<ul>
<li>If at least one transition has happened, use the <tt>SAVE</tt> and <tt>LETTER</tt>
data from the most recent.
<p>
<li>If switching to a named rule before any transition has happened, assume standard
time (<tt>SAVE</tt> zero), and use the <tt>LETTER</tt> data from the earliest
transition with a <tt>SAVE</tt> of zero.
</ul>
<p>And two last things about the <tt>FORMAT</tt> column:
<ul>
<li>The <a href="http://en.wikipedia.org/wiki/Zoneinfo">tz database</a> gives
abbreviations for time zone names in <i>popular usage</i>, which is not
necessarily “correct” by law. For example, the last line in
<nobr><tt>Zone</tt> <tt>Pacific/Honolulu</tt></nobr> (shown below) gives
“HST” for “Hawaii standard time” even though the
<a href="http://www.law.cornell.edu/uscode/html/uscode15/usc_sec_15_00000263----000-.html">legal</a>
name for that time zone is “Hawaii-Aleutian standard time.”
This author has read that there are also some places in Australia where
popular time zone names differ from the legal ones.
<p>
<li>No attempt is made to
<a href="http://en.wikipedia.org/wiki/Internationalization_and_localization">localize</a>
the abbreviations. They are intended to be the values returned through the
<nobr><tt>"%Z"</tt></nobr> format specifier to
<a href="http://en.wikipedia.org/wiki/C_(programming_language)">C</a>’s
<a href="http://opengroup.org/onlinepubs/007908799/xsh/strftime.html"><tt>strftime</tt></a>
function in the
<a href="http://www.chemie.fu-berlin.de/chemnet/use/info/libc/libc_19.html#SEC324">“C” locale</a>.
</ul>
<p>As a final example, here’s the complete history for Hawaii:
<p>
<table border>
<tr>
<th colspan=6>Relevant Excerpts from the US Rules</th>
</tr>
<tr>
<td colspan=6>
<pre>
# Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
Rule US 1918 1919 - Oct lastSun 2:00 0 S
Rule US 1942 only - Feb 9 2:00 1:00 W # War
Rule US 1945 only - Aug 14 23:00u 1:00 P # Peace
Rule US 1945 only - Sep 30 2:00 0 S
</pre>
</td>
</tr>
<tr>
<th colspan=6>The Zone Record</th>
</tr>
<tr>
<td colspan=6 align=center><table border=0><tr><td>
<pre>
# Zone NAME GMTOFF RULES FORMAT [UNTIL]
Zone Pacific/Honolulu -10:31:26 - LMT 1900 Jan 1 12:00
-10:30 - HST 1933 Apr 30 2:00
-10:30 1:00 HDT 1933 May 21 2:00
-10:30 US H%sT 1947 Jun 8 2:00
-10:00 - HST
</pre>
</td></tr></table></td>
</tr>
<tr>
<th colspan=6>What We Infer</th>
</tr>
<tr>
<th rowspan=2>Wall-Clock<br>Offset from<br>Prime Meridian</th>
<th rowspan=2>Adjust<br>Clocks</th>
<th colspan=2>Time Zone</th>
<th colspan=2>Ending at Local Time</th>
</tr>
<tr>
<th>Abbrv.</th>
<th>Name</th>
<th>Date</th>
<th>Time</th>
</tr>
<tr align=center>
<td>−10:31:26</td>
<td>—</td>
<td>LMT</td>
<td>local mean time</td>
<td>1900-01-01</td>
<td>12:00</td>
</tr>
<tr align=center>
<td>−10:30</td>
<td>+0:01:26</td>
<td>HST</td>
<td>Hawaii standard time</td>
<td>1933-04-30</td>
<td rowspan=3>02:00</td>
</tr>
<tr align=center>
<td>−9:30</td>
<td>+1:00</td>
<td>HDT</td>
<td>Hawaii daylight time</td>
<td>1933-05-21</td>
</tr>
<tr align=center>
<td>−10:30¹</td>
<td>−1:00¹</td>
<td>HST¹</td>
<td>Hawaii standard time</td>
<td>1942-02-09</td>
</tr>
<tr align=center>
<td rowspan=2>−9:30</td>
<td>+1:00</td>
<td>HWT</td>
<td>Hawaii war time</td>
<td>1945-08-14</td>
<td>13:30²</td>
</tr>
<tr align=center>
<td>0</td>
<td>HPT</td>
<td>Hawaii peace time</td>
<td>1945-09-30</td>
<td rowspan=2>02:00</td>
</tr>
<tr align=center>
<td>−10:30</td>
<td>−1:00</td>
<td rowspan=2>HST</td>
<td rowspan=2>Hawaii standard time</td>
<td>1947-06-08</td>
</tr>
<tr align=center>
<td>−10:00³</td>
<td>+0:30³</td>
<td colspan=2>—</td>
</tr>
<tr>
<td colspan=6>
¹Switching to US rules…most recent transition (in 1919) was to standard time
</td>
</tr>
<tr>
<td colspan=6>
²23:00 <a href="http://en.wikipedia.org/wiki/Universal_Time">UT</a>
+ (−9:30) = 13:30 local
</td>
</tr>
<tr>
<td colspan=6>
³Since <a href="http://en.wikipedia.org/wiki/ISO_8601">1947–06–08T12:30Z</a>,
the civil time in Hawaii has been
<a href="http://en.wikipedia.org/wiki/Universal_Time">UT</a>/<a href="http://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a>
− 10:00 year-round.
</td>
</tr>
</table>
<p>There will be a short quiz <nobr>later. <tt>8-)</tt></nobr>
<p><hr>
All suggestions and corrections will be welcome; all flames will be amusing.
Mail to was at pobox dot com.
</body>
</html>