This just changes documentation: it does not change code or data. Mostly, it just adopts more terminology from RFC 8536. It also contains an example of what the std/wall and UT/local indicators are for. * newtzset.3, theory.html, tz-how-to.html, tzfile.5, tzfile.h, zic.8: In documentation and comments, make it clearer that local time equals wall clock time. * tzfile.5, tzfile.h: In documentation and comments, say that when isut is 1, isstd must also be 1. * tzfile.5: Specify that bytes are 8 bits, that binary integers use two's complement, and that booleans use 0 and 1. Say that UT offsets are never equal to -2**31, and that they realistically are in the range [-89999, 93599]. Say that leap second counts are signed. Say why std/wall and UT/local indicators are present, and give AKST9AKDT as an example. Do not say that the first standard-time ttinfo is used by localtime, as the actual heuristic is far more complicated; instead, document what RFC 8536 says as what's normally used. * zic.c (struct rule): Adjust comments. --- newtzset.3 | 4 ++-- theory.html | 10 ++++---- tz-how-to.html | 14 ++++++------ tzfile.5 | 62 +++++++++++++++++++++++++++++++++----------------- tzfile.h | 15 ++++++------ zic.8 | 16 ++++++------- zic.c | 6 ++--- 7 files changed, 73 insertions(+), 54 deletions(-) diff --git a/newtzset.3 b/newtzset.3 index 29e8a21..4959851 100644 --- a/newtzset.3 +++ b/newtzset.3 @@ -65,8 +65,8 @@ falls back on Universal Time (UT). .PP If .B TZ -is null, the best available approximation to local wall -clock time, as specified by the +is null, the best available approximation to local (wall +clock) time, as specified by the .IR tzfile (5)-format file .B localtime diff --git a/theory.html b/theory.html index e580ccc..61d556b 100644 --- a/theory.html +++ b/theory.html @@ -955,7 +955,7 @@ an older <code>zic</code>. </li> <li> In POSIX, there is no tamper-proof way for a process to learn the - system's best idea of local wall clock. + system's best idea of local (wall clock) time. This is important for applications that an administrator wants used only at certain times – without regard to whether the user has fiddled the @@ -1052,14 +1052,14 @@ an older <code>zic</code>. </li> <li> A function <code>tzsetwall</code> has been added to arrange for the - system's best approximation to local wall clock time to be delivered + system's best approximation to local (wall clock) time to be delivered by subsequent calls to <code>localtime</code>. - Source code for portable applications that "must" run on local wall - clock time should call <code>tzsetwall</code>; + Source code for portable applications that "must" run on local + time should call <code>tzsetwall</code>; if such code is moved to "old" systems that do not provide <code>tzsetwall</code>, you will not be able to generate an executable program. - (These functions also arrange for local wall clock time to + (These functions also arrange for local time to be used if <code>tzset</code> is called – directly or indirectly – and there is no <code>TZ</code> environment variable; portable applications should not, however, rely on this diff --git a/tz-how-to.html b/tz-how-to.html index 7274af4..2e4842d 100644 --- a/tz-how-to.html +++ b/tz-how-to.html @@ -102,7 +102,7 @@ in some localizable way. It’s used in the file, <code>pacificnew</code>, to determine whether a given year will have a US presidential election; but everything related to that use is commented out.) -<p>The <code>SAVE</code> column contains the wall clock offset from +<p>The <code>SAVE</code> column contains the local (wall clock) offset from local standard time. This is usually either zero for standard time or one hour for daylight saving time; but there’s no reason, in principle, why it can’t @@ -250,10 +250,10 @@ Rule US 2007 max - Nov Sun>=1 2:00 0 S <p>There are two interesting things to note here.</p> <p>First, the time that something happens (in the <code>AT</code> -column) is not necessarily the local wall clock time. The time can be +column) is not necessarily the local (wall clock) time. The time can be suffixed with ‘s’ (for “standard”) to mean -local standard time (different from wall clock time when observing -daylight saving time); or it can be suffixed with ‘g’, +local standard time, different from local (wall clock) time when observing +daylight saving time; or it can be suffixed with ‘g’, ‘u’, or ‘z’, all three of which mean the standard time at the <a href="https://en.wikipedia.org/wiki/Prime_Meridian">prime meridian</a>. @@ -265,8 +265,8 @@ href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a>&rdquo; (whichever was official at the time); ‘z’ stands for the <a href="https://en.wikipedia.org/wiki/Nautical_time">nautical time zone</a> Z (a.k.a. “Zulu” which, in turn, stands for ‘Z’). -The time can also be suffixed with ‘w’ meaning “wall -clock time;” but it usually isn’t because that’s the +The time can also be suffixed with ‘w’ meaning local (wall +clock) time; but it usually isn’t because that’s the default.</p> <p>Second, the day in the <code>ON</code> column, in addition to @@ -467,7 +467,7 @@ Zone Pacific/Honolulu ... 1933 Apr 30 2:00 <p>Hawaii tried daylight saving time for three weeks in 1933 and decided they didn’t like it. <code>8-) </code>Note that the <code>STDOFF</code> column always contains the standard time -offset, so the wall clock time during this period was GMT − +offset, so the local (wall clock) time during this period was GMT − 10:30 + 1:00 = GMT − 9:30.</p> <p>The <code>FORMAT</code> column specifies the usual abbreviation of diff --git a/tzfile.5 b/tzfile.5 index b591e56..d13029c 100644 --- a/tzfile.5 +++ b/tzfile.5 @@ -16,6 +16,13 @@ The timezone information files used by are typically found under a directory with a name like .IR /usr/share/zoneinfo . These files use the format described in Internet RFC 8536. +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). The format begins with a 44-byte header containing the following fields: .IP * 2 The magic four-byte ASCII sequence @@ -30,11 +37,7 @@ or .IP * Fifteen bytes containing zeros reserved for future use. .IP * -Six four-byte integer values -written in a standard byte order -(the high-order byte of the value is written first). -These values are, -in order: +Six four-byte integer values, in the following order: .RS .TP .I tzh_ttisutcnt @@ -64,7 +67,7 @@ depend on the contents of the header: .IP * 2 .I tzh_timecnt four-byte signed integer values sorted in ascending order. -These values are written in standard byte order. +These values are written in network byte order. Each is used as a transition time (as returned by .BR time (2)) at which the rules for computing local time change. @@ -96,7 +99,7 @@ struct ttinfo { .sp Each structure is written as a four-byte signed integer value for .IR tt_utoff , -in a standard byte order, followed by a one-byte value for +in network byte order, followed by a one-byte boolean for .I tt_isdst and a one-byte value for .IR tt_desigidx . @@ -114,14 +117,23 @@ serves as an index into the array of time zone abbreviation bytes that follow the .I ttinfo structure(s) in the file. +The +.I tt_utoff +value is never equal to -2**31, to let 32-bit clients negate it without +overflow. +Also, in realistic applications +.I 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]. .IP * .I tzh_leapcnt -pairs of four-byte values, written in standard byte order; +pairs of four-byte values, written in network byte order; the first value of each pair gives the nonnegative time (as returned by .BR time (2)) at which a leap second occurs; -the second gives the +the second is a signed integer specifying the .I total number of leap seconds to be applied during the time period starting at the given time. @@ -130,28 +142,36 @@ Each transition is for one leap second, either positive or negative; transitions always separated by at least 28 days minus 1 second. .IP * .I tzh_ttisstdcnt -standard/wall indicators, each stored as a one-byte value; +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 wall clock time, -and are used when a timezone file is used in handling POSIX-style -timezone environment variables. +were specified as standard time or local (wall clock) time. .IP * .I tzh_ttisutcnt -UT/local indicators, each stored as a one-byte value; +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, -and are used when a timezone file is used in handling POSIX-style -timezone environment variables. +were specified as UT or local time. +If a UT/local indicator is set, the corresponding standard/wall indicator +must also be set. +.PP +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-style TZ string that lacks rules. +For example, when TZ="AKST9AKDT" and there is no TZif file "AKST9AKDT", +the transition times might be adapted from a TZif file with the +well-known name "posixrules" that is present only for this purpose and +is a copy of the file "America/New_York", a file with a different UT offset. +POSIX does not specify this obsolescent transformational behavior and +widely used platforms such as GNU/Linux do not support it correctly, so users +desiring Alaska time should specify TZ="America/Anchorage" for better +historical coverage, or TZ="AKST9AKDT,M3.2.0,M11.1.0" for POSIX +conformance and coverage for recent timestamps only. .PP The .BR localtime (3) function -uses the first standard-time +normally uses the first .I ttinfo structure in the file -(or simply the first -.I ttinfo -structure in the absence of a standard-time structure) if either .I tzh_timecnt is zero or the time argument is less than the first transition time recorded diff --git a/tzfile.h b/tzfile.h index 52673d6..ee91104 100644 --- a/tzfile.h +++ b/tzfile.h @@ -69,14 +69,15 @@ struct tzhead { ** one (char [4]) total correction after above ** tzh_ttisstdcnt (char)s indexed by type; if 1, transition ** time is standard time, if 0, -** transition time is wall clock time -** if absent, transition times are -** assumed to be wall clock time -** tzh_ttisutcnt (char)s indexed by type; if 1, transition -** time is UT, if 0, -** transition time is local time -** if absent, transition times are +** transition time is local (wall clock) +** time; if absent, transition times are ** assumed to be local time +** tzh_ttisutcnt (char)s indexed by type; if 1, transition +** time is UT, if 0, transition time is +** local time; if absent, transition +** times are assumed to be local time. +** When this is 1, the corresponding +** std/wall indicator must also be 1. */ /* diff --git a/zic.8 b/zic.8 index 02b6048..3a4d96f 100644 --- a/zic.8 +++ b/zic.8 @@ -385,13 +385,12 @@ to other applications requiring greater precision. The source format does not specify any maximum precision. Any of these forms may be followed by the letter .B w -if the given time is local +if the given time is local or .q "wall clock" time, .B s -if the given time is local -.q "standard" -time, or +if the given time is standard time without any adjustment for daylight saving, +or .B u (or .B g @@ -399,7 +398,7 @@ or .BR z ) if the given time is universal time; in the absence of an indicator, -wall clock time is assumed. +local (wall clock) time is assumed. These forms ignore leap seconds; for example, if a leap second occurs at 00:59:60 local time, .q "1:00" @@ -478,7 +477,8 @@ a file name component is a maximal substring that does not contain .q "/" . .TP .B STDOFF -The amount of time to add to UT to get standard time. +The amount of time to add to UT to get standard time, +without any adjustment for daylight saving. This field has the same format as the .B AT and @@ -636,7 +636,7 @@ or (an abbreviation of) .q "Rolling" if the leap second time given by the other fields should be interpreted as -local wall clock time. +local (wall clock) time. .SH "EXTENDED EXAMPLE" Here is an extended example of .B zic @@ -720,7 +720,7 @@ coincides with and is equal to a clock retreat caused by a change in UT offset, .B zic produces a single transition to daylight saving at the new UT offset -(without any change in wall clock time). +without any change in local (wall clock) time. To get separate transitions use multiple zone continuation lines specifying transition instants using universal time. diff --git a/zic.c b/zic.c index b3665bd..3fb32c7 100644 --- a/zic.c +++ b/zic.c @@ -92,10 +92,8 @@ struct rule { int r_wday; zic_t r_tod; /* time from midnight */ - bool r_todisstd; /* above is standard time if 1 */ - /* or wall clock time if 0 */ - bool r_todisut; /* above is GMT if 1 */ - /* or local time if 0 */ + bool r_todisstd; /* is r_tod standard time? */ + bool r_todisut; /* is r_tod UT? */ bool r_isdst; /* is this daylight saving time? */ zic_t r_save; /* offset from standard time */ const char * r_abbrvar; /* variable part of abbreviation */ -- 2.21.0