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