]>
Commit | Line | Data |
---|---|---|
2d6c6dd1 | 1 | .\" %%%LICENSE_START(PUBLIC_DOMAIN) |
fea681da MK |
2 | .\" This file is in the public domain, so clarified as of |
3 | .\" 1996-06-05 by Arthur David Olson <arthur_david_olson@nih.gov>. | |
2d6c6dd1 | 4 | .\" %%%LICENSE_END |
2297bf0e | 5 | .\" |
72942d65 | 6 | .TH TZFILE 5 2017-08-04 "" "Linux Programmer's Manual" |
fea681da | 7 | .SH NAME |
2061865f | 8 | tzfile \- timezone information |
fea681da | 9 | .SH DESCRIPTION |
72942d65 PE |
10 | .ie '\(lq'' .ds lq \&"\" |
11 | .el .ds lq \(lq\" | |
12 | .ie '\(rq'' .ds rq \&"\" | |
13 | .el .ds rq \(rq\" | |
14 | .de q | |
15 | \\$3\*(lq\\$1\*(rq\\$2 | |
16 | .. | |
2061865f | 17 | The timezone information files used by |
72942d65 PE |
18 | .BR tzset (3) |
19 | are typically found under a directory with a name like | |
56c4cc36 | 20 | .IR /usr/share/zoneinfo . |
72942d65 PE |
21 | These files begin with a 44-byte header containing the following fields: |
22 | .IP * 2 | |
23 | The magic four-byte ASCII sequence | |
24 | .q "TZif" | |
2061865f | 25 | identifies the file as a timezone information file. |
7291261f | 26 | .IP * |
72942d65 PE |
27 | A byte identifying the version of the file's format |
28 | (as of 2017, either an ASCII NUL, or | |
29 | .q "2", | |
30 | or | |
31 | .q "3" ). | |
7291261f MK |
32 | .IP * |
33 | Fifteen bytes containing zeros reserved for future use. | |
34 | .IP * | |
72942d65 PE |
35 | Six four-byte integer values |
36 | written in a standard byte order | |
fea681da MK |
37 | (the high-order byte of the value is written first). |
38 | These values are, | |
39 | in order: | |
7291261f | 40 | .RS |
fea681da MK |
41 | .TP |
42 | .I tzh_ttisgmtcnt | |
72942d65 | 43 | The number of UT/local indicators stored in the file. |
fea681da MK |
44 | .TP |
45 | .I tzh_ttisstdcnt | |
46 | The number of standard/wall indicators stored in the file. | |
47 | .TP | |
48 | .I tzh_leapcnt | |
72942d65 | 49 | The number of leap seconds for which data entries are stored in the file. |
fea681da MK |
50 | .TP |
51 | .I tzh_timecnt | |
72942d65 | 52 | The number of transition times for which data entries are stored |
fea681da MK |
53 | in the file. |
54 | .TP | |
55 | .I tzh_typecnt | |
72942d65 | 56 | The number of local time types for which data entries are stored |
fea681da MK |
57 | in the file (must not be zero). |
58 | .TP | |
59 | .I tzh_charcnt | |
a312fa03 | 60 | The number of bytes of time zone abbreviation strings |
fea681da | 61 | stored in the file. |
7291261f | 62 | .RE |
fea681da | 63 | .PP |
72942d65 | 64 | The above header is followed by the following fields, whose lengths |
a312fa03 | 65 | depend on the contents of the header: |
72942d65 | 66 | .IP * 2 |
fea681da | 67 | .I tzh_timecnt |
72942d65 PE |
68 | four-byte signed integer values sorted in ascending order. |
69 | These values are written in standard byte order. | |
fea681da MK |
70 | Each is used as a transition time (as returned by |
71 | .BR time (2)) | |
72 | at which the rules for computing local time change. | |
72942d65 | 73 | .IP * |
fea681da | 74 | .I tzh_timecnt |
72942d65 | 75 | one-byte unsigned integer values; |
a312fa03 | 76 | each one but the last tells which of the different types of local time types |
72942d65 | 77 | described in the file is associated with the time period |
a312fa03 PE |
78 | starting with the same-indexed transition time |
79 | and continuing up to but not including the next transition time. | |
80 | (The last time type is present only for consistency checking with the | |
81 | POSIX-style TZ string described below.) | |
72942d65 PE |
82 | These values serve as indices into the next field. |
83 | .IP * | |
64fb5aed | 84 | .I tzh_typecnt |
72942d65 PE |
85 | .I ttinfo |
86 | entries, each defined as follows: | |
a312fa03 PE |
87 | .in +.5i |
88 | .sp | |
89 | .nf | |
90 | .ta .5i +\w'unsigned char\0\0'u | |
fea681da | 91 | struct ttinfo { |
a312fa03 PE |
92 | int32_t tt_gmtoff; |
93 | unsigned char tt_isdst; | |
94 | unsigned char tt_abbrind; | |
fea681da | 95 | }; |
a312fa03 PE |
96 | .in -.5i |
97 | .fi | |
98 | .sp | |
72942d65 PE |
99 | Each structure is written as a four-byte signed integer value for |
100 | .IR tt_gmtoff , | |
fea681da MK |
101 | in a standard byte order, followed by a one-byte value for |
102 | .I tt_isdst | |
103 | and a one-byte value for | |
104 | .IR tt_abbrind . | |
105 | In each structure, | |
106 | .I tt_gmtoff | |
72942d65 | 107 | gives the number of seconds to be added to UT, |
fea681da MK |
108 | .I tt_isdst |
109 | tells whether | |
110 | .I tm_isdst | |
111 | should be set by | |
72942d65 | 112 | .BR localtime (3) |
fea681da MK |
113 | and |
114 | .I tt_abbrind | |
a312fa03 | 115 | serves as an index into the array of time zone abbreviation bytes |
fea681da MK |
116 | that follow the |
117 | .I ttinfo | |
118 | structure(s) in the file. | |
72942d65 | 119 | .IP * |
fea681da MK |
120 | .I tzh_leapcnt |
121 | pairs of four-byte values, written in standard byte order; | |
72942d65 | 122 | the first value of each pair gives the nonnegative time |
fea681da MK |
123 | (as returned by |
124 | .BR time (2)) | |
125 | at which a leap second occurs; | |
126 | the second gives the | |
127 | .I total | |
72942d65 PE |
128 | number of leap seconds to be applied during the time period |
129 | starting at the given time. | |
fea681da | 130 | The pairs of values are sorted in ascending order by time. |
72942d65 PE |
131 | Each transition is for one leap second, either positive or negative; |
132 | transitions always separated by at least 28 days minus 1 second. | |
133 | .IP * | |
fea681da MK |
134 | .I tzh_ttisstdcnt |
135 | standard/wall indicators, each stored as a one-byte value; | |
136 | they tell whether the transition times associated with local time types | |
137 | were specified as standard time or wall clock time, | |
2061865f MK |
138 | and are used when a timezone file is used in handling POSIX-style |
139 | timezone environment variables. | |
72942d65 | 140 | .IP * |
fea681da | 141 | .I tzh_ttisgmtcnt |
72942d65 | 142 | UT/local indicators, each stored as a one-byte value; |
fea681da | 143 | they tell whether the transition times associated with local time types |
72942d65 | 144 | were specified as UT or local time, |
2061865f MK |
145 | and are used when a timezone file is used in handling POSIX-style |
146 | timezone environment variables. | |
fea681da | 147 | .PP |
72942d65 | 148 | The |
64fb5aed | 149 | .BR localtime (3) |
72942d65 | 150 | function |
fea681da MK |
151 | uses the first standard-time |
152 | .I ttinfo | |
153 | structure in the file | |
154 | (or simply the first | |
155 | .I ttinfo | |
156 | structure in the absence of a standard-time structure) | |
157 | if either | |
158 | .I tzh_timecnt | |
159 | is zero or the time argument is less than the first transition time recorded | |
160 | in the file. | |
f09abf6d | 161 | .SS Version 2 format |
2061865f | 162 | For version-2-format timezone files, |
72942d65 | 163 | the above header and data are followed by a second header and data, |
64fb5aed | 164 | identical in format except that |
72942d65 PE |
165 | eight bytes are used for each transition time or leap second time. |
166 | (Leap second counts remain four bytes.) | |
64fb5aed MK |
167 | After the second header and data comes a newline-enclosed, |
168 | POSIX-TZ-environment-variable-style string for use in handling instants | |
169 | after the last transition time stored in the file | |
a312fa03 PE |
170 | or for all instants if the file has no transitions. |
171 | The POSIX-style TZ string is empty (i.e., nothing between the newlines) | |
172 | if there is no POSIX representation for such instants. | |
173 | If nonempty, the POSIX-style TZ string must agree with the local time | |
174 | type after the last transition time if present in the eight-byte data; | |
175 | for example, given the string | |
72942d65 PE |
176 | .q "WET0WEST,M3.5.0,M10.5.0/3" |
177 | then if a last transition time is in July, the transition's local time | |
178 | type must specify a daylight-saving time abbreviated | |
179 | .q "WEST" | |
180 | that is one hour east of UT. | |
a312fa03 PE |
181 | Also, if there is at least one transition, time type 0 is associated |
182 | with the time period from the indefinite past up to but not including | |
183 | the earliest transition time. | |
72942d65 | 184 | .SS Version 3 format |
2061865f | 185 | For version-3-format timezone files, the POSIX-TZ-style string may |
72942d65 | 186 | use two minor extensions to the POSIX TZ format, as described in |
3c0e88e4 | 187 | .BR newtzset (3). |
72942d65 | 188 | First, the hours part of its transition times may be signed and range from |
aec6e1d9 | 189 | \-167 through 167 instead of the POSIX-required unsigned values |
2061865f MK |
190 | from 0 through 24. |
191 | Second, DST is in effect all year if it starts | |
72942d65 PE |
192 | January 1 at 00:00 and ends December 31 at 24:00 plus the difference |
193 | between daylight saving and standard time. | |
f09abf6d | 194 | .PP |
72942d65 | 195 | Future changes to the format may append more data. |
64fb5aed | 196 | .SH SEE ALSO |
72942d65 PE |
197 | .BR time (2), |
198 | .BR localtime (3), | |
b58ee47a | 199 | .BR tzset (3), |
c80ce5bc | 200 | .BR tzselect (8), |
72942d65 PE |
201 | .BR zdump (8), |
202 | .BR zic (8) | |
203 | .\" This file is in the public domain, so clarified as of | |
204 | .\" 1996-06-05 by Arthur David Olson. |