idnits 2.17.1 draft-murchison-tzdist-tzif-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 18, 2018) is 2010 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 892 -- Looks like a reference, but probably isn't: '2' on line 894 -- Looks like a reference, but probably isn't: '3' on line 897 == Missing Reference: '-89999' is mentioned on line 385, but not defined -- Looks like a reference, but probably isn't: '93599' on line 385 -- Looks like a reference, but probably isn't: '4' on line 900 -- Looks like a reference, but probably isn't: '5' on line 903 -- Looks like a reference, but probably isn't: '6' on line 906 -- Looks like a reference, but probably isn't: '7' on line 908 -- Looks like a reference, but probably isn't: '8' on line 910 -- Looks like a reference, but probably isn't: '9' on line 912 -- Looks like a reference, but probably isn't: '10' on line 921 == Missing Reference: '-3599' is mentioned on line 1028, but not defined == Missing Reference: '-1' is mentioned on line 1028, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'POSIX' ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 13 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Independent Submission A. Olson 3 Internet-Draft 4 Intended status: Standards Track P. Eggert 5 Expires: April 21, 2019 UCLA 6 K. Murchison 7 FastMail 8 October 18, 2018 10 The Time Zone Information Format (TZif) 11 draft-murchison-tzdist-tzif-15 13 Abstract 15 This document defines the Time Zone Information Format (TZif) for 16 representing and exchanging time zone information, independent of any 17 particular service or protocol. Two MIME media types for this format 18 are also defined. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on April 21, 2019. 37 Copyright Notice 39 Copyright (c) 2018 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 53 3. The Time Zone Information Format (TZif) . . . . . . . . . . . 5 54 3.1. TZif Header . . . . . . . . . . . . . . . . . . . . . . . 6 55 3.2. TZif Data Block . . . . . . . . . . . . . . . . . . . . . 8 56 3.3. TZif Footer . . . . . . . . . . . . . . . . . . . . . . . 11 57 3.3.1. TZ String Extensions . . . . . . . . . . . . . . . . 12 58 4. Interoperability Considerations . . . . . . . . . . . . . . . 13 59 5. Use with the Time Zone Data Distribution Service . . . . . . 14 60 5.1. Truncating TZif Files . . . . . . . . . . . . . . . . . . 14 61 5.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 15 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 17 63 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 64 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 65 8.1. application/tzif . . . . . . . . . . . . . . . . . . . . 17 66 8.2. application/tzif-leap . . . . . . . . . . . . . . . . . . 18 67 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 68 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 69 10.1. Normative References . . . . . . . . . . . . . . . . . . 19 70 10.2. Informative References . . . . . . . . . . . . . . . . . 20 71 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 20 72 Appendix A. Common Interoperability Issues . . . . . . . . . . . 21 73 Appendix B. Change History (To be removed by RFC Editor before 74 publication) . . . . . . . . . . . . . . . . . . . . 23 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 77 1. Introduction 79 Time zone data typically consists of offsets from Universal Time 80 (UT), daylight saving transition rules, one or more local time 81 designations (acronyms or abbreviations), and optional leap second 82 adjustments. One such format for conveying this information is 83 iCalendar [RFC5545]. It is a text-based format used by calendaring 84 and scheduling systems. 86 This document defines the Time Zone Information Format (TZif). It is 87 a binary format used by most UNIX systems to calculate local time. 88 There is a wide variety of interoperable software [tz-link] capable 89 of generating and reading files in this format. 91 This specification does not define the source of the data assembled 92 into a TZif file. One such source is the IANA-hosted time zone 93 database [RFC6557]. 95 2. Conventions Used in This Document 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 99 "OPTIONAL" in this document are to be interpreted as described in BCP 100 14 [1] [RFC2119] [RFC8174] when, and only when, they appear in all 101 capitals, as shown here. 103 The following terms are used in this document (see "Sources for Time 104 Zone and Daylight Saving Time Data" [tz-link] for more-detailed 105 information about civil timekeeping data and practice): 107 Coordinated Universal Time (UTC): The basis for civil time since 108 1960. It is approximately equal to mean solar time at the prime 109 meridian (0 degrees longitude). 111 Daylight Saving Time (DST): The time according to a location's law 112 or practice, when adjusted as necessary from standard time. The 113 adjustment may be positive or negative, and the amount of 114 adjustment may vary depending on the date and time; the TZif 115 format even allows the adjustment to be zero, although this is not 116 common practice. 118 International Atomic Time (TAI): The time standard based on atomic 119 clocks since 1972. It is equal to UTC except without leap second 120 adjustments. 122 Leap Second Correction (LEAPCORR): The value of TAI - UTC - 10 for 123 timestamps after the first leap second, and zero for timestamps 124 before that. The expression "TAI - UTC - 10" comes from the fact 125 that TAI - UTC was defined to be 10 just prior to the first leap 126 second in 1972, so clocks with leap seconds have a zero LEAPCORR 127 before the first leap second. 129 Local Time: Civil time for a particular location. Its offset from 130 Universal Time can depend on the date and time of day. 132 POSIX Epoch: 1970-01-01 00:00:00 UTC, the basis for absolute 133 timestamps in this document. 135 Standard Time: The time according to a location's law or practice, 136 unadjusted for Daylight Saving Time. 138 Time Change: A change to civil timekeeping practice. It occurs when 139 one or more of the following happen simultaneously: 141 1. a change in UT offset 142 2. a change in whether daylight saving time is in effect 144 3. a change in time zone abbreviation 146 4. a leap second (i.e., a change in LEAPCORR) 148 Time Zone Data: The Time Zone Data Distribution Service (TZDIST) 149 [RFC7808] defines "Time zone data" as "data that defines a single 150 time zone, including an identifier, UTC offset values, DST rules, 151 and other information such as time zone abbreviations." The 152 interchange format defined in this document is one such form of 153 time zone data. 155 Transition Time: The moment of occurrence of a time change that is 156 not a leap second. It is identified with a signed integer count 157 of Unix Leap Time seconds since the POSIX Epoch. 159 Universal Time (UT): The basis of civil time. This is the principal 160 form of the mean solar time at the prime meridian (0 degrees 161 longitude) for timestamps before UTC was introduced in 1960, and 162 is UTC for timestamps thereafter. Although UT is sometimes called 163 "UTC" or "GMT" in other sources, this specification uses the term 164 "UT" to avoid confusion with UTC or with GMT. 166 UNIX Time: The time as returned by the C time() function (see 167 Section 3 of the "System Interfaces" Volume [2] of [POSIX]). This 168 is an integer number of seconds since the POSIX Epoch, not 169 counting leap seconds. As an extension to POSIX, negative values 170 represent times before the POSIX Epoch, using UT. 172 UNIX Leap Time: UNIX time plus all preceding leap second 173 corrections. For example, if the first leap second record in a 174 TZif file occurs at 1972-06-30 23:59:60 UTC, the UNIX leap time 175 for the timestamp 1972-07-01 00:00:00 UTC would be 78796801, one 176 greater than the UNIX time for the same timestamp. Similarly, if 177 the second leap second record occurs at 1972-12-31 23:59:60 UTC it 178 accounts for the first leap second, so the UNIX leap time of 179 1972-12-31 23:59:60 UTC would be 94694401 and the Unix leap time 180 of 1973-01-01 00:00:00 UTC would be 94694402. If a TZif file 181 specifies no leap second records, UNIX leap time is equal to UNIX 182 time. 184 Wall Time: Another name for local time; short for "wall clock time". 186 3. The Time Zone Information Format (TZif) 188 The time zone information format begins with a fixed 44-octet version 189 1 header (Section 3.1) containing a field that specifies the version 190 of the file's format. Readers designed for version N can read 191 version N+1 files without too much trouble; data specific to version 192 N+1 either typically appears after version N data so that earlier- 193 version readers can easily ignore later-version data they are not 194 designed for, or it appears as a minor extension to version N that 195 version N readers are likely to tolerate well. 197 The version 1 header is followed by a variable-length version 1 data 198 block (Section 3.2) containing four-octet (32-bit) transition times 199 and leap second occurrences. These 32-bit values are limited to 200 representing time changes from 1901-12-13 20:45:52 through 2038-01-19 201 03:14:07 UT, and the version 1 header and data block are present only 202 for backward compatibility with obsolescent readers as discussed in 203 Common Interoperability Issues (Appendix A). 205 Version 1 files terminate after the version 1 data block. Version 2 206 and 3 files extend the format by appending a second 44-octet version 207 2+ header, a variable-length version 2+ data block containing eight- 208 octet (64-bit) transition times and leap second occurrences, and a 209 variable length footer (Section 3.3). These 64-bit values can 210 represent times approximately 292 billion years into the past or 211 future. 213 NOTE: All multi-octet integer values MUST be stored in network octet 214 order format (high-order octet first, otherwise known as big-endian), 215 with all bits significant. Signed integer values MUST be represented 216 using two's complement. 218 A TZif file is structured as follows: 220 Version 1 Versions 2 & 3 221 +-------------+ +-------------+ 222 | Version 1 | | Version 1 | 223 | Header | | Header | 224 +-------------+ +-------------+ 225 | Version 1 | | Version 1 | 226 | Data Block | | Data Block | 227 +-------------+ +-------------+ 228 | Version 2+ | 229 | Header | 230 +-------------+ 231 | Version 2+ | 232 | Data Block | 233 +-------------+ 234 | Footer | 235 +-------------+ 237 General Format of TZif Files 239 3.1. TZif Header 241 A TZif header is structured as follows (the lengths of multi-octet 242 fields are shown in parenthesis): 244 +---------------+---+ 245 | magic (4) |ver| 246 +---------------+---+---------------------------------------+ 247 | [unused - reserved for future use] (15) | 248 +---------------+---------------+---------------+-----------+ 249 | isutcnt (4) | isstdcnt (4) | leapcnt (4) | 250 +---------------+---------------+---------------+ 251 | timecnt (4) | typecnt (4) | charcnt (4) | 252 +---------------+---------------+---------------+ 254 TZif Header 256 The fields of the header are defined as follows: 258 magic: The four-octet ASCII [RFC0020] sequence "TZif" (0x54 0x5A 259 0x69 0x66) which identifies the file as utilizing the Time Zone 260 Information Format. 262 ver(sion): An octet identifying the version of the file's format. 263 The value MUST be one of the following: 265 NUL (0x00) Version 1 - The file contains only the version 1 266 header and data block. Version 1 files MUST NOT contain a 267 version 2+ header, data block, or footer. 269 '2' (0x32) Version 2 - The file MUST contain the version 1 header 270 and data block, a version 2+ header and data block, and a 271 footer. The TZ string in the footer (Section 3.3), if 272 nonempty, MUST strictly adhere to the requirements for the TZ 273 environment variable as defined in Section 8.3 of the "Base 274 Definitions" Volume [3] of [POSIX], and MUST encode the POSIX 275 portable character set as ASCII. 277 '3' (0x33) Version 3 - The file MUST contain the version 1 header 278 and data block, a version 2+ header and data block, and a 279 footer. The TZ string in the footer (Section 3.3), if 280 nonempty, MUST conform to POSIX requirements with ASCII 281 encoding, except that it MAY use the TZ string extensions 282 described below (Section 3.3.1). 284 isutcnt: A four-octet unsigned integer specifying the number of UT/ 285 local indicators contained in the data block - MUST either be zero 286 or equal to 'typecnt'. 288 isstdcnt: A four-octet unsigned integer specifying the number of 289 standard/wall indicators contained in the data block - MUST either 290 be zero or equal to 'typecnt'. 292 leapcnt: A four-octet unsigned integer specifying the number of leap 293 second records contained in the data block. 295 timecnt: A four-octet unsigned integer specifying the number of 296 transition times contained in the data block. 298 typecnt: A four-octet unsigned integer specifying the number of 299 local time type records contained in the data block - MUST NOT be 300 zero. (Although local time type records convey no useful 301 information in files that have nonempty TZ strings but no 302 transitions, at least one such record is nevertheless required 303 because many TZif readers reject files that have zero time types.) 305 charcnt: A four-octet unsigned integer specifying the total number 306 of octets used by the set of time zone designations contained in 307 the data block - MUST NOT be zero. The count includes the 308 trailing NUL (0x00) octet at the end of the last time zone 309 designation. 311 Although the version 1 and 2+ headers have the same format with the 312 same magic number and version fields, their count fields may differ 313 because the version 1 data can be a subset of the version 2+ data. 315 3.2. TZif Data Block 317 A TZif data block consists of seven variable-length elements, each of 318 which is series of zero or more items. The number of items in each 319 series is determined by the corresponding count field in the header. 320 The total length of each element is calculated by multiplying the 321 number of items by the size of each item. Therefore, implementations 322 that do not wish to parse or use the version 1 data block can 323 calculate its total length and skip directly to the header of the 324 verrsion 2+ data block. 326 In the version 1 data block, time values are 32-bit (TIME_SIZE = 4 327 octets). In the version 2+ data block, present only in version 2 and 328 3 files, time values are 64-bit (TIME_SIZE = 8 octets). 330 The data block is structured as follows (the lengths of multi-octet 331 fields are shown in parenthesis): 333 +---------------------------------------------------------+ 334 | transition times (timecnt x TIME_SIZE) | 335 +---------------------------------------------------------+ 336 | transition types (timecnt) | 337 +---------------------------------------------------------+ 338 | local time type records (typecnt x 6) | 339 +---------------------------------------------------------+ 340 | time zone designations (charcnt) | 341 +---------------------------------------------------------+ 342 | leap second records (leapcnt x (TIME_SIZE + 4)) | 343 +---------------------------------------------------------+ 344 | standard/wall indicators (isstdcnt) | 345 +---------------------------------------------------------+ 346 | UT/local indicators (isutcnt) | 347 +---------------------------------------------------------+ 349 TZif Data Block 351 The elements of the data block are defined as follows: 353 transition times: A series of four- or eight-octet UNIX leap time 354 values sorted in strictly ascending order. Each value is used as 355 a transition time at which the rules for computing local time may 356 change. The number of time values is specified by the 'timecnt' 357 field in the header. Each time value SHOULD be at least -2**59. 358 (-2**59 is the greatest negated power of 2 that predates the Big 359 Bang, and avoiding earlier timestamps works around known TZif 360 reader bugs relating to outlandlishly negative timestamps.) 362 transition types: A series of one-octet unsigned integers specifying 363 the type of local time of the corresponding transition time. 364 These values serve as indices into the array of local time type 365 records. The number of type indices is specified by the 'timecnt' 366 field in the header. Each type index MUST be in the range [0, 367 'typecnt' -1]. 369 local time type records: A series of six-octet records specifying a 370 local time type. The number of records is specified by the 371 'typecnt' field in the header. Each record has the following 372 format (the lengths of multi-octet fields are shown in 373 parenthesis): 375 +---------------+-+-+---+ 376 | utoff (4) |dst|idx| 377 +---------------+---+---+ 379 utoff: A four-octet signed integer specifying the number of 380 seconds to be added to UT in order to determine local time. 381 The value MUST NOT be -2**31, and SHOULD be in the range 382 [-89999, 93599] (i.e., its value SHOULD be more than -25 hours 383 and less than 26 hours). (Avoiding -2**31 allows 32-bit 384 clients to negate the value without overflow. Restricting it 385 to [-89999, 93599] allows easy support by implementations that 386 already support the the POSIX-required range [-24:59:59, 387 25:59:59].) 389 (is)dst: A one-octet value indicating whether local time should 390 be considered Daylight Savings Time (DST). The value MUST be 0 391 or 1. A value of one (1) indicates that this type time is DST. 392 A value of zero (0) indicates that this time type is standard 393 time. 395 (desig)idx: A one-octet unsigned integer specifying an index into 396 the series of time zone designation octets, thereby selecting a 397 particular designation string. Each index MUST be in the range 398 [0, 'charcnt' -1], and designates the NUL-terminated string of 399 octets starting at position 'idx' in the time zone 400 designations. (This string MAY be empty.) A NUL octet MUST 401 exist in the time zone designations at or after position 'idx'. 403 time zone designations: A series of octets constituting an array of 404 NUL-terminated (0x00) time zone designation strings. The total 405 number of octets is specified by the 'charcnt' field in the 406 header. Note that two designations MAY overlap if one is a suffix 407 of the other. The character encoding of time zone designation 408 strings is not specified; however, see Section 4 of this document. 410 leap second records: A series of eight- or twelve-octet records 411 specifying the corrections that need to be applied to UTC in order 412 to determine TAI. The records are sorted by the occurrence time 413 in strictly ascending order. The number of records is specified 414 by the 'leapcnt' field in the header. Each record has one of the 415 following structures (the lengths of multi-octet fields are shown 416 in parenthesis): 418 Version 1 Data Block: 420 +---------------+---------------+ 421 | occur (4) | corr (4) | 422 +---------------+---------------+ 424 version 2+ Data Block: 426 +---------------+---------------+---------------+ 427 | occur (8) | corr (4) | 428 +---------------+---------------+---------------+ 430 occur(rence): A four- or eight-octet UNIX leap time value 431 specifying the time at which a leap second correction occurs. 432 The first value, if present, MUST be nonnegative, and each 433 later value MUST be at least 2419199 greater than the previous 434 value. (This is 28 days' worth of seconds, minus a potential 435 negative leap second.) 437 corr(ection): A four-octet signed integer specifying the value of 438 LEAPCORR on or after the occurrence. The correction value in 439 the first leap second record, if present, MUST be either one 440 (1) or minus one (-1). The correction values in adjacent leap 441 second records MUST differ by exactly one (1). The value of 442 LEAPCORR is zero for timestamps that occur before the 443 occurrence time in the first leap second record (or for all 444 timestamps if there are no leap second records). 446 standard/wall indicators: A series of one-octet values indicating 447 whether the transition times associated with local time types were 448 specified as standard time or wall clock time. Each value MUST be 449 0 or 1. A value of one (1) indicates standard time, and MUST be 450 set to one (1) if the corresponding UT/local indicator is set to 451 one (1). A value of zero (0) indicates wall time. The number of 452 values is specified by the 'isstdcnt' field in the header. If 453 'isstdcnt' is zero (0), all transition times associated with local 454 time types are assumed to be specified as wall time. 456 UT/local indicators: A series of one-octet values indicating whether 457 the transition times associated with local time types were 458 specified as UT or local time. Each value MUST be 0 or 1. A 459 value of one (1) indicates UT, and the corresponding standard/wall 460 indicator MUST also be set to one (1). A value of zero (0) 461 indicates local time. The number of values is specified by the 462 'isutcnt' field in the header. If 'isutcnt' is zero (0), all 463 transition times associated with local time types are assumed to 464 be specified as local time. 466 The type corresponding to a transition time specifies local time for 467 timestamps starting at the given transition time and continuing up 468 to, but not including, the next transition time. Local time for 469 timestamps before the first transition is specified by the first time 470 type (time type 0). Local time for timestamps on or after the last 471 transition is specified by the TZ string in the footer (Section 3.3) 472 if present and nonempty, and is unspecified otherwise. If there are 473 no transitions, local time for all timestamps is specified by the TZ 474 string in the footer if present and nonempty, and is specified by 475 time type 0 otherwise. 477 A given pair of standard/wall and UT/local indicators is used to 478 designate whether the corresponding transition time was specified as 479 UT, standard time, or wall clock time. Note that there are only 480 three combinations of the two indicators given that the standard/wall 481 value MUST be one (1) if the UT/local value is one (1). This 482 information can be useful if the transition times in a TZif file need 483 to be transformed into transitions appropriate for another time zone 484 (e.g. when calculating transition times for a simple POSIX TZ string 485 such as "AKST9AKDT"). 487 In order to eliminate unused space in a TZif file, every nonzero 488 local time type index SHOULD appear at least once in the transition 489 type array. Likewise, every octet in the time zone designations 490 array SHOULD be used by at least one time type record. 492 3.3. TZif Footer 494 The TZif footer is structured as follows (the lengths of multi-octet 495 fields are shown in parenthesis): 497 +---+--------------------+---+ 498 | NL| TZ string (0...) |NL | 499 +---+--------------------+---+ 501 TZif Footer 503 The elements of the footer are defined as follows: 505 NL: An ASCII new line character (0x0A). 507 TZ string: A rule for computing local time changes after the last 508 transition time stored in the version 2+ data block. The string 509 is either empty or uses the expanded format of the "TZ" 510 environment variable as defined in Section 8.3 of the "Base 511 Definitions" Volume [4] of [POSIX] with ASCII encoding, possibly 512 utilizing extensions described below (Section 3.3.1) in version 3 513 files. If the string is empty, the corresponding information is 514 not available. If the string is nonempty and one or more 515 transitions appear in the version 2+ data, the string MUST be 516 consistent with the last version 2+ transition - i.e., evaluating 517 the TZ string at the time of the last transition should yield the 518 same time type as the time type specified in the last transition. 519 The string MUST NOT contain NUL octets or be NUL-terminated, and 520 SHOULD NOT begin with the ':' (colon) character. 522 The TZif footer is present only in Version 2 and 3 files, as the 523 obsolescent Version 1 format was designed before the need for a 524 footer was apparent. 526 3.3.1. TZ String Extensions 528 The TZ string in a Version 3 TZif file MAY use the following 529 extensions to POSIX TZ strings. These extensions are described using 530 the terminology of Section 8.3 of the "Base Definitions" Volume [5] 531 of [POSIX]. 533 o The hours part of the transition times may be signed and range 534 from -167 through 167 (-167 <= hh <= 167) instead of the POSIX- 535 required unsigned values from 0 through 24. 537 Example: <-03>3<-02>,M3.5.0/-2,M10.5.0/-1 538 This represents a time zone that observes daylight saving time 539 from 22:00 on the day before March's last Sunday until 23:00 on 540 the day before October's last Sunday. Standard time is 3 hours 541 west of UT and is abbreviated "-03"; daylight saving time is 2 542 hours west of UT and is abbreviated "-02". 544 o DST is considered to be in effect all year if it starts January 1 545 at 00:00 and ends December 31 at 24:00 plus the difference between 546 daylight saving and standard time, leaving no room for standard 547 time in the calendar. 549 Example: EST5EDT,0/0,J365/25 550 This represents a time zone that observes daylight saving time 551 all year. It is 4 hours west of UT and is abbreviated "EDT". 553 4. Interoperability Considerations 555 These recommended practices should be followed in order to assure 556 interoperability of TZif applications. 558 o Version 1 files are considered a legacy format and SHOULD NOT be 559 generated, as they do not support transition times after the year 560 2038. 562 o Implementations that only understand Version 1 MUST ignore any 563 data that extends beyond the calculated end of the version 1 data 564 block. 566 o Implementations SHOULD generate a version 3 file if TZ string 567 extensions are necessary to accurately model transition times. 568 Otherwise, version 2 files SHOULD be generated. 570 o The sequence of time changes defined by the version 1 header and 571 data block SHOULD be a contiguous subsequence of the time changes 572 defined by the version 2+ header and data block, and by the 573 footer. This guideline helps obsolescent version 1 readers agree 574 with current readers about timestamps within the contiguous 575 subsequence. It also lets writers not supporting obsolescent 576 readers use a 'timecnt' of zero in the version 1 data block to 577 save space. 579 o Time zone designations SHOULD consist of at least three (3) and no 580 more than six (6) ASCII characters from the set of alphanumerics, 581 '-', and '+'. This is for compatibility with POSIX requirements 582 for time zone abbreviations. 584 o When reading a version 2 or 3 file, implementations SHOULD ignore 585 the version 1 header and data block except for the purpose of 586 skipping over them. 588 o Implementations SHOULD calculate the total lengths of the headers 589 and data blocks and check that they all fit within the actual file 590 size, as part of a validity check for the file. 592 o When a TZif file is used in a MIME message entity it SHOULD be 593 indicated by one of the following media types: 595 * "application/tzif-leap" (Section 8.2) to indicate that leap 596 second records are included in the TZif data as necessary (none 597 are necessary if the file is truncated to a range that precedes 598 the first leap second). 600 * "application/tzif" (Section 8.1) to indicate that leap second 601 records are not included in the TZif data; 'leapcnt' in the 602 header(s) MUST be zero (0). 604 o Common interoperability issues and possible workarounds are 605 described in Appendix A. 607 5. Use with the Time Zone Data Distribution Service 609 The Time Zone Data Distribution Service (TZDIST) [RFC7808] is a 610 service that allows reliable, secure, and fast delivery of time zone 611 data and leap second rules to client systems such as calendaring and 612 scheduling applications or operating systems. 614 A TZDIST service MAY supply time zone data to clients in the Time 615 Zone Information Format. Such a service MUST indicate that it 616 supports this format by including the MIME media type "application/ 617 tzif" (Section 8.1) in its "capabilities" response (see Section 5.1 618 of [RFC7808]). A TZDIST service MAY also include the MIME media type 619 "application/tzif-leap" (Section 8.2) in its "capabilities" response 620 if it is able to generate TZif files containing leap second records. 621 A TZDIST service MUST NOT advertise the "application/tzif-leap" MIME 622 media type without also advertising "application/tzif". 624 TZDIST clients MUST use the HTTP "Accept" [RFC7231] header field to 625 indicate their preference to receive data in the "application/tzif" 626 and/or "application/tzif-leap" formats. 628 5.1. Truncating TZif Files 630 As described in Section 3.9 of [RFC7808], a TZDIST service MAY 631 truncate time zone transition data. A truncated TZif file is valid 632 from its first and up to, but not including, its last version 2+ 633 transition time, if present. 635 When truncating the start of a TZif file, the service MUST supply in 636 the version 2+ data a first transition time that is the start point 637 of the truncation range. As with untruncated TZif files, time type 0 638 indicates local time immediately before the start point, and the time 639 type of the first transition indicates local time thereafter. 641 When truncating the end of a TZif file, the service MUST supply in 642 the version 2+ data a last transition time that is the end point of 643 the truncation range, and MUST supply an empty TZ string. As with 644 untruncated TZif files with empty TZ strings, a truncated TZif file 645 does not indicate local time after the last transition. 647 All represented information that falls inside the truncation range 648 MUST be the same as that represented by a corresponding untruncated 649 TZif file. 651 TZDIST clients SHOULD NOT use a truncated TZif file (as described 652 above) to interpret timestamps outside the truncation time range. 654 5.2. Example 656 In this example, the client checks the server for the available 657 formats and then requests that the time zone with a specific time 658 zone identifier be returned in Time Zone Information Format. 660 Note that this example presumes that the time zone context path has 661 been discovered (see [RFC7808] Section 4.2.1) to be "/tzdist". 663 >> Request << 665 GET /tzdist/capabilities HTTP/1.1 666 Host: tz.example.com 668 >> Response << 670 HTTP/1.1 200 OK 671 Date: Fri, 01 Jun 2018 14:52:23 GMT 672 Content-Type: application/json; charset="utf-8" 673 Content-Length: xxxx 675 { 676 "version": 1, 678 "info": { 679 "primary-source": "IANA:2018e", 680 "formats": [ 681 "text/calendar", 682 "application/tzif", 683 "application/tzif-leap" 684 ], 685 ... 686 }, 687 ... 688 } 690 >> Request << 692 GET /tzdist/zones/America%2FNew_York HTTP/1.1 693 Host: tz.example.com 694 Accept: application/tzif 696 >> Response << 698 HTTP/1.1 200 OK 699 Date: Fri, 01 Jun 2018 14:52:24 GMT 700 Content-Type: application/tzif 701 Content-Length: xxxx 702 ETag: "123456789-000-111" 704 TZif2...[binary data without leap second records]... 705 EST5EDT,M3.2.0,M11.1.0 707 6. Security Considerations 709 The Time Zone Information Format contains no executable code and the 710 format does not define any extensible areas that could be used to 711 store such code. 713 TZif contains counted arrays of data elements. All counts should be 714 checked when processing TZif objects to guard against references past 715 the end of the object. 717 TZif provides no confidentiality or integrity protection. Time zone 718 information is normally public and does not call for confidentiality 719 protection. Since time zone information is used in many critical 720 applications, integrity protection may be required, and must be 721 provided externally. 723 7. Privacy Considerations 725 The Time Zone Information Format contains publicly available data and 726 the format does not define any extensible areas that could be used to 727 store private data. 729 8. IANA Considerations 731 This document defines two MIME [RFC6838] media types for the exchange 732 of data utilizing the Time Zone Information Format. 734 8.1. application/tzif 736 Type name: application 738 Subtype name: tzif 740 Required parameters: none 742 Optional parameters: none 744 Encoding considerations: binary 746 Security considerations: See Section 6 of this document. 748 Interoperability considerations: See Section 4 of this document. 750 Published specification: This specification. 752 Applications that use this media type: This media type is designed 753 for widespread use by applications that need to use or exchange 754 time zone information, such as the Time Zone Information Compiler 755 (zic) [6] and the GNU C Library [7]. The Time Zone Distribution 756 Service [RFC7808] can directly use this media type. 758 Fragment identifier considerations: N/A 760 Additional information: 762 Magic number(s): The first 4 octets are 0x54, 0x5A, 0x69, 0x66 764 File extensions(s): N/A 766 Macintosh file type code(s): N/A 768 Person & email address to contact for further 769 information: 770 Time Zone Database mailing list 772 Intended usage: COMMON 774 Restrictions on usage: N/A 776 Author: See the "Author's Address" section of this document. 778 Change controller: IETF 780 8.2. application/tzif-leap 782 Type name: application 784 Subtype name: tzif-leap 786 Required parameters: none 788 Optional parameters: none 790 Encoding considerations: binary 792 Security considerations: See Section 6 of this document. 794 Interoperability considerations: See Section 4 of this document. 796 Published specification: This specification. 798 Applications that use this media type: This media type is designed 799 for widespread use by applications that need to use or exchange 800 time zone information, such as the Time Zone Information Compiler 801 (zic) [8] and the GNU C Library [9]. The Time Zone Distribution 802 Service [RFC7808] can directly use this media type. 804 Fragment identifier considerations: N/A 806 Additional information: 808 Magic number(s): The first 4 octets are 0x54, 0x5A, 0x69, 0x66 810 File extensions(s): N/A 812 Macintosh file type code(s): N/A 814 Person & email address to contact for further 815 information: 816 Time Zone Database mailing list 818 Intended usage: COMMON 820 Restrictions on usage: N/A 822 Author: See the "Author's Address" section of this document. 824 Change controller: IETF 826 9. Acknowledgments 828 The authors would like to thank the following individuals for 829 contributing their ideas and support for writing this specification: 830 Michael Douglass, Ned Freed, Guy Harris, Eliot Lear, and Alexey 831 Melnikov. 833 10. References 835 10.1. Normative References 837 [POSIX] IEEE, "Standard for Information Technology--Portable 838 Operating System Interface (POSIX(R)) Base Specifications, 839 Issue 7", IEEE 1003.1-2017, 840 DOI 10.1109/IEEESTD.2018.8277153, January 2018, 841 . 843 This standard is also 844 published by ieeexplore.ieee.org. 847 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 848 RFC 20, DOI 10.17487/RFC0020, October 1969, 849 . 851 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 852 Requirement Levels", BCP 14, RFC 2119, 853 DOI 10.17487/RFC2119, March 1997, 854 . 856 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 857 Specifications and Registration Procedures", BCP 13, 858 RFC 6838, DOI 10.17487/RFC6838, January 2013, 859 . 861 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 862 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 863 DOI 10.17487/RFC7231, June 2014, 864 . 866 [RFC7808] Douglass, M. and C. Daboo, "Time Zone Data Distribution 867 Service", RFC 7808, DOI 10.17487/RFC7808, March 2016, 868 . 870 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 871 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 872 May 2017, . 874 10.2. Informative References 876 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 877 Scheduling Core Object Specification (iCalendar)", 878 RFC 5545, DOI 10.17487/RFC5545, September 2009, 879 . 881 [RFC6557] Lear, E. and P. Eggert, "Procedures for Maintaining the 882 Time Zone Database", BCP 175, RFC 6557, 883 DOI 10.17487/RFC6557, February 2012, 884 . 886 [tz-link] Eggert, P. and A. Olson, "Sources for Time Zone and 887 Daylight Saving Time Data", 2018, 888 . 890 10.3. URIs 892 [1] https://tools.ietf.org/html/bcp14 894 [2] http://pubs.opengroup.org/onlinepubs/9699919799/functions/ 895 time.html 897 [3] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 898 V1_chap08.html#tag_08_03 900 [4] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 901 V1_chap08.html#tag_08_03 903 [5] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 904 V1_chap08.html#tag_08_03 906 [6] http://man7.org/linux/man-pages/man8/zic.8.html 908 [7] https://www.gnu.org/software/libc/ 910 [8] http://man7.org/linux/man-pages/man8/zic.8.html 912 [9] https://www.gnu.org/software/libc/ 914 [10] https://github.com/eggert/tz/commits/master/tzfile.5 916 Appendix A. Common Interoperability Issues 918 This section documents common problems in implementing this 919 specification. Most of these are problems in generating TZif files 920 for use by readers conforming to predecessors of this specification 921 [10]. The goals of this section are: 923 1. to help TZif writers output files that avoid common pitfalls in 924 older or buggy TZif readers, 926 2. to help TZif readers avoid common pitfalls when reading files 927 generated by future TZif writers, and 929 3. to help any future specification authors see what sort of 930 problems arise when the TZif format is changed. 932 When new versions of the TZif format have been defined, a design goal 933 has been that a reader can successfully use a TZif file even if the 934 file is of a later TZif version than what the reader was designed 935 for. When complete compatibility was not achieved, an attempt was 936 made to limit glitches to rarely-used timestamps, and to allow simple 937 partial workarounds in writers designed to generate new-version data 938 useful even for older-version readers. This section attempts to 939 document these compatibility issues and workarounds, as well as to 940 document other common bugs in readers. 942 Interoperability problems with TZif include the following: 944 o Some readers examine only version 1 data. As a partial 945 workaround, a writer can output as much version 1 data as 946 possible. However, a reader should ignore version 1 data, and 947 should use version 2+ data even if the reader's native timestamps 948 have only 32 bits. 950 o Some readers designed for version 2 might mishandle timestamps 951 after a version 3 file's last transition, because they cannot 952 parse extensions to POSIX in the TZ-like string. As a partial 953 workaround, a writer can output more transitions than necessary, 954 so that only far-future timestamps are mishandled by version 2 955 readers. 957 o Some readers designed for version 2 do not support permanent 958 daylight saving time, e.g., a TZ string "EST5EDT,0/0,J365/25" 959 denoting permanent Eastern Daylight Time (-04). As a partial 960 workaround, a writer can substitute standard time for the next 961 time zone east, e.g., "AST4" for permanent Atlantic Standard Time 962 (-04). 964 o Some readers ignore the footer, and instead predict future 965 timestamps from the time type of the last transition. As a 966 partial workaround, a writer can output more transitions than 967 necessary. 969 o Some readers do not use time type 0 for timestamps before the 970 first transition, in that they infer a time type using a heuristic 971 that does not always select time type 0. As a partial workaround, 972 a writer can output a dummy (no-op) first transition at an early 973 time. 975 o Some readers mishandle timestamps before the first transition that 976 has a timestamp not less than -2**31. Readers that support only 977 32-bit timestamps are likely to be more prone to this problem, for 978 example, when they process 64-bit transitions only some of which 979 are representable in 32 bits. As a partial workaround, a writer 980 can output a dummy transition at timestamp -2**31. 982 o Some readers mishandle a transition if its timestamp has the 983 minimum possible signed 64-bit value. Timestamps less than -2**59 984 are not recommended. 986 o Some readers mishandle POSIX-style TZ strings that contain '<' or 987 '>'. As a partial workaround, a writer can avoid using '<' or '>' 988 for time zone abbreviations containing only alphabetic characters. 990 o Many readers mishandle time zone abbreviations that contain non- 991 ASCII characters. These characters are not recommended. 993 o Some readers may mishandle time zone abbreviations that contain 994 fewer than 3 or more than 6 characters, or that contain ASCII 995 characters other than alphanumerics, '-', and '+'. These 996 abbreviations are not recommended. 998 o Some readers mishandle TZif files that specify daylight-saving 999 time UT offsets that are less than the UT offsets for the 1000 corresponding standard time. These readers do not support 1001 locations like Ireland, which uses the equivalent of the POSIX TZ 1002 string "IST-1GMT0,M10.5.0,M3.5.0/1", observing standard time (IST, 1003 +01) in summer and daylight saving time (GMT, +00) in winter. As 1004 a partial workaround, a writer can output data for the equivalent 1005 of the POSIX TZ string "GMT0IST,M3.5.0/1,M10.5.0", thus swapping 1006 standard and daylight saving time. Although this workaround 1007 misidentifies which part of the year uses daylight saving time, it 1008 records UT offsets and time zone abbreviations correctly. 1010 Some interoperability problems are reader bugs that are listed here 1011 mostly as warnings to developers of readers. 1013 o Some readers do not support negative timestamps. Developers of 1014 distributed applications should keep this in mind if they need to 1015 deal with pre-1970 data. 1017 o Some readers mishandle timestamps before the first transition that 1018 has a nonnegative timestamp. Readers that do not support negative 1019 timestamps are likely to be more prone to this problem. 1021 o Some readers mishandle time zone abbreviations like "-08" that 1022 contain '+', '-', or digits. 1024 o Some readers mishandle UT offsets that are out of the traditional 1025 range of -12 through +12 hours, and so do not support locations 1026 like Kiritimati that are outside this range. 1028 o Some readers mishandle UT offsets in the range [-3599, -1] seconds 1029 from UT, because they integer-divide the offset by 3600 to get 0 1030 and then display the hour part as "+00". 1032 o Some readers mishandle UT offsets that are not a multiple of one 1033 hour, or of 15 minutes, or of 1 minute. 1035 Appendix B. Change History (To be removed by RFC Editor before 1036 publication) 1038 Changes since -14: 1040 o Addressed last call comments from Tom Petch. 1042 o Addressed last call comments from Qin Wu. 1044 o Addressed last call comments from Dale Worley. 1046 Changes since -13: 1048 o Added text to Privacy Considerations. 1050 Changes since -12: 1052 o Added reference to RFC0020. 1054 o Fully fleshed out application/tzif-leap declaration rather than 1055 referencing application/tzif. 1057 o Added definition for "Leap Second Correction". 1059 o Added external references directly to the relevant sections of 1060 POSIX. 1062 Changes since -11: 1064 o Removed text requiring leapcnt by non-zero for application/tzif- 1065 leap files. 1067 Changes since -10: 1069 o Removed text mandating all TZDIST features be supported. 1071 o Minor editorial changes. 1073 Changes since -09: 1075 o Removed "Update 7808" from header as this spec doesn't introduce 1076 new TZDIST functionality. 1078 o Added text regarding truncation of TZif via TZDIST. 1080 o Expanded what this spec DOESN'T define. 1082 o Added reasons for some of the recommended practices. 1084 o Added common interoperability issues appendix. 1086 o Minor editorial changes. 1088 Changes since -08: 1090 o Clarifying text regarding MIME types. 1092 o Consolidated/referenced duplicate security and interoperability 1093 text. 1095 o Switched to 'octets' instead of 'characters' when describing time 1096 zone designations. 1098 o Minor editorial changes. 1100 Changes since -07: 1102 o Clarifying text regarding TZ string. 1104 o Added "application/tzif-leap" MIME media type. 1106 o New reference for zic(8) man page. 1108 o Minor editorial changes. 1110 Changes since -06: 1112 o Added definition of UNIX Leap Time and used it to describe 1113 transition times and leap second occurrences. 1115 o Moved TZif generation recommendations into discussion of version 1116 field. 1118 o Repeated TZif generation recommendations in TZDIST section. 1120 o Rewrote part of the TZ string text. 1122 o Minor editorial changes. 1124 Changes since -05: 1126 o Clarify TAI, leap seconds, some descriptions, and some field 1127 values/ranges with text from Paul Eggert. 1129 o Refined MIME declaration based on feedback from Ned Freed. 1131 Changes since -04: 1133 o Edited text discussing timestamps before first and after last 1134 transition. 1136 o Specified legal range of time type indices and time zone 1137 designation indices. 1139 o Notes that corrections in adjacent leap second records must differ 1140 by one. 1142 o Added recommendations to eliminate unused space. 1144 o Minor editorial changes. 1146 Changes since -03: 1148 o Removed definition of GMT. 1150 o Updated definitions of UTC, TAI, and UT 1152 o Switched to using UT rather than UTC. 1154 o Added more text about the use of standard/wall and UT/local 1155 indicators. 1157 o Added Acknowledgments. 1159 o Minor editorial changes. 1161 Changes since -02: 1163 o Updated definitions of Standard Time and DST. 1165 o Added definitions of GMT and UT. 1167 o Added a definition of Time Zone Data from RFC7808. 1169 o Removed sentence stating that TZDB is accurate. 1171 o Added more text for standard/wall and UTC/local indicators and 1172 counts. 1174 o Added text discussing timestamps before first and after last 1175 transition. 1177 o Added more guidance text regarding 32-bit and 64-bit data 1178 consistency. 1180 o Minor editorial changes. 1182 Changes since -01: 1184 o Renamed "POSIX Time" to "UNIX Time" and noted that values can be 1185 negative. 1187 o Noted that signed values MUST be represented using two's 1188 complement. 1190 o Renamed "POSIX TZ string" to "TZ string" and noted that it can be 1191 empty. 1193 o Moved TZ string extensions into its own subsection with examples. 1195 o Renamed leap second "epoch" to "occurrence". 1197 o Editorial changes from Paul Eggert. 1199 Changes since -00: 1201 o Split TZif format description into a general overview and 3 1202 subsections. 1204 o Updated Keywords boilerplate. 1206 o Updated POSIX reference. 1208 o Editorial changes from Eliot Lear. 1210 Authors' Addresses 1212 Arthur David Olson 1214 Email: arthurdavidolson@gmail.com 1216 Paul Eggert 1217 University of California, Los Angeles 1219 Email: eggert@cs.ucla.edu 1221 Kenneth Murchison 1222 FastMail US LLC 1224 Email: murch@fastmailteam.com