Hi Paul! On Mon, Jun 10, 2024 at 03:00:13PM GMT, Paul Eggert wrote: > POSIX.1-2024 is now official, and tm_gmtoff and tm_zone > are now part of POSIX. Update the man pages accordingly. Thanks for the patch! It's nice to see that we finally have POSIX.1-2024. :) > Don't overpromise the global state that tzset updates. > Its contents are unspecified if you use a geographical > time zone. For more details, see: I would prefer that we separate the update to POSIX from the overpromise fix in two separate commits. Would you mind doing that? (Unless this is intrinsic to the POSIX update; is it?) > https://austingroupbugs.net/view.php?id=1816 > https://sourceware.org/bugzilla/show_bug.cgi?id=31876 > > The hours in a TZ string time can now range from -167 to 167. > > Update NZ example to use NZ's current practice. > > Omit leading ":" from TZ examples as this usage is rare. This, and other wording fixes that aren't related to POSIX.1-2024, I prefer them in a separate commit that only does trivial wording and formatting fixes. > --- > man/man3/ctime.3 | 15 +++++---------- > man/man3/tzset.3 | 39 ++++++++++++++++++++++++++++----------- > man/man3type/tm.3type | 7 ++++--- > 3 files changed, 37 insertions(+), 24 deletions(-) > > diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 > index b8543a1cf..94819961d 100644 > --- a/man/man3/ctime.3 > +++ b/man/man3/ctime.3 > @@ -102,9 +102,8 @@ The return value points to a statically allocated string which > might be overwritten by subsequent calls to any of the date and time > functions. > The function also sets the external > -variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see > -.BR tzset (3)) > -with information about the current timezone. > +variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP as if it called > +.BR tzset (3). > The reentrant version > .BR ctime_r () > does the same, but stores the > @@ -131,13 +130,9 @@ The > function converts the calendar time \fItimep\fP to > broken-down time representation, > expressed relative to the user's specified timezone. > -The function acts as if it called > -.BR tzset (3) > -and sets the external variables \fItzname\fP with > -information about the current timezone, \fItimezone\fP with the difference > -between Coordinated Universal Time (UTC) and local standard time in > -seconds, and \fIdaylight\fP to a nonzero value if daylight savings > -time rules apply during some part of the year. > +The function also sets the external variables \fItzname\fP, > +\fItimezone\fP, and \fIdaylight\fP as if it called > +.BR tzset (3). > The return value points to a statically allocated struct which might be > overwritten by subsequent calls to any of the date and time functions. > The > diff --git a/man/man3/tzset.3 b/man/man3/tzset.3 > index 8479b17b0..8623abf09 100644 > --- a/man/man3/tzset.3 > +++ b/man/man3/tzset.3 > @@ -63,6 +63,18 @@ In a System-V-like environment, it will also set the variables \fItimezone\fP > have any daylight saving time rules, or to nonzero if there is a time, > past, present, or future when daylight saving time applies). > .P > +The > +.BR tzset () > +function initializes these variables to unspecified values if this > +timezone is a geographical timezone like "America/New_York" (see below). > +Because these variables' contents are often unspecified, > +code should instead obtain time zone offset and abbreviations from the > +.I tm_gmtoff > +and > +.I tm_zone > +members of the broken-down time structure > +.BR tm (3type). > +.P This could go to a CAVEATS section. > If the > .B TZ > variable does not appear in the environment, the system timezone is used. > @@ -79,7 +91,7 @@ variable does appear in the environment, but its value is empty, > or its value cannot be interpreted using any of the formats specified > below, then Coordinated Universal Time (UTC) is used. > .P > -The value of > +A nonempty value of > .B TZ > can be one of two formats. > The first format is a string of characters that directly represent the > @@ -141,44 +153,49 @@ Day 0 is a Sunday. > .P > The \fItime\fP fields specify when, in the local time currently in effect, > the change to the other time occurs. > +They use the same format as \fIoffset\fP except that the hour can range > +from \-167 to 167 to represent times before and after the named day. > If omitted, the default is 02:00:00. > .P > Here is an example for New Zealand, > where the standard time (NZST) is 12 hours ahead of UTC, > and daylight saving time (NZDT), 13 hours ahead of UTC, > -runs from the first Sunday in October to the third Sunday in March, > -and the changeovers happen at the default time of 02:00:00: > +runs from September's last Sunday at 02:00:00 > +to April's first Sunday at 03:00:00. > .P > .in +4n > .EX > -TZ="NZST\-12:00:00NZDT\-13:00:00,M10.1.0,M3.3.0" > +TZ="NZST\-12:00:00NZDT\-13:00:00,M9.5.0,M4.1.0/3" > .EE > .in > .P > -The second format specifies that the timezone information should be read > +The second, or "geographical", > +format specifies that the timezone information should be read > from a file: > .P > .in +4n > .EX > -:[filespec] > +filespec > .EE > .in > .P > -If the file specification \fIfilespec\fP is omitted, or its value cannot > -be interpreted, then Coordinated Universal Time (UTC) is used. > If \fIfilespec\fP is given, it specifies another > .BR tzfile (5)-format > file to read the timezone information from. > If \fIfilespec\fP does not begin with a \[aq]/\[aq], the file specification is > relative to the system timezone directory. > -If the colon is omitted each > -of the above \fBTZ\fP formats will be tried. > +If the named file cannot be read or interpreted, > +Coordinated Universal Time (UTC) is used; > +however, applications should not depend on random \fIfilespec\fP values > +standing for UTC, as > +.B TZ > +formats may be extended in the future. > .P > Here's an example, once more for New Zealand: > .P > .in +4n > .EX > -TZ=":Pacific/Auckland" > +TZ="Pacific/Auckland" > .EE > .in > .SH ENVIRONMENT > diff --git a/man/man3type/tm.3type b/man/man3type/tm.3type > index 5d5b28658..cbf89a54c 100644 > --- a/man/man3type/tm.3type > +++ b/man/man3type/tm.3type > @@ -90,9 +90,9 @@ points to static storage and may be overridden on subsequent calls to > .BR localtime (3) > and similar functions (however, this never happens under glibc). > .SH STANDARDS > -C11, POSIX.1-2008. > +C23, POSIX.1-2024. > .SH HISTORY > -C89, POSIX.1-2001. > +C89, C99, POSIX.1-2001, POSIX.1-2008. Nah, I only keep here the first one, for simplifying. If it was added in C89, and is present in C23, we can assume that it was present in C99 and C11 too. > .P > .I tm_gmtoff > and > @@ -100,7 +100,8 @@ and > originate from 4.3BSD-Tahoe (where > .I tm_zone > is a > -.IR "char *" ). > +.IR "char *" ), > +and were first standardized in POSIX.1-2024. > .SH NOTES > .I tm_sec > can represent a leap second with the value > -- > 2.43.0 > -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
