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