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