TZ - library facilities for time zones.

The greatest difficulty in handling time zones is the way they differ from place to place. For example, some places go on daylight saving time while others do not; furthermore, the rules for when a particular place goes on daylight savings time have changed many times in the past and may change again in future.

To cope with such complications, the B library has sophisticated facilities that let sites define the ways that dates and times are handled locally. These facilities also make it possible to add library support for any time zone. At present, however, the standard distribution of B only includes complete definitions for selected North American zones.

Time Zone Locales:

A time zone locale ("locale" for short) is a named set of time zones associated with a geographical location. Usually, there are two time zones in the set: a "standard" time zone and a corresponding "daylight savings" time zone. However, the B library allows for up to four time zones in the set; this allows for places which may go on "double daylight" savings time.

The definition of a locale also gives a set of instructions for switching between the associated time zones. For example, it tells when to switch from standard time to daylight, and when to switch back again. The instructions allow for different criteria in different years (since the switchover times may vary from year to year).

Time Zone Definition Files:

GCOS8's system clock runs on Greenwich Mean Time (GMT); however, an unprivileged user cannot obtain the time setting from this clock. Instead, users obtain the current date/time from a clock which runs on local time...sort of. This clock does not automatically reflect changes from Standard Time to Daylight Savings and vice versa; the clock doesn't get adjusted until the next time the system is booted, when the operators manually enter the new time settings.

The result is that the B library can't get accurate time zone information from GCOS8 itself -- GCOS8 doesn't make this information available. Therefore the library uses "Time Zone Definition Files" which describe the time zone rules in various places. For example, here are a few lines extracted from the default time zone definition file:

US/EST   EST                # U.S. Eastern Standard
             1967 EDT apr/24 sun@2 oct/25 sun@1
             1974 EDT jan/1  sun@2 oct/25 sun@1
             1975 EDT feb/23 sun@2 oct/25 sun@1
             1976 EDT apr/24 sun@2 oct/25 sun@1
             1987 EDT apr/1  sun@2 oct/25 sun@1
US/CST       same as US/EST with  CST CDT
US/MST       same as US/EST with  MST MDT
US/PST       same as US/EST with  PST PDT

The first line starts the definition of a "time zone locale":

In a heading line like this, the name of the locale must start in the first column of the line. Each locale name must be unique. All other lines in the definition of this locale must have their first column blank or a tab.

After the heading line come a series of exceptions to the first line. These exceptions specify ranges of time when the locale deviates from the standard time. In this case, the definitions tell when US/EST went to EDT (Eastern Daylight Time):

1967 EDT apr/24 sun@2 oct/25 sun@1

says that starting in 1967, the locale went to EDT beginning at 2:00 a.m. on the Sunday following April 24 (or on April 24 in years when that was a Sunday). The locale stayed on EDT until 1:00 a.m. on the Sunday following October 25 (or on October 25 in years when that was a Sunday). It's important to recognize that the changeover time is given relative to the STANDARD time. Thus you may think of the clocks being set back at 2:00 a.m. (daylight savings time), but the definition file records this as 1:00 a.m. (standard time). Similarly, the next line

1974 EDT jan/1  sun@2 oct/25 sun@1

says that starting in 1974, US/EST went to EDT beginning at 2:00 a.m. on the Sunday following January 1 (or on January 1 if that was a Sunday). Again, the locale stayed on EDT until 1:00 a.m. (EST) on the Sunday following October 25 (or on October 25 if that was a Sunday).

Each line applies to the year stated in the beginning of the line and to all subsequent years until the next line in the definition. For example, the rule for 1976 applies until 1987.

It is possible that some locales will not have any exceptions listed after the heading line. For example, if a locale never goes on daylight savings time, it usually doesn't need any exceptions.

After the definition for the US/EST locale come definitions for US/CST, US/MST, and US/PST (Central, Mountain, and Pacific time). The keywords "same as" indicate that the rules parallel those for US/EST. However, the notation

with CST CDT

on the end of the line says that the standard time in the US/CST locale is CST and the daylight time is CDT.

