Debian Codegraph @

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