Home | History | Annotate | Line # | Download | only in time
tzfile.5 revision 1.16.2.3 
 $NetBSD: tzfile.5,v 1.16.2.3 2014/05/22 11:36:54 yamt Exp $

 This file is in the public domain, so clarified as of
 1996-06-05 by Arthur David Olson (arthur_david_olson (at] nih.gov).
.Dd September 20, 2013
.Dt TZFILE 5
.Os
.Sh NAME
.Nm tzfile
.Nd time zone information
.Sh SYNOPSIS
n tzfile.h .Sh DESCRIPTION
The time zone information files used by
.Xr tzset 3
begin with the magic characters
.Dq TZif
to identify them as time zone information files,
followed by a character identifying the version of the file's format
(as of 2013, either an ASCII NUL or a '2', or '3')
followed by fifteen bytes containing zeroes reserved for future use,
followed by six four-byte values of type
.Fa long ,
followed by six four-byte integer values written in a
.Dq standard
byte order (the high-order byte of the value is written first).
These values are, in order:
l -tag -width XXXXXX -compact t Va tzh_ttisgmtcnt The number of UT/local indicators stored in the file.
t Va tzh_ttisstdcnt The number of standard/wall indicators stored in the file.
t Va tzh_leapcnt The number of leap seconds for which data is stored in the file.
t Va tzh_timecnt The number of
.Dq transition times
for which data is stored in the file.
t Va tzh_typecnt The number of
.Dq local time types
for which data is stored in the file (must not be zero).
t Va tzh_charcnt The number of characters of "time zone abbreviation strings"
stored in the file.
.El

p
The above header is followed by
.Va tzh_timecnt
four-byte signed integer values sorted in ascending order.
These values are written in
These values are written in
.Dq standard
byte order.
Each is used as a transition time (as returned by
.Xr time 3 )
at which the rules for computing local time change.
Next come
.Va tzh_timecnt
one-byte unsigned integer values;
each one tells which of the different types of
.Dq local time
types described in the file is associated with the same-indexed
transition time.
These values serve as indices into an array of
.Fa ttinfo
structures (with
.Va tzh_typecnt
entries) that appears next in the file;
these structures are defined as follows:
d -literal struct ttinfo {
 int32_t tt_gmtoff;
 unsigned char tt_isdst;
 unsigned char tt_abbrind;
};
.Ed
Each structure is written as a four-byte signed integer value for
.Va tt_gmtoff
in a standard byte order, followed by a one-byte value for
.Va tt_isdst
and a one-byte value for
.Va tt_abbrind .
In each structure,
.Va tt_gmtoff
gives the number of seconds to be added to UT,
.Va tt_isdst
tells whether
.Va tm_isdst
should be set by
.Xr localtime 3
and
.Va tt_abbrind
serves as an index into the array of time zone abbreviation characters
that follow the
.Va ttinfo
structure(s) in the file.

p
Then there are
.Va tzh_leapcnt
pairs of four-byte values, written in standard byte order;
the first value of each pair gives the time
(as returned by
.Xr time 3 )
at which a leap second occurs;
the second gives the
.Em total
number of leap seconds to be applied after the given time.
The pairs of values are sorted in ascending order by time.

p
Then there are
.Va tzh_ttisstdcnt
standard/wall indicators, each stored as a one-byte value;
they tell whether the transition times associated with local time types
were specified as standard time or wall clock time,
and are used when a time zone file is used in handling POSIX-style
time zone environment variables.

p
Finally there are
.Va tzh_ttisgmtcnt
UT/local indicators, each stored as a one-byte value;
they tell whether the transition times associated with local time types
were specified as UT or local time,
and are used when a time zone file is used in handling POSIX-style
time zone environment variables.

p
.Xr localtime 3
uses the first standard-time
.Fa ttinfo
structure in the file
(or simply the first
.Fa ttinfo
structure in the absence of a standard-time structure)
if either
.Va tzh_timecnt
is zero or the time argument is less than the first transition time recorded
in the file.

p
For version-2-format time zone files,
the above header and data are followed by a second header and data,
identical in format except that
eight bytes are used for each transition time or leap second time.
After the second header and data comes a newline-enclosed,
POSIX-TZ-environment-variable-style string for use in handling instants
after the last transition time stored in the file
(with nothing between the newlines if there is no POSIX representation for
such instants).

p
For version-3-format time zone files, the POSIX-TZ-style string may
use two minor extensions to the POSIX TZ format, as described in
.Xr tzset 3 .
First, the hours part of its transition times may be signed and range from
-167 through 167 instead of the POSIX-required unsigned values
from 0 through 24.
Second, DST is in effect all year if it starts
January 1 at 00:00 and ends December 31 at 24:00 plus the difference
between daylight saving and standard time.

p
Future changes to the format may append more data.
.Sh SEE ALSO
.Xr ctime 3 ,
.Xr localtime 3 ,
.Xr time 3 ,
.Xr tzset 3 ,
.Xr zdump 8
.Xr zic 8
 @(#)tzfile.5 8.3
 This file is in the public domain, so clarified as of
 1996-06-05 by Arthur David Olson.