How to Read the tz Database Source Files

by Bill Seymour

This guide uses the America/Chicago and Pacific/Honolulu zones as examples of how to infer times of day from the tz database source files. It might be helpful, but not absolutely necessary, for the reader to have already downloaded the latest release of the database and become familiar with the basic layout of the data files. The format is explained in the “man page” for the zic compiler, zic.8.txt, in the code subdirectory. Although this guide covers many of the common cases, it is not a complete summary of what zic accepts; the man page is the authoritative reference.

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.

First, let’s consider the special daylight saving time rules for Chicago (from the northamerica file in the data subdirectory):

From the Source File
#Rule NAME    FROM TO    -   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
Reformatted a Bit
From To On At Action
1920 only June 13th 02:00 local go to daylight saving time
1920 1921 last Sunday in October return to standard time
1921 only in March go to daylight saving time
1922 1966 in April
1954 in September return to standard time
1955 1966 in October

The FROM and TO columns, respectively, specify the first and last calendar years defining a contiguous range over which a specific Rule line is to apply. The keyword only can be used in the TO field to repeat the value of the FROM field in the event that a rule should only apply to a single year. Often, the keyword max is used to extend a rule’s application into the indefinite future; it is a platform-agnostic stand-in for the largest representable year.

The next column, -, is reserved; for compatibility with earlier releases, it always contains a hyphen, which acts as a kind of null value. Prior to the 2020b release, it was called the TYPE field, though it had not been used in the main data since the 2000e release. An obsolescent supplementary file used the field as a proof-of-concept to allow zic to apply a given Rule line only to certain “types” of years within the specified range as dictated by the output of a separate script, such as: only years which would have a US presidential election, or only years which wouldn’t.

The SAVE column contains the local (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.

The LETTER (sometimes called LETTER/S) 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 LETTER column in the Chicago rules. More about this when we talk about “Zone” lines.

One important thing to notice is that “Rule” lines want at once to be both transitions and steady states:

In the example above, the transition to daylight saving time happened on the 13th 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?

OK, now for the somewhat more interesting “US” rules:

From the Source File
#Rule NAME FROM TO    -   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
Reformatted a Bit
From To On At Action
1918 1919 last Sunday in March 02:00 local go to daylight saving time
in October return to standard time
1942 only February 9th go to “war time”
1945 only August 14th 23:00 UT rename “war time” to “peace
time;” clocks don’t change
September 30th 02:00 local return to standard time
1967 2006 last Sunday in October
1973 in April go to daylight saving time
1974 only January 6th
1975 only February 23rd
1976 1986 last Sunday in April
1987 2006 first Sunday
2007 present second Sunday in March
first Sunday in November return to standard time

There are two interesting things to note here.

First, the time that something happens (in the AT 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 local (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 prime meridian. ‘g’ stands for “GMT”; ‘u’ stands for “UT” or “UTC” (whichever was official at the time); ‘z’ stands for the nautical time zone Z (a.k.a. “Zulu” which, in turn, stands for ‘Z’). The time can also be suffixed with ‘w’ meaning local (wall clock) time; but it usually isn’t because that’s the default.

Second, the day in the ON column, in addition to “lastSun” or a particular day of the month, can have the form, “Sun>=x” or “Sun<=x,” where x is a day of the month. For example, “Sun>=8” 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 “Sun” in either form, but can be the usual three-character English abbreviation for any day of the week.

And the US rules give us more examples of a couple of things already mentioned:

OK, now let’s look at a Zone record:

From the Source File
#Zone       NAME      STDOFF   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
Columns Renamed
Standard Offset
from Prime Meridian
Daylight
Saving Time
Abbreviation(s) Ending at Local Time
Date Time
−5:50:36 not observed LMT 1883-11-18 12:09:24
−6:00:00 US rules CST or CDT 1920-01-01 00:00:00
Chicago rules 1936-03-01 02:00:00
−5:00:00 not observed EST 1936-11-15
−6:00:00 Chicago rules CST or CDT 1942-01-01 00:00:00
US rules CST, CWT or CPT 1946-01-01
Chicago rules CST or CDT 1967-01-01
US rules

There are a couple of interesting differences between Zones and Rules.

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 continuation lines. Thus, the keyword, “Zone,” and the zone name are not repeated. The last line is the one without anything in the [UNTIL] column.

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 [UNTIL] column up to the date and time in the current line’s [UNTIL] column. In other words, the date and time in the [UNTIL] column is the instant that separates this state from the next. Where that would be ambiguous because we’re setting our clocks back, the [UNTIL] column specifies the first occurrence of the instant. The state specified by the last line, the one without anything in the [UNTIL] column, continues to the present.

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 beginning. 8-) For some places near the International Date Line, the first two lines will show solar times differing by 24 hours; this corresponds to a movement of the Date Line. For example:

#Zone NAME          STDOFF   RULES FORMAT [UNTIL]
Zone America/Juneau 15:02:19 -     LMT    1867 Oct 18
                    -8:57:41 -     LMT    ...

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. <aside>(6 October in the Julian calendar, which Russia was still using then for religious reasons, was followed by a second instance of the same day with a different name, 18 October in the Gregorian calendar. Isn’t civil time wonderful? 8-))</aside>

The abbreviation, “LMT” stands for “local mean time”, which is an invention of the tz database 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.)

