170 lines
5.1 KiB
Groff
170 lines
5.1 KiB
Groff
.\" $NetBSD: tzfile.5,v 1.20 2013/09/20 19:06:54 christos Exp $
|
|
.\"
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov).
|
|
.Dd September 20, 2013
|
|
.Dt TZFILE 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tzfile
|
|
.Nd time zone information
|
|
.Sh SYNOPSIS
|
|
.In 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:
|
|
.Bl -tag -width XXXXXX -compact
|
|
.It Va tzh_ttisgmtcnt
|
|
The number of UT/local indicators stored in the file.
|
|
.It Va tzh_ttisstdcnt
|
|
The number of standard/wall indicators stored in the file.
|
|
.It Va tzh_leapcnt
|
|
The number of leap seconds for which data is stored in the file.
|
|
.It Va tzh_timecnt
|
|
The number of
|
|
.Dq transition times
|
|
for which data is stored in the file.
|
|
.It Va tzh_typecnt
|
|
The number of
|
|
.Dq local time types
|
|
for which data is stored in the file (must not be zero).
|
|
.It Va tzh_charcnt
|
|
The number of characters of "time zone abbreviation strings"
|
|
stored in the file.
|
|
.El
|
|
.Pp
|
|
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:
|
|
.Bd -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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
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).
|
|
.Pp
|
|
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
|
|
\(mi167 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.
|
|
.Pp
|
|
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.
|