diff options
Diffstat (limited to 'tzfile.5.txt')
| -rw-r--r-- | tzfile.5.txt | 398 |
1 files changed, 203 insertions, 195 deletions
diff --git a/tzfile.5.txt b/tzfile.5.txt index ed1763ae956b..7ebcf5a35b88 100644 --- a/tzfile.5.txt +++ b/tzfile.5.txt @@ -24,276 +24,284 @@ DESCRIPTION o Six four-byte integer values, in the following order: - tzh_ttisutcnt - The number of UT/local indicators stored in the file. (UT - is Universal Time.) + tzh_ttisutcnt + The number of UT/local indicators stored in the file. (UT is + Universal Time.) - tzh_ttisstdcnt - The number of standard/wall indicators stored in the file. + tzh_ttisstdcnt + The number of standard/wall indicators stored in the file. - tzh_leapcnt - The number of leap seconds for which data entries are stored - in the file. + tzh_leapcnt + The number of leap seconds for which data entries are stored + in the file. - tzh_timecnt - The number of transition times for which data entries are - stored in the file. + tzh_timecnt + The number of transition times for which data entries are + stored in the file. - tzh_typecnt - The number of local time types for which data entries are - stored in the file (must not be zero). + tzh_typecnt + The number of local time types for which data entries are + stored in the file (must not be zero). - tzh_charcnt - The number of bytes of time zone abbreviation strings stored - in the file. + tzh_charcnt + The number of bytes of time zone abbreviation strings stored + in the file. - The above header is followed by the following fields, whose lengths - depend on the contents of the header: + The above header is followed by the following fields, whose lengths + depend on the contents of the header: - o tzh_timecnt four-byte signed integer values sorted in ascending - order. These values are written in network byte order. Each is - used as a transition time (as returned by time(2)) at which the - rules for computing local time change. + o tzh_timecnt four-byte signed integer values sorted in ascending + order. These values are written in network byte order. Each is + used as a transition time (as returned by time(2)) at which the + rules for computing local time change. - o tzh_timecnt one-byte unsigned integer values; each one but the - last tells which of the different types of local time types - described in the file is associated with the time period - starting with the same-indexed transition time and continuing up - to but not including the next transition time. (The last time - type is present only for consistency checking with the - POSIX.1-2017-style TZ string described below.) These values - serve as indices into the next field. + o tzh_timecnt one-byte unsigned integer values; each one but the + last tells which of the different types of local time types + described in the file is associated with the time period starting + with the same-indexed transition time and continuing up to but not + including the next transition time. (The last time type is + present only for consistency checking with the proleptic TZ string + described below.) These values serve as indices into the next + field. - o tzh_typecnt ttinfo entries, each defined as follows: + o tzh_typecnt ttinfo entries, each defined as follows: - struct ttinfo { - int32_t tt_utoff; - unsigned char tt_isdst; - unsigned char tt_desigidx; - }; + struct ttinfo { + int32_t tt_utoff; + unsigned char tt_isdst; + unsigned char tt_desigidx; + }; - Each structure is written as a four-byte signed integer value - for tt_utoff, in network byte order, followed by a one-byte - boolean for tt_isdst and a one-byte value for tt_desigidx. In - each structure, tt_utoff 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 time zone abbreviation bytes that follow the ttinfo 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]. + Each structure is written as a four-byte signed integer value for + tt_utoff, in network byte order, followed by a one-byte boolean + for tt_isdst and a one-byte value for tt_desigidx. In each + structure, tt_utoff 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 time zone + abbreviation bytes that follow the ttinfo 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]. - o tzh_charcnt bytes that represent time zone designations, which - are null-terminated byte strings, each indexed by the - tt_desigidx values mentioned above. The byte strings can - overlap if one is a suffix of the other. The encoding of - these strings is not specified. + o tzh_charcnt bytes that represent time zone designations, which are + null-terminated byte strings, each indexed by the tt_desigidx + values mentioned above. The byte strings can overlap if one is a + suffix of the other. The encoding of these strings is not + specified. - o tzh_leapcnt pairs of four-byte values, written in network byte - order; the first value of each pair gives the nonnegative time - (as returned by time(2)) at which a leap second occurs or at - which the leap second table expires; the second is a signed - integer specifying the correction, which is the total number - of leap seconds to be applied during the time period starting - at the given time. The pairs of values are sorted in strictly - ascending order by time. Each pair denotes one leap second, - either positive or negative, except that if the last pair has - the same correction as the previous one, the last pair denotes - the leap second table's expiration time. Each leap second is - at the end of a UTC calendar month. The first leap second has - a nonnegative occurrence time, and is a positive leap second - if and only if its correction is positive; the correction for - each leap second after the first differs from the previous - leap second by either 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). + o tzh_leapcnt pairs of four-byte values, written in network byte + order; the first value of each pair gives the nonnegative time (as + returned by time(2)) at which a leap second occurs or at which the + leap second table expires; the second is a signed integer + specifying the correction, which is the total number of leap + seconds to be applied during the time period starting at the given + time. The pairs of values are sorted in strictly ascending order + by time. Each pair denotes one leap second, either positive or + negative, except that if the last pair has the same correction as + the previous one, the last pair denotes the leap second table's + expiration time. Each leap second is at the end of a UTC calendar + month. The first leap second has a nonnegative occurrence time, + and is a positive leap second if and only if its correction is + positive; the correction for each leap second after the first + differs from the previous leap second by either 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). - o tzh_ttisstdcnt standard/wall indicators, each stored as a one- - byte boolean; they tell whether the transition times - associated with local time types were specified as standard - time or local (wall clock) time. + o tzh_ttisstdcnt standard/wall indicators, each stored as a one-byte + boolean; they tell whether the transition times associated with + local time types were specified as standard time or local (wall + clock) time. - o tzh_ttisutcnt UT/local indicators, each stored as a one-byte - boolean; they tell whether the transition times associated - with local time types were specified as UT or local time. If - a UT/local indicator is set, the corresponding standard/wall - indicator must also be set. + o tzh_ttisutcnt UT/local indicators, each stored as a one-byte + boolean; they tell whether the transition times associated with + local time types were specified as UT or local time. If a + UT/local indicator is set, the corresponding standard/wall + indicator must also be set. - 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 - POSIX.1-2017-style TZ string that lacks rules. For example, when - TZ="EET-2EEST" and there is no TZif file "EET-2EEST", 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 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="EET-2EEST,M3.5.0/3,M10.5.0/4" if POSIX conformance is required - and older timestamps need not be handled accurately. + 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="EET-2EEST" and there is no + TZif file "EET-2EEST", 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="EET-2EEST,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. + 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. Version 2 format - 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 - POSIX.1-2017 TZ environment variable, 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 POSIX.1-2017-style representation - for such instants. If nonempty, 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-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 nonempty, 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. Version 3 format - For version-3-format timezone files, the TZ string may use two minor - extensions to the POSIX.1-2017 TZ format, as described in newtzset(3). - First, the hours part of its transition times may be signed and range - from -167 through 167 instead of the POSIX-required unsigned values - from 0 through 24. Second, DST is in effect all year if it starts - January 1 at 00:00 and ends December 31 at 24:00 plus the difference + For version-3-format timezone files, a TZ string (see newtzset(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. Version 4 format - 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 + 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. Interoperability considerations Future changes to the format may append more data. - Version 1 files are considered a legacy format and should not be + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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. Common interoperability issues - This section documents common problems in reading or writing TZif - files. Most of these are problems in generating TZif files for use by + 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: - o to help TZif writers output files that avoid common pitfalls in + o to help TZif writers output files that avoid common pitfalls in older or buggy TZif readers, - o to help TZif readers avoid common pitfalls when reading files + o to help TZif readers avoid common pitfalls when reading files generated by future TZif writers, and o 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, 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 new-version data useful - even for older-version readers. This section attempts to document - these compatibility issues and workarounds, as well as to document + 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 new-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: - o 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 - should use version 2+ data even if the reader's native timestamps + o 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 + should use version 2+ data even if the reader's native timestamps have only 32 bits. - o Some readers designed for version 2 might mishandle timestamps - after a version 3 or higher file's last transition, because they - cannot parse extensions to POSIX.1-2017 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. + o Some readers designed for version 2 might mishandle timestamps + after a version 3 or higher file's last transition, because they + cannot parse the POSIX.1-2024 extensions to POSIX.1-2017 in the + proleptic TZ 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. - o Some readers designed for version 2 do not support permanent - daylight saving time with transitions after 24:00 - e.g., a TZ - string "EST5EDT,0/0,J365/25" denoting permanent Eastern Daylight - Time (-04). As a workaround, a writer can substitute standard - time for two time zones east, e.g., "XXX3EDT4,0/0,J365/23" for a - time zone with a never-used standard time (XXX, -03) and negative - daylight saving time (EDT, -04) all year. Alternatively, as a - partial workaround a writer can substitute standard time for the + o Some readers designed for version 2 do not support permanent + daylight saving time with transitions after 24:00 - e.g., a TZ + string "EST5EDT,0/0,J365/25" denoting permanent Eastern Daylight + Time (-04). As a workaround, a writer can substitute standard + time for two time zones east, e.g., "XXX3EDT4,0/0,J365/23" for a + time zone with a never-used standard time (XXX, -03) and negative + daylight saving time (EDT, -04) all year. Alternatively, 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). - o Some readers designed for version 2 or 3, and that require strict - conformance to RFC 8536, reject version 4 files whose leap second + o Some readers designed for version 2 or 3, and that require strict + conformance to RFC 8536, reject version 4 files whose leap second tables are truncated at the start or that end in expiration times. o 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 + timestamps from the time type of the last transition. As a + partial workaround, a writer can output more transitions than necessary. + o Some stripped-down readers ignore everything but the footer, and + use its proleptic TZ string to calculate all timestamps. Although + this approach often works for current and future timestamps, it + obviously has problems with past timestamps, and even for current + timestamps it can fail for settings like TZ="Africa/Casablanca". + This corresponds to a TZif file containing explicit transitions + through the year 2087, followed by a footer containing the TZ + string "<+01>-1", which should be used only for timestamps after + the last explicit transition. + o 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, |