Debian Codegraph @

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