1TZFILE(5) Linux Programmer's Manual TZFILE(5)
2
6 tzfile - timezone information
7
9 The timezone information files used by tzset(3) are typically found un‐
10 der a directory with a name like /usr/share/zoneinfo. These files use
11 the format described in Internet RFC 8536. Each file is a sequence of
12 8-bit bytes. In a file, a binary integer is represented by a sequence
13 of one or more bytes in network order (bigendian, or high-order byte
14 first), with all bits significant, a signed binary integer is repre‐
15 sented using two's complement, and a boolean is represented by a one-
16 byte binary integer that is either 0 (false) or 1 (true). The format
17 begins with a 44-byte header containing the following fields:
18 * The magic four-byte ASCII sequence “TZif” identifies the file as a
20 timezone information file.
21 * A byte identifying the version of the file's format (as of 2017, ei‐
23 ther an ASCII NUL, or “2”, or “3”).
24 * Fifteen bytes containing zeros reserved for future use.
26 * Six four-byte integer values, in the following order:
28 tzh_ttisutcnt
30 The number of UT/local indicators stored in the file. (UT is
31 Universal Time.)
32 tzh_ttisstdcnt
34 The number of standard/wall indicators stored in the file.
35 tzh_leapcnt
37 The number of leap seconds for which data entries are stored
38 in the file.
39 tzh_timecnt
41 The number of transition times for which data entries are
42 stored in the file.
43 tzh_typecnt
45 The number of local time types for which data entries are
46 stored in the file (must not be zero).
47 tzh_charcnt
49 The number of bytes of time zone abbreviation strings stored
50 in the file.
51 The above header is followed by the following fields, whose lengths de‐
53 pend on the contents of the header:
54 * tzh_timecnt four-byte signed integer values sorted in ascending or‐
56 der. These values are written in network byte order. Each is used
57 as a transition time (as returned by time(2)) at which the rules for
58 computing local time change.
59 * tzh_timecnt one-byte unsigned integer values; each one but the last
61 tells which of the different types of local time types described in
62 the file is associated with the time period starting with the same-
63 indexed transition time and continuing up to but not including the
64 next transition time. (The last time type is present only for con‐
65 sistency checking with the POSIX-style TZ string described below.)
66 These values serve as indices into the next field.
67 * tzh_typecnt ttinfo entries, each defined as follows:
69 struct ttinfo {
71 int32_t tt_utoff;
72 unsigned char tt_isdst;
73 unsigned char tt_desigidx;
74 };
75 Each structure is written as a four-byte signed integer value for
77 tt_utoff, in network byte order, followed by a one-byte boolean for
78 tt_isdst and a one-byte value for tt_desigidx. In each structure,
79 tt_utoff gives the number of seconds to be added to UT, tt_isdst
80 tells whether tm_isdst should be set by localtime(3) and tt_desigidx
81 serves as an index into the array of time zone abbreviation bytes
82 that follow the ttinfo structure(s) in the file. The tt_utoff value
83 is never equal to -2**31, to let 32-bit clients negate it without
84 overflow. Also, in realistic applications tt_utoff is in the range
85 [-89999, 93599] (i.e., more than -25 hours and less than 26 hours);
86 this allows easy support by implementations that already support the
87 POSIX-required range [-24:59:59, 25:59:59].
88 * tzh_leapcnt pairs of four-byte values, written in network byte order;
90 the first value of each pair gives the nonnegative time (as returned
91 by time(2)) at which a leap second occurs; the second is a signed in‐
92 teger specifying the total number of leap seconds to be applied dur‐
93 ing the time period starting at the given time. The pairs of values
94 are sorted in ascending order by time. Each transition is for one
95 leap second, either positive or negative; transitions always sepa‐
96 rated by at least 28 days minus 1 second.
97 * tzh_ttisstdcnt standard/wall indicators, each stored as a one-byte
99 boolean; they tell whether the transition times associated with local
100 time types were specified as standard time or local (wall clock)
101 time.
102 * tzh_ttisutcnt UT/local indicators, each stored as a one-byte boolean;
104 they tell whether the transition times associated with local time
105 types were specified as UT or local time. If a UT/local indicator is
106 set, the corresponding standard/wall indicator must also be set.
107 The standard/wall and UT/local indicators were designed for transform‐
109 ing a TZif file's transition times into transitions appropriate for an‐
110 other time zone specified via a POSIX-style TZ string that lacks rules.
111 For example, when TZ="EET-2EEST" and there is no TZif file "EET-2EEST",
112 the idea was to adapt the transition times from a TZif file with the
113 well-known name "posixrules" that is present only for this purpose and
114 is a copy of the file "Europe/Brussels", a file with a different UT
115 offset. POSIX does not specify this obsolete transformational behav‐
116 ior, the default rules are installation-dependent, and no implementa‐
117 tion is known to support this feature for timestamps past 2037, so
118 users desiring (say) Greek time should instead specify TZ="Eu‐
119 rope/Athens" for better historical coverage, falling back on
120 TZ="EET-2EEST,M3.5.0/3,M10.5.0/4" if POSIX conformance is required and
121 older timestamps need not be handled accurately.
122 The localtime(3) function normally uses the first ttinfo structure in
124 the file if either tzh_timecnt is zero or the time argument is less
125 than the first transition time recorded in the file.
126 Version 2 format
128 For version-2-format timezone files, the above header and data are fol‐
129 lowed by a second header and data, identical in format except that
130 eight bytes are used for each transition time or leap second time.
131 (Leap second counts remain four bytes.) After the second header and
132 data comes a newline-enclosed, POSIX-TZ-environment-variable-style
133 string for use in handling instants after the last transition time
134 stored in the file or for all instants if the file has no transitions.
135 The POSIX-style TZ string is empty (i.e., nothing between the newlines)
136 if there is no POSIX representation for such instants. If nonempty,
137 the POSIX-style TZ string must agree with the local time type after the
138 last transition time if present in the eight-byte data; for example,
139 given the string “WET0WEST,M3.5.0,M10.5.0/3” then if a last transition
140 time is in July, the transition's local time type must specify a day‐
141 light-saving time abbreviated “WEST” that is one hour east of UT.
142 Also, if there is at least one transition, time type 0 is associated
143 with the time period from the indefinite past up to but not including
144 the earliest transition time.
145 Version 3 format
147 For version-3-format timezone files, the POSIX-TZ-style string may use
148 two minor extensions to the POSIX TZ format, as described in
149 newtzset(3). First, the hours part of its transition times may be
150 signed and range from -167 through 167 instead of the POSIX-required
151 unsigned values from 0 through 24. Second, DST is in effect all year
152 if it starts January 1 at 00:00 and ends December 31 at 24:00 plus the
153 difference between daylight saving and standard time.
154 Interoperability considerations
156 Future changes to the format may append more data.
157 Version 1 files are considered a legacy format and should be avoided,
159 as they do not support transition times after the year 2038. Readers
160 that only understand Version 1 must ignore any data that extends beyond
161 the calculated end of the version 1 data block.
162 Writers should generate a version 3 file if TZ string extensions are
164 necessary to accurately model transition times. Otherwise, version 2
165 files should be generated.
166 The sequence of time changes defined by the version 1 header and data
168 block should be a contiguous subsequence of the time changes defined by
169 the version 2+ header and data block, and by the footer. This guide‐
170 line helps obsolescent version 1 readers agree with current readers
171 about timestamps within the contiguous subsequence. It also lets writ‐
172 ers not supporting obsolescent readers use a tzh_timecnt of zero in the
173 version 1 data block to save space.
174 Time zone designations should consist of at least three (3) and no more
176 than six (6) ASCII characters from the set of alphanumerics, “-”, and
177 “+”. This is for compatibility with POSIX requirements for time zone
178 abbreviations.
179 When reading a version 2 or 3 file, readers should ignore the version 1
181 header and data block except for the purpose of skipping over them.
182 Readers should calculate the total lengths of the headers and data
184 blocks and check that they all fit within the actual file size, as part
185 of a validity check for the file.
186 Common interoperability issues
188 This section documents common problems in reading or writing TZif
189 files. Most of these are problems in generating TZif files for use by
190 older readers. The goals of this section are:
191 * to help TZif writers output files that avoid common pitfalls in older
193 or buggy TZif readers,
194 * to help TZif readers avoid common pitfalls when reading files gener‐
196 ated by future TZif writers, and
197 * to help any future specification authors see what sort of problems
199 arise when the TZif format is changed.
200 When new versions of the TZif format have been defined, a design goal
202 has been that a reader can successfully use a TZif file even if the
203 file is of a later TZif version than what the reader was designed for.
204 When complete compatibility was not achieved, an attempt was made to
205 limit glitches to rarely used timestamps, and to allow simple partial
206 workarounds in writers designed to generate new-version data useful
207 even for older-version readers. This section attempts to document
208 these compatibility issues and workarounds, as well as to document
209 other common bugs in readers.
210 Interoperability problems with TZif include the following:
212 * Some readers examine only version 1 data. As a partial workaround, a
214 writer can output as much version 1 data as possible. However, a
215 reader should ignore version 1 data, and should use version 2+ data
216 even if the reader's native timestamps have only 32 bits.
217 * Some readers designed for version 2 might mishandle timestamps after
219 a version 3 file's last transition, because they cannot parse exten‐
220 sions to POSIX in the TZ-like string. As a partial workaround, a
221 writer can output more transitions than necessary, so that only far-
222 future timestamps are mishandled by version 2 readers.
223 * Some readers designed for version 2 do not support permanent daylight
225 saving time, e.g., a TZ string “EST5EDT,0/0,J365/25” denoting perma‐
226 nent Eastern Daylight Time (-04). As a partial workaround, a writer
227 can substitute standard time for the next time zone east, e.g.,
228 “AST4” for permanent Atlantic Standard Time (-04).
229 * Some readers ignore the footer, and instead predict future timestamps
231 from the time type of the last transition. As a partial workaround,
232 a writer can output more transitions than necessary.
233 * Some readers do not use time type 0 for timestamps before the first
235 transition, in that they infer a time type using a heuristic that
236 does not always select time type 0. As a partial workaround, a
237 writer can output a dummy (no-op) first transition at an early time.
238 * Some readers mishandle timestamps before the first transition that
240 has a timestamp not less than -2**31. Readers that support only
241 32-bit timestamps are likely to be more prone to this problem, for
242 example, when they process 64-bit transitions only some of which are
243 representable in 32 bits. As a partial workaround, a writer can out‐
244 put a dummy transition at timestamp -2**31.
245 * Some readers mishandle a transition if its timestamp has the minimum
247 possible signed 64-bit value. Timestamps less than -2**59 are not
248 recommended.
249 * Some readers mishandle POSIX-style TZ strings that contain “<” or
251 “>”. As a partial workaround, a writer can avoid using “<” or “>”
252 for time zone abbreviations containing only alphabetic characters.
253 * Many readers mishandle time zone abbreviations that contain non-ASCII
255 characters. These characters are not recommended.
256 * Some readers may mishandle time zone abbreviations that contain fewer
258 than 3 or more than 6 characters, or that contain ASCII characters
259 other than alphanumerics, “-”, and “+”. These abbreviations are not
260 recommended.
261 * Some readers mishandle TZif files that specify daylight-saving time
263 UT offsets that are less than the UT offsets for the corresponding
264 standard time. These readers do not support locations like Ireland,
265 which uses the equivalent of the POSIX TZ string
266 “IST-1GMT0,M10.5.0,M3.5.0/1”, observing standard time (IST, +01) in
267 summer and daylight saving time (GMT, +00) in winter. As a partial
268 workaround, a writer can output data for the equivalent of the POSIX
269 TZ string “GMT0IST,M3.5.0/1,M10.5.0”, thus swapping standard and day‐
270 light saving time. Although this workaround misidentifies which part
271 of the year uses daylight saving time, it records UT offsets and time
272 zone abbreviations correctly.
273 Some interoperability problems are reader bugs that are listed here
275 mostly as warnings to developers of readers.
276 * Some readers do not support negative timestamps. Developers of dis‐
278 tributed applications should keep this in mind if they need to deal
279 with pre-1970 data.
280 * Some readers mishandle timestamps before the first transition that
282 has a nonnegative timestamp. Readers that do not support negative
283 timestamps are likely to be more prone to this problem.
284 * Some readers mishandle time zone abbreviations like “-08” that con‐
286 tain “+”, “-”, or digits.
287 * Some readers mishandle UT offsets that are out of the traditional
289 range of -12 through +12 hours, and so do not support locations like
290 Kiritimati that are outside this range.
291 * Some readers mishandle UT offsets in the range [-3599, -1] seconds
293 from UT, because they integer-divide the offset by 3600 to get 0 and
294 then display the hour part as “+00”.
295 * Some readers mishandle UT offsets that are not a multiple of one
297 hour, or of 15 minutes, or of 1 minute.
298
300 time(2), localtime(3), tzset(3), tzselect(8), zdump(8), zic(8).
301 Olson A, Eggert P, Murchison K. The Time Zone Information Format
303 (TZif). 2019 Feb. Internet RFC 8536 ⟨https://www.rfc-editor.org/info/
304 rfc8536⟩ doi:10.17487/RFC8536 ⟨https://doi.org/10.17487/RFC8536⟩.
305
307 This page is part of release 5.12 of the Linux man-pages project. A
308 description of the project, information about reporting bugs, and the
309 latest version of this page, can be found at
310 https://www.kernel.org/doc/man-pages/.
311 2020-04-27 TZFILE(5)