]> Savannah Git Hosting - gnulib.git/commitdiff
tzname: document some limitations
authorPaul Eggert <eggert@cs.ucla.edu>
Thu, 6 Jun 2024 19:54:21 +0000 (12:54 -0700)
committerPaul Eggert <eggert@cs.ucla.edu>
Thu, 6 Jun 2024 20:00:50 +0000 (13:00 -0700)
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.

14 files changed:
ChangeLog
doc/pastposix-functions/ftime.texi
doc/posix-functions/ctime.texi
doc/posix-functions/daylight.texi
doc/posix-functions/fstat.texi
doc/posix-functions/localtime.texi
doc/posix-functions/mktime.texi
doc/posix-functions/stat.texi
doc/posix-functions/strftime.texi
doc/posix-functions/timezone.texi
doc/posix-functions/tzname.texi
doc/posix-functions/tzset.texi
doc/posix-functions/utime.texi
doc/posix-functions/wcsftime.texi

index b0fa4f8a4c118e606bea0c970e090a5ba7146e6f..72e95ef5212a7020f4fc624f883904d7c46f1e81 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2024-06-06  Paul Eggert  <eggert@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  <bruno@clisp.org>
 
        nstrftime, c-nstrftime: Support time zone names on MSVC.
index a6c130c6b72f310b42caff410eac5b143910a508..00349cabf094ca38aba2fe359f5ffca2b04603f3 100644 (file)
@@ -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
index 3ed8e29840667f66896bcc65c5fc17ac85e2ab71..5027abcb056b7e7b97d56007f3fd60add1fa43c5 100644 (file)
@@ -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:
index d5bfecedc1fd5fd6314e0d61c024d7421d0d3fba..ea3d25d466aa20c6a935e80d90648b79b0f41c1b 100644 (file)
@@ -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}.
index e8ef3245538e65a7452ba4b1fe205fa0fdd25fe1..d43bc47fcce2eca4b89417eb9e86114fdf83d5db 100644 (file)
@@ -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:
index 7ce348e286cfb209fdcf2259fb543dd1c416181c..2cfa7316f04eb1e43298541dc5fa2e40bb762b4d 100644 (file)
@@ -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:
index a7713b5a0ebe30c1c76df5f97c8924ee7283d092..1b389b0cb79c7c7d44326bdd01fc43fbf5759115 100644 (file)
@@ -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
index 8afd3b17bbf660233ce9a085546cf272fa638d01..1b7edb9edcfbd7ff8ca52b7d373ad103cb3db29f 100644 (file)
@@ -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
index 3a2eceb8ef479cce2a35ce0307345d1d964acb59..65a6ea8fd2b49ba94f03c88297e8d10e2a22adf5 100644 (file)
@@ -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:
index 5c040cab832e37e4545016dbb1dc8fd005bd8236..f771791a2a8790c13c22df95e11e14dc16c4bce8 100644 (file)
@@ -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}.
index e3413d47deae9d45d8e28cd51371c1099afad36a..dbc98c0751e794b750aa5fc2c22485ac52544fb8 100644 (file)
@@ -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}.
index 30901d3488d3d12d4ee6de468c3dc730a811e1f2..19095a286bead50c387a5f830213308f0efe9894 100644 (file)
@@ -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:
index 893a342bdb15135a17db0b76d0a9ebe94e9cd11b..0e2d9cad80969a14fac4a5d2a78a2fa94b03c7dc 100644 (file)
@@ -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:
index 323ac2152bf453097bc504bd7e3521d31e8bd5b7..50782d84795ee373c7390318014313aafcae728d 100644 (file)
@@ -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: