| .\" %%%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>. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)tzfile.5 7.11 |
| .\" |
| .TH TZFILE 5 2015-05-07 "" "Linux Programmer's Manual" |
| .SH NAME |
| tzfile \- timezone information |
| .SH DESCRIPTION |
| This page describes the structure of the timezone files used by |
| .BR tzset (3). |
| These files are typically found under one of the directories |
| .IR /usr/lib/zoneinfo |
| or |
| .IR /usr/share/zoneinfo . |
| |
| Timezone information files begin with a 44-byte header structured as follows: |
| .IP * 3 |
| The magic four-byte sequence |
| "TZif" identifying this as a |
| timezone information file. |
| .IP * |
| A single character identifying the version of the file's format: |
| either an ASCII NUL (\(aq\\0\(aq) or a \(aq2\(aq (\fB0x32\fP). |
| .IP * |
| Fifteen bytes containing zeros reserved for future use. |
| .IP * |
| Six four-byte values of type |
| .IR long , |
| 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. |
| .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. |
| .TP |
| .I tzh_timecnt |
| The number of "transition times" for which data is stored |
| in the file. |
| .TP |
| .I tzh_typecnt |
| The number of "local time types" for which data is stored |
| in the file (must not be zero). |
| .TP |
| .I tzh_charcnt |
| The number of characters of "timezone abbreviation strings" |
| stored in the file. |
| .RE |
| .PP |
| The above header is followed by |
| .I tzh_timecnt |
| four-byte values of type |
| .IR long , |
| 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 |
| .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 |
| .I ttinfo |
| structures (with |
| .I tzh_typecnt |
| entries) that appear next in the file; |
| these structures are defined as follows: |
| .in +4n |
| .sp |
| .nf |
| struct ttinfo { |
| long tt_gmtoff; |
| int tt_isdst; |
| unsigned int tt_abbrind; |
| }; |
| .in |
| .fi |
| .sp |
| Each structure is written as a four-byte value for |
| .I tt_gmtoff |
| of type |
| .IR long , |
| 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, |
| .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 timezone abbreviation characters |
| that follow the |
| .I ttinfo |
| structure(s) in the file. |
| .PP |
| Then there are |
| .I tzh_leapcnt |
| pairs of four-byte values, written in standard byte order; |
| the first value of each pair gives the 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. |
| The pairs of values are sorted in ascending order by time. |
| .PP |
| Then there are |
| .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 timezone file is used in handling POSIX-style |
| timezone environment variables. |
| .PP |
| Finally, there are |
| .I tzh_ttisgmtcnt |
| UTC/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 timezone file is used in handling POSIX-style |
| timezone environment variables. |
| .PP |
| .BR localtime (3) |
| 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 timezone files, |
| the above header and data is followed by a second header and data, |
| identical in format except that |
| eight bytes are used for each transition time or leap-second time |
| (and that the version byte in the header record is |
| \fB0x32\fP rather than \fB0x00\fP). |
| 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 |
| The second section of the timezone file consists of another 44-byte header |
| record, identical in structure to the one at the beginning of the file, |
| except that it applies to the data that follows, |
| which is also identical in structure |
| to the first section of the timezone file, with the following differences: |
| .IP * 3 |
| The transition time values, after the header, are eight-byte values. |
| .IP * |
| In each leap second record, the leap second value is an eight-byte value. |
| The accumulated leap second count is still a four-byte value. |
| .PP |
| In all cases, the eight-byte time values are given in |
| the "standard" byte order, |
| the high-order byte first. |
| .SS POSIX timezone string |
| The second eight-byte time value section is followed by an optional |
| third section: |
| a single ASCII newline character (\(aq\\n\(aq), |
| then a text string followed by a second |
| newline character. |
| The text string is a POSIX timezone string, whose format is described in the |
| .BR tzset (3) |
| manual page. |
| .PP |
| The POSIX timezone string defines a rule for computing transition times |
| that follow the last transition time explicitly specified in the timezone |
| information file. |
| .SS Summary of the timezone information file format |
| \& |
| .RS |
| .nf |
| Four-byte value section |
| (header version \fB0x00\fP or \fB0x32\fP) |
| Header record |
| Four-byte transition times |
| Transition time index |
| \fBttinfo\fP structures |
| Timezone abbreviation array |
| Leap second records |
| Standard/Wall array |
| UTC/Local array |
| |
| Eight-byte value section |
| (only if first header version is \fB0x32\fP, |
| the second header's version is also \fB0x32\fP) |
| Header record |
| Eight-byte transition times |
| Transition time index |
| \fBttinfo\fP structures |
| Timezone abbreviation array |
| Leap second records |
| Standard/Wall array |
| UTC/Local array |
| |
| Third section |
| (optional, only in \fB0x32\fP version files) |
| Newline character |
| Timezone string |
| Newline character |
| .fi |
| .RE |
| .\" |
| .SH SEE ALSO |
| .BR ctime (3), |
| .BR tzset (3), |
| .BR tzselect (8), |
| |
| .I timezone/tzfile.h |
| in the glibc source tree |