As another example, here's an extract from the definition of US/AZ (Arizona time):

US/AZ    MST                # Arizona -- no DST
             1944 MST jan/1  day@0 dec/31 day@24

This says that US/AZ follows MST. Beginning in 1944, the locale stayed at MST from January 1 to December 31. The notation "day@0" stands for midnight beginning the exact day (as opposed to "sun@0" which would stand for the closest Sunday following). Similarly, "day@24" stands for the midnight ending the exact day.

The only recognized changeover times are:

sun@1   sun@2   sun@3   sun@4
day@0   day@1   day@2   day@3   day@24

These are the only changeover times known to be necessary, and by restricting the possibilities, the time zone tables can be encoded more compactly.

You may define locale names which are synonyms for other locales, as in

US/NY    synonym for US/EST

This defines a locale named US/NY (for New York) which is the same as US/EST. Note that there is a difference between the "same as" notation and a "synonym":

Time Zone Definitions:

The locale definitions in the time zone definition file tell when a locale switches from one time zone to another (for example, from EST to EDT). After the locale definitions, the time zone definition file contains definitions for the time zones themselves. The notation "time zones" in the first column of a line marks the beginning of the list of time zone definitions.

Time zone definitions are given relative to Greenwich Mean Time. For example, this part of the file might contain

EST     5:00     # Eastern Standard
EDT     4:00 DST # Eastern Daylight

The first definition says EST is 5:00 hours behind GMT. The second definition says EDT is 4:00 hours behind GMT; the notation "DST" after the "4:00" notes that this is a Daylight Savings Time, as opposed to a standard time. The .TZISDST library function (discussed later) checks whether or not a zone has the DST marker to determine whether that zone is a daylight savings time zone.

Negative numbers may be used for time zones that are ahead of GMT, as in

MSK    -3:00     # Moscow Winter Time

It is possible to define different time zones with the same name; for example, the U.S. traditionally uses EST as the short form for Eastern Standard Time while Easter Island uses the same short form for its own time zone. In this case, the time zone definition file can distinguish between the two with the format

name@offset

where "name" is the name of the time zone and "offset" is its offset from GMT in the form "hh" or "hh:mm". For example, you might use the notation

US/EST  EST@5:00    # U.S. Eastern Standard

to indicate which EST is appropriate to the US/EST locale.

Default and System Time Zones:

In addition to definitions for standard time zones, a time zone definition file must define a locale named "default" and may also define a locale named "system".

default
stands for the locale where the GCOS8 system is located. For example,
default   synonym for US/AZ

suggests that the GCOS8 system is in the Arizona locale.

system
is used to determine GMT, relative to the system clock. Normally, "system" and "default" will be the same. However, differences arise if the time given by the system clock is not the same as time in the outside world.

This happens most often when the time switches from standard to daylight savings or vice versa. The system clock doesn't get changed until the next time the system is booted. Thus, for a time, the system clock is running in a different time zone than the "default". For example, suppose you change from EST to EDT; until the system is booted, the "default" time zone should be EDT, but the "system" time zone is still EST. In this situation, you would change the time definition file so that "system" was associated with EST and "default" was EDT. When you boot the system and set the system clock to EDT, you would change the time definition file so that both "system" and "default" were EDT.

There is one hour a year when the B library may not give correct times. When you switch from Daylight Savings Time to Standard Time, the clock goes back and you run through the same hour again. During this time, the library won't be able to tell whether it's in standard or daylight time. For example, it may report that it's still on EDT when it's really on EST.

Default Time Definition File:

The time zone definition file distributed with the package is found in

uw_tools/8fw1.5/aux/tzdata.def

This file contains definitions for locales in the U.S. and Canada. However, we should note that these definitions are generalized and may not apply to specific sites. For example, until 1986 individual municipalities in Ontario, Canada could decide whether or not to go on Daylight Savings Time. If you wanted to create a precise time zone definition for a particular municipality, you'd have to find out which years that municipality actually voted to go on Daylight Time and which years it decided to stay on Standard.

The TZDATA Command:

