* tzfile.5: Break out field descriptions into bulleted lists, to make them easier to follow. This does not change the technical content of the spec, just its presentation. --- tzfile.5 | 77 ++++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 48 insertions(+), 29 deletions(-) diff --git a/tzfile.5 b/tzfile.5 index 52c5301..b7dc828 100644 --- a/tzfile.5 +++ b/tzfile.5 @@ -10,17 +10,29 @@ tzfile \- time zone information \\$3\*(lq\\$1\*(rq\\$2 .. The time zone information files used by -.IR tzset (3) -begin with the magic characters "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 '2', or '3') -followed by fifteen bytes containing zeroes reserved for future use, -followed by six four-byte integer values +.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. @@ -40,28 +52,30 @@ 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 +vary 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 -.IR time (2)) +.BR time (2)) at which the rules for computing local time change. -Next come +.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 an array of -.I ttinfo -structures (with +These values serve as indices into the next field. +.IP * .I tzh_typecnt -entries) that appears next in the file; -these structures are defined as follows: +.I ttinfo +entries, each defined as follows: .in +.5i .sp .nf @@ -87,20 +101,19 @@ gives the number of seconds to be added to UT, tells whether .I tm_isdst should be set by -.I 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 nonnegative time (as returned by -.IR time(2)) +.BR time (2)) at which a leap second occurs; the second gives the .I total @@ -109,16 +122,14 @@ 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. -.PP -Then there are +.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 +.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 @@ -126,7 +137,9 @@ 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 -.I Localtime +The +.BR localtime (3) +function uses the first standard-time .I ttinfo structure in the file @@ -137,11 +150,12 @@ if either .I tzh_timecnt is zero or the time argument is less than the first transition time recorded in the file. -.PP +.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 @@ -154,7 +168,7 @@ 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. -.PP +.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 .IR newtzset (3). @@ -166,6 +180,11 @@ between daylight saving and standard time. .PP Future changes to the format may append more data. .SH SEE ALSO -newctime(3), newtzset(3), zdump(8), zic(8) +.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. -- 2.7.4