Debian Codegraph @

upstream/debian-trixie/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 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=122906#47
214 .\" Reviewed by upstream and rejected, May 2012
215 .SH NOTES
216 This manual page documents
217 .I <tzfile.h>
218 in the glibc source archive, see
219 .IR timezone/tzfile.h .
220 .PP
221 It seems that
222 .BR timezone (3)
223 uses
224 .B tzfile
225 internally, but glibc refuses to expose it to userspace. This is most
226 likely because the standardised functions are more useful and
227 portable, and actually documented by glibc. It may only be in glibc
228 just to support the non-glibc-maintained timezone data (which is
229 maintained by some other entity).
230 .\" End of patch
231 .SS Version 2 format
232 For version-2-format timezone files,
233 the above header and data are followed by a second header and data,
234 identical in format except that
235 eight bytes are used for each transition time or leap second time.
236 (Leap second counts remain four bytes.)
237 After the second header and data comes a newline-enclosed string
238 in the style of the contents of a POSIX.1-2017 TZ environment variable,
239 for use in handling instants
240 after the last transition time stored in the file
241 or for all instants if the file has no transitions.
242 The TZ string is empty (i.e., nothing between the newlines)
243 if there is no POSIX.1-2017-style representation for such instants.
244 If nonempty, the TZ string must agree with the local time
245 type after the last transition time if present in the eight-byte data;
246 for example, given the string
247 .q "WET0WEST,M3.5.0/1,M10.5.0"
248 then if a last transition time is in July, the transition's local time
249 type must specify a daylight-saving time abbreviated
250 .q "WEST"
251 that is one hour east of UT.
252 Also, if there is at least one transition, time type 0 is associated
253 with the time period from the indefinite past up to but not including
254 the earliest transition time.
255 .SS Version 3 format
256 For version-3-format timezone files, the TZ string may
257 use two minor extensions to the POSIX.1-2017 TZ format, as described in
258 .BR newtzset (3).
259 First, the hours part of its transition times may be signed and range from
260 \-167 through 167 instead of the POSIX-required unsigned values
261 from 0 through 24.
262 Second, DST is in effect all year if it starts
263 January 1 at 00:00 and ends December 31 at 24:00 plus the difference
264 between daylight saving and standard time.
265 .SS Version 4 format
266 For version-4-format TZif files,
267 the first leap second record can have a correction that is neither
268 +1 nor \-1, to represent truncation of the TZif file at the start.
269 Also, if two or more leap second transitions are present and the last
270 entry's correction equals the previous one, the last entry
271 denotes the expiration of the leap second table instead of a leap second;
272 timestamps after this expiration are unreliable in that future
273 releases will likely add leap second entries after the expiration, and
274 the added leap seconds will change how post-expiration timestamps are treated.
275 .SS Interoperability considerations
276 Future changes to the format may append more data.
277 .PP
278 Version 1 files are considered a legacy format and
279 should not be generated, as they do not support transition
280 times after the year 2038.
281 Readers that understand only Version 1 must ignore
282 any data that extends beyond the calculated end of the version
283 1 data block.
284 .PP
285 Other than version 1, writers should generate
286 the lowest version number needed by a file's data.
287 For example, a writer should generate a version 4 file
288 only if its leap second table either expires or is truncated at the start.
289 Likewise, a writer not generating a version 4 file
290 should generate a version 3 file only if
291 TZ string extensions are necessary to accurately
292 model transition times.
293 .PP
294 The sequence of time changes defined by the version 1
295 header and data block should be a contiguous sub-sequence
296 of the time changes defined by the version 2+ header and data
297 block, and by the footer.
298 This guideline helps obsolescent version 1 readers
299 agree with current readers about timestamps within the
300 contiguous sub-sequence. It also lets writers not
301 supporting obsolescent readers use a
302 .B tzh_timecnt
303 of zero
304 in the version 1 data block to save space.
305 .PP
306 When a TZif file contains a leap second table expiration
307 time, TZif readers should either refuse to process
308 post-expiration timestamps, or process them as if the expiration
309 time did not exist (possibly with an error indication).
310 .PP
311 Time zone designations should consist of at least three (3)
312 and no more than six (6) ASCII characters from the set of
313 alphanumerics,
314 .q "\*-",
315 and
316 .q "+".
317 This is for compatibility with POSIX requirements for
318 time zone abbreviations.
319 .PP
320 When reading a version 2 or higher file, readers
321 should ignore the version 1 header and data block except for
322 the purpose of skipping over them.
323 .PP
324 Readers should calculate the total lengths of the
325 headers and data blocks and check that they all fit within
326 the actual file size, as part of a validity check for the file.
327 .PP
328 When a positive leap second occurs, readers should append an extra
329 second to the local minute containing the second just before the leap
330 second. If this occurs when the UTC offset is not a multiple of 60
331 seconds, the leap second occurs earlier than the last second of the
332 local minute and the minute's remaining local seconds are numbered
333 through 60 instead of the usual 59; the UTC offset is unaffected.
334 .SS Common interoperability issues
335 This section documents common problems in reading or writing TZif files.
336 Most of these are problems in generating TZif files for use by
337 older readers.
338 The goals of this section are:
339 .RS 2
340 .IP \(bu 3
341 to help TZif writers output files that avoid common
342 pitfalls in older or buggy TZif readers,
343 .IP \(bu
344 to help TZif readers avoid common pitfalls when reading
345 files generated by future TZif writers, and
346 .IP \(bu
347 to help any future specification authors see what sort of
348 problems arise when the TZif format is changed.
349 .RE
350 .PP
351 When new versions of the TZif format have been defined, a
352 design goal has been that a reader can successfully use a TZif
353 file even if the file is of a later TZif version than what the
354 reader was designed for.
355 When complete compatibility was not achieved, an attempt was
356 made to limit glitches to rarely used timestamps and allow
357 simple partial workarounds in writers designed to generate
358 new-version data useful even for older-version readers.
359 This section attempts to document these compatibility issues and
360 workarounds, as well as to document other common bugs in
361 readers.
362 .PP
363 Interoperability problems with TZif include the following:
364 .RS 2
365 .IP \(bu 3
366 Some readers examine only version 1 data.
367 As a partial workaround, a writer can output as much version 1
368 data as possible.
369 However, a reader should ignore version 1 data, and should use
370 version 2+ data even if the reader's native timestamps have only
371 32 bits.
372 .IP \(bu
373 Some readers designed for version 2 might mishandle
374 timestamps after a version 3 or higher file's last transition, because
375 they cannot parse extensions to POSIX.1-2017 in the TZ-like string.
376 As a partial workaround, a writer can output more transitions
377 than necessary, so that only far-future timestamps are
378 mishandled by version 2 readers.
379 .IP \(bu
380 Some readers designed for version 2 do not support
381 permanent daylight saving time with transitions after 24:00
382 \(en e.g., a TZ string
383 .q "EST5EDT,0/0,J365/25"
384 denoting permanent Eastern Daylight Time
385 (\-04).
386 As a workaround, a writer can substitute standard time
387 for two time zones east, e.g.,
388 .q "XXX3EDT4,0/0,J365/23"
389 for a time zone with a never-used standard time (XXX, \-03)
390 and negative daylight saving time (EDT, \-04) all year.
391 Alternatively,
392 as a partial workaround a writer can substitute standard time
393 for the next time zone east \(en e.g.,
394 .q "AST4"
395 for permanent
396 Atlantic Standard Time (\-04).
397 .IP \(bu
398 Some readers designed for version 2 or 3, and that require strict
399 conformance to RFC 8536, reject version 4 files whose leap second
400 tables are truncated at the start or that end in expiration times.
401 .IP \(bu
402 Some readers ignore the footer, and instead predict future
403 timestamps from the time type of the last transition.
404 As a partial workaround, a writer can output more transitions
405 than necessary.
406 .IP \(bu
407 Some readers do not use time type 0 for timestamps before
408 the first transition, in that they infer a time type using a
409 heuristic that does not always select time type 0.
410 As a partial workaround, a writer can output a dummy (no-op)
411 first transition at an early time.
412 .IP \(bu
413 Some readers mishandle timestamps before the first
414 transition that has a timestamp not less than \-2**31.
415 Readers that support only 32-bit timestamps are likely to be
416 more prone to this problem, for example, when they process
417 64-bit transitions only some of which are representable in 32
418 bits.
419 As a partial workaround, a writer can output a dummy
420 transition at timestamp \-2**31.
421 .IP \(bu
422 Some readers mishandle a transition if its timestamp has
423 the minimum possible signed 64-bit value.
424 Timestamps less than \-2**59 are not recommended.
425 .IP \(bu
426 Some readers mishandle TZ strings that
427 contain
428 .q "<"
429 or
430 .q ">".
431 As a partial workaround, a writer can avoid using
432 .q "<"
433 or
434 .q ">"
435 for time zone abbreviations containing only alphabetic
436 characters.
437 .IP \(bu
438 Many readers mishandle time zone abbreviations that contain
439 non-ASCII characters.
440 These characters are not recommended.
441 .IP \(bu
442 Some readers may mishandle time zone abbreviations that
443 contain fewer than 3 or more than 6 characters, or that
444 contain ASCII characters other than alphanumerics,
445 .q "\*-",
446 and
447 .q "+".
448 These abbreviations are not recommended.
449 .IP \(bu
450 Some readers mishandle TZif files that specify
451 daylight-saving time UT offsets that are less than the UT
452 offsets for the corresponding standard time.
453 These readers do not support locations like Ireland, which
454 uses the equivalent of the TZ string
455 .q "IST\*-1GMT0,M10.5.0,M3.5.0/1",
456 observing standard time
457 (IST, +01) in summer and daylight saving time (GMT, +00) in winter.
458 As a partial workaround, a writer can output data for the
459 equivalent of the TZ string
460 .q "GMT0IST,M3.5.0/1,M10.5.0",
461 thus swapping standard and daylight saving time.
462 Although this workaround misidentifies which part of the year
463 uses daylight saving time, it records UT offsets and time zone
464 abbreviations correctly.
465 .IP \(bu
466 Some readers generate ambiguous timestamps for positive leap seconds
467 that occur when the UTC offset is not a multiple of 60 seconds.
468 For example, in a timezone with UTC offset +01:23:45 and with
469 a positive leap second 78796801 (1972-06-30 23:59:60 UTC), some readers will
470 map both 78796800 and 78796801 to 01:23:45 local time the next day
471 instead of mapping the latter to 01:23:46, and they will map 78796815 to
472 01:23:59 instead of to 01:23:60.
473 This has not yet been a practical problem, since no civil authority
474 has observed such UTC offsets since leap seconds were
475 introduced in 1972.
476 .RE
477 .PP
478 Some interoperability problems are reader bugs that
479 are listed here mostly as warnings to developers of readers.
480 .RS 2
481 .IP \(bu 3
482 Some readers do not support negative timestamps.
483 Developers of distributed applications should keep this
484 in mind if they need to deal with pre-1970 data.
485 .IP \(bu
486 Some readers mishandle timestamps before the first
487 transition that has a nonnegative timestamp.
488 Readers that do not support negative timestamps are likely to
489 be more prone to this problem.
490 .IP \(bu
491 Some readers mishandle time zone abbreviations like
492 .q "\*-08"
493 that contain
494 .q "+",
495 .q "\*-",
496 or digits.
497 .IP \(bu
498 Some readers mishandle UT offsets that are out of the
499 traditional range of \-12 through +12 hours, and so do not
500 support locations like Kiritimati that are outside this
501 range.
502 .IP \(bu
503 Some readers mishandle UT offsets in the range [\-3599, \-1]
504 seconds from UT, because they integer-divide the offset by
505 3600 to get 0 and then display the hour part as
506 .q "+00".
507 .IP \(bu
508 Some readers mishandle UT offsets that are not a multiple
509 of one hour, or of 15 minutes, or of 1 minute.
510 .RE
511 .SH SEE ALSO
512 .BR time (2),
513 .BR localtime (3),
514 .BR tzset (3),
515 .BR tzselect (8),
516 .BR zdump (8),
517 .BR zic (8).
518 .PP
519 Olson A, Eggert P, Murchison K. The Time Zone Information Format (TZif).
520 2019 Feb.
521 .UR https://\:datatracker.ietf.org/\:doc/\:html/\:rfc8536
522 Internet RFC 8536
523 .UE
524 .UR https://\:doi.org/\:10.17487/\:RFC8536
525 doi:10.17487/RFC8536
526 .UE .