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