Improve documentation for the now-approved POSIX.1-2024. It’s not yet published, so continue to hyperlink to POSIX.1-2017 for now, but note that POSIX.1-2017 is no longer the latest edition. --- Makefile | 11 ++- NEWS | 4 ++ etcetera | 2 +- localtime.c | 9 ++- newstrftime.3 | 16 ++--- newtzset.3 | 11 +-- private.h | 5 +- theory.html | 187 +++++++++++++++++++++++++++++++++----------------- tz-link.html | 12 ++-- tzfile.5 | 28 ++++---- tzfile.h | 8 ++- zic.8 | 10 +-- zic.c | 7 +- 13 files changed, 186 insertions(+), 124 deletions(-) diff --git a/Makefile b/Makefile index 344bb8ed..99f2f56b 100644 --- a/Makefile +++ b/Makefile @@ -231,7 +231,7 @@ LDLIBS= # where LDLIBS also needs to contain -lintl on some hosts; # -DHAVE_GETTEXT=0 to avoid using gettext # -DHAVE_INCOMPATIBLE_CTIME_R if your system's time.h declares -# ctime_r and asctime_r incompatibly with POSIX.1-2017 +# ctime_r and asctime_r incompatibly with POSIX.1-2017 and earlier # (Solaris when _POSIX_PTHREAD_SEMANTICS is not defined). # -DHAVE_INTTYPES_H=0 if <inttypes.h> does not work*+ # -DHAVE_LINK=0 if your system lacks a link function @@ -279,7 +279,7 @@ LDLIBS= # -DTZ_DOMAINDIR=\"/path\" to use "/path" for gettext directory; # the default is system-supplied, typically "/usr/lib/locale" # -DTZDEFRULESTRING=\",date/time,date/time\" to default to the specified -# DST transitions for POSIX.1-2017-style TZ strings lacking them, +# DST transitions for proleptic format TZ strings lacking them, # in the usual case where POSIXRULES is '-'. If not specified, # TZDEFRULESTRING defaults to US rules for future DST transitions. # This mishandles some past timestamps, as US DST rules have changed. @@ -347,9 +347,8 @@ GCC_DEBUG_FLAGS = -DGCC_LINT -g3 -O3 \ # Similarly, if your system has a "zone abbreviation" field, define # -DTM_ZONE=tm_zone # and define NO_TM_ZONE to suppress any guessing. -# Although these two fields are not required by POSIX.1-2017, -# POSIX 202x/D4 requires them and they are widely available -# on GNU/Linux and BSD systems. +# Although POSIX.1-2024 requires these fields and they are widely available +# on GNU/Linux and BSD systems, some older systems lack them. # # The next batch of options control support for external variables # exported by tzcode. In practice these variables are less useful @@ -434,7 +433,7 @@ GCC_DEBUG_FLAGS = -DGCC_LINT -g3 -O3 \ # The name of a POSIX-like library archiver, its flags, C compiler, # linker flags, and 'make' utility. Ordinarily the defaults suffice. -# The commented-out values are the defaults specified by POSIX.1-202x/D4. +# The commented-out values are the defaults specified by POSIX.1-2024. #AR = ar #ARFLAGS = -rv #CC = c17 diff --git a/NEWS b/NEWS index 5238cb9e..8f362cb9 100644 --- a/NEWS +++ b/NEWS @@ -76,6 +76,10 @@ Unreleased, experimental changes maintenance. To build on Solaris 10, the only extant system still defaulting to pre-POSIX, prepend /usr/xpg4/bin to PATH. + Changes to documentation + + The documentation now reflects POSIX.1-2024. + Release 2024a - 2024-02-01 09:28:56 -0800 diff --git a/etcetera b/etcetera index a7921169..a5ecd6de 100644 --- a/etcetera +++ b/etcetera @@ -5,7 +5,7 @@ # These entries are for uses not otherwise covered by the tz database. # Their main practical use is for platforms like Android that lack -# support for POSIX.1-2017-style TZ strings. On such platforms these entries +# support for POSIX proleptic TZ strings. On such platforms these entries # can be useful if the timezone database is wrong or if a ship or # aircraft at sea is not in a timezone. diff --git a/localtime.c b/localtime.c index 7e3fd149..7ae9ce5e 100644 --- a/localtime.c +++ b/localtime.c @@ -106,7 +106,7 @@ static char const UNSPEC[] = "-00"; for ttunspecified to work without crashing. */ enum { CHARS_EXTRA = max(sizeof UNSPEC, 2) - 1 }; -/* Limit to time zone abbreviation length in POSIX.1-2017-style TZ strings. +/* Limit to time zone abbreviation length in proleptic TZ strings. This is distinct from TZ_MAX_CHARS, which limits TZif file contents. */ #ifndef TZNAME_MAXIMUM # define TZNAME_MAXIMUM 255 @@ -1024,7 +1024,7 @@ transtime(const int year, register const struct rule *const rulep, } /* -** Given a POSIX.1-2017-style TZ string, fill in the rule tables as +** Given a POSIX.1 proleptic TZ string, fill in the rule tables as ** appropriate. */ @@ -1259,7 +1259,7 @@ tzparse(const char *name, struct state *sp, struct state const *basep) /* ** Transitions from DST to DDST ** will effectively disappear since - ** POSIX.1-2017 provides for only one + ** proleptic TZ strings have only one ** DST offset. */ if (isdst && !sp->ttis[j].tt_ttisstd) { @@ -1428,8 +1428,7 @@ tzfree(timezone_t sp) ** ** If successful and SETNAME is nonzero, ** set the applicable parts of tzname, timezone and altzone; -** however, it's OK to omit this step -** if the timezone is compatible with POSIX.1-2017 +** however, it's OK to omit this step for proleptic TZ strings ** since in that case tzset should have already done this step correctly. ** SETNAME's type is int_fast32_t for compatibility with gmtsub, ** but it is actually a boolean and its value should be 0 or 1. diff --git a/newstrftime.3 b/newstrftime.3 index 704318ea..11e37ae8 100644 --- a/newstrftime.3 +++ b/newstrftime.3 @@ -91,11 +91,11 @@ as specified by brackets in the description. If a bracketed member name is followed by .q + , .B strftime -can use the named member even though POSIX.1-2017 does not list it; +can use the named member even though POSIX.1-2024 does not list it; if the name is followed by .q \*- , .B strftime -ignores the member even though POSIX.1-2017 lists it +ignores the member even though POSIX.1-2024 lists it which means portable code should set it. For portability, .BI * timeptr @@ -137,8 +137,8 @@ is replaced by the locale's appropriate date and time representation. .IR tm_hour , .IR tm_min , .IR tm_sec , -.IR tm_gmtoff +, -.IR tm_zone +, +.IR tm_gmtoff , +.IR tm_zone , .IR tm_isdst \*-]. .TP %D @@ -326,8 +326,8 @@ is replaced by the locale's appropriate time representation. .IR tm_hour , .IR tm_min , .IR tm_sec , -.IR tm_gmtoff +, -.IR tm_zone +, +.IR tm_gmtoff , +.IR tm_zone , .IR tm_isdst \*-]. .TP %x @@ -355,7 +355,7 @@ is replaced by the year without century as a decimal number [00,99]. %Z is replaced by the time zone abbreviation, or by the empty string if this is not determinable. -.RI [ tm_zone +, +.RI [ tm_zone , .IR tm_isdst \*-] .TP %z @@ -369,7 +369,7 @@ but local time is indeterminate; by convention this is used for locations while uninhabited, and corresponds to a zero offset when the time zone abbreviation begins with .q "\*-" . -.RI [ tm_gmtoff +, +.RI [ tm_gmtoff , .IR tm_zone +, .IR tm_isdst \*-] .TP diff --git a/newtzset.3 b/newtzset.3 index b1384f32..4708106d 100644 --- a/newtzset.3 +++ b/newtzset.3 @@ -165,7 +165,7 @@ describes when the change back happens. Each .I time field describes when, in current local time, the change to the other time is made. -As an extension to POSIX.1-2017, daylight saving is assumed to be in effect +Daylight saving is assumed to be in effect all year if it begins January 1 at 00:00 and ends December 31 at 24:00 plus the difference between daylight saving and standard time, leaving no room for standard time in the calendar. @@ -212,11 +212,7 @@ The .I time has the same format as .I offset -except that POSIX.1-2017 does not allow a leading sign (\c -.q "\*-" -or -.q "+" ). -As an extension to POSIX.1-2017, the hours part of +except that the hours part of .I time can range from \-167 through 167; this allows for unusual rules such as @@ -229,8 +225,7 @@ is not given, is .LP Here are some examples of .I TZ -values that directly specify the timezone; they use some of the -extensions to POSIX.1-2017. +values that directly specify the timezone. .TP .B EST5 stands for US Eastern Standard diff --git a/private.h b/private.h index 19d7f7d6..c3304104 100644 --- a/private.h +++ b/private.h @@ -996,8 +996,9 @@ enum { /* How many years to generate (in zic.c) or search through (in localtime.c). This is two years larger than the obvious 400, to avoid edge cases. - E.g., suppose a non-POSIX.1-2017 rule applies from 2012 on with transitions - in March and September, plus one-off transitions in November 2013. + E.g., suppose a rule applies from 2012 on with transitions + in March and September, plus one-off transitions in November 2013, + and suppose the rule cannot be expressed as a proleptic TZ string. If zic looked only at the last 400 years, it would set max_year=2413, with the intent that the 400 years 2014 through 2413 will be repeated. The last transition listed in the tzfile would be in 2413-09, diff --git a/theory.html b/theory.html index 4cb293da..d27d0f2d 100644 --- a/theory.html +++ b/theory.html @@ -89,13 +89,15 @@ The <code><abbr>tz</abbr></code> code is upwards compatible with <a href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international standard for <a href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems. -As of this writing, the current edition of POSIX is: <a +As of this writing, the current edition of POSIX is POSIX.1-2024, +which has been approved but is not yet published. +Unlike its predecessor POSIX.1-2017 (<a href="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018 -Edition. -Because the database's scope encompasses real-world changes to civil -timekeeping, its model for describing time is more complex than the -standard and daylight saving times supported by POSIX.1-2017. +Edition), POSIX.1-2024 requires support for the +<code><abbr>tz</abbr></code> database, which has a +model for describing civil time that is more complex than the +standard and daylight saving times required by POSIX.1-2017. A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can have more than two changes per year, these changes need not merely flip back and forth between two alternatives, and the rules themselves @@ -159,7 +161,7 @@ among the following goals: </ul> <p> -Names normally have the form +Names normally have the format <var>AREA</var><code>/</code><var>LOCATION</var>, where <var>AREA</var> is a continent or ocean, and <var>LOCATION</var> is a specific location within the area. @@ -187,7 +189,7 @@ in decreasing order of importance: href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters, '<code>.</code>', '<code>-</code>' and '<code>_</code>'. Do not use digits, as that might create an ambiguity with <a - href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX.1-2017 + href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX's proleptic <code>TZ</code> strings</a>. A file name component must not exceed 14 characters or start with '<code>-</code>'. @@ -378,7 +380,8 @@ nowadays distributions typically use it and no great weight should be attached to whether a link is defined in <code>backward</code> or in some other file. The source file <code>etcetera</code> defines names that may be useful -on platforms that do not support POSIX.1-2017-style <code>TZ</code> strings; +on platforms that do not support proleptic <code>TZ</code> strings +like <code><+08>-8</code>; no other source file other than <code>backward</code> contains links to its zones. One of <code>etcetera</code>'s names is <code>Etc/UTC</code>, @@ -425,8 +428,8 @@ in decreasing order of importance: In other words, in the C locale the POSIX extended regular expression <code>[-+[:alnum:]]{3,6}</code> should match the abbreviation. - This guarantees that all abbreviations could have been specified by a - POSIX.1-2017 <code>TZ</code> string. + This guarantees that all abbreviations could have been specified + explicitly by a POSIX proleptic <code>TZ</code> string. </p> </li> <li> @@ -775,7 +778,7 @@ href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanes the Western 06:00 to be 12:00. These practices are largely outside the scope of the <code><abbr>tz</abbr></code> code and data, which provide only limited support for date and time localization - such as that required by POSIX.1-2017. + such as that required by POSIX. If <abbr>DST</abbr> is not used a different time zone can often do the trick; for example, in Kenya a <code>TZ</code> setting like <code><-03>3</code> or <code>America/Cayenne</code> starts @@ -866,29 +869,62 @@ Code compatible with this package is already <a href="tz-link.html#tzdb">part of many platforms</a>, where the primary use of this package is to update obsolete time-related files. To do this, you may need to compile the time zone compiler -'<code>zic</code>' supplied with this package instead of using the -system '<code>zic</code>', since the format of <code>zic</code>'s +<code>zic</code> supplied with this package instead of using the +system <code>zic</code>, since the format of <code>zic</code>'s input is occasionally extended, and a platform may still be shipping an older <code>zic</code>. </p> -<h3 id="POSIX">POSIX.1-2017 properties and limitations</h3> +<p> +In POSIX, time display in a process is controlled by the +environment variable <code>TZ</code>, which can have two forms: +</p> <ul> + <li> + A <dfn>proleptic <code>TZ</code></dfn> value + like <code>CET-1CEST,M3.5.0,M10.5.0/3</code> uses a complex + notation that specifies a single standard time along with daylight + saving rules that apply to all years past, present, and future. + </li> + <li> + A <dfn>geographical <code>TZ</code></dfn> value + like <code>Europe/Berlin</code> names a location that stands for + civil time near that location, which can have more than + one standard time and more than one set of daylight saving rules, + to record timekeeping practice more accurately. + These names are defined by the <code><abbr>tz</abbr></code> database</a>. + </li> +</ul> + +<h3 id="POSIX.1-2017">POSIX.1-2017 properties and limitations</h3> +<p> +Some platforms support only the features required by POSIX.1-2017, +and have not yet upgraded to POSIX.1-2024. +Code intended to be portable to these platforms must deal +with problems that were fixed in later POSIX editions. +</p> + +<ul> + <li> + POSIX.1-2017 does not require support for geographical <code>TZ</code>, + and there is no convenient and efficient way to determine + the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary + timestamps, particularly for timezones + that do not fit into the POSIX model. + </li> <li> <p> - In POSIX.1-2017, time display in a process is controlled by the - environment variable <code>TZ</code>. - Unfortunately, the POSIX.1-2017 - <code>TZ</code> string takes a form that is hard to describe and - is error-prone in practice. - Also, POSIX.1-2017 <code>TZ</code> strings cannot deal with daylight + The proleptic <code>TZ</code> string, + which is all that POSIX.1-2017 requires, + has a format that is hard to describe and is error-prone in practice. + Also, proleptic <code>TZ</code> strings cannot deal with daylight saving time rules not based on the Gregorian calendar (as in Morocco), or with situations where more than two time zone abbreviations or <abbr>UT</abbr> offsets are used in an area. </p> <p> - The POSIX.1-2017 <code>TZ</code> string takes the following form: + A proleptic <code>TZ</code> string has the following format: </p> <p> @@ -955,7 +991,7 @@ an older <code>zic</code>. </dl> <p> - Here is an example POSIX.1-2017 <code>TZ</code> string for New + Here is an example proleptic <code>TZ</code> string for New Zealand after 2007. It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead of <abbr>UT</abbr>, and that daylight saving time @@ -966,26 +1002,46 @@ an older <code>zic</code>. <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> <p> - This POSIX.1-2017 <code>TZ</code> string is hard to remember, and + This proleptic <code>TZ</code> string is hard to remember, and mishandles some timestamps before 2008. - With this package you can use this instead: + With this package you can use a geographical <code>TZ</code> instead: </p> <pre><code>TZ='Pacific/Auckland'</code></pre> </li> +</ul> + +<p> +POSIX.1-2017 also has the limitations of POSIX.1-2024, +discussed in the next section. +</p> + +<h3 id="POSIX.1-2024">POSIX.1-2024 properties and limitations</h3> +<p> +POSIX.1-2024 extends POSIX.1-2017 in the following significant ways: +</p> +<ul> <li> - POSIX does not define the <abbr>DST</abbr> transitions - for <code>TZ</code> values like - "<code>EST5EDT</code>". - Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules - were used to interpret such values, but this meant that the - <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each - time conversion package, and when - <abbr>US</abbr> time conversion rules changed (as in the United - States in 1987 and again in 2007), all packages that - interpreted <code>TZ</code> values had to be updated - to ensure proper results. + POSIX.1-2024 requires support for geographical <code>TZ</code>. + Earlier POSIX editions require support only for proleptic <code>TZ</code>. + </li> + <li> + POSIX.1-2024 requires <code>struct tm</code> + to have a <abbr>UT</abbr> offset member <code>tm_gmtoff</code> + and a time zone abbreviation member <codce>tm_zone</code>. + Earlier POSIX editions lack this requirement. + </li> + <li> + DST transition times can range from −167:59:59 + to 167:59:59 instead of merely from 00:00:00 to 24:59:59. + This allows for proleptic TZ strings + like <code>"<-02>2<-01>,M3.5.0/-1,M10.5.0/0"</code> + where the transition time −1:00 means 23:00 the previous day. </li> +</ul> +<p> +However POSIX.1-2024, like earlier POSIX editions, has some limitations: +<ul> <li> The <code>TZ</code> environment variable is process-global, which makes it hard to write efficient, thread-safe applications that @@ -1003,16 +1059,34 @@ an older <code>zic</code>. handling daylight saving time shifts – as might be required to limit phone calls to off-peak hours. </li> - <li> - POSIX.1-2017 provides no convenient and efficient way to determine - the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary - timestamps, particularly for timezones - that do not fit into the POSIX model. - </li> <li> POSIX requires that <code>time_t</code> clock counts exclude leap seconds. </li> + <li> + POSIX does not define the <abbr>DST</abbr> transitions + for <code>TZ</code> values like + "<code>EST5EDT</code>". + Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules + were used to interpret such values, but this meant that the + <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each + time conversion package, and when + <abbr>US</abbr> time conversion rules changed (as in the United + States in 1987 and again in 2007), all packages that + interpreted <code>TZ</code> values had to be updated + to ensure proper results. + </li> +</ul> + +<h3 id="POSIX-extensions">Extensions to POSIX in the +<code><abbr>tz</abbr></code> code</h3> +<p> + The <code><abbr>tz</abbr></code> code defines some properties + left unspecified by POSIX, and attempts to support some + extensions to POSIX. +</p> + +<ul> <li> The <code><abbr>tz</abbr></code> code attempts to support all the <code>time_t</code> implementations allowed by POSIX. @@ -1026,21 +1100,14 @@ an older <code>zic</code>. and 40-bit integers are also used occasionally. Although earlier POSIX versions allowed <code>time_t</code> to be a floating-point type, this was not supported by any practical system, - and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both + and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both require <code>time_t</code> to be an integer type. </li> -</ul> - -<h3 id="POSIX-extensions">Extensions to POSIX.1-2017 in the -<code><abbr>tz</abbr></code> code</h3> -<ul> <li> <p> - The <code>TZ</code> environment variable is used in generating - the name of a file from which time-related information is read - (or is interpreted à la POSIX.1-2017); <code>TZ</code> is no longer - constrained to be a string containing abbreviations - and numeric data as described <a href="#POSIX">above</a>. + If the <code>TZ</code> environment variable uses the geographical format, + it is used in generating + the name of a file from which time-related information is read. The file's format is <dfn><abbr>TZif</abbr></dfn>, a timezone information format that contains binary data; see <a href="https://datatracker.ietf.org/doc/html/8536">Internet @@ -1053,10 +1120,11 @@ an older <code>zic</code>. abbreviations are used. </p> <p> - It was recognized that allowing the <code>TZ</code> environment + When the <code><abbr>tz</abbr></code> code was developed in the 1980s, + it was recognized that allowing the <code>TZ</code> environment variable to take on values such as '<code>America/New_York</code>' might cause "old" programs (that expect <code>TZ</code> to have a - certain form) to operate incorrectly; consideration was given to using + certain format) to operate incorrectly; consideration was given to using some other environment variable (for example, <code>TIMEZONE</code>) to hold the string used to generate the <abbr>TZif</abbr> file's name. In the end, however, it was decided to continue using @@ -1069,15 +1137,6 @@ an older <code>zic</code>. assume pre-POSIX <code>TZ</code> values. </p> </li> - <li> - The code supports platforms with a <abbr>UT</abbr> offset member - in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>, - or with a time zone abbreviation member in - <code>struct tm</code>, e.g., <code>tm_zone</code>. As noted - in <a href="https://austingroupbugs.net/view.php?id=1533">Austin - Group defect 1533</a>, a future version of POSIX is planned to - require <code>tm_gmtoff</code> and <code>tm_zone</code>. - </li> <li> Functions <code>tzalloc</code>, <code>tzfree</code>, <code>localtime_rz</code>, and <code>mktime_z</code> for @@ -1116,6 +1175,7 @@ The vestigial <abbr>API</abbr>s are: <li> The POSIX <code>tzname</code> variable does not suffice and is no longer needed. + It is planned to be removed in a future edition of POSIX. To get a timestamp's time zone abbreviation, consult the <code>tm_zone</code> member if available; otherwise, use <code>strftime</code>'s <code>"%Z"</code> conversion @@ -1124,6 +1184,7 @@ The vestigial <abbr>API</abbr>s are: <li> The POSIX <code>daylight</code> and <code>timezone</code> variables do not suffice and are no longer needed. + They are planned to be removed in a future edition of POSIX. To get a timestamp's <abbr>UT</abbr> offset, consult the <code>tm_gmtoff</code> member if available; otherwise, subtract values returned by <code>localtime</code> diff --git a/tz-link.html b/tz-link.html index aaab7555..d14ea81b 100644 --- a/tz-link.html +++ b/tz-link.html @@ -112,9 +112,9 @@ eastern time but with different <abbr>DST</abbr> rules in 1975; and other entries represent smaller regions like Starke County, Indiana, which switched from central to eastern time in 1991 and switched back in 2006. -To use the database on an extended <a +To use the database on a <a href="https://en.wikipedia.org/wiki/POSIX"><abbr -title="Portable Operating System Interface">POSIX</abbr>.1-2017</a> +title="Portable Operating System Interface">POSIX</abbr>.1-2024</a> implementation set the <code><abbr>TZ</abbr></code> environment variable to the location's full name, e.g., <code><abbr>TZ</abbr>="America/New_York"</code>.</p> @@ -619,11 +619,11 @@ License.</li> <a href="https://github.com/nayarsystems/posix_tz_db"><code>posix_tz_db</code> package</a> contains Python code to generate <abbr>CSV</abbr> and <abbr>JSON</abbr> tables that map -<code><abbr>tz</abbr></code> settings to POSIX.1-2017-like approximations. +<code><abbr>tz</abbr></code> settings to proleptic TZ approximations. For example, it maps <code>"Africa/Cairo"</code> to <code>"EET-2EEST,M4.5.5/0,M10.5.4/24"</code>, an approximation valid for Cairo timestamps from 2023 on. -This can help porting to platforms that support only POSIX.1-2017. +This can help porting to platforms that support only proleptic TZ. The package is freely available under the MIT license.</li> <li><a href="https://github.com/derickr/timelib">Timelib</a> is a C library that reads <abbr>TZif</abbr> files and converts @@ -1187,8 +1187,8 @@ unfortunately some of these abbreviations were merely the database maintainers' inventions, and these have been removed when possible.</li> <li>Numeric time zone abbreviations typically count hours east of <abbr>UT</abbr>, e.g., +09 for Japan and -−10 for Hawaii. However, the <abbr>POSIX</abbr> -<code><abbr>TZ</abbr></code> environment variable uses the opposite convention. +−10 for Hawaii. However, <abbr>POSIX</abbr> proleptic +<code><abbr>TZ</abbr></code> settings use the opposite convention. For example, one might use <code><abbr>TZ</abbr>="<abbr title="Japan Standard Time">JST</abbr>-9"</code> and <code><abbr>TZ</abbr>="<abbr title="Hawaii Standard Time">HST</abbr>10"</code> diff --git a/tzfile.5 b/tzfile.5 index 73dd51ca..6e2fd70b 100644 --- a/tzfile.5 +++ b/tzfile.5 @@ -86,7 +86,7 @@ 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.) +proleptic TZ string described below.) These values serve as indices into the next field. .IP \(bu .B tzh_typecnt @@ -187,12 +187,12 @@ 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. +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 this obsolete transformational behavior, +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 @@ -217,12 +217,12 @@ 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, +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 POSIX.1-2017-style representation for such instants. +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 @@ -235,13 +235,14 @@ 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. .SS 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 -.BR 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 +For version-3-format timezone files, a TZ string (see +.BR 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, DST is in effect all year if it starts +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. .SS Version 4 format @@ -354,7 +355,8 @@ version 2+ data even if the reader's native timestamps have only .IP \(bu 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. +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. @@ -387,7 +389,7 @@ As a partial workaround, a writer can output more transitions than necessary. .IP \(bu Some stripped-down readers ignore everything but the footer, -and use its POSIX.1-2017 TZ string to calculate all timestamps. +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 diff --git a/tzfile.h b/tzfile.h index 3155010e..b1541466 100644 --- a/tzfile.h +++ b/tzfile.h @@ -76,14 +76,16 @@ struct tzhead { ** If tzh_version is '2' or greater, the above is followed by a second instance ** of tzhead and a second instance of the data in which each coded transition ** time uses 8 rather than 4 chars, -** then a POSIX-TZ-environment-variable-style string for use in handling +** then a POSIX.1-2017 proleptic TZ string for use in handling ** instants after the last transition time stored in the file ** (with nothing between the newlines if there is no POSIX.1-2017 ** representation for such instants). ** -** If tz_version is '3' or greater, the above is extended as follows. +** If tz_version is '3' or greater, the TZ string can be any POSIX.1-2024 +** proleptic TZ string, which means the above is extended as follows. ** First, the TZ string's hour offset may range from -167 -** through 167 as compared to the POSIX-required 0 through 24. +** through 167 as compared to the range 0 through 24 required +** by POSIX.1-2017 and earlier. ** Second, its DST start time may be January 1 at 00:00 and its stop ** time December 31 at 24:00 plus the difference between DST and ** standard time, indicating DST all year. diff --git a/zic.8 b/zic.8 index 11a31ec3..578b5211 100644 --- a/zic.8 +++ b/zic.8 @@ -171,7 +171,7 @@ boundaries, particularly if causes a TZif file to contain explicit entries for .RI pre- hi transitions rather than concisely representing them -with an extended POSIX.1-2017 TZ string. +with a proleptic TZ string. Also see the .B "\*-b slim" option for another way to shrink output size. @@ -181,10 +181,10 @@ Generate redundant trailing explicit transitions for timestamps that occur less than .I hi seconds since the Epoch, even though the transitions could be -more concisely represented via the extended POSIX.1-2017 TZ string. +more concisely represented via the proleptic TZ string. This option does not affect the represented timestamps. Although it accommodates nonstandard TZif readers -that ignore the extended POSIX.1-2017 TZ string, +that ignore the proleptic TZ string, it increases the size of the altered output files. .TP .BI "\*-t " file @@ -245,10 +245,10 @@ for .PP The output file does not contain all the information about the long-term future of a timezone, because the future cannot be summarized as -an extended POSIX.1-2017 TZ string. For example, as of 2023 this problem +an proleptic TZ string. For example, as of 2023 this problem occurs for Morocco's daylight-saving rules, as these rules are based on predictions for when Ramadan will be observed, something that -an extended POSIX.1-2017 TZ string cannot represent. +a proleptic TZ string cannot represent. .PP The output contains data that may not be handled properly by client code designed for older diff --git a/zic.c b/zic.c index 8d40fe3c..cf8e79df 100644 --- a/zic.c +++ b/zic.c @@ -2982,7 +2982,7 @@ rule_cmp(struct rule const *a, struct rule const *b) return a->r_dayofmonth - b->r_dayofmonth; } -/* Store into RESULT a POSIX.1-2017 TZ string that represent the future +/* Store into RESULT a proleptic TZ string that represent the future predictions for the zone ZPFIRST with ZONECOUNT entries. Return a compatibility indicator (a TZDB release year) if successful, a negative integer if no such TZ string exists. */ @@ -3177,8 +3177,7 @@ outzone(const struct zone *zpfirst, ptrdiff_t zonecount) if (noise) { if (!*envvar) warning("%s %s", - _("no POSIX.1-2017 environment variable" - " for zone"), + _("no proleptic TZ string for zone"), zpfirst->z_name); else if (compat != 0) { /* Circa-COMPAT clients, and earlier clients, might @@ -3442,7 +3441,7 @@ outzone(const struct zone *zpfirst, ptrdiff_t zonecount) if (do_extend) { /* ** If we're extending the explicitly listed observations for - ** 400 years because we can't fill the POSIX.1-2017 TZ field, + ** 400 years because we can't fill the proleptic TZ field, ** check whether we actually ended up explicitly listing ** observations through that period. If there aren't any ** near the end of the 400-year period, add a redundant -- 2.43.0