tzcode2022g.tar.gz: tzfile.5.txt

"Fossies" - the Fresh Open Source Software Archive

Member "tzfile.5.txt" (25 Nov 2022, 20562 Bytes) of package /linux/misc/tzcode2022g.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "tzfile.5.txt":

2021e_vs_2022e.

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