Debian Codegraph @

upstream/fedora-44/man5/tzfile.5

raw
1 .\" This file is in the public domain, so clarified as of
2 .\" 1996-06-05 by Arthur David Olson.
3 .TH tzfile 5 "" "Time Zone Database"
4 .SH NAME
5 tzfile \- timezone information
6 .SH DESCRIPTION
7 .ie '\(lq'' .ds lq \&"\"
8 .el .ds lq \(lq\"
9 .ie '\(rq'' .ds rq \&"\"
10 .el .ds rq \(rq\"
11 .de q
12 \\$3\*(lq\\$1\*(rq\\$2
13 ..
14 .ie \n(.g .ds - \f(CR-\fP
15 .el .ds - \-
16 The timezone information files used by
17 .BR tzset (3)
18 are typically found under a directory with a name like
19 .IR /usr/share/zoneinfo .
20 These files use the format described in Internet RFC 8536.
21 Each file is a sequence of 8-bit bytes.
22 In a file, a binary integer is represented by a sequence of one or
23 more bytes in network order (bigendian, or high-order byte first),
24 with all bits significant,
25 a signed binary integer is represented using two's complement,
26 and a boolean is represented by a one-byte binary integer that is
27 either 0 (false) or 1 (true).
28 The format begins with a 44-byte header containing the following fields:
29 .RS 2
30 .IP \(bu 3
31 The magic four-byte ASCII sequence
32 .q "TZif"
33 identifies the file as a timezone information file.
34 .IP \(bu
35 A byte identifying the version of the file's format
36 (as of 2021, either an ASCII NUL,
37 .q "2",
38 .q "3",
39 or
40 .q "4" ).
41 .IP \(bu
42 Fifteen bytes containing zeros reserved for future use.
43 .IP \(bu
44 Six four-byte integer values, in the following order:
45 .RS
46 .TP 2
47 .B tzh_ttisutcnt
48 The number of UT/local indicators stored in the file.
49 (UT is Universal Time.)
50 .TP
51 .B tzh_ttisstdcnt
52 The number of standard/wall indicators stored in the file.
53 .TP
54 .B tzh_leapcnt
55 The number of leap seconds for which data entries are stored in the file.
56 .TP
57 .B tzh_timecnt
58 The number of transition times for which data entries are stored
59 in the file.
60 .TP
61 .B tzh_typecnt
62 The number of local time types for which data entries are stored
63 in the file (must not be zero).
64 .TP
65 .B tzh_charcnt
66 The number of bytes of time zone abbreviation strings
67 stored in the file.
68 .RE
69 .RE
70 .PP
71 The above header is followed by the following fields, whose lengths
72 depend on the contents of the header:
73 .RS 2
74 .IP \(bu 3
75 .B tzh_timecnt
76 four-byte signed integer values sorted in ascending order.
77 These values are written in network byte order.
78 Each is used as a transition time (as returned by
79 .BR time (2))
80 at which the rules for computing local time change.
81 .IP \(bu
82 .B tzh_timecnt
83 one-byte unsigned integer values;
84 each one but the last tells which of the different types of local time types
85 described in the file is associated with the time period
86 starting with the same-indexed transition time
87 and continuing up to but not including the next transition time.
88 (The last time type is present only for consistency checking with the
89 POSIX.1-2017-style TZ string described below.)
90 These values serve as indices into the next field.
91 .IP \(bu
92 .B tzh_typecnt
93 .B ttinfo
94 entries, each defined as follows:
95 .in +2
96 .sp
97 .nf
98 .ta \w'\0\0\0\0'u +\w'unsigned char\0'u
99 struct ttinfo {
100 int32_t tt_utoff;
101 unsigned char tt_isdst;
102 unsigned char tt_desigidx;
103 };
104 .in
105 .fi
106 .sp
107 Each structure is written as a four-byte signed integer value for
108 .BR tt_utoff ,
109 in network byte order, followed by a one-byte boolean for
110 .B tt_isdst
111 and a one-byte value for
112 .BR tt_desigidx .
113 In each structure,
114 .B tt_utoff
115 gives the number of seconds to be added to UT,
116 .B tt_isdst
117 tells whether
118 .B tm_isdst
119 should be set by
120 .BR localtime (3)
121 and
122 .B tt_desigidx
123 serves as an index into the array of time zone abbreviation bytes
124 that follow the
125 .B ttinfo
126 entries in the file; if the designated string is "\*-00", the
127 .B ttinfo
128 entry is a placeholder indicating that local time is unspecified.
129 The
130 .B tt_utoff
131 value is never equal to \-2**31, to let 32-bit clients negate it without
132 overflow.
133 Also, in realistic applications
134 .B tt_utoff
135 is in the range [\-89999, 93599] (i.e., more than \-25 hours and less
136 than 26 hours); this allows easy support by implementations that
137 already support the POSIX-required range [\-24:59:59, 25:59:59].
138 .IP \(bu
139 .B tzh_charcnt
140 bytes that represent time zone designations,
141 which are null-terminated byte strings, each indexed by the
142 .B tt_desigidx
143 values mentioned above.
144 The byte strings can overlap if one is a suffix of the other.
145 The encoding of these strings is not specified.
146 .IP \(bu
147 .B tzh_leapcnt
148 pairs of four-byte values, written in network byte order;
149 the first value of each pair gives the nonnegative time
150 (as returned by
151 .BR time (2))
152 at which a leap second occurs or at which the leap second table expires;
153 the second is a signed integer specifying the correction, which is the
154 .I total
155 number of leap seconds to be applied during the time period
156 starting at the given time.
157 The pairs of values are sorted in strictly ascending order by time.
158 Each pair denotes one leap second, either positive or negative,
159 except that if the last pair has the same correction as the previous one,
160 the last pair denotes the leap second table's expiration time.
161 Each leap second is at the end of a UTC calendar month.
162 The first leap second has a nonnegative occurrence time,
163 and is a positive leap second if and only if its correction is positive;
164 the correction for each leap second after the first differs
165 from the previous leap second by either 1 for a positive leap second,
166 or \-1 for a negative leap second.
167 If the leap second table is empty, the leap-second correction is zero
168 for all timestamps;
169 otherwise, for timestamps before the first occurrence time,
170 the leap-second correction is zero if the first pair's correction is 1 or \-1,
171 and is unspecified otherwise (which can happen only in files
172 truncated at the start).
173 .IP \(bu
174 .B tzh_ttisstdcnt
175 standard/wall indicators, each stored as a one-byte boolean;
176 they tell whether the transition times associated with local time types
177 were specified as standard time or local (wall clock) time.
178 .IP \(bu
179 .B tzh_ttisutcnt
180 UT/local indicators, each stored as a one-byte boolean;
181 they tell whether the transition times associated with local time types
182 were specified as UT or local time.
183 If a UT/local indicator is set, the corresponding standard/wall indicator
184 must also be set.
185 .RE
186 .PP
187 The standard/wall and UT/local indicators were designed for
188 transforming a TZif file's transition times into transitions appropriate
189 for another time zone specified via
190 a POSIX.1-2017-style TZ string that lacks rules.
191 For example, when TZ="EET\*-2EEST" and there is no TZif file "EET\*-2EEST",
192 the idea was to adapt the transition times from a TZif file with the
193 well-known name "posixrules" that is present only for this purpose and
194 is a copy of the file "Europe/Brussels", a file with a different UT offset.
195 POSIX does not specify this obsolete transformational behavior,
196 the default rules are installation-dependent, and no implementation
197 is known to support this feature for timestamps past 2037,
198 so users desiring (say) Greek time should instead specify
199 TZ="Europe/Athens" for better historical coverage, falling back on
200 TZ="EET\*-2EEST,M3.5.0/3,M10.5.0/4" if POSIX conformance is required
201 and older timestamps need not be handled accurately.
202 .PP
203 The
204 .BR localtime (3)
205 function
206 normally uses the first
207 .B ttinfo
208 structure in the file
209 if either
210 .B tzh_timecnt
211 is zero or the time argument is less than the first transition time recorded
212 in the file.
213 .SS Version 2 format
214 For version-2-format timezone files,
215 the above header and data are followed by a second header and data,
216 identical in format except that
217 eight bytes are used for each transition time or leap second time.
218 (Leap second counts remain four bytes.)
219 After the second header and data comes a newline-enclosed string
220 in the style of the contents of a POSIX.1-2017 TZ environment variable,
221 for use in handling instants
222 after the last transition time stored in the file
223 or for all instants if the file has no transitions.
224 The TZ string is empty (i.e., nothing between the newlines)
225 if there is no POSIX.1-2017-style representation for such instants.
226 If nonempty, the TZ string must agree with the local time
227 type after the last transition time if present in the eight-byte data;
228 for example, given the string
229 .q "WET0WEST,M3.5.0/1,M10.5.0"
230 then if a last transition time is in July, the transition's local time
231 type must specify a daylight-saving time abbreviated
232 .q "WEST"
233 that is one hour east of UT.
234 Also, if there is at least one transition, time type 0 is associated
235 with the time period from the indefinite past up to but not including
236 the earliest transition time.
237 .SS Version 3 format
238 For version-3-format timezone files, the TZ string may
239 use two minor extensions to the POSIX.1-2017 TZ format, as described in
240 .BR newtzset (3).
241 First, the hours part of its transition times may be signed and range from
242 \-167 through 167 instead of the POSIX-required unsigned values
243 from 0 through 24.
244 Second, DST is in effect all year if it starts
245 January 1 at 00:00 and ends December 31 at 24:00 plus the difference
246 between daylight saving and standard time.
247 .SS Version 4 format
248 For version-4-format TZif files,
249 the first leap second record can have a correction that is neither
250 +1 nor \-1, to represent truncation of the TZif file at the start.
251 Also, if two or more leap second transitions are present and the last
252 entry's correction equals the previous one, the last entry
253 denotes the expiration of the leap second table instead of a leap second;
254 timestamps after this expiration are unreliable in that future
255 releases will likely add leap second entries after the expiration, and
256 the added leap seconds will change how post-expiration timestamps are treated.
257 .SS Interoperability considerations
258 Future changes to the format may append more data.
259 .PP
260 Version 1 files are considered a legacy format and
261 should not be generated, as they do not support transition
262 times after the year 2038.
263 Readers that understand only Version 1 must ignore
264 any data that extends beyond the calculated end of the version
265 1 data block.
266 .PP
267 Other than version 1, writers should generate
268 the lowest version number needed by a file's data.
269 For example, a writer should generate a version 4 file
270 only if its leap second table either expires or is truncated at the start.
271 Likewise, a writer not generating a version 4 file
272 should generate a version 3 file only if
273 TZ string extensions are necessary to accurately
274 model transition times.
275 .PP
276 The sequence of time changes defined by the version 1
277 header and data block should be a contiguous sub-sequence
278 of the time changes defined by the version 2+ header and data
279 block, and by the footer.
280 This guideline helps obsolescent version 1 readers
281 agree with current readers about timestamps within the
282 contiguous sub-sequence. It also lets writers not
283 supporting obsolescent readers use a
284 .B tzh_timecnt
285 of zero
286 in the version 1 data block to save space.
287 .PP
288 When a TZif file contains a leap second table expiration
289 time, TZif readers should either refuse to process
290 post-expiration timestamps, or process them as if the expiration
291 time did not exist (possibly with an error indication).
292 .PP
293 Time zone designations should consist of at least three (3)
294 and no more than six (6) ASCII characters from the set of
295 alphanumerics,
296 .q "\*-",
297 and
298 .q "+".
299 This is for compatibility with POSIX requirements for
300 time zone abbreviations.
301 .PP
302 When reading a version 2 or higher file, readers
303 should ignore the version 1 header and data block except for
304 the purpose of skipping over them.
305 .PP
306 Readers should calculate the total lengths of the
307 headers and data blocks and check that they all fit within
308 the actual file size, as part of a validity check for the file.
309 .PP
310 When a positive leap second occurs, readers should append an extra
311 second to the local minute containing the second just before the leap
312 second. If this occurs when the UTC offset is not a multiple of 60
313 seconds, the leap second occurs earlier than the last second of the
314 local minute and the minute's remaining local seconds are numbered
315 through 60 instead of the usual 59; the UTC offset is unaffected.
316 .SS Common interoperability issues
317 This section documents common problems in reading or writing TZif files.
318 Most of these are problems in generating TZif files for use by
319 older readers.
320 The goals of this section are:
321 .RS 2
322 .IP \(bu 3
323 to help TZif writers output files that avoid common
324 pitfalls in older or buggy TZif readers,
325 .IP \(bu
326 to help TZif readers avoid common pitfalls when reading
327 files generated by future TZif writers, and
328 .IP \(bu
329 to help any future specification authors see what sort of
330 problems arise when the TZif format is changed.
331 .RE
332 .PP
333 When new versions of the TZif format have been defined, a
334 design goal has been that a reader can successfully use a TZif
335 file even if the file is of a later TZif version than what the
336 reader was designed for.
337 When complete compatibility was not achieved, an attempt was
338 made to limit glitches to rarely used timestamps and allow
339 simple partial workarounds in writers designed to generate
340 new-version data useful even for older-version readers.
341 This section attempts to document these compatibility issues and
342 workarounds, as well as to document other common bugs in
343 readers.
344 .PP
345 Interoperability problems with TZif include the following:
346 .RS 2
347 .IP \(bu 3
348 Some readers examine only version 1 data.
349 As a partial workaround, a writer can output as much version 1
350 data as possible.
351 However, a reader should ignore version 1 data, and should use
352 version 2+ data even if the reader's native timestamps have only
353 32 bits.
354 .IP \(bu
355 Some readers designed for version 2 might mishandle
356 timestamps after a version 3 or higher file's last transition, because
357 they cannot parse extensions to POSIX.1-2017 in the TZ-like string.
358 As a partial workaround, a writer can output more transitions
359 than necessary, so that only far-future timestamps are
360 mishandled by version 2 readers.
361 .IP \(bu
362 Some readers designed for version 2 do not support
363 permanent daylight saving time with transitions after 24:00
364 \(en e.g., a TZ string
365 .q "EST5EDT,0/0,J365/25"
366 denoting permanent Eastern Daylight Time
367 (\-04).
368 As a workaround, a writer can substitute standard time
369 for two time zones east, e.g.,
370 .q "XXX3EDT4,0/0,J365/23"
371 for a time zone with a never-used standard time (XXX, \-03)
372 and negative daylight saving time (EDT, \-04) all year.
373 Alternatively,
374 as a partial workaround a writer can substitute standard time
375 for the next time zone east \(en e.g.,
376 .q "AST4"
377 for permanent
378 Atlantic Standard Time (\-04).
379 .IP \(bu
380 Some readers designed for version 2 or 3, and that require strict
381 conformance to RFC 8536, reject version 4 files whose leap second
382 tables are truncated at the start or that end in expiration times.
383 .IP \(bu
384 Some readers ignore the footer, and instead predict future
385 timestamps from the time type of the last transition.
386 As a partial workaround, a writer can output more transitions
387 than necessary.
388 .IP \(bu
389 Some readers do not use time type 0 for timestamps before
390 the first transition, in that they infer a time type using a
391 heuristic that does not always select time type 0.
392 As a partial workaround, a writer can output a dummy (no-op)
393 first transition at an early time.
394 .IP \(bu
395 Some readers mishandle timestamps before the first
396 transition that has a timestamp not less than \-2**31.
397 Readers that support only 32-bit timestamps are likely to be
398 more prone to this problem, for example, when they process
399 64-bit transitions only some of which are representable in 32
400 bits.
401 As a partial workaround, a writer can output a dummy
402 transition at timestamp \-2**31.
403 .IP \(bu
404 Some readers mishandle a transition if its timestamp has
405 the minimum possible signed 64-bit value.
406 Timestamps less than \-2**59 are not recommended.
407 .IP \(bu
408 Some readers mishandle TZ strings that
409 contain
410 .q "<"
411 or
412 .q ">".
413 As a partial workaround, a writer can avoid using
414 .q "<"
415 or
416 .q ">"
417 for time zone abbreviations containing only alphabetic
418 characters.
419 .IP \(bu
420 Many readers mishandle time zone abbreviations that contain
421 non-ASCII characters.
422 These characters are not recommended.
423 .IP \(bu
424 Some readers may mishandle time zone abbreviations that
425 contain fewer than 3 or more than 6 characters, or that
426 contain ASCII characters other than alphanumerics,
427 .q "\*-",
428 and
429 .q "+".
430 These abbreviations are not recommended.
431 .IP \(bu
432 Some readers mishandle TZif files that specify
433 daylight-saving time UT offsets that are less than the UT
434 offsets for the corresponding standard time.
435 These readers do not support locations like Ireland, which
436 uses the equivalent of the TZ string
437 .q "IST\*-1GMT0,M10.5.0,M3.5.0/1",
438 observing standard time
439 (IST, +01) in summer and daylight saving time (GMT, +00) in winter.
440 As a partial workaround, a writer can output data for the
441 equivalent of the TZ string
442 .q "GMT0IST,M3.5.0/1,M10.5.0",
443 thus swapping standard and daylight saving time.
444 Although this workaround misidentifies which part of the year
445 uses daylight saving time, it records UT offsets and time zone
446 abbreviations correctly.
447 .IP \(bu
448 Some readers generate ambiguous timestamps for positive leap seconds
449 that occur when the UTC offset is not a multiple of 60 seconds.
450 For example, in a timezone with UTC offset +01:23:45 and with
451 a positive leap second 78796801 (1972-06-30 23:59:60 UTC), some readers will
452 map both 78796800 and 78796801 to 01:23:45 local time the next day
453 instead of mapping the latter to 01:23:46, and they will map 78796815 to
454 01:23:59 instead of to 01:23:60.
455 This has not yet been a practical problem, since no civil authority
456 has observed such UTC offsets since leap seconds were
457 introduced in 1972.
458 .RE
459 .PP
460 Some interoperability problems are reader bugs that
461 are listed here mostly as warnings to developers of readers.
462 .RS 2
463 .IP \(bu 3
464 Some readers do not support negative timestamps.
465 Developers of distributed applications should keep this
466 in mind if they need to deal with pre-1970 data.
467 .IP \(bu
468 Some readers mishandle timestamps before the first
469 transition that has a nonnegative timestamp.
470 Readers that do not support negative timestamps are likely to
471 be more prone to this problem.
472 .IP \(bu
473 Some readers mishandle time zone abbreviations like
474 .q "\*-08"
475 that contain
476 .q "+",
477 .q "\*-",
478 or digits.
479 .IP \(bu
480 Some readers mishandle UT offsets that are out of the
481 traditional range of \-12 through +12 hours, and so do not
482 support locations like Kiritimati that are outside this
483 range.
484 .IP \(bu
485 Some readers mishandle UT offsets in the range [\-3599, \-1]
486 seconds from UT, because they integer-divide the offset by
487 3600 to get 0 and then display the hour part as
488 .q "+00".
489 .IP \(bu
490 Some readers mishandle UT offsets that are not a multiple
491 of one hour, or of 15 minutes, or of 1 minute.
492 .RE
493 .SH SEE ALSO
494 .BR time (2),
495 .BR localtime (3),
496 .BR tzset (3),
497 .BR tzselect (8),
498 .BR zdump (8),
499 .BR zic (8).
500 .PP
501 Olson A, Eggert P, Murchison K. The Time Zone Information Format (TZif).
502 2019 Feb.
503 .UR https://\:datatracker.ietf.org/\:doc/\:html/\:rfc8536
504 Internet RFC 8536
505 .UE
506 .UR https://\:doi.org/\:10.17487/\:RFC8536
507 doi:10.17487/RFC8536
508 .UE .