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.
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).
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":
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
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.
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 synonym for US/AZ
suggests that the GCOS8 system is in the Arizona locale.
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.
The time zone definition file distributed with the package is found in
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.
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
which is a processed version of
You can also use the TZDATA command to decode a processed file.
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.
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:
The following library functions do work related to time zones.
returns the "_T_locale" reference number for the "US/EST" locale.
returns a "_T_time_zone" structure for EST.
For further information on all these functions, see the relevant explain files.
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 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
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.
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
Copyright © 1996, Thinkage Ltd.