"Fossies" - the Fresh Open Source Software Archive

Member "tzfile.5.txt" (25 Oct 2018, 14487 Bytes) of package /linux/misc/tzcode2018i.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": 2018f_vs_2018g.

    1 TZFILE(5)                     File Formats Manual                    TZFILE(5)
    2 
    3 NAME
    4        tzfile - timezone information
    5 
    6 DESCRIPTION
    7        The timezone information files used by tzset(3) are typically found
    8        under a directory with a name like /usr/share/zoneinfo.  These files
    9        begin with a 44-byte header containing the following fields:
   10 
   11        * The magic four-byte ASCII sequence "TZif" identifies the file as a
   12          timezone information file.
   13 
   14        * A byte identifying the version of the file's format (as of 2017,
   15          either an ASCII NUL, or "2", or "3").
   16 
   17        * Fifteen bytes containing zeros reserved for future use.
   18 
   19        * Six four-byte integer values written in a standard byte order (the
   20          high-order byte of the value is written first).  These values are, in
   21          order:
   22 
   23          tzh_ttisgmtcnt
   24                 The number of UT/local indicators stored in the file.
   25 
   26          tzh_ttisstdcnt
   27                 The number of standard/wall indicators stored in the file.
   28 
   29          tzh_leapcnt
   30                 The number of leap seconds for which data entries are stored
   31                 in the file.
   32 
   33          tzh_timecnt
   34                 The number of transition times for which data entries are
   35                 stored in the file.
   36 
   37          tzh_typecnt
   38                 The number of local time types for which data entries are
   39                 stored in the file (must not be zero).
   40 
   41          tzh_charcnt
   42                 The number of bytes of time zone abbreviation strings stored
   43                 in the file.
   44 
   45        The above header is followed by the following fields, whose lengths
   46        depend on the contents of the header:
   47 
   48        * tzh_timecnt four-byte signed integer values sorted in ascending
   49          order.  These values are written in standard byte order.  Each is
   50          used as a transition time (as returned by time(2)) at which the rules
   51          for computing local time change.
   52 
   53        * tzh_timecnt one-byte unsigned integer values; each one but the last
   54          tells which of the different types of local time types described in
   55          the file is associated with the time period starting with the same-
   56          indexed transition time and continuing up to but not including the
   57          next transition time.  (The last time type is present only for
   58          consistency checking with the POSIX-style TZ string described below.)
   59          These values serve as indices into the next field.
   60 
   61        * tzh_typecnt ttinfo entries, each defined as follows:
   62 
   63               struct ttinfo {
   64                    int32_t        tt_gmtoff;
   65                    unsigned char  tt_isdst;
   66                    unsigned char  tt_abbrind;
   67               };
   68 
   69          Each structure is written as a four-byte signed integer value for
   70          tt_gmtoff, in a standard byte order, followed by a one-byte value for
   71          tt_isdst and a one-byte value for tt_abbrind.  In each structure,
   72          tt_gmtoff gives the number of seconds to be added to UT, tt_isdst
   73          tells whether tm_isdst should be set by localtime(3) and tt_abbrind
   74          serves as an index into the array of time zone abbreviation bytes
   75          that follow the ttinfo structure(s) in the file.
   76 
   77        * tzh_leapcnt pairs of four-byte values, written in standard byte
   78          order; the first value of each pair gives the nonnegative time (as
   79          returned by time(2)) at which a leap second occurs; the second gives
   80          the total number of leap seconds to be applied during the time period
   81          starting at the given time.  The pairs of values are sorted in
   82          ascending order by time.  Each transition is for one leap second,
   83          either positive or negative; transitions always separated by at least
   84          28 days minus 1 second.
   85 
   86        * tzh_ttisstdcnt standard/wall indicators, each stored as a one-byte
   87          value; they tell whether the transition times associated with local
   88          time types were specified as standard time or wall clock time, and
   89          are used when a timezone file is used in handling POSIX-style
   90          timezone environment variables.
   91 
   92        * tzh_ttisgmtcnt UT/local indicators, each stored as a one-byte value;
   93          they tell whether the transition times associated with local time
   94          types were specified as UT or local time, and are used when a
   95          timezone file is used in handling POSIX-style timezone environment
   96          variables.
   97 
   98        The localtime(3) function uses the first standard-time ttinfo structure
   99        in the file (or simply the first ttinfo structure in the absence of a
  100        standard-time structure) if either tzh_timecnt is zero or the time
  101        argument is less than the first transition time recorded in the file.
  102 
  103    Version 2 format
  104        For version-2-format timezone files, the above header and data are
  105        followed by a second header and data, identical in format except that
  106        eight bytes are used for each transition time or leap second time.
  107        (Leap second counts remain four bytes.)  After the second header and
  108        data comes a newline-enclosed, POSIX-TZ-environment-variable-style
  109        string for use in handling instants after the last transition time
  110        stored in the file or for all instants if the file has no transitions.
  111        The POSIX-style TZ string is empty (i.e., nothing between the newlines)
  112        if there is no POSIX representation for such instants.  If nonempty,
  113        the POSIX-style TZ string must agree with the local time type after the
  114        last transition time if present in the eight-byte data; for example,
  115        given the string "WET0WEST,M3.5.0,M10.5.0/3" then if a last transition
  116        time is in July, the transition's local time type must specify a
  117        daylight-saving time abbreviated "WEST" that is one hour east of UT.
  118        Also, if there is at least one transition, time type 0 is associated
  119        with the time period from the indefinite past up to but not including
  120        the earliest transition time.
  121 
  122    Version 3 format
  123        For version-3-format timezone files, the POSIX-TZ-style string may use
  124        two minor extensions to the POSIX TZ format, as described in
  125        newtzset(3).  First, the hours part of its transition times may be
  126        signed and range from -167 through 167 instead of the POSIX-required
  127        unsigned values from 0 through 24.  Second, DST is in effect all year
  128        if it starts January 1 at 00:00 and ends December 31 at 24:00 plus the
  129        difference between daylight saving and standard time.
  130 
  131    Interoperability considerations
  132        Future changes to the format may append more data.
  133 
  134        Version 1 files are considered a legacy format and should be avoided,
  135        as they do not support transition times after the year 2038.  Readers
  136        that only understand Version 1 must ignore any data that extends beyond
  137        the calculated end of the version 1 data block.
  138 
  139        Writers should generate a version 3 file if TZ string extensions are
  140        necessary to accurately model transition times.  Otherwise, version 2
  141        files should be generated.
  142 
  143        The sequence of time changes defined by the version 1 header and data
  144        block should be a contiguous subsequence of the time changes defined by
  145        the version 2+ header and data block, and by the footer.  This
  146        guideline helps obsolescent version 1 readers agree with current
  147        readers about timestamps within the contiguous subsequence.  It also
  148        lets writers not supporting obsolescent readers use a tzh_timecnt of
  149        zero in the version 1 data block to save space.
  150 
  151        Time zone designations should consist of at least three (3) and no more
  152        than six (6) ASCII characters from the set of alphanumerics, "-", and
  153        "+".  This is for compatibility with POSIX requirements for time zone
  154        abbreviations.
  155 
  156        When reading a version 2 or 3 file, readers should ignore the version 1
  157        header and data block except for the purpose of skipping over them.
  158 
  159        Readers should calculate the total lengths of the headers and data
  160        blocks and check that they all fit within the actual file size, as part
  161        of a validity check for the file.
  162 
  163    Common interoperability issues
  164        This section documents common problems in reading or writing TZif
  165        files.  Most of these are problems in generating TZif files for use by
  166        older readers.  The goals of this section are:
  167 
  168        * to help TZif writers output files that avoid common pitfalls in older
  169          or buggy TZif readers,
  170 
  171        * to help TZif readers avoid common pitfalls when reading files
  172          generated by future TZif writers, and
  173 
  174        * to help any future specification authors see what sort of problems
  175          arise when the TZif format is changed.
  176 
  177        When new versions of the TZif format have been defined, a design goal
  178        has been that a reader can successfully use a TZif file even if the
  179        file is of a later TZif version than what the reader was designed for.
  180        When complete compatibility was not achieved, an attempt was made to
  181        limit glitches to rarely-used timestamps, and to allow simple partial
  182        workarounds in writers designed to generate new-version data useful
  183        even for older-version readers.  This section attempts to document
  184        these compatibility issues and workarounds, as well as to document
  185        other common bugs in readers.
  186 
  187        Interoperability problems with TZif include the following:
  188 
  189        * Some readers examine only version 1 data.  As a partial workaround, a
  190          writer can output as much version 1 data as possible.  However, a
  191          reader should ignore version 1 data, and should use version 2+ data
  192          even if the reader's native timestamps have only 32 bits.
  193 
  194        * Some readers designed for version 2 might mishandle timestamps after
  195          a version 3 file's last transition, because they cannot parse
  196          extensions to POSIX in the TZ-like string.  As a partial workaround,
  197          a writer can output more transitions than necessary, so that only
  198          far-future timestamps are mishandled by version 2 readers.
  199 
  200        * Some readers designed for version 2 do not support permanent daylight
  201          saving time, e.g., a TZ string "EST5EDT,0/0,J365/25" denoting
  202          permanent Eastern Daylight Time (-04).  As a partial workaround, a
  203          writer can substitute standard time for the next time zone east,
  204          e.g., "AST4" for permanent Atlantic Standard Time (-04).
  205 
  206        * Some readers ignore the footer, and instead predict future timestamps
  207          from the time type of the last transition.  As a partial workaround,
  208          a writer can output more transitions than necessary.
  209 
  210        * Some readers do not use time type 0 for timestamps before the first
  211          transition, in that they infer a time type using a heuristic that
  212          does not always select time type 0.  As a partial workaround, a
  213          writer can output a dummy (no-op) first transition at an early time.
  214 
  215        * Some readers mishandle timestamps before the first transition that
  216          has a timestamp not less than -2**31.  Readers that support only
  217          32-bit timestamps are likely to be more prone to this problem, for
  218          example, when they process 64-bit transitions only some of which are
  219          representable in 32 bits.  As a partial workaround, a writer can
  220          output a dummy transition at timestamp -2**31.
  221 
  222        * Some readers mishandle a transition if its timestamp has the minimum
  223          possible signed 64-bit value.  Timestamps less than -2**59 are not
  224          recommended.
  225 
  226        * Some readers mishandle POSIX-style TZ strings that contain "<" or
  227          ">".  As a partial workaround, a writer can avoid using "<" or ">"
  228          for time zone abbreviations containing only alphabetic characters.
  229 
  230        * Many readers mishandle time zone abbreviations that contain non-ASCII
  231          characters.  These characters are not recommended.
  232 
  233        * Some readers may mishandle time zone abbreviations that contain fewer
  234          than 3 or more than 6 characters, or that contain ASCII characters
  235          other than alphanumerics, "-", and "+".  These abbreviations are not
  236          recommended.
  237 
  238        * Some readers mishandle TZif files that specify daylight-saving time
  239          UT offsets that are less than the UT offsets for the corresponding
  240          standard time.  These readers do not support locations like Ireland,
  241          which uses the equivalent of the POSIX TZ string
  242          "IST-1GMT0,M10.5.0,M3.5.0/1", observing standard time (IST, +01) in
  243          summer and daylight saving time (GMT, +00) in winter.  As a partial
  244          workaround, a writer can output data for the equivalent of the POSIX
  245          TZ string "GMT0IST,M3.5.0/1,M10.5.0", thus swapping standard and
  246          daylight saving time.  Although this workaround misidentifies which
  247          part of the year uses daylight saving time, it records UT offsets and
  248          time zone abbreviations correctly.
  249 
  250        Some interoperability problems are reader bugs that are listed here
  251        mostly as warnings to developers of readers.
  252 
  253        * Some readers do not support negative timestamps.  Developers of
  254          distributed applications should keep this in mind if they need to
  255          deal with pre-1970 data.
  256 
  257        * Some readers mishandle timestamps before the first transition that
  258          has a nonnegative timestamp.  Readers that do not support negative
  259          timestamps are likely to be more prone to this problem.
  260 
  261        * Some readers mishandle time zone abbreviations like "-08" that
  262          contain "+", "-", or digits.
  263 
  264        * Some readers mishandle UT offsets that are out of the traditional
  265          range of -12 through +12 hours, and so do not support locations like
  266          Kiritimati that are outside this range.
  267 
  268        * Some readers mishandle UT offsets in the range [-3599, -1] seconds
  269          from UT, because they integer-divide the offset by 3600 to get 0 and
  270          then display the hour part as "+00".
  271 
  272        * Some readers mishandle UT offsets that are not a multiple of one
  273          hour, or of 15 minutes, or of 1 minute.
  274 
  275 SEE ALSO
  276        time(2), localtime(3), tzset(3), tzselect(8), zdump(8), zic(8)
  277 
  278                                                                      TZFILE(5)