Debian Codegraph @

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