diff options
Diffstat (limited to 'tzfile.5')
-rw-r--r-- | tzfile.5 | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/tzfile.5 b/tzfile.5 new file mode 100644 index 000000000000..530397f72e67 --- /dev/null +++ b/tzfile.5 @@ -0,0 +1,190 @@ +.TH TZFILE 5 +.SH NAME +tzfile \- time zone information +.SH DESCRIPTION +.ie '\(lq'' .ds lq \&"\" +.el .ds lq \(lq\" +.ie '\(rq'' .ds rq \&"\" +.el .ds rq \(rq\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +The time zone information files used by +.BR tzset (3) +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 time zone 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 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 entries are stored in the file. +.TP +.I tzh_timecnt +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 entries are stored +in the file (must not be zero). +.TP +.I tzh_charcnt +The number of bytes of time zone abbreviation strings +stored in the file. +.RE +.PP +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 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. +.IP * +.I tzh_timecnt +one-byte unsigned integer values; +each one 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. +These values serve as indices into the next field. +.IP * +.I tzh_typecnt +.I ttinfo +entries, each defined as follows: +.in +.5i +.sp +.nf +.ta .5i +\w'unsigned char\0\0'u +struct ttinfo { + int32_t tt_gmtoff; + unsigned char tt_isdst; + unsigned char tt_abbrind; +}; +.in -.5i +.fi +.sp +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 UT, +.I tt_isdst +tells whether +.I tm_isdst +should be set by +.BR localtime (3) +and +.I tt_abbrind +serves as an index into the array of time zone abbreviation bytes +that follow the +.I ttinfo +structure(s) in the file. +.IP * +.I tzh_leapcnt +pairs of four-byte values, written in standard byte order; +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 during the time period +starting at the given time. +The pairs of values are sorted in ascending order by time. +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. +.IP * +.I 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 +The +.BR localtime (3) +function +uses the first standard-time +.I ttinfo +structure in the file +(or simply the first +.I ttinfo +structure in the absence of a standard-time structure) +if either +.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 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. +(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 +(with nothing between the newlines if there is no POSIX representation for +such instants). +The POSIX-style string must agree with the local time type after +both data's last transition times; 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. +.SS Version 3 format +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 +.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. |