The RULES column tells us whether daylight saving time is being observed:

An example of a specific amount of time is:

#Zone NAME            STDOFF RULES FORMAT [UNTIL]
Zone Pacific/Honolulu ...                 1933 Apr 30  2:00
                      -10:30 1:00  HDT    1933 May 21 12:00
                      ...

Hawaii tried daylight saving time for three weeks in 1933 and decided they didn’t like it. 8-) Note that the STDOFF column always contains the standard time offset, so the local (wall clock) time during this period was GMT − 10:30 + 1:00 = GMT − 9:30.

The FORMAT column specifies the usual abbreviation of the time zone name. It should have one of four forms:

The last two make sense only if there’s a named rule in effect.

An example of a slash is:

#Zone NAME          STDOFF RULES FORMAT  [UNTIL]
Zone  Europe/London ...                  1996
                    0:00   EU    GMT/BST

The current time in the UK is called either Greenwich mean time or British summer time.

One wrinkle, not fully explained in zic.8.txt, is what happens when switching to a named rule. To what values should the SAVE and LETTER data be initialized?

And three last things about the FORMAT column:

As a final example, here’s the complete history for Hawaii:

Relevant Excerpts from the US Rules
#Rule NAME FROM TO   -    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 lastSun  2:00  0    S
The Zone Record
#Zone NAME            STDOFF    RULES FORMAT [UNTIL]
Zone Pacific/Honolulu -10:31:26 -     LMT    1896 Jan 13 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
What We Infer
Wall-Clock
Offset from
Prime Meridian
Adjust
Clocks
Time Zone Ending at Local Time
Abbrv. Name Date Time
−10:31:26 LMT local mean time 1896-01-13 12:00
−10:30 +0:01:26 HST Hawaii standard time 1933-04-30 02:00
−9:30 +1:00 HDT Hawaii daylight time 1933-05-21 12:00
−10:30¹ −1:00¹ HST¹ Hawaii standard time 1942-02-09 02:00
−9:30 +1:00 HWT Hawaii war time 1945-08-14 13:30²
0 HPT Hawaii peace time 1945-09-30 02:00
−10:30 −1:00 HST Hawaii standard time 1947-06-08
−10:00³ +0:30³
¹Switching to US rules…most recent transition (in 1919) was to standard time
²23:00 UT + (−9:30) = 13:30 local
³Since 1947–06–08T12:30Z, the civil time in Hawaii has been UT/UTC − 10:00 year-round.

There will be a short quiz later. 8-)


This web page is in the public domain, so clarified as of 2015-10-20 by Bill Seymour.
All suggestions and corrections will be welcome; all flames will be amusing. Mail to was at pobox dot com.