From c00fb506f74f705933c5796adde73efa90bfc872 Mon Sep 17 00:00:00 2001 From: Bill Seymour Date: Sun, 28 Feb 2016 17:12:59 -0800 Subject: [PATCH 1/3] New file tz-how-to.html Contributed by Bill Seymour; see: http://mm.icann.org/pipermail/tz/2015-October/022789.html * tz-how-to.html: New file. --- tz-how-to.html | 628 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 628 insertions(+) create mode 100644 tz-how-to.html diff --git a/tz-how-to.html b/tz-how-to.html new file mode 100644 index 0000000..544ef7b --- /dev/null +++ b/tz-how-to.html @@ -0,0 +1,628 @@ + +How to Read the tz Database + +

How to Read the tz Database Source Files

+

by Bill Seymour

+

This paper is in the public domain.

+ +This paper 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 database from +ftp://elsie.nci.nih.gov/pub/ +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. + +

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        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
+
+
Reformatted a Bit
FromToOnAtAction
1920 onlyJune 13th02:00 localgo to daylight saving time
19201921last Sundayin Octoberreturn to standard time
1921 onlyin Marchgo to daylight saving time
19221966in April
1954in Septemberreturn to standard time
19551966in October
+ +

We’ll basically just ignore the TYPE column. +In the 2007j release, the most recent as of this writing, the +TYPE column never contains anything but a hyphen, +a kind of null value. (From the description in zic.8.txt, +this appears to be a mechanism for removing years from a set +in some localizable way. It’s used in the file, pacificnew, +to determine whether a given year will have a US presidential election; +but everything related to that use is commented out.) + +

The SAVE 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. + +

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        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
+
+
Reformatted a Bit
FromToOnAtAction
19181919last Sundayin March02:00 localgo to daylight saving time
in Octoberreturn to standard time
1942 onlyFebruary 9thgo to “war time”
1945 onlyAugust 14th23:00 UT + rename “war time” to “peace
time;” clocks don’t change +
September 30th02:00 localreturn to standard time
19672006last Sundayin October
1973in Aprilgo to daylight saving time
1974 onlyJanuary 6th
1975 onlyFebruary 23rd
19761986last Sundayin April
19872006first Sunday
2007presentsecond Sunday in March
first Sunday in Novemberreturn 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 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 meridan. ‘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 “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                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
+
+
Columns Renamed
Standard Offset
from Prime Meridian		Daylight
Saving Time		Abbreviation(s)Ending at Local Time
DateTime
−5:50:36not observedLMT1883-11-1812:09:24
−6:00:00US rulesCST or CDT1920-01-0100:00:00
Chicago rules1936-03-0102:00:00
−5:00:00not observedEST1936-11-15
−6:00:00Chicago rulesCST or CDT1942-01-0100:00:00
US rulesCST, CWT or CPT1946-01-01
Chicago rulesCST or CDT1967-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                GMTOFF        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                GMTOFF        RULES        FORMAT        [UNTIL]
+Zone Pacific/Honolulu        ...                        1933 Apr 30 2:00
+                        -10:30        1:00        HDT        1933 May 21 2:00
+                        ...
+
+Hawaii tried daylight saving time for three weeks in 1933 and decided they didn’t +like it. 8-) Note that the GMTOFF column always contains +the standard time offset, so the 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 can 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                GMTOFF        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 two 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        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
+
+
The Zone Record
+
+
+# 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
+
+
What We Infer
Wall-Clock
Offset from
Prime Meridian		Adjust
Clocks		Time ZoneEnding at Local Time
Abbrv.NameDateTime
−10:31:26—LMTlocal mean time1900-01-0112:00
−10:30+0:01:26HSTHawaii standard time1933-04-3002:00
−9:30+1:00HDTHawaii daylight time1933-05-21
−10:30¹−1:00¹HST¹Hawaii standard time1942-02-09
−9:30+1:00HWTHawaii war time1945-08-1413:30²
0HPTHawaii peace time1945-09-3002:00
−10:30−1:00HSTHawaii standard time1947-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-) + +

+All suggestions and corrections will be welcome; all flames will be amusing. +Mail to was at pobox dot com. + + -- 2.5.0