"Fossies" - the Fresh Open Source Software Archive

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

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

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