Deprecate tzsetwall

* Makefile, NEWS, theory.html: Document this.

Makefile

@@ -335,9 +335,7 @@ GCC_DEBUG_FLAGS = -DGCC_LINT -g3 -O3 -fno-common \
 # to the end of the "CFLAGS=" line.  This arranges for the functions
 # "tzsetwall", "offtime", "timelocal", "timegm", "timeoff",
 # "posix2time", and "time2posix" to be added to the time conversion library.
-# "tzsetwall" is like "tzset" except that it arranges for local wall clock
-# time (rather than the timezone specified in the TZ environment variable)
-# to be used.
+# "tzsetwall" is deprecated and is intended to be removed soon; see NEWS.
 # "offtime" is like "gmtime" except that it accepts a second (long) argument
 # that gives an offset to add to the time_t when converting it.
 # "timelocal" is equivalent to "mktime".
@@ -347,7 +345,6 @@ GCC_DEBUG_FLAGS = -DGCC_LINT -g3 -O3 -fno-common \
 # that gives an offset to use when converting to a time_t.
 # "posix2time" and "time2posix" are described in an included manual page.
 # X3J11's work does not describe any of these functions.
-# Sun has provided "tzsetwall", "timelocal", and "timegm" in SunOS 4.0.
 # These functions may well disappear in future releases of the time
 # conversion package.
 #

NEWS

@@ -67,6 +67,13 @@ Unreleased, experimental changes
     The code's defense against CRLF in leap-seconds.list is now
     portable to POSIX awk.  (Problem reported by Deborah Goldsmith.)
 
+    Although the undocumented tzsetwall function is not changed in
+    this release, it is now deprecated in preparation for removal in
+    future releases.  Due to POSIX requirements, tzsetwall has not
+    worked for some time.  Any code that uses it should instead use
+    tzalloc(NULL) or, if portability trumps thread-safety, should
+    unset the TZ environment variable.
+
   Changes to commentary
 
     The Îles-de-la-Madeleine and the Listuguj reserve are noted as

theory.html

@@ -1057,23 +1057,6 @@ an older <code>zic</code>.
     extra <code>timezone_t</code> argument.
     The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>.
   </li>
-  <li>
-    A function <code>tzsetwall</code> has been added to arrange for the
-    system's best approximation to local (wall clock) time to be delivered
-    by subsequent calls to <code>localtime</code>.
-    Source code for portable applications that "must" run on local
-    time should call <code>tzsetwall</code>;
-    if such code is moved to "old" systems that do not
-    provide <code>tzsetwall</code>, you will not be able to generate an
-    executable program.
-    (These functions also arrange for local time to
-    be used if <code>tzset</code> is called &ndash; directly or
-    indirectly &ndash; and there is no <code>TZ</code> environment
-    variable; portable applications should not, however, rely on this
-    behavior since it is not the way <a
-    href="https://en.wikipedia.org/wiki/UNIX_System_V#SVR2"><abbr>SVR2</abbr></a>
-    systems behave.)
-  </li>
   <li>
     Negative <code>time_t</code> values are supported, on systems
     where <code>time_t</code> is signed.