-.\" @(#)tzfile.5 7.11
+.\" %%%LICENSE_START(PUBLIC_DOMAIN)
.\" This file is in the public domain, so clarified as of
.\" 1996-06-05 by Arthur David Olson <arthur_david_olson@nih.gov>.
-.TH TZFILE 5 1996-06-05 "" "Linux Programmer's Manual"
+.\" %%%LICENSE_END
+.\"
+.TH TZFILE 5 2017-08-04 "" "Linux Programmer's Manual"
.SH NAME
-tzfile \- time zone information
-.SH SYNOPSIS
-.B #include <tzfile.h>
+tzfile \- timezone information
.SH DESCRIPTION
-The time zone information files used by
+.ie '\(lq'' .ds lq \&"\"
+.el .ds lq \(lq\"
+.ie '\(rq'' .ds rq \&"\"
+.el .ds rq \(rq\"
+.de q
+\\$3\*(lq\\$1\*(rq\\$2
+..
+The timezone information files used by
.BR tzset (3)
-begin with the magic characters "TZif" to identify then as
-time zone information files,
-followed by sixteen bytes reserved for future use,
-followed by six four-byte values of type
-.IR long ,
-written in a "standard" byte order
+are typically found under a directory with a name like
+.IR /usr/share/zoneinfo .
+These files begin with a 44-byte header containing the following fields:
+.IP * 2
+The magic four-byte ASCII sequence
+.q "TZif"
+identifies the file as a timezone information file.
+.IP *
+A byte identifying the version of the file's format
+(as of 2017, either an ASCII NUL, or
+.q "2",
+or
+.q "3" ).
+.IP *
+Fifteen bytes containing zeros reserved for future use.
+.IP *
+Six four-byte integer values
+written in a standard byte order
(the high-order byte of the value is written first).
These values are,
in order:
+.RS
.TP
.I tzh_ttisgmtcnt
-The number of UTC/local indicators stored in the file.
+The number of UT/local indicators stored in the file.
.TP
.I tzh_ttisstdcnt
The number of standard/wall indicators stored in the file.
.TP
.I tzh_leapcnt
-The number of leap seconds for which data is stored in the file.
+The number of leap seconds for which data entries are stored in the file.
.TP
.I tzh_timecnt
-The number of "transition times" for which data is stored
+The number of transition times for which data entries are stored
in the file.
.TP
.I tzh_typecnt
-The number of "local time types" for which data is stored
+The number of local time types for which data entries are stored
in the file (must not be zero).
.TP
.I tzh_charcnt
-The number of characters of "time zone abbreviation strings"
+The number of bytes of time zone abbreviation strings
stored in the file.
+.RE
.PP
-The above header is followed by
+The above header is followed by the following fields, whose lengths
+depend on the contents of the header:
+.IP * 2
.I tzh_timecnt
-four-byte values of type
-.IR long ,
-sorted in ascending order.
-These values are written in "standard" byte order.
+four-byte signed integer values sorted in ascending order.
+These values are written in standard byte order.
Each is used as a transition time (as returned by
.BR time (2))
at which the rules for computing local time change.
-Next come
+.IP *
.I tzh_timecnt
-one-byte values of type
-.IR "unsigned char" ;
-each one tells which of the different types of "local time" types
-described in the file is associated with the same-indexed transition time.
-These values serve as indices into an array of
+one-byte unsigned integer values;
+each one but the last tells which of the different types of local time types
+described in the file is associated with the time period
+starting with the same-indexed transition time
+and continuing up to but not including the next transition time.
+(The last time type is present only for consistency checking with the
+POSIX-style TZ string described below.)
+These values serve as indices into the next field.
+.IP *
+.I tzh_typecnt
.I ttinfo
-structures that appears next in the file;
-these structures are defined as follows:
-.in +4n
+entries, each defined as follows:
+.in +.5i
.sp
.nf
+.ta .5i +\w'unsigned char\0\0'u
struct ttinfo {
- long tt_gmtoff;
- int tt_isdst;
- unsigned int tt_abbrind;
+ int32_t tt_gmtoff;
+ unsigned char tt_isdst;
+ unsigned char tt_abbrind;
};
-.in
+.in -.5i
.fi
.sp
-Each structure is written as a four-byte value for
-.I tt_gmtoff
-of type
-.IR long ,
+Each structure is written as a four-byte signed integer value for
+.IR tt_gmtoff ,
in a standard byte order, followed by a one-byte value for
.I tt_isdst
and a one-byte value for
.IR tt_abbrind .
In each structure,
.I tt_gmtoff
-gives the number of seconds to be added to UTC,
+gives the number of seconds to be added to UT,
.I tt_isdst
tells whether
.I tm_isdst
should be set by
-.BR localtime (3),
+.BR localtime (3)
and
.I tt_abbrind
-serves as an index into the array of time zone abbreviation characters
+serves as an index into the array of time zone abbreviation bytes
that follow the
.I ttinfo
structure(s) in the file.
-.PP
-Then there are
+.IP *
.I tzh_leapcnt
pairs of four-byte values, written in standard byte order;
-the first value of each pair gives the time
+the first value of each pair gives the nonnegative time
(as returned by
.BR time (2))
at which a leap second occurs;
the second gives the
.I total
-number of leap seconds to be applied after the given time.
+number of leap seconds to be applied during the time period
+starting at the given time.
The pairs of values are sorted in ascending order by time.
-.PP
-Then there are
+Each transition is for one leap second, either positive or negative;
+transitions always separated by at least 28 days minus 1 second.
+.IP *
.I 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
+and are used when a timezone file is used in handling POSIX-style
+timezone environment variables.
+.IP *
.I tzh_ttisgmtcnt
-UTC/local indicators, each stored as a one-byte value;
+UT/local indicators, each stored as a one-byte value;
they tell whether the transition times associated with local time types
-were specified as UTC or local time,
-and are used when a time zone file is used in handling POSIX-style
-time zone environment variables.
+were specified as UT or local time,
+and are used when a timezone file is used in handling POSIX-style
+timezone environment variables.
.PP
-.I Localtime
+The
+.BR localtime (3)
+function
uses the first standard-time
.I ttinfo
structure in the file
.I tzh_timecnt
is zero or the time argument is less than the first transition time recorded
in the file.
+.SS Version 2 format
+For version-2-format timezone 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.
+(Leap second counts remain four bytes.)
+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
+or for all instants if the file has no transitions.
+The POSIX-style TZ string is empty (i.e., nothing between the newlines)
+if there is no POSIX representation for such instants.
+If nonempty, the POSIX-style TZ string must agree with the local time
+type after the last transition time if present in the eight-byte data;
+for example, given the string
+.q "WET0WEST,M3.5.0,M10.5.0/3"
+then if a last transition time is in July, the transition's local time
+type must specify a daylight-saving time abbreviated
+.q "WEST"
+that is one hour east of UT.
+Also, if there is at least one transition, time type 0 is associated
+with the time period from the indefinite past up to but not including
+the earliest transition time.
+.SS Version 3 format
+For version-3-format timezone files, the POSIX-TZ-style string may
+use two minor extensions to the POSIX TZ format, as described in
+.BR newtzset (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.
+.PP
+Future changes to the format may append more data.
+.SH SEE ALSO
+.BR time (2),
+.BR localtime (3),
+.BR tzset (3),
+.BR tzselect (8),
+.BR zdump (8),
+.BR zic (8)
+.\" This file is in the public domain, so clarified as of
+.\" 1996-06-05 by Arthur David Olson.
projects / thirdparty / man-pages.git / blobdiff