[tz] [PROPOSED] More documentation updates for POSIX.1-2024

[Paul Eggert]

Be more careful when documenting tm_zone, tm_gmtoff, tzname, etc.,
in the light of POSIX.1-2024 etc.
---
 Makefile      |  8 ++++--
 newctime.3    | 79 ++++++++++++++++++++++++---------------------------
 newstrftime.3 | 14 ++++-----
 newtzset.3    | 55 +++++++++++++++++++++++++++++++----
 4 files changed, 100 insertions(+), 56 deletions(-)

diff --git a/Makefile b/Makefile
index 99f2f56b..d6d66a1f 100644
--- a/Makefile
+++ b/Makefile
@@ -358,7 +358,9 @@ GCC_DEBUG_FLAGS = -DGCC_LINT -g3 -O3 \
 # #	-DHAVE_TZNAME=0 # do not support "tzname"
 # #	-DHAVE_TZNAME=1 # support "tzname", which is defined by system library
 # #	-DHAVE_TZNAME=2 # support and define "tzname"
-# # to the "CFLAGS=" line.  "tzname" is required by POSIX.1-1988 and later.
+# # to the "CFLAGS=" line.  Although "tzname" is required by POSIX.1-1988
+# # and later, its contents are unspecified if you use a geographical TZ
+# # and the variable is planned to be removed in a future POSIX edition.
 # # If not defined, the code attempts to guess HAVE_TZNAME from other macros.
 # # Warning: unless time_tz is also defined, HAVE_TZNAME=1 can cause
 # # crashes when combined with some platforms' standard libraries,
@@ -369,7 +371,9 @@ GCC_DEBUG_FLAGS = -DGCC_LINT -g3 -O3 \
 # #	-DUSG_COMPAT=1 # support, and variables are defined by system library
 # #	-DUSG_COMPAT=2 # support and define variables
 # # to the "CFLAGS=" line; "timezone" and "daylight" are inspired by Unix
-# # Systems Group code and are required by POSIX.1-2008 and later (with XSI).
+# # Systems Group code and are required by POSIX.1-2008 and later (with XSI),
+# # although their contents are unspecified if you use a geographical TZ
+# # and the variables are planned to be rmeoved in a future edition of POSIX.
 # # If not defined, the code attempts to guess USG_COMPAT from other macros.
 # #
 # # To support the external variable "altzone", add
diff --git a/newctime.3 b/newctime.3
index ccc19748..d19fd25b 100644
--- a/newctime.3
+++ b/newctime.3
@@ -9,8 +9,6 @@ asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time
 .el .ds - \-
 .B #include <time.h>
 .PP
-.BR "extern char *tzname[];" " /\(** (optional) \(**/"
-.PP
 .B [[deprecated]] char *ctime(time_t const *clock);
 .PP
 /* Only in POSIX.1-2017 and earlier.  */
@@ -114,17 +112,6 @@ The
 function
 corrects for the time zone and any time zone adjustments
 (such as Daylight Saving Time in the United States).
-After filling in the
-.q "tm"
-structure,
-.B localtime
-sets the
-.BR tm_isdst 'th
-element of
-.B tzname
-to a pointer to a string that's the time zone abbreviation to be used with
-.BR localtime 's
-return value.
 .PP
 The
 .B gmtime
@@ -294,21 +281,43 @@ from UT, with positive values indicating east
 of the Prime Meridian.
 The field's name is derived from Greenwich Mean Time, a precursor of UT.
 .PP
-In
+In platforms conforming to POSIX.1-2024 the
 .B "struct tm"
 the
 .B tm_zone
 and
 .B tm_gmtoff
-fields exist, and are filled in, only if arrangements to do
-so were made when the library containing these functions was
-created.
-Similarly, the
-.B tzname
-variable is optional; also, there is no guarantee that
-.B tzname
-will
-continue to exist in this form in future releases of this code.
+fields exist, and are filled in.
+For
+.B localtime_rz
+and
+.B mktime_rz
+the storage lifetime of the strings addressed by
+.B tm_zone
+extends until the corresponding
+.B timezone_t
+object is freed via
+.BR tzfree .
+For the other functions the lifetime extends until the
+.I TZ
+environment variable changes state and
+.B tzset
+is then called.
+.PP
+As a side effect, the
+.BR ctime ,
+.B localtime
+and
+.B mktime
+functions also behave as if
+.B tzset
+were called.
+The
+.B ctime_r
+and
+.B localtime_r
+functions might (or might not) also behave this way.
+This is for compatibility with older platforms, as required by POSIX.
 .SH FILES
 .ta \w'/usr/share/zoneinfo/posixrules\0\0'u
 /etc/localtime	local timezone file
