RFC 8536

The Time Zone Information Format (TZif)

📅 published February 2019, from ietf

RFC 8536: The Time Zone Information Format (TZif) 🕰️🦋

Internet Engineering Task Force (IETF) 🌸 Authors: A. Olson, P. Eggert (UCLA), and K. Murchison (FastMail) 💖 Category: Standards Track 🎀 ISSN: 2070-1721 ✨ Date: February 2019 📅 Obsoletes / Updates: nothing listed in the header 🙈

Abstract ✨

okay so this doc specifies the Time Zone Information Format (TZif) 🕰️ for representing and exchanging time zone info, and it's totally independent of any particular service or protocol 🫶. It also defines two media types for the format. iconic.

Status of This Memo 📜

this is an Internet Standards Track document 🔥.

it's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). for more on Internet Standards, check out Section 2 of RFC 7841 🧚.

for the current status, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc8536 🌈.

Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved 💜.

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication. please read these carefully, because they describe your rights and restrictions for this doc 👀. also, Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 💅.

Table of Contents 🗺️

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
2.  Conventions Used in This Document . . . . . . . . . . . . . .   3
3.  The Time Zone Information Format (TZif) . . . . . . . . . . .   5
  3.1.  TZif Header . . . . . . . . . . . . . . . . . . . . . . .   6
  3.2.  TZif Data Block . . . . . . . . . . . . . . . . . . . . .   8
  3.3.  TZif Footer . . . . . . . . . . . . . . . . . . . . . . .  12
    3.3.1.  TZ String Extensions  . . . . . . . . . . . . . . . .  13
4.  Interoperability Considerations . . . . . . . . . . . . . . .  13
5.  Use with the Time Zone Data Distribution Service  . . . . . .  14
  5.1.  Truncating TZif Files . . . . . . . . . . . . . . . . . .  15
  5.2.  Example TZDIST Request for TZif Data  . . . . . . . . . .  15
6.  Security Considerations . . . . . . . . . . . . . . . . . . .  17
7.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  17
8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  17
  8.1.  application/tzif  . . . . . . . . . . . . . . . . . . . .  17
  8.2.  application/tzif-leap . . . . . . . . . . . . . . . . . .  18
9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  19
  9.1.  Normative References  . . . . . . . . . . . . . . . . . .  19
  9.2.  Informative References  . . . . . . . . . . . . . . . . .  20
Appendix A.  Common Interoperability Issues . . . . . . . . . . .  21
Appendix B.  Example TZif Files . . . . . . . . . . . . . . . . .  23
  B.1.  Version 1 File Representing UTC (with Leap Seconds) . . .  24
  B.2.  Version 2 File Representing Pacific/Honolulu  . . . . . .  28
  B.3.  Truncated Version 3 File Representing Asia/Jerusalem  . .  33
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  34
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  34

1. Introduction 🌷

okay so time zone data usually includes offsets from universal time (UT) 🌍, daylight saving transition rules, one or more local time designations (acronyms or abbreviations) 🏷️, and optional leap-second adjustments ⏱️. one format for passing this info around is iCalendar [RFC5545]. it's text-based and used by calendaring and scheduling systems 📆.

this document specifies the widely deployed Time Zone Information Format (TZif) 💅. it's a binary format that most UNIX systems use to calculate local time, and it was introduced in the 1980s and has since evolved into multiple upward-compatible versions 🦋. there's a huge variety of interoperable software that can generate and read files in this format [tz-link] ✨. literally so iconic.

this spec does not define where the data assembled into a TZif file comes from. one such source is the IANA-hosted time zone database [RFC6557] 🧚.

2. Conventions Used in This Document 📖

bestie, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🔥. so lowercase versions are just regular words, no cap 🙈.

the following terms are used in this doc (see "Sources for Time Zone and Daylight Saving Time Data" [tz-link] for more detailed info about civil timekeeping data and practice) 🌸:

Coordinated Universal Time (UTC): the basis for civil time since 1960. it's approximately equal to mean solar time at the prime meridian (0 degrees longitude) 🌍.

Daylight Saving Time (DST): the time according to a location's law or practice, when adjusted as necessary from standard time. the adjustment may be positive or negative, and the amount of adjustment may vary depending on the date and time. the TZif format even allows the adjustment to be zero, although this is not common practice 🌞.

International Atomic Time (TAI): the time standard based on atomic clocks since 1972. it's equal to UTC but without leap-second adjustments ⚛️.

Leap-Second Correction (LEAPCORR): the value of TAI - UTC - 10 for timestamps after the first leap second, and zero for timestamps before that. the expression "TAI - UTC - 10" comes from the fact that TAI - UTC was defined to be 10 just prior to the first leap second in 1972, so clocks with leap seconds have a zero LEAPCORR before the first leap second 🧮.

Local Time: civil time for a particular location. its offset from universal time can depend on the date and time of day 📍.

POSIX Epoch: 1970-01-01 00:00:00 UTC, the basis for absolute timestamps in this document ⭐.

Standard Time: the time according to a location's law or practice, unadjusted for Daylight Saving Time 🍓.

Time Change: a change to civil timekeeping practice. it happens when one or more of the following occur simultaneously 🌈:

  1. a change in UT offset
  2. a change in whether daylight saving time is in effect
  3. a change in time zone abbreviation
  4. a leap second (i.e., a change in LEAPCORR)

Time Zone Data: the Time Zone Data Distribution Service (TZDIST) [RFC7808] defines "Time zone data" as "data that defines a single time zone, including an identifier, UTC offset values, DST rules, and other information such as time zone abbreviations." the interchange format defined in this document is one such form of time zone data 💜.

Transition Time: the moment a time change occurs that is not a leap second. it's identified with a signed integer count of UNIX leap time seconds since the POSIX epoch 🦋.

Universal Time (UT): the basis of civil time. this is the principal form of the mean solar time at the prime meridian (0 degrees longitude) for timestamps before UTC was introduced in 1960, and it's UTC for timestamps after that. although UT is sometimes called "UTC" or "GMT" in other sources, this specification uses the term "UT" to avoid confusion with UTC or with GMT 🌎.

UNIX Time: the time as returned by the time() function provided by the C programming language (see Section 3 of the "System Interfaces" volume of [POSIX]). it's an integer number of seconds since the POSIX epoch, not counting leap seconds. as an extension to POSIX, negative values represent times before the POSIX epoch, using UT 🕓.

UNIX Leap Time: UNIX time plus all preceding leap-second corrections. for example, if the first leap-second record in a TZif file occurs at 1972-06-30 23:59:60 UTC, the UNIX leap time for the timestamp 1972-07-01 00:00:00 UTC would be 78796801, one greater than the UNIX time for the same timestamp. similarly, if the second leap-second record occurs at 1972-12-31 23:59:60 UTC, it accounts for the first leap second, so the UNIX leap time of 1972-12-31 23:59:60 UTC would be 94694401, and the UNIX leap time of 1973-01-01 00:00:00 UTC would be 94694402. if a TZif file specifies no leap-second records, UNIX leap time is equal to UNIX time 🧠.

