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):

#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

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:

• 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).
• On the other hand, the SAVE and LETTER columns contain state that exists between transitions. More about this when we talk about the US rules.

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

#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

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:

• The rules for changing to and from daylight saving time are actually different sets 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).
• The SAVE and LETTER columns contain steady state, not transitions. Consider, for example, the transition from “war time” to “peace time” that happened on August 14, 1945. The “1:00” in the SAVE column is not an instruction to advance the clock an hour. It means that clocks should be one hour ahead of standard time, which they already are because of the previous rule, so there should be no change.

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

#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

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:

• A hyphen, a kind of null value, means that we have not set our clocks ahead of standard time.
• An amount of time (usually but not necessarily “1:00” meaning one hour) means that we have set our clocks ahead by that amount.
• Some alphabetic string means that we might have set our clocks ahead; and we need to check the rule the name of which is the given alphabetic string.

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:

• a time zone abbreviation that is a string of three or more characters that are either ASCII alphanumerics, “+”, or “-”
• the string “%z”, in which case the “%z” will be replaced by a numeric time zone abbreviation
• a pair of time zone abbreviations separated by a slash (‘/’), 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
• a string containing “%s”, in which case the “%s” will be replaced by the text in the appropriate Rule’s LETTER column, and the resulting string should be a time zone abbreviation

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?

• If at least one transition has happened, use the SAVE and LETTER data from the most recent.
• If switching to a named rule before any transition has happened, assume standard time (SAVE zero), and use the LETTER data from the earliest transition with a SAVE of zero.

And three last things about the FORMAT column:

• The tz database gives abbreviations for time zones in popular usage, which is not necessarily “correct” by law. For example, the last line in Zone Pacific/Honolulu (shown below) gives “HST” for “Hawaii standard time” even though the legal 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.
• No attempt is made to localize the abbreviations. They are intended to be the values returned through the "%Z" format specifier to C’s strftime function in the “C” locale.
• If there is no generally-accepted abbreviation for a time zone, a numeric offset is used instead, e.g., +07 for 7 hours ahead of Greenwich. By convention, -00 is used in a zone while uninhabited, where the offset is zero but in some sense the true offset is undefined.

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

#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

#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

There will be a short quiz later. 8-)