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