Wall Time: another name for local time, short for "wall-clock time" ⏰.

3. The Time Zone Information Format (TZif) ✨

okay so section 3 is where the file format actually lives 🎀 TZif starts with a fixed 44-octet version 1 header (Section 3.1) that has a version field saying which format the file uses. Readers built for version N can usually handle version N+1 files without too much drama 💅 Newer data either goes after the older data, so older readers can just skip the stuff they don't understand, or it's a small tweak to version N that version N readers will probably tolerate just fine 🦋

The version 1 header is followed by a variable-length version 1 data block (Section 3.2) with four-octet (32-bit) transition times and leap-second occurrences. These 32-bit values can only represent time changes from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 UT 😭 The version 1 header and data block are only there for backward compatibility with obsolescent readers, as covered in Common Interoperability Issues (Appendix A) 🌸

Version 1 files end right after the version 1 data block 🍓 Files from versions 2 and 3 keep going: they add a second 44-octet version 2+ header, a variable-length version 2+ data block with eight-octet (64-bit) transition times and leap-second occurrences, and a variable-length footer (Section 3.3). These 64-bit values can represent times roughly 292 billion years into the past or future. Literally iconic 👑

NOTE: All multi-octet integer values MUST be stored in network octet order format (high-order octet first, otherwise known as big-endian), with all bits significant. Signed integer values MUST be represented using two's complement. 🔥 this is the main vibe check for the whole file, so don't skip it bestie 🫶

A TZif file is structured as follows:

                     Version 1       Versions 2 & 3
                  +-------------+   +-------------+
                  |  Version 1  |   |  Version 1  |
                  |   Header    |   |   Header    |
                  +-------------+   +-------------+
                  |  Version 1  |   |  Version 1  |
                  |  Data Block |   |  Data Block |
                  +-------------+   +-------------+
                                    |  Version 2+ |
                                    |   Header    |
                                    +-------------+
                                    |  Version 2+ |
                                    |  Data Block |
                                    +-------------+
                                    |   Footer    |
                                    +-------------+

General Format of TZif Files

3.1. TZif Header

ok the header is where the vibes get organised 🧚 A TZif header is structured as follows (the lengths of multi-octet fields are shown in parentheses):

    +---------------+---+
    |  magic    (4) |ver|
    +---------------+---+---------------------------------------+
    |           [unused - reserved for future use] (15)         |
    +---------------+---------------+---------------+-----------+
    |  isutcnt  (4) |  isstdcnt (4) |  leapcnt  (4) |
    +---------------+---------------+---------------+
    |  timecnt  (4) |  typecnt  (4) |  charcnt  (4) |
    +---------------+---------------+---------------+

TZif Header