@@ -322,11 +331,11 @@ continue to exist in this form in future releases of this code.
 If /usr/share/zoneinfo/GMT is absent,
 UTC leap seconds are loaded from /usr/share/zoneinfo/GMT0 if present.
 .SH SEE ALSO
-getenv(3),
-newstrftime(3),
-newtzset(3),
-time(2),
-tzfile(5)
+.BR getenv (3),
+.BR newstrftime (3),
+.BR newtzset (3),
+.BR time (2),
+.BR tzfile (5).
 .SH NOTES
 The return values of
 .BR asctime ,
@@ -336,20 +345,6 @@ and
 .B localtime
 point to static data
 overwritten by each call.
-The
-.B tzname
-variable (once set) and the
-.B tm_zone
-field of a returned
-.B "struct tm"
-both point to an array of characters that
-can be freed or overwritten by later calls to the functions
-.BR localtime ,
-.BR tzfree ,
-and
-.BR tzset ,
-if these functions affect the timezone information that specifies the
-abbreviation in question.
 The remaining functions and data are thread-safe.
 .PP
 The
diff --git a/newstrftime.3 b/newstrftime.3
index 11e37ae8..a9997a09 100644
--- a/newstrftime.3
+++ b/newstrftime.3
@@ -398,7 +398,7 @@ also behaves as if
 were called.
 This is for compatibility with older platforms, as required by POSIX;
 it is not needed for
-.BR tzset 's
+.BR strftime 's
 own use.
 .SH "RETURN VALUE"
 If the conversion is successful,
@@ -428,11 +428,11 @@ conversion and the number of seconds since the Epoch cannot be represented
 in a
 .c time_t .
 .SH SEE ALSO
-date(1),
-getenv(3),
-newctime(3),
-newtzset(3),
-time(2),
-tzfile(5)
+.BR date (1),
+.BR getenv (3),
+.BR newctime (3),
+.BR newtzset (3),
+.BR time (2),
+.BR tzfile (5).
 .SH BUGS
 There is no conversion specification for the phase of the moon.
diff --git a/newtzset.3 b/newtzset.3
index 4708106d..661fb25b 100644
--- a/newtzset.3
+++ b/newtzset.3
@@ -15,6 +15,14 @@ tzset \- initialize time conversion information
 .PP
 .B void tzset(void);
 .PP
+/\(** Optional and obsolescent:  \(**/
+.br
+.B extern char *tzname[];
+.br
+.B extern long timezone;
+.br
+.B extern int daylight;
+.PP
 .B cc ... \*-ltz
 .fi
 .SH DESCRIPTION
@@ -341,6 +349,22 @@ if the implied call to
 fails,
 .B tzset
 falls back on UT.
+.PP
+As a side effect, the
+.B tzset
+function sets some external variables if the platform defines them.
+It sets
+.BR tzname [0]
+and
+.BR tzname [1]
+to pointers to strings that are time zone abbreviations to be used with
+standard and daylight saving time, respectively.
+It also sets
+.B timezone
+to be the number of seconds that standard time is west of the Prime Meridian,
+and
+.B daylight
+to be zero if daylight saving time is never in effect, non-zero otherwise.
 .SH "RETURN VALUE"
 If successful, the
 .B tzalloc
@@ -379,8 +403,29 @@ and
 If /usr/share/zoneinfo/GMT is absent,
 UTC leap seconds are loaded from /usr/share/zoneinfo/GMT0 if present.
 .SH SEE ALSO
-getenv(3),
-newctime(3),
-newstrftime(3),
-time(2),
-tzfile(5)
+.BR getenv (3),
+.BR newctime (3),
+.BR newstrftime (3),
+.BR time (2),
+.BR tzfile (5).
+.SH NOTES
+Portable code should not rely on the contents of the external variables
+.BR tzname ,
+.B timezone
+and
+.B daylight
+as their contents are unspecified (and do not make sense in general)
+when a geographical TZ is used.
+In multithreaded applications behavior is undefined if one thread accesses
+one of these variables while another thread invokes
+.BR tzset .
+A future version of POSIX is planned to remove these variables;
+callers can instead use the
+.I tm_gmtoff
+and
+.I tm_zone
+members of
+.B struct tm,
+or use
+.B strftime
+with "%z" or "%Z".
-- 
2.43.0