After you have produced a time zone definition file, you must "compile" it with the TZDATA command. TZDATA simply converts the text descriptions into a format that is suitable for direct use by programs.

The format of the TZDATA command is

TZDATA deffile TZData=outfile

where "deffile" is a time zone definition file (in text) and "outfile" is the processed version of the file. The standard distribution of UW Tools contains

uw_tools/8fw1.5/aux/tzdata

which is a processed version of

uw_tools/8fw1.5/aux/tzdata.def

You can also use the TZDATA command to decode a processed file.

TZDATA procfile

writes a text version of "procfile" to the standard output. If you omit the file name, TZDATA writes a text version of the default time zone definition file.

Program Support:

Once you have created a processed time zone definition file, you can use that information in programs through library functions. These functions use a number of standard data types. We'll refer to these data types using standard C names:

_T_time_zone
is a value representing a time zone (e.g. EST or EDT). We call this a time zone reference value.
_T_locale
is a value representing a locale (e.g. "US/EST").

The following library functions do work related to time zones.

.TINIT
reads a processed time zone definition file and stores the result in memory as a "_T_tzfile" data structure. .TINIT automatically creates the "system" and "default" locales, plus any other locales defined in the file. The "_T_tzfile" structure created by .TINIT replaces the default time zone definitions of the B library.
.TLOCALE
gives you the "_T_locale" value associated with the name of a time zone locale. For example,
 .tlocale("US/EST")

returns the "_T_locale" reference number for the "US/EST" locale.

.TLNAME
is the inverse of .TLOCALE. It takes a "_T_locale" reference number and returns a string giving the associated name of the time zone locale. As a special case, if you specify a "_T_locale" of zero, .TLNAME returns the name of the current time zone locale.
.TSWITCH
switches to a new time zone locale. Various B library functions will then calculate dates and times using the "US/EST" rules as specified in the time zone definition file.
.TZUSE
given a locale and a time, tells the time zone that was in effect at that time. For example, given "US/EST" and a time, .TZUSE tells whether the locale was using EST or EDT at that time.
.TZOFF
gives the offset (in minutes) of a particular time zone from GMT.
.TZISDST
tells whether or not a time zone is a daylight savings time zone.
.TZSTD
returns a "_T_time_zone" structure representing the standard time zone for a given locale.
.TZQRY
returns a "_T_time_zone" structure corresponding to a given time zone name. For example,
 .tzqry("EST");

returns a "_T_time_zone" structure for EST.

.TZDOFF
returns the offset between daylight and standard time in a given locale at a given time.
.TZNAME
returns the name associated with a given "_T_time_zone" structure (e.g. "EST").

For further information on all these functions, see the relevant explain files.

The Error Time Zone:

The library has a built-in definition of an "erroneous" time zone, which is used in various situations. For example, if you pass .TZQRY a string which is not the name of a recognized time zone, .TZQRY returns a time zone reference value for the Error Time Zone.

The Error Time Zone has the following qualities:

If the Error Time Zone is in effect, the date/time functions that can return statuses will return error statuses. However, most of the date/time functions still work as normal, except that work with times relative to the Error Time Zone (effectively GMT).

The .NO_TZ Variable:

The various date/time functions normally call .TINIT to load a time zone definition file the first time any such function is called during program execution. The time zone definitions are stored in memory for the rest of the program; therefore, programs that are extremely tight for memory space may wish to create a minimal time zone definition containing as few definitions as possible.

If you link your program with

Use=.NO_TZ

on the command line, the library won't load time zone definitions. This means that all date/time functions operate in the context of the Error Time Zone.

Notes:

The internal structure of a processed time zone definition is subject to change, from one release of UW Tools to the next. While we will attempt to make these changes transparent to the user, we cannot guarantee it -- providing support for international date and time formats may force us to make visible changes in the interface.

We are interested in additional time zone information from various locales around the globe. You can send us such information via electronic mail at the address

pjf@thinkage.ca

See Also:

expl b time
for functions that perform date and time calculations.
expl tzdata
for information on the TZDATA command for processing time zone definition files.

Copyright © 1996, Thinkage Ltd.