The fields of the header work like this 💖

  • magic: The four-octet ASCII [RFC20] sequence "TZif" (0x54 0x5A 0x69 0x66). This is how a file says "yep, I'm a TZif file" ✨
  • ver(sion): An octet telling you which version of the format the file uses. The value MUST be one of the following:
    • NUL (0x00) Version 1: the file only has the version 1 header and data block. Version 1 files MUST NOT contain a version 2+ header, data block, or footer. no extras, bestie 🙈
    • '2' (0x32) Version 2: the file MUST contain the version 1 header and data block, a version 2+ header and data block, and a footer. The TZ string in the footer (Section 3.3), if nonempty, MUST strictly adhere to the requirements for the TZ environment variable as defined in Section 8.3 of the "Base Definitions" volume of [POSIX] and MUST encode the POSIX portable character set as ASCII. very strict, very iconic 💅
    • '3' (0x33) Version 3: the file MUST contain the version 1 header and data block, a version 2+ header and data block, and a footer. The TZ string in the footer (Section 3.3), if nonempty, MUST conform to POSIX requirements with ASCII encoding, except that it MAY use the TZ string extensions described below (Section 3.3.1). the glow-up version 🦋
  • isutcnt: A four-octet unsigned integer that says how many UT/local indicators are in the data block. It MUST either be zero or equal to "typecnt". 🌈
  • isstdcnt: A four-octet unsigned integer that says how many standard/wall indicators are in the data block. It MUST either be zero or equal to "typecnt". 🌈
  • leapcnt: A four-octet unsigned integer counting the leap-second records in the data block. 🍓
  • timecnt: A four-octet unsigned integer counting the transition times in the data block. ⭐
  • typecnt: A four-octet unsigned integer counting the local time type records in the data block. It MUST NOT be zero. (Even though local time type records don't give you any useful info in files that have a nonempty TZ string but no transitions, you still need at least one, because lots of TZif readers reject files with zero time types 💀)
  • charcnt: A four-octet unsigned integer for the total number of octets used by the time zone designations in the data block. It MUST NOT be zero. The count includes the trailing NUL (0x00) octet at the end of the last time zone designation. the little NUL at the end is doing the most 😭

Although the version 1 and 2+ headers have the same format, magic number, and version fields, their count fields may differ, because the version 1 data can be a subset of the version 2+ data. so they look like twins but have different counts, iykyk 👯‍♀️🎀

3.2. TZif Data Block ✨

okay bestie, the data block is where all the juicy stuff lives 💖 It has seven variable-length elements, and each one is just a series of items. The count for each series comes from the matching count field in the header, and the total length of an element is the number of items times the size of each item 🧮 So if you don't want to parse or use the version 1 data block, you can work out its total length and skip straight to the version 2+ header. no cap, that's a whole vibe 🦋

In the version 1 data block, time values are 32 bits (TIME_SIZE = 4 octets) 🌸 In the version 2+ data block, which only shows up in version 2 and 3 files, time values are 64 bits (TIME_SIZE = 8 octets) 💜

Here's the layout, with the lengths of multi-octet fields in parentheses 🍓

     +---------------------------------------------------------+
     |  transition times          (timecnt x TIME_SIZE)        |
     +---------------------------------------------------------+
     |  transition types          (timecnt)                    |
     +---------------------------------------------------------+
     |  local time type records   (typecnt x 6)                |
     +---------------------------------------------------------+
     |  time zone designations    (charcnt)                    |
     +---------------------------------------------------------+
     |  leap-second records       (leapcnt x (TIME_SIZE + 4))  |
     +---------------------------------------------------------+
     |  standard/wall indicators  (isstdcnt)                   |
     +---------------------------------------------------------+
     |  UT/local indicators       (isutcnt)                    |
     +---------------------------------------------------------+

                           TZif Data Block

Now let's break down each element 👀

  • transition times: A series of four- or eight-octet UNIX leap-time values, sorted in strictly ascending order. Each one is a transition time where the rules for working out local time might change 🕰️ The count comes from timecnt in the header. Each time value SHOULD be at least -2**59.
(-2**59 is the greatest negated power of 2 that predates the Big Bang, and steering clear of anything earlier dodges known TZif reader bugs with outlandishly negative timestamps.) 🙈
  • transition types: A series of one-octet unsigned integers, each one saying which type of local time goes with the matching transition time 🎀 These act as zero-based indices into the array of local time type records, and the count comes from timecnt in the header. Each type index MUST be in the range [0, "typecnt" - 1].
  • local time type records: A series of six-octet records that each describe a local time type ✨ The count comes from typecnt in the header. Each record looks like this (the lengths of multi-octet fields are in parentheses):
     +---------------+---+---+
     |  utoff (4)    |dst|idx|
     +---------------+---+---+
  • utoff: A four-octet signed integer for the number of seconds added to UT to get local time 🌍 The value MUST NOT be -2**31, and it SHOULD be in the range [-89999, 93599] (i.e., its value SHOULD be more than -25 hours and less than 26 hours). Avoiding -2**31 lets 32-bit clients negate the value without overflow 🧠 Keeping it in [-89999, 93599] makes things easy for implementations that already handle the POSIX-required range [-24:59:59, 25:59:59].
  • (is)dst: A one-octet value that says whether the local time counts as Daylight Saving Time (DST) ☀️ The value MUST be 0 or 1. A one (1) means DST, and a zero (0) means standard time.
  • (desig)idx: A one-octet unsigned integer, a zero-based index into the series of time zone designation octets, which picks out one designation string 🏷️ Each index MUST be in the range [0, "charcnt" - 1]. It points at the NUL-terminated string of octets starting at position idx in the time zone designations. (This string MAY be empty.) A NUL octet MUST exist in the time zone designations at or after position idx.
  • time zone designations: A series of octets forming an array of NUL-terminated (0x00) time zone designation strings 💅 The total number of octets is in the charcnt field of the header. Note that two designations MAY overlap if one is a suffix of the other. The character encoding of these strings isn't specified, but check out Section 4 of this document for more on that 📖
  • leap-second records: A series of eight- or twelve-octet records that describe the corrections needed to get from UTC to TAI 🍭 They're sorted by occurrence time in strictly ascending order, and the count comes from leapcnt in the header. Each record has one of these two structures (the lengths of multi-octet fields are in parentheses):
Version 1 Data Block:

     +---------------+---------------+
     |  occur (4)    |  corr (4)     |
     +---------------+---------------+

version 2+ Data Block:

     +---------------+---------------+---------------+
     |  occur (8)                    |  corr (4)     |
     +---------------+---------------+---------------+
  • occur(rence): A four- or eight-octet UNIX leap time value for when a leap-second correction happens ⏰ The first value, if present, MUST be nonnegative, and each later value MUST be at least 2419199 greater than the previous value. (That's 28 days' worth of seconds, minus a potential negative leap second.)
  • corr(ection): A four-octet signed integer for the value of LEAPCORR on or after the occurrence 💫 The correction value in the first leap-second record, if present, MUST be either one (1) or minus one (-1). The correction values in adjacent leap-second records MUST differ by exactly one (1). The value of LEAPCORR is zero for timestamps before the occurrence time in the first leap-second record (or for all timestamps if there are no leap-second records).
  • standard/wall indicators: A series of one-octet values showing whether the transition times for local time types were specified as standard time or wall-clock time 🧾 Each value MUST be 0 or 1. A one (1) means standard time, and the value MUST be set to one (1) if the matching UT/local indicator is set to one (1). A zero (0) means wall time. The count comes from isstdcnt in the header. If isstdcnt is zero (0), all transition times for local time types are assumed to be wall time.
  • UT/local indicators: A series of one-octet values showing whether those transition times were specified as UT or local time 🌐 Each value MUST be 0 or 1. A one (1) means UT, and the matching standard/wall indicator MUST also be set to one (1). A zero (0) means local time. The count comes from isutcnt in the header. If isutcnt is zero (0), all transition times for local time types are assumed to be local time.

The type linked to a transition time gives the local time for timestamps starting at that transition and running up to, but not including, the next one 🩷 Timestamps before the first transition use the first time type (time type 0). Timestamps on or after the last transition use the TZ string in the footer (Section 3.3) if it's present and nonempty. Otherwise, it's unspecified. If there are no transitions at all, every timestamp uses the TZ string in the footer if it's present and nonempty. If not, they use time type 0.

Each pair of standard/wall and UT/local indicators tells you whether the matching transition time was specified as UT, standard time, or wall-clock time 🎯 There are only three combinations of the two indicators, since the standard/wall value MUST be one (1) whenever the UT/local value is one (1). This is handy if the transition times in a TZif file need to be turned into transitions for a different time zone, like when working out transition times for a simple POSIX TZ string such as "AKST9AKDT".

To keep a TZif file from wasting space, every nonzero local time type index SHOULD appear at least once in the transition type array 🧹 Likewise, every octet in the time zone designations array SHOULD be used by at least one time type record.

The TZif footer is structured like this (the lengths of multi-octet fields are in parentheses):

                 +---+--------------------+---+
                 | NL|  TZ string (0...)  |NL |
                 +---+--------------------+---+

                           TZif Footer

Here's what the footer pieces mean 💖

  • NL: An ASCII new line character (0x0A) 🫶
  • TZ string: A rule for working out local time changes after the last transition time stored in the version 2+ data block 🗺️ The string is either empty or uses the expanded format of the "TZ" environment variable, as defined in Section 8.3 of the "Base Definitions" volume of [POSIX] with ASCII encoding. In version 3 files it may also use the extensions described below (Section 3.3.1). If the string is empty, the matching information isn't available. If the string is nonempty and one or more transitions show up in the version 2+ data, the string MUST be consistent with the last version 2+ transition. In other words, evaluating the TZ string at the time of the last transition should yield the same time type that was specified in that last transition. The string MUST NOT contain NUL octets or be NUL-terminated, and it SHOULD NOT begin with the ':' (colon) character.

The TZif footer is only present in version 2 and 3 files 🌈 The obsolescent version 1 format came out before anyone realised a footer was needed.

3.3.1. TZ String Extensions ✨

okay so a version 3 TZif file is allowed to use some extra tricks on top of regular POSIX TZ strings 💅 MAY is the word here, so it's optional, but the rules are described using the terminology from Section 8.3 of the "Base Definitions" volume of [POSIX] 🎀

  • The hours part of the transition times can be signed and go from -167 through 167 (-167 <= hh <= 167) 🌈 POSIX only lets it be unsigned, from 0 through 24, so this is a major glow-up 💖

Example: <-03>3<-02>,M3.5.0/-2,M10.5.0/-1 This one is giving DST from 22:00 on the day before March's last Sunday until 23:00 on the day before October's last Sunday 🌸 Standard time is 3 hours west of UT and gets abbreviated "-03", and daylight saving time is 2 hours west of UT and gets abbreviated "-02" 🦋

  • DST counts as being in effect all year if it starts January 1 at 00:00 and ends December 31 at 24:00 plus the difference between daylight saving and standard time 😭 That leaves no room at all for standard time on the calendar, so it's a full DST-forever moment 🧚

Example: EST5EDT,0/0,J365/25 This is a time zone that observes daylight saving time all year long ☀️ It's 4 hours west of UT and gets abbreviated "EDT" 💜

4. Interoperability Considerations ✨

these practices are the secret sauce for making sure TZif apps actually get along 🫶

  • Version 1 files are a legacy format, so they SHOULD NOT be generated 🙈 They don't support transition times after the year 2038, which is literally the cutoff 💀
  • Implementations that only understand version 1 MUST ignore any data that goes past the calculated end of the version 1 data block 🚫
  • Implementations SHOULD generate a version 3 file if TZ string extensions are necessary to model transition times accurately 🔥 Otherwise, version 2 files SHOULD be generated 💅
  • The sequence of time changes in the version 1 header and data block SHOULD be a contiguous sub-sequence of the time changes in the version 2+ header and data block, plus the footer 🧚 This helps obsolescent version 1 readers agree with current readers about timestamps inside that contiguous sub-sequence 🌈 It also lets writers that don't support obsolescent readers set "timecnt" to zero in the version 1 data block to save space 🍓
  • Time zone designations SHOULD consist of at least three (3) and no more than six (6) ASCII characters from the set of alphanumerics, '-', and '+' ✨ This is for compatibility with POSIX requirements for time zone abbreviations 🎀
  • When reading a version 2 or 3 file, implementations SHOULD ignore the version 1 header and data block, except for skipping over them 🦋
  • Implementations SHOULD calculate the total lengths of the headers and data blocks and check that they all fit within the actual file size, as part of a validity check for the file 🫶
  • When a TZif file is used in a MIME message entity, it SHOULD be indicated by one of the following media types 💌
    • "application/tzif-leap" (Section 8.2) to indicate that leap-second records are included in the TZif data as necessary (none are necessary if the file is truncated to a range that precedes the first leap second) 🌸
    • "application/tzif" (Section 8.1) to indicate that leap-second records are not included in the TZif data; "leapcnt" in the header(s) MUST be zero (0) 💜
  • Common interoperability issues and possible workarounds are described in Appendix A 📚

5. Use with the Time Zone Data Distribution Service ✨

the Time Zone Data Distribution Service (TZDIST) [RFC7808] is a service that delivers time zone data and leap-second rules reliably, securely, and fast 🚀 It's built for client systems like calendaring and scheduling apps or operating systems 📅

A TZDIST service MAY supply time zone data to clients in the Time Zone Information Format 🧚 If it does, it MUST indicate that support by including the media type "application/tzif" (Section 8.1) in its "capabilities" response (see Section 5.1 of [RFC7808]) 💅 A TZDIST service MAY also include "application/tzif-leap" (Section 8.2) in its "capabilities" response if it can generate TZif files containing leap-second records 🌈 But a TZDIST service MUST NOT advertise "application/tzif-leap" without also advertising "application/tzif" 🙅‍♀️

TZDIST clients MUST use the HTTP "Accept" [RFC7231] header field to say whether they want data in "application/tzif", "application/tzif-leap", or both 🎀

5.1. Truncating TZif Files

as described in Section 3.9 of [RFC7808], a TZDIST service MAY truncate time zone transition data ✂️ A truncated TZif file is valid from its first transition time up to, but not including, its last version 2+ transition time, if there is one 🦋

When truncating the start of a TZif file, the service MUST supply a first transition time in the version 2+ data that is the start point of the truncation range 🌸 Just like with untruncated files, time type 0 means local time right before the start point, and the time type of the first transition means local time after that 💜

When truncating the end of a TZif file, the service MUST supply a last transition time in the version 2+ data that is the end point of the truncation range, and it MUST supply an empty TZ string 😭 Just like untruncated TZif files with empty TZ strings, a truncated TZif file doesn't indicate local time after the last transition 🙈

All represented information inside the truncation range MUST be the same as the information represented by a corresponding untruncated TZif file 🫶

TZDIST clients SHOULD NOT use a truncated TZif file (as described above) to interpret timestamps outside the truncation time range 🚫

5.2. Example TZDIST Request for TZif Data

in this example, the client checks the server for the available formats, then asks for the time zone with a specific time zone identifier in Time Zone Information Format 🎀

Note that this example assumes the time zone context path has been discovered (see [RFC7808], Section 4.2.1) to be "/tzdist" 🧚

>> Request <<

GET /tzdist/capabilities HTTP/1.1
Host: tz.example.com

>> Response <<

HTTP/1.1 200 OK
Date: Fri, 01 Jun 2018 14:52:23 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx

{
  "version": 1,

  "info": {
    "primary-source": "IANA:2018e",
    "formats": [
      "text/calendar",
      "application/tzif",
      "application/tzif-leap"
    ],
...
  },
...
}


>> Request <<

GET /tzdist/zones/America%2FNew_York HTTP/1.1
Host: tz.example.com
Accept: application/tzif

>> Response <<

HTTP/1.1 200 OK
Date: Fri, 01 Jun 2018 14:52:24 GMT
Content-Type: application/tzif
Content-Length: xxxx
ETag: "123456789-000-111"

TZif2...[binary data without leap-second records]...
EST5EDT,M3.2.0,M11.1.0

6. Security Considerations ✨

okay this section is serious, bestie 🚨 The Time Zone Information Format has no executable code, and it doesn't define any extensible areas that could be used to store such code 🔒

TZif contains counted arrays of data elements 🧮 All counts should be checked when processing TZif objects, so nothing gets read past the end of the object 🛑

TZif provides no confidentiality or integrity protection 😬 Time zone information is normally public and doesn't need confidentiality protection 🌍 But since time zone information is used in lots of critical applications, integrity protection may be required, and it must be provided externally 🛡️

7. Privacy Considerations ✨

the Time Zone Information Format contains publicly available data, and it doesn't define any extensible areas that could be used to store private data 🌷

as discussed in Section 9 of [RFC7808], sending time zone data over an insecure channel could leak the past, current, or future location of a device or user 👀 So TZif data sent over a public communications channel MUST be protected with a confidentiality layer, such as the one provided by Transport Layer Security (TLS) [RFC8446] 🔐

8. IANA Considerations ✨

this document defines two media types [RFC6838] for exchanging data in the Time Zone Information Format 📬

8.1. application/tzif

   Type name:  application

   Subtype name:  tzif

   Required parameters:  none

   Optional parameters:  none

   Encoding considerations:  binary

   Security considerations:  See Section 6 of RFC 8536.

   Interoperability considerations:  See Section 4 of RFC 8536.

   Published specification:  This specification.

   Applications that use this media type:  This media type is designed
      for widespread use by applications that need to use or exchange
      time zone information, such as the Time Zone Information Compiler
      (zic) [ZIC] and the GNU C Library [GNU-C].  The Time Zone
      Distribution Service [RFC7808] can directly use this media type.

   Fragment identifier considerations:  N/A

   Additional information:

      Magic number(s):  The first 4 octets are 0x54, 0x5A, 0x69, 0x66

      File extensions(s):  N/A

      Macintosh file type code(s):  N/A

   Person & email address to contact for further information:
      Time Zone Database mailing list <tz@iana.org>

   Intended usage:  COMMON

   Restrictions on usage:  N/A

   Author:  See the "Authors' Addresses" section of RFC 8536.

   Change controller:  IETF

8.2. application/tzif-leap

   Type name:  application

   Subtype name:  tzif-leap

   Required parameters:  none

   Optional parameters:  none

   Encoding considerations:  binary

   Security considerations:  See Section 6 of RFC 8536.

   Interoperability considerations:  See Section 4 of RFC 8536.

   Published specification:  This specification.

   Applications that use this media type:  This media type is designed
      for widespread use by applications that need to use or exchange
      time zone information, such as the Time Zone Information Compiler
      (zic) [ZIC] and the GNU C Library [GNU-C].  The Time Zone
      Distribution Service [RFC7808] can directly use this media type.

   Fragment identifier considerations:  N/A

   Additional information:

      Magic number(s):  The first 4 octets are 0x54, 0x5A, 0x69, 0x66

      File extensions(s):  N/A

      Macintosh file type code(s):  N/A

   Person & email address to contact for further information:
      Time Zone Database mailing list <tz@iana.org>

   Intended usage:  COMMON

   Restrictions on usage:  N/A

   Author:  See the "Authors' Addresses" section of RFC 8536.

   Change controller:  IETF

9. References ✨

9.1. Normative References

Okay, these are the docs this spec literally can't function without, bestie 📚✨

9.2. Informative References

These ones are the extra reading, the "ooh tell me more" stuff 🧚💜

Appendix A. Common Interoperability Issues ✨

Okay, this appendix is the "things that trip people up" list 🫣 Most of these are problems with writing TZif files for readers that follow the older versions of this spec [EGGERT-TZ]. The goals here are:

  1. to help TZif writers output files that avoid common pitfalls in older or buggy TZif readers,
  2. to help TZif readers avoid common pitfalls when reading files generated by future TZif writers, and
  3. to help any future specification authors see what sort of problems arise when the TZif format is changed.

When new versions of the TZif format have been defined, the design goal was that a reader can successfully use a TZif file even if the file is of a later TZif version than what the reader was designed for. When full compatibility wasn't achieved, the aim was to limit glitches to rarely used timestamps and to allow simple partial workarounds in writers designed to generate new-version data that's still useful for older-version readers. This section documents these compatibility issues and workarounds, along with other common bugs in readers. 💅

Here are the interoperability problems with TZif, bestie:

  • Some readers examine only version 1 data. As a partial workaround, a writer can output as much version 1 data as possible. However, a reader should ignore version 1 data and use version 2+ data, even if the reader's native timestamps have only 32 bits.
  • Some readers designed for version 2 might mishandle timestamps after a version 3 file's last transition, because they cannot parse extensions to POSIX in the TZ-like string. As a partial workaround, a writer can output more transitions than necessary, so that only far-future timestamps are mishandled by version 2 readers.
  • Some readers designed for version 2 do not support permanent daylight saving time -- e.g., a TZ string "EST5EDT,0/0,J365/25" denoting permanent Eastern Daylight Time (-04). As a partial workaround, a writer can substitute standard time for the next time zone east -- e.g., "AST4" for permanent Atlantic Standard Time (-04). 🌸
  • Some readers ignore the footer and instead predict future timestamps from the time type of the last transition. As a partial workaround, a writer can output more transitions than necessary.
  • Some readers do not use time type 0 for timestamps before the first transition, in that they infer a time type using a heuristic that does not always select time type 0. As a partial workaround, a writer can output a dummy (no-op) first transition at an early time.
  • Some readers mishandle timestamps before the first transition that has a timestamp not less than -231. Readers that support only 32-bit timestamps are likely to be more prone to this problem, for example, when they process 64-bit transitions, only some of which are representable in 32 bits. As a partial workaround, a writer can output a dummy transition at timestamp -231.
  • Some readers mishandle a transition if its timestamp has the minimum possible signed 64-bit value. Timestamps less than -2**59 are not recommended. 🙈
  • Some readers mishandle POSIX-style TZ strings that contain "<" or ">". As a partial workaround, a writer can avoid using '<' or '>' for time zone abbreviations containing only alphabetic characters.
  • Many readers mishandle time zone abbreviations that contain non-ASCII characters. These characters are not recommended.
  • Some readers may mishandle time zone abbreviations that contain fewer than 3 or more than 6 characters, or that contain ASCII characters other than alphanumerics, '-', and '+'. These abbreviations are not recommended.
  • Some readers mishandle TZif files that specify daylight saving time UT offsets that are less than the UT offsets for the corresponding standard time. These readers do not support locations like Ireland, which uses the equivalent of the POSIX TZ string "IST-1GMT0,M10.5.0,M3.5.0/1", observing standard time (IST, +01) in summer and daylight saving time (GMT, +00) in winter. As a partial workaround, a writer can output data for the equivalent of the POSIX TZ string "GMT0IST,M3.5.0/1,M10.5.0", thus swapping standard and daylight saving time. Although this workaround misidentifies which part of the year uses daylight saving time, it records UT offsets and time zone abbreviations correctly. 🍓

Some interoperability problems are reader bugs that are listed here mostly as warnings to developers of readers. Consider this your heads-up, reader devs 🚨

  • Some readers do not support negative timestamps. Developers of distributed applications should keep this in mind if they need to deal with pre-1970 data.
  • Some readers mishandle timestamps before the first transition that has a nonnegative timestamp. Readers that do not support negative timestamps are likely to be more prone to this problem.
  • Some readers mishandle time zone abbreviations like "-08" that contain '+', '-', or digits.
  • Some readers mishandle UT offsets that are out of the traditional range of -12 through +12 hours and so do not support locations like Kiritimati that are outside this range.
  • Some readers mishandle UT offsets in the range [-3599, -1] seconds from UT, because they integer-divide the offset by 3600 to get 0 and then display the hour part as "+00". 😭
  • Some readers mishandle UT offsets that are not a multiple of one hour, 15 minutes, or 1 minute.

Appendix B. Example TZif Files 🎀

The following sections contain annotated hexadecimal dumps of example TZif files.

Note that these examples should only be considered informative. Although the example data entries are current as of the publication date of this document, the data will likely change in the future as leap seconds are added and changes are made to civil time. ⏰

B.1. Version 1 File Representing UTC (with Leap Seconds)

Okay bestie, this is the big hex table 🦋 Every row is a field in the file, with its offset, the raw data octets in hex, the record or field name, and what the value means. Let's look at it together 💅

+-------+---------------+------------------+------------------------+
| File  | Data Octets   | Record Name /    | Field Value            |
| Offset| (hexadecimal) | Field Name       |                        |
+-------+---------------+------------------+------------------------+
| 000   | 54 5a 69 66   | magic            | "TZif"                 |
| 004   | 00            | version          | 0 (1)                  |
| 005   | 00 00 00 00   |                  |                        |
|       | 00 00 00 00   |                  |                        |
|       | 00 00 00 00   |                  |                        |
|       | 00 00 00      |                  |                        |
| 020   | 00 00 00 01   | isutccnt         | 1                      |
| 024   | 00 00 00 01   | isstdcnt         | 1                      |
| 028   | 00 00 00 1b   | isleapcnt        | 27                     |
| 032   | 00 00 00 00   | timecnt          | 0                      |
| 036   | 00 00 00 01   | typecnt          | 1                      |
| 040   | 00 00 00 04   | charcnt          | 4                      |
|       |               |                  |                        |
|       |               | localtimetype[0] |                        |
| 044   | 00 00 00 00   | utcoff           | 00:00                  |
| 048   | 00            | isdst            | 0 (no)                 |
| 049   | 00            | desigidx         | 0                      |
|       |               |                  |                        |
| 050   | 55 54 43 00   | designations[0]  | "UTC"                  |
|       |               |                  |                        |
|       |               | leapsecond[0]    |                        |
| 054   | 04 b2 58 00   | occurrence       | 78796800               |
|       |               |                  | (1972-06-30T23:59:60Z) |
| 058   | 00 00 00 01   | correction       | 1                      |
|       |               |                  |                        |
|       |               | leapsecond[1]    |                        |
| 062   | 05 a4 ec 01   | occurrence       | 94694401               |
|       |               |                  | (1972-12-31T23:59:60Z) |
| 066   | 00 00 00 02   | correction       | 2                      |
|       |               |                  |                        |
|       |               | leapsecond[2]    |                        |
| 070   | 07 86 1f 82   | occurrence       | 126230402              |
|       |               |                  | (1973-12-31T23:59:60Z) |
| 074   | 00 00 00 03   | correction       | 3                      |
|       |               |                  |                        |
|       |               | leapsecond[3]    |                        |
| 078   | 09 67 53 03   | occurrence       | 157766403              |
|       |               |                  | (1974-12-31T23:59:60Z) |
| 082   | 00 00 00 04   | correction       | 4                      |
|       |               |                  |                        |
|       |               | leapsecond[4]    |                        |
| 086   | 0b 48 86 84   | occurrence       | 189302404              |
|       |               |                  | (1975-12-31T23:59:60Z) |
| 090   | 00 00 00 05   | correction       | 5                      |
|       |               |                  |                        |
|       |               | leapsecond[5]    |                        |
| 094   | 0d 2b 0b 85   | occurrence       | 220924805              |
|       |               |                  | (1976-12-31T23:59:60Z) |
| 098   | 00 00 00 06   | correction       | 6                      |
|       |               |                  |                        |
|       |               | leapsecond[6]    |                        |
| 102   | 0f 0c 3f 06   | occurrence       | 252460806              |
|       |               |                  | (1977-12-31T23:59:60Z) |
| 106   | 00 00 00 07   | correction       | 7                      |
|       |               |                  |                        |
|       |               | leapsecond[7]    |                        |
| 110   | 10 ed 72 87   | occurrence       | 283996807              |
|       |               |                  | (1978-12-31T23:59:60Z) |
| 114   | 00 00 00 08   | correction       | 8                      |
|       |               |                  |                        |
|       |               | leapsecond[8]    |                        |
| 118   | 12 ce a6 08   | occurrence       | 315532808              |
|       |               |                  | (1979-12-31T23:59:60Z) |
| 122   | 00 00 00 09   | correction       | 9                      |
|       |               |                  |                        |
|       |               | leapsecond[9]    |                        |
| 126   | 15 9f ca 89   | occurrence       | 362793609              |
|       |               |                  | (1981-06-30T23:59:60Z) |
| 130   | 00 00 00 0a   | correction       | 10                     |
|       |               |                  |                        |
|       |               | leapsecond[10]   |                        |
| 134   | 17 80 fe 0a   | occurrence       | 394329610              |
|       |               |                  | (1982-06-30T23:59:60Z) |
| 138   | 00 00 00 0b   | correction       | 11                     |
|       |               |                  |                        |
|       |               | leapsecond[11]   |                        |
| 142   | 19 62 31 8b   | occurrence       | 425865611              |
|       |               |                  | (1983-06-30T23:59:60Z) |
| 146   | 00 00 00 0c   | correction       | 12                     |
|       |               |                  |                        |
|       |               | leapsecond[12]   |                        |
| 150   | 1d 25 ea 0c   | occurrence       | 489024012              |
|       |               |                  | (1985-06-30T23:59:60Z) |
| 154   | 00 00 00 0d   | correction       | 13                     |
|       |               |                  |                        |
|       |               | leapsecond[13]   |                        |
| 158   | 21 da e5 0d   | occurrence       | 567993613              |
|       |               |                  | (1987-12-31T23:59:60Z) |
| 162   | 00 00 00 0e   | correction       | 14                     |
|       |               |                  |                        |
|       |               | leapsecond[14]   |                        |
| 166   | 25 9e 9d 8e   | occurrence       | 631152014              |
|       |               |                  | (1989-12-31T23:59:60Z) |
| 170   | 00 00 00 0f   | correction       | 15                     |
|       |               |                  |                        |
|       |               | leapsecond[15]   |                        |
| 174   | 27 7f d1 0f   | occurrence       | 662688015              |
|       |               |                  | (1990-12-31T23:59:60Z) |
| 178   | 00 00 00 10   | correction       | 16                     |
|       |               |                  |                        |
|       |               | leapsecond[16]   |                        |
| 182   | 2a 50 f5 90   | occurrence       | 709948816              |
|       |               |                  | (1992-06-30T23:59:60Z) |
| 186   | 00 00 00 11   | correction       | 17                     |
|       |               |                  |                        |
|       |               | leapsecond[17]   |                        |
| 190   | 2c 32 29 11   | occurrence       | 741484817              |
|       |               |                  | (1993-06-30T23:59:60Z) |
| 194   | 00 00 00 12   | correction       | 18                     |
|       |               |                  |                        |
|       |               | leapsecond[18]   |                        |
| 198   | 2e 13 5c 92   | occurrence       | 773020818              |
|       |               |                  | (1994-06-30T23:59:60Z) |
| 202   | 00 00 00 13   | correction       | 19                     |
|       |               |                  |                        |
|       |               | leapsecond[19]   |                        |
| 206   | 30 e7 24 13   | occurrence       | 820454419              |
|       |               |                  | (1995-12-31T23:59:60Z) |
| 210   | 00 00 00 14   | correction       | 20                     |
|       |               |                  |                        |
|       |               | leapsecond[20]   |                        |
| 214   | 33 b8 48 94   | occurrence       | 867715220              |
|       |               |                  | (1997-06-30T23:59:60Z) |
| 218   | 00 00 00 15   | correction       | 21                     |
|       |               |                  |                        |
|       |               | leapsecond[21]   |                        |
| 222   | 36 8c 10 15   | occurrence       | 915148821              |
|       |               |                  | (1998-12-31T23:59:60Z) |
| 226   | 00 00 00 16   | correction       | 22                     |
|       |               |                  |                        |
|       |               | leapsecond[22]   |                        |
| 230   | 43 b7 1b 96   | occurrence       | 1136073622             |
|       |               |                  | (2005-12-31T23:59:60Z) |
| 234   | 00 00 00 17   | correction       | 23                     |
|       |               |                  |                        |
|       |               | leapsecond[23]   |                        |
| 238   | 49 5c 07 97   | occurrence       | 1230768023             |
|       |               |                  | (2008-12-31T23:59:60Z) |
| 242   | 00 00 00 18   | correction       | 24                     |
|       |               |                  |                        |
|       |               | leapsecond[24]   |                        |
| 246   | 4f ef 93 18   | occurrence       | 1341100824             |
|       |               |                  | (2012-06-30T23:59:60Z) |
| 250   | 00 00 00 19   | correction       | 25                     |
|       |               |                  |                        |
|       |               | leapsecond[25]   |                        |
| 254   | 55 93 2d 99   | occurrence       | 1435708825             |
|       |               |                  | (2015-06-30T23:59:60Z) |
| 258   | 00 00 00 1a   | correction       | 26                     |
|       |               |                  |                        |
|       |               | leapsecond[26]   |                        |
| 262   | 58 68 46 9a   | occurrence       | 1483228826             |
|       |               |                  | (2016-12-31T23:59:60Z) |
| 266   | 00 00 00 1b   | correction       | 27                     |
|       |               |                  |                        |
| 270   | 00            | UT/local[0]      | 0 (local)              |
|       |               |                  |                        |
| 271   | 00            | standard/wall[0] | 0 (wall)               |
+-------+---------------+------------------+------------------------+

okay so bestie, let's figure out TAI for 2000-01-01T00:00:00Z (UNIX time = 946684800) 🕰️✨ it's literally just two steps:

  1. Find the latest leap-second occurrence prior to the time of interest (leapsecond[21]) and note the correction value (LEAPCORR = 22). 💖
  2. Add LEAPCORR + 10 to the time of interest to yield TAI of 2000-01-01T00:00:32. 🦋

the way that math just works out, no cap 😭💅

B.2. Version 2 File Representing Pacific/Honolulu 🌺

+--------+--------------+------------------+------------------------+

FileHexadecimalRecord Name /Field Value
OffsetOctetsField Name

+--------+--------------+------------------+------------------------+

00054 5a 69 66magic"TZif"
00432version'2' (2)
00500 00 00 00
00 00 00 00
00 00 00 00
00 00 00
02000 00 00 06isutccnt6
02400 00 00 06isstdcnt6
02800 00 00 00isleapcnt0
03200 00 00 07timecnt7
03600 00 00 06typecnt6
04000 00 00 14charcnt20
04480 00 00 00trans time[0]-2147483648
(1901-12-13T20:45:52Z)
048bb 05 43 48trans time[1]-1157283000
(1933-04-30T12:30:00Z)
052bb 21 71 58trans time[2]-1155436200
(1933-05-21T21:30:00Z)
056cb 89 3d c8trans time[3]-880198200
(1942-02-09T12:30:00Z)
060d2 23 f4 70trans time[4]-769395600
(1945-08-14T23:00:00Z)
064d2 61 49 38trans time[5]-765376200
(1945-09-30T11:30:00Z)
068d5 8d 73 48trans time[6]-712150200
(1947-06-08T12:30:00Z)
07201trans type[0]1
07302trans type[1]2
07401trans type[2]1
07503trans type[3]3
07604trans type[4]4
07701trans type[5]1
07805trans type[6]5
localtimetype[0]
079ff ff 6c 02utcoff-37886 (-10:21:26)
08300isdst0 (no)
08400desigidx0
localtimetype[1]
085ff ff 6c 58utcoff-37800 (-10:30)
08900isdst0 (no)
09004desigidx4
localtimetype[2]
091ff ff 7a 68utcoff-34200 (-09:30)
09501isdst1 (yes)
09608desigidx8
localtimetype[3]
097ff ff 7a 68utcoff-34200 (-09:30)
10101isdst1 (yes)
1020cdesigidx12
localtimetype[4]
103ff ff 7a 68utcoff-34200 (-09:30)
10701isdst1 (yes)
10810desigidx16
localtimetype[5]
109ff ff 73 60utcoff-36000 (-10:00)
11300isdst0 (no)
11404desigidx4
1154c 4d 54 00designations[0]"LMT"
11948 53 54 00designations[4]"HST"
12348 44 54 00designations[8]"HDT"
12748 57 54 00designations[12]"HWT"
13148 50 54 00designations[16]"HPT"
13500UT/local[0]1 (UT)
13600UT/local[1]0 (local)
13700UT/local[2]0 (local)
13800UT/local[3]0 (local)
13901UT/local[4]1 (UT)
14000UT/local[5]0 (local)
14100standard/wall[0]1 (standard)
14200standard/wall[1]0 (wall)
14300standard/wall[2]0 (wall)
14400standard/wall[3]0 (wall)
14501standard/wall[4]1 (standard)
14600standard/wall[5]0 (wall)
14754 5a 69 66magic"TZif"
15132version'2' (2)
15200 00 00 00
00 00 00 00
00 00 00 00
00 00 00
16700 00 00 06isutccnt6
17100 00 00 06isstdcnt6
17500 00 00 00isleapcnt0
17900 00 00 07timecnt7
18300 00 00 06typecnt6
18700 00 00 14charcnt20
191ff ff ff fftrans time[0]-2334101314
74 e0 70 be(1896-01-13T22:31:26Z)
199ff ff ff fftrans time[1]-1157283000
bb 05 43 48(1933-04-30T12:30:00Z)
207ff ff ff fftrans time[2]-1155436200
bb 21 71 58(1933-05-21T21:30:00Z)
215ff ff ff fftrans time[3]-880198200
cb 89 3d c8(1942-02-09T12:30:00Z)
223ff ff ff fftrans time[4]-769395600
d2 23 f4 70(1945-08-14T23:00:00Z)
231ff ff ff fftrans time[5]-765376200
d2 61 49 38(1945-09-30T11:30:00Z)
239ff ff ff fftrans time[6]-712150200
d5 8d 73 48(1947-06-08T12:30:00Z)
24701trans type[0]1
24802trans type[1]2
24901trans type[2]1
25003trans type[3]3
25104trans type[4]4
25201trans type[5]1
25305trans type[6]5
localtimetype[0]
254ff ff 6c 02utcoff-37886 (-10:21:26)
25800isdst0 (no)
25900desigidx0
localtimetype[1]
260ff ff 6c 58utcoff-37800 (-10:30)
26400isdst0 (no)
26504desigidx4
localtimetype[2]
266ff ff 7a 68utcoff-34200 (-09:30)
27001isdst1 (yes)
27108desigidx8
localtimetype[3]
272ff ff 7a 68utcoff-34200 (-09:30)
27601isdst1 (yes)
2770cdesigidx12
localtimetype[4]
278ff ff 7a 68utcoff-34200 (-09:30)
28201isdst1 (yes)
28310desigidx16
localtimetype[5]
284ff ff 73 60utcoff-36000 (-10:00)
28800isdst0 (no)
28904desigidx4
2904c 4d 54 00designations[0]"LMT"
29448 53 54 00designations[4]"HST"
29848 44 54 00designations[8]"HDT"
30248 57 54 00designations[12]"HWT"
30648 50 54 00designations[16]"HPT"
31000UT/local[0]0 (local)
31100UT/local[1]0 (local)
   | 312    | 00           | UT/local[2]      | 0 (local)              |
   | 313    | 00           | UT/local[3]      | 0 (local)              |
   | 314    | 01           | UT/local[4]      | 1 (UT)                 |
   | 315    | 00           | UT/local[5]      | 0 (local)              |
   |        |              |                  |                        |
   | 316    | 00           | standard/wall[0] | 0 (wall)               |
   | 317    | 00           | standard/wall[1] | 0 (wall)               |
   | 318    | 00           | standard/wall[2] | 0 (wall)               |
   | 319    | 00           | standard/wall[3] | 0 (wall)               |
   | 320    | 01           | standard/wall[4] | 1 (standard)           |
   | 321    | 00           | standard/wall[5] | 0 (wall)               |
   |        |              |                  |                        |
   | 322    | 0a           | NL               | '\n'                   |
   | 323    | 48 53 54 31  | TZ string        | "HST10"                |
   |        | 30           |                  |                        |
   | 328    | 0a           | NL               | '\n'                   |
   +--------+--------------+------------------+------------------------+

Okay, so to figure out the local time in this zone for 1933-05-04T12:00:00Z (UNIX time = -1156939200), you'd do this 💅:

  1. Find the latest time transition before your time of interest (trans time[1]). 🕰️
  2. Check the matching transition type (trans type[1]) to get the local time type index (2). 🔍
  3. Look at that local time type (localtimetype[2]) to grab the offset from UTC (-09:30), the daylight saving indicator (1 = yes), and the index into the time zone designation strings (8). ✨
  4. Look up the designation string (designations[8] = "HDT"). 🎀
  5. Add the UTC offset to your time of interest and you get 1933-05-04T02:30:00-09:30 (HDT). 🌸

Now for 2019-01-01T00:00:00Z (UNIX time = 1546300800), it's a whole different vibe 😭:

  1. Find the latest time transition before your time of interest. Spoiler: there isn't one 🙈
  2. Look at the TZ string in the footer ("HST10"). This tells you the designation is "HST" all year round, and the offset to UTC is 10:00. 🦋
  3. Subtract the UTC offset from your time of interest and you land on 2018-12-31T14:00:00-10:00 (HST). 💖

B.3. Truncated Version 3 File Representing Asia/Jerusalem

Next up is a version 3 file that's been chopped off to start on 2038-01-01T00:00:00Z. It's giving main character energy of a future-proof timezone 🧚

   +--------+--------------+------------------+------------------------+
   | File   | Hexadecimal  | Record Name /    | Field Value            |
   | Offset | Octets       | Field Name       |                        |
   +--------+--------------+------------------+------------------------+
   | 000    | 54 5a 69 66  | magic            | "TZif"                 |
   | 004    | 33           | version          | '3' (3)                |
   | 005    | 00 00 00 00  |                  |                        |
   |        | 00 00 00 00  |                  |                        |
   |        | 00 00 00 00  |                  |                        |
   |        | 00 00 00     |                  |                        |
   | 020    | 00 00 00 00  | isutccnt         | 0                      |
   | 024    | 00 00 00 00  | isstdcnt         | 0                      |
   | 028    | 00 00 00 00  | isleapcnt        | 0                      |
   | 032    | 00 00 00 00  | timecnt          | 0                      |
   | 036    | 00 00 00 00  | typecnt          | 0                      |
   | 040    | 00 00 00 00  | charcnt          | 0                      |
   |        |              |                  |                        |
   | 044    | 54 5a 69 66  | magic            | "TZif"                 |
   | 048    | 33           | version          | '3' (3)                |
   | 049    | 00 00 00 00  |                  |                        |
   |        | 00 00 00 00  |                  |                        |
   |        | 00 00 00 00  |                  |                        |
   |        | 00 00 00     |                  |                        |
   | 064    | 00 00 00 03  | isutccnt         | 1                      |
   | 068    | 00 00 00 03  | isstdcnt         | 1                      |
   | 072    | 00 00 00 00  | isleapcnt        | 0                      |
   | 076    | 00 00 00 03  | timecnt          | 1                      |
   | 080    | 00 00 00 03  | typecnt          | 1                      |
   | 084    | 00 00 00 08  | charcnt          | 4                      |
   |        |              |                  |                        |
   | 088    | 00 00 00 00  | trans time[0]    | 2145916800             |
   |        | 7f e8 17 80  |                  | (2038-01-01T00:00:00Z) |
   |        |              |                  |                        |
   | 096    | 00           | trans type[0]    | 0                      |
   |        |              |                  |                        |
   |        |              | localtimetype[0] |                        |
   | 097    | 00 00 1c 20  | utcoff           | 7200 (+02:00)          |
   | 101    | 00           | isdst            | 0 (no)                 |
   | 102    | 00           | desigidx         | 0                      |
   |        |              |                  |                        |
   | 103    | 49 53 54 00  | designations[0]  | "IST"                  |
   |        |              |                  |                        |
   | 107    | 01           | UT/local[0]      | 1 (UT)                 |
   |        |              |                  |                        |
   | 108    | 01           | standard/wall[0] | 1 (standard)           |
   |        |              |                  |                        |
   | 109    | 0a           | NL               | '\n'                   |
   | 110    | 49 53 54 2d  | TZ string        | "IST-2IDT,             |
   |        | 32 49 44 54  |                  | M3.4.4/26,M10.5.0"     |
   |        | 2c 4d 33 2e  |                  |                        |
   |        | 34 2e 34 2f  |                  |                        |
   |        | 32 36 2c 4d  |                  |                        |
   |        | 31 30 2e 35  |                  |                        |
   |        | 2e 30        |                  |                        |
   | 136    | 0a           | NL               | '\n'                   |
   +--------+--------------+------------------+------------------------+

Acknowledgments

Huge thanks to these legends for contributing their ideas and support while the authors were writing this spec: Michael Douglass, Ned Freed, Guy Harris, Eliot Lear, and Alexey Melnikov. 🫶🌈

Authors' Addresses

Arthur David Olson

Email: arthurdavidolson@gmail.com

Paul Eggert University of California, Los Angeles

Email: eggert@cs.ucla.edu

Kenneth Murchison FastMail US LLC

Email: murch@fastmailteam.com

That's the whole thing, bestie! 💜 The authors are right there if you want to say hi. ✨

📦 where this page comes from