Some suggestions for improvement:* Don't make tzname a module, as this mistakenly suggests that tzname is useful. Instead, leave tzname's implementation as internal detail of the nstrftime and c-nstrftime modules. This should be easy.
* Since tzname should be an internal detail, Gnulib can still use AC_STRUCT_TIMEZONE and have MS-specific code for _tzname that is private to nstrftime and c-nstrftime. This would be a less-intrusive change to Gnulib. This should be relatively easy too.
* Support tm_zone and tm_gmtoff instead. They're in most useful systems nowadays, and are standardized in POSIX.1-2024. This would be considerably harder.
At the very least we need to document that tzname has significant problems, which I did by installing the attached.
From 744b55fb968b86e1f1b89d187ae317d2e159a193 Mon Sep 17 00:00:00 2001 From: Paul Eggert <egg...@cs.ucla.edu> Date: Thu, 6 Jun 2024 12:54:21 -0700 Subject: [PATCH] tzname: document some limitations Unfortunately tzname is a vestigial interface that doesn't work <https://data.iana.org/time-zones/theory.html#vestigial>. It's relatively useless in portable code and is planned to be removed from POSIX <https://austingroupbugs.net/view.php?id=1816>. Document this better here. --- ChangeLog | 9 +++++++++ doc/pastposix-functions/ftime.texi | 2 +- doc/posix-functions/ctime.texi | 2 +- doc/posix-functions/daylight.texi | 5 +++++ doc/posix-functions/fstat.texi | 2 +- doc/posix-functions/localtime.texi | 2 +- doc/posix-functions/mktime.texi | 2 +- doc/posix-functions/stat.texi | 2 +- doc/posix-functions/strftime.texi | 2 +- doc/posix-functions/timezone.texi | 5 +++++ doc/posix-functions/tzname.texi | 5 +++++ doc/posix-functions/tzset.texi | 2 +- doc/posix-functions/utime.texi | 2 +- doc/posix-functions/wcsftime.texi | 2 +- 14 files changed, 34 insertions(+), 10 deletions(-) diff --git a/ChangeLog b/ChangeLog index b0fa4f8a4c..72e95ef521 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2024-06-06 Paul Eggert <egg...@cs.ucla.edu> + + tzname: document some limitations + Unfortunately tzname is a vestigial interface that doesn't work + <https://data.iana.org/time-zones/theory.html#vestigial>. + It's relatively useless in portable code and is planned to be removed + from POSIX <https://austingroupbugs.net/view.php?id=1816>. + Document this better here. + 2024-06-06 Bruno Haible <br...@clisp.org> nstrftime, c-nstrftime: Support time zone names on MSVC. diff --git a/doc/pastposix-functions/ftime.texi b/doc/pastposix-functions/ftime.texi index a6c130c6b7..00349cabf0 100644 --- a/doc/pastposix-functions/ftime.texi +++ b/doc/pastposix-functions/ftime.texi @@ -21,7 +21,7 @@ This function is not declared on some platforms: Android 13. @item On native Windows platforms (mingw, MSVC), this function works incorrectly -when the environment variable @code{TZ} has been set by Cygwin. +when the environment variable @env{TZ} has been set by Cygwin. @item This function is removed in POSIX.1-2008. Better use @code{clock_gettime} instead, and use @code{ftime} only as a fallback for diff --git a/doc/posix-functions/ctime.texi b/doc/posix-functions/ctime.texi index 3ed8e29840..5027abcb05 100644 --- a/doc/posix-functions/ctime.texi +++ b/doc/posix-functions/ctime.texi @@ -10,7 +10,7 @@ Portability problems fixed by Gnulib: @itemize @item On native Windows platforms (mingw, MSVC), this function works incorrectly -when the environment variable @code{TZ} has been set by Cygwin. +when the environment variable @env{TZ} has been set by Cygwin. @end itemize Portability problems not fixed by Gnulib: diff --git a/doc/posix-functions/daylight.texi b/doc/posix-functions/daylight.texi index d5bfecedc1..ea3d25d466 100644 --- a/doc/posix-functions/daylight.texi +++ b/doc/posix-functions/daylight.texi @@ -13,6 +13,9 @@ Portability problems fixed by Gnulib: Portability problems not fixed by Gnulib: @itemize @item +This variable's contents are unreliable if you use a geographical +@env{TZ} setting like @code{TZ="America/Los_Angeles"}. +@item This variable is missing on some platforms: FreeBSD 14.0, OpenBSD 5.7. @item @@ -26,5 +29,7 @@ Native Windows platforms (mingw, MSVC) support only a subset of time zones supported by GNU or specified by POSIX@. @xref{tzset}. @end itemize +This variable is vestigial: it is not needed and does not suffice in general. +It is planned to be removed from a future version of POSIX@. A more portable way of getting the UTC offset is to use @code{strftime} with the @code{%z} format. @xref{strftime}. diff --git a/doc/posix-functions/fstat.texi b/doc/posix-functions/fstat.texi index e8ef324553..d43bc47fcc 100644 --- a/doc/posix-functions/fstat.texi +++ b/doc/posix-functions/fstat.texi @@ -30,7 +30,7 @@ offset from @code{tv_sec}. Solaris 11.4 is similar, except that The @code{st_atime}, @code{st_ctime}, @code{st_mtime} fields are affected by the current time zone and by the DST flag of the current time zone on some platforms: -mingw, MSVC 14 (when the environment variable @code{TZ} is set). +mingw, MSVC 14 (when the environment variable @env{TZ} is set). @end itemize Portability problems not fixed by Gnulib: diff --git a/doc/posix-functions/localtime.texi b/doc/posix-functions/localtime.texi index 7ce348e286..2cfa7316f0 100644 --- a/doc/posix-functions/localtime.texi +++ b/doc/posix-functions/localtime.texi @@ -10,7 +10,7 @@ Portability problems fixed by Gnulib: @itemize @item On native Windows platforms (mingw, MSVC), this function works incorrectly -when the environment variable @code{TZ} has been set by Cygwin. +when the environment variable @env{TZ} has been set by Cygwin. @end itemize Portability problems not fixed by Gnulib: diff --git a/doc/posix-functions/mktime.texi b/doc/posix-functions/mktime.texi index a7713b5a0e..1b389b0cb7 100644 --- a/doc/posix-functions/mktime.texi +++ b/doc/posix-functions/mktime.texi @@ -10,7 +10,7 @@ Portability problems fixed by Gnulib: @itemize @item On native Windows platforms (mingw, MSVC), this function works incorrectly -when the environment variable @code{TZ} has been set by Cygwin. +when the environment variable @env{TZ} has been set by Cygwin. @item @code{mktime} may go into an endless loop on some platforms. @item diff --git a/doc/posix-functions/stat.texi b/doc/posix-functions/stat.texi index 8afd3b17bb..1b7edb9edc 100644 --- a/doc/posix-functions/stat.texi +++ b/doc/posix-functions/stat.texi @@ -21,7 +21,7 @@ file systems such as XFS (typically on large disks) and NFS. The @code{st_atime}, @code{st_ctime}, @code{st_mtime} fields are affected by the current time zone and by the DST flag of the current time zone on some platforms: -mingw, MSVC 14 (when the environment variable @code{TZ} is set). +mingw, MSVC 14 (when the environment variable @env{TZ} is set). @item On MSVC 14, this function fails with error @code{ENOENT} on files such as @samp{C:\pagefile.sys} and diff --git a/doc/posix-functions/strftime.texi b/doc/posix-functions/strftime.texi index 3a2eceb8ef..65a6ea8fd2 100644 --- a/doc/posix-functions/strftime.texi +++ b/doc/posix-functions/strftime.texi @@ -10,7 +10,7 @@ Portability problems fixed by Gnulib: @itemize @item On native Windows platforms (mingw, MSVC), this function works incorrectly -when the environment variable @code{TZ} has been set by Cygwin. +when the environment variable @env{TZ} has been set by Cygwin. @end itemize Portability problems not fixed by Gnulib: diff --git a/doc/posix-functions/timezone.texi b/doc/posix-functions/timezone.texi index 5c040cab83..f771791a2a 100644 --- a/doc/posix-functions/timezone.texi +++ b/doc/posix-functions/timezone.texi @@ -13,6 +13,9 @@ Portability problems fixed by Gnulib: Portability problems not fixed by Gnulib: @itemize @item +This variable's contents are unreliable if you use a geographical +@env{TZ} setting like @code{TZ="America/Los_Angeles"}. +@item This variable is missing (and instead, a function named @code{timezone} exists) on some platforms: FreeBSD 14.0, OpenBSD 5.7. @@ -27,5 +30,7 @@ Native Windows platforms (mingw, MSVC) support only a subset of time zones supported by GNU or specified by POSIX@. @xref{tzset}. @end itemize +This variable is vestigial: it is not needed and does not suffice in general. +It is planned to be removed from a future version of POSIX@. A more portable way of getting the UTC offset is to use @code{strftime} with the @code{%z} format. @xref{strftime}. diff --git a/doc/posix-functions/tzname.texi b/doc/posix-functions/tzname.texi index e3413d47de..dbc98c0751 100644 --- a/doc/posix-functions/tzname.texi +++ b/doc/posix-functions/tzname.texi @@ -16,6 +16,9 @@ mingw with @code{-DNO_OLDNAMES}, MSVC. Portability problems not fixed by Gnulib: @itemize @item +This variable's contents are unreliable if you use a geographical +@env{TZ} setting like @code{TZ="America/Los_Angeles"}. +@item The address of this variable is not a compile-time constant on some platforms: Cygwin, mingw, MSVC. @item @@ -23,5 +26,7 @@ Native Windows platforms (mingw, MSVC) support only a subset of time zones supported by GNU or specified by POSIX@. @xref{tzset}. @end itemize +This variable is vestigial: it is not needed and does not suffice in general. +It is planned to be removed from a future version of POSIX@. A more portable way of getting the time zone abbreviation is to use @code{strftime} with the @code{%Z} format. @xref{strftime}. diff --git a/doc/posix-functions/tzset.texi b/doc/posix-functions/tzset.texi index 30901d3488..19095a286b 100644 --- a/doc/posix-functions/tzset.texi +++ b/doc/posix-functions/tzset.texi @@ -10,7 +10,7 @@ Portability problems fixed by Gnulib: @itemize @item On native Windows platforms (mingw, MSVC), this function works incorrectly -when the environment variable @code{TZ} has been set by Cygwin. +when the environment variable @env{TZ} has been set by Cygwin. @end itemize Portability problems not fixed by Gnulib: diff --git a/doc/posix-functions/utime.texi b/doc/posix-functions/utime.texi index 893a342bdb..0e2d9cad80 100644 --- a/doc/posix-functions/utime.texi +++ b/doc/posix-functions/utime.texi @@ -12,7 +12,7 @@ Portability problems fixed by Gnulib: @item The times that are set on the file are affected by the current time zone and by the DST flag of the current time zone on some platforms: -mingw, MSVC 14 (when the environment variable @code{TZ} is set). +mingw, MSVC 14 (when the environment variable @env{TZ} is set). @item On some platforms, the prototype for @code{utime} omits @code{const} for the second argument: diff --git a/doc/posix-functions/wcsftime.texi b/doc/posix-functions/wcsftime.texi index 323ac2152b..50782d8479 100644 --- a/doc/posix-functions/wcsftime.texi +++ b/doc/posix-functions/wcsftime.texi @@ -10,7 +10,7 @@ Portability problems fixed by Gnulib: @itemize @item On native Windows platforms (mingw, MSVC), this function works incorrectly -when the environment variable @code{TZ} has been set by Cygwin. +when the environment variable @env{TZ} has been set by Cygwin. @end itemize Portability problems not fixed by Gnulib: -- 2.43.0
