TZFILE(5) | File Formats Manual | TZFILE(5) |
tzfile
— time zone
information
The timezone information files used by
tzset(3) are typically found
under a directory with a name like
/usr/share/zoneinfo. These files use the format
described in Internet RFC
9536. Each file is a sequence of 8-bit bytes. In a file, a
binary integer is represented by a sequence of one or more bytes in network
order (bigendian, or high-order byte first), with all bits significant, a
signed binary integer is represented using two's complement, and a boolean
is represented by a one-byte binary integer that is either
0
(false) or 1
(true).
NUL
, or “3”, or “4
).”struct ttinfo { int32_t tt_uttoff; unsigned char tt_isdst; unsigned char tt_desigind; };
Each structure is written as a four-byte signed integer
value for tt_gmtoff in a network byte order,
followed by a one-byte value for tt_isdst and
a one-byte value for tt_desigidx. In each
structure, tt_gmtoff gives the number of
seconds to be added to UT, tt_isdst tells
whether tm_isdst should be set by
localtime(3) and
tt_desigidx serves as an index into the array
of timezone abbreviation bytes that follow the
ttinfo structure(s) in the file. entries in
the file; if the designated string is “\*-00”, the
ttinfo entry is a placeholder indicating that
local time is unspecified. The tt_utoff +value
is never equal to -2**31, to let 32-bit clients negate it without
overflow. Also, in realistic applications
tt_utoff is in the range [-89999, 93599]
(i.e., more than -25 hours and less than 26 hours); this allows easy
support by implementations that already support the POSIX-required
range [-24:59:59
,
25:59:59
].
1
for
a positive leap second, or -1
for a negative
leap second. If the leap second table is empty, the leap-second
correction is zero for all timestamps; otherwise, for timestamps
before the first occurrence time, the leap-second correction is zero
if the first pair's correction is 1
or
-1
, and is unspecified otherwise (which can
happen only in files truncated at the start).The standard/wall and UT/local indicators were designed
for transforming a TZif file's transition times into transitions
appropriate for another time zone specified via a proleptic TZ
string that lacks rules. For example, when
TZ="EET2EEST"
and there is no TZif
file “EET2EEST”, the idea was to adapt the transition
times from a TZif file with the well-known name
"posixrules" that is present only for this purpose and is
a copy of the file “Europe/Brussels”, a file with a
different UT offset. POSIX does not specify the details of this
obsolete transformational behavior, the default rules are
installation-dependent, and no implementation is known to support
this feature for timestamps past 2037
, so
users desiring (say) Greek time should instead specify
TZ="Europe/Athens"
for better
historical coverage, falling back on
TZ="EET2EEST,M3.5.0/3,M10.5.0/4"
if POSIX conformance is required and older timestamps need not be
handled accurately.
The localtime(3) function normally uses the first ttinfo structure in the file if either tzh_timecnt is zero or the time argument is less than the first transition time recorded in the file.
For version-2-format timezone files, the above header and data are followed by a second header and data, identical in format except that eight bytes are used for each transition time or leap second time. (Leap second counts remain four bytes.) After the second header and data comes a newline-enclosed string in the style of the contents of a proleptic TZ, for use in handling instants after the last transition time stored in the file or for all instants if the file has no transitions. The TZ string is empty (i.e., nothing between the newlines) if there is no proleptic representation for such instants. If non-empty, the TZ string must agree with the local time type after the last transition time if present in the eight-byte data; for example, given the string “WET0WEST,M3.5.0/1,M10.5.0” then if a last transition time is in July, the transition's local time type must specify a daylight-saving time abbreviated “WEST” that is one hour east of UT. Also, if there is at least one transition, time type 0 is associated with the time period from the indefinite past up to but not including the earliest transition time.
For version-3-format timezone files, a TZ string (see tzset(3) may use the following POSIX.1-2024 extensions to POSIX.1-2017: First, as in TZ="<02>2<01>,M3.5.0/1,M10.5.0/0", the hours part of its transition times may be signed and range from -167 through 167 instead of being limited to unsigned values from 0 through 24. Second, as in TZ="XXX3EDT4,0/0,J365/23", DST is 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.
For version-4-format TZif files, the first leap second record can
have a correction that is neither +1
nor
-1
, to represent truncation of the TZif file at the
start. Also, if two or more leap second transitions are present and the last
entry's correction equals the previous one, the last entry denotes the
expiration of the leap second table instead of a leap second; timestamps
after this expiration are unreliable in that future releases will likely add
leap second entries after the expiration, and the added leap seconds will
change how post-expiration timestamps are treated.
Version 1 files are considered a legacy format and should not be generated, as they do not support transition times after the year 2038. Readers that understand only Version 1 must ignore any data that extends beyond the calculated end of the version 1 data block. Other than version 1, writers should generate the lowest version number needed by a file's data. For example, a writer should generate a version 4 file only if its leap second table either expires or is truncated at the start. Likewise, a writer not generating a version 4 file should generate a version 3 file only if TZ string extensions are necessary to accurately model transition times.
The sequence of time changes defined by the version 1 header and
data block should be a contiguous sub-sequence of the time changes defined
by the version 2+ header and data block, and by the footer. This guideline
helps obsolescent version 1 readers agree with current readers about
timestamps within the contiguous sub-sequence. It also lets writers not
supporting obsolescent readers use a tzh_timecnt
of
zero in the version 1 data block to save space.
When a TZif file contains a leap second table expiration time, TZif readers should either refuse to process post-expiration timestamps, or process them as if the expiration time did not exist (possibly with an error indication).
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 higher file, readers should ignore the version 1 header and data block except for the purpose of skipping over them.
Readers 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 positive leap second occurs, readers should append an extra second to the local minute containing the second just before the leap second. If this occurs when the UTC offset is not a multiple of 60 seconds, the leap second occurs earlier than the last second of the local minute and the minute's remaining local seconds are numbered through 60 instead of the usual 59; the UTC offset is unaffected.
This section documents common problems in reading or writing TZif files. Most of these are problems in generating TZif files for use by older readers. The goals of this section are to help:
+When new versions of the TZif format have been defined, a design goal has been 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 complete compatibility was not achieved, an attempt was made to limit glitches to rarely used timestamps and allow simple partial workarounds in writers designed to generate newer-version data useful even for older-version readers. This section attempts to document these compatibility issues and workarounds, as well as to document other common bugs in readers.
Interoperability problems with TZif include the following:
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 interoperability problems are reader bugs that are listed here mostly as warnings to developers of readers.
ctime(3), localtime(3), time(3), tzset(3), zdump(8), zic(8).
%U https://www.rfc-editor.org/rfc/rfc9636 %U https://doi.org/10.17487/RFC9536 %R RFC 9536 Olson A, Eggert P, Murchison K., The Time Zone Information Format (TZif)., October 2024..
September 10, 2024 | NetBSD 10.99 |