From: Paul Eggert <eggert@cs.ucla.edu>
Date: Wed, 19 Jul 2023 20:51:55 +0000 (-0700)
Subject: Document POSIX obsolescence
X-Git-Tag: v1.0~1055
X-Git-Url: https://gitweb.git.savannah.gnu.org/gitweb/?a=commitdiff_plain;h=ab2470cf4605e4a8ff488b5dd6528f00f762e207;p=gnulib.git

Document POSIX obsolescence

* doc/posix-functions/_longjmp.texi, doc/posix-functions/_setjmp.texi:
* doc/posix-functions/_tolower.texi, doc/posix-functions/_toupper.texi:
* doc/posix-functions/asctime.texi, doc/posix-functions/asctime_r.texi:
* doc/posix-functions/ctime.texi, doc/posix-functions/ctime_r.texi:
* doc/posix-functions/encrypt.texi, doc/posix-functions/ftw.texi:
* doc/posix-functions/getitimer.texi, doc/posix-functions/gets.texi:
* doc/posix-functions/gettimeofday.texi:
* doc/posix-functions/inet_addr.texi:
* doc/posix-functions/inet_ntoa.texi, doc/posix-functions/isascii.texi:
* doc/posix-functions/pthread_getconcurrency.texi:
* doc/posix-functions/pthread_setconcurrency.texi:
* doc/posix-functions/rand_r.texi, doc/posix-functions/setitimer.texi:
* doc/posix-functions/setkey.texi, doc/posix-functions/setpgrp.texi:
* doc/posix-functions/sighold.texi, doc/posix-functions/sigignore.texi:
* doc/posix-functions/siginterrupt.texi:
* doc/posix-functions/sigpause.texi, doc/posix-functions/sigrelse.texi:
* doc/posix-functions/sigset.texi, doc/posix-functions/tempnam.texi:
* doc/posix-functions/toascii.texi, doc/posix-functions/ulimit.texi:
* doc/posix-functions/utime.texi:
Update as per draft 3 of POSIX 10003.1-202x.
---

diff --git a/ChangeLog b/ChangeLog
index 6a4d92d218..ec8cd5261d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,27 @@
+2023-07-19  Paul Eggert  <eggert@cs.ucla.edu>
+
+	Document POSIX obsolescence
+	* doc/posix-functions/_longjmp.texi, doc/posix-functions/_setjmp.texi:
+	* doc/posix-functions/_tolower.texi, doc/posix-functions/_toupper.texi:
+	* doc/posix-functions/asctime.texi, doc/posix-functions/asctime_r.texi:
+	* doc/posix-functions/ctime.texi, doc/posix-functions/ctime_r.texi:
+	* doc/posix-functions/encrypt.texi, doc/posix-functions/ftw.texi:
+	* doc/posix-functions/getitimer.texi, doc/posix-functions/gets.texi:
+	* doc/posix-functions/gettimeofday.texi:
+	* doc/posix-functions/inet_addr.texi:
+	* doc/posix-functions/inet_ntoa.texi, doc/posix-functions/isascii.texi:
+	* doc/posix-functions/pthread_getconcurrency.texi:
+	* doc/posix-functions/pthread_setconcurrency.texi:
+	* doc/posix-functions/rand_r.texi, doc/posix-functions/setitimer.texi:
+	* doc/posix-functions/setkey.texi, doc/posix-functions/setpgrp.texi:
+	* doc/posix-functions/sighold.texi, doc/posix-functions/sigignore.texi:
+	* doc/posix-functions/siginterrupt.texi:
+	* doc/posix-functions/sigpause.texi, doc/posix-functions/sigrelse.texi:
+	* doc/posix-functions/sigset.texi, doc/posix-functions/tempnam.texi:
+	* doc/posix-functions/toascii.texi, doc/posix-functions/ulimit.texi:
+	* doc/posix-functions/utime.texi:
+	Update as per draft 3 of POSIX 10003.1-202x.
+
 2023-07-19  Paul Eggert  <eggert@cs.ucla.edu>
 
 	Don’t worry about Version 7 tolower
diff --git a/doc/posix-functions/_longjmp.texi b/doc/posix-functions/_longjmp.texi
index dd439c9d5b..4cbf8f3b32 100644
--- a/doc/posix-functions/_longjmp.texi
+++ b/doc/posix-functions/_longjmp.texi
@@ -15,10 +15,12 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 mingw, MSVC 14.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
 
-Note: A future revision of POSIX later than the 2008/2009 one may drop the
-functions @code{_setjmp} and @code{_longjmp}.  Still, in 2008, on all
+Note: Despite its being removed from POSIX, in 2023 on all
 systems which have @code{_setjmp}, it is the fastest way to save the
 registers but not the signal mask (up to 30 times faster than @code{setjmp}
 on some systems).
diff --git a/doc/posix-functions/_setjmp.texi b/doc/posix-functions/_setjmp.texi
index 84e3c4f3f5..1e6a39907d 100644
--- a/doc/posix-functions/_setjmp.texi
+++ b/doc/posix-functions/_setjmp.texi
@@ -12,10 +12,12 @@ Portability problems fixed by Gnulib:
 
 Portability problems not fixed by Gnulib:
 @itemize
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
 
-Note: A future revision of POSIX later than the 2008/2009 one may drop the
-functions @code{_setjmp} and @code{_longjmp}.  Still, in 2008, on all
+Note: Despite its being removed from POSIX, in 2023 on all
 systems which have @code{_setjmp}, it is the fastest way to save the
 registers but not the signal mask (up to 30 times faster than @code{setjmp}
 on some systems).
diff --git a/doc/posix-functions/_tolower.texi b/doc/posix-functions/_tolower.texi
index 0d2b6c7757..8446eac3d6 100644
--- a/doc/posix-functions/_tolower.texi
+++ b/doc/posix-functions/_tolower.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 macOS 11.1, Minix 3.1.8, Android 4.4.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/_toupper.texi b/doc/posix-functions/_toupper.texi
index d2025e34b6..8bcf922a02 100644
--- a/doc/posix-functions/_toupper.texi
+++ b/doc/posix-functions/_toupper.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 macOS 11.1, Minix 3.1.8, Android 4.4.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/asctime.texi b/doc/posix-functions/asctime.texi
index 5c4654a866..d1a959d5c1 100644
--- a/doc/posix-functions/asctime.texi
+++ b/doc/posix-functions/asctime.texi
@@ -16,5 +16,8 @@ Portability problems not fixed by Gnulib:
 This function is deprecated in C23.
 Portable applications can use @code{strftime} (or even @code{sprintf}) instead.
 @item
+POSIX says this function is obsolescent and it is planned to be
+removed in a future version.
+@item
 This function may overflow its internal buffer if an invalid year is passed.
 @end itemize
diff --git a/doc/posix-functions/asctime_r.texi b/doc/posix-functions/asctime_r.texi
index 4605b90e72..df1b6c9264 100644
--- a/doc/posix-functions/asctime_r.texi
+++ b/doc/posix-functions/asctime_r.texi
@@ -21,6 +21,9 @@ Portability problems not fixed by Gnulib:
 This function is missing on some platforms:
 mingw, MSVC 14.
 @item
+POSIX says this function is obsolescent and it is planned to be
+removed in a future version.
+@item
 This function may put more than 26 bytes into the argument buffer if an
 invalid year is passed.
 @end itemize
diff --git a/doc/posix-functions/ctime.texi b/doc/posix-functions/ctime.texi
index 2ac56cb524..3e8bfcb703 100644
--- a/doc/posix-functions/ctime.texi
+++ b/doc/posix-functions/ctime.texi
@@ -20,6 +20,9 @@ This function is deprecated in C23.
 Portable applications can use @code{localtime_r} and @code{strftime}
 (or even @code{sprintf}) instead.
 @item
+POSIX says this function is obsolescent and it is planned to be
+removed in a future version.
+@item
 This function may overflow its internal buffer if an invalid year is passed.
 @item
 The @code{ctime} function need not be reentrant, and consequently is
diff --git a/doc/posix-functions/ctime_r.texi b/doc/posix-functions/ctime_r.texi
index 23b9e17005..b9ecc6177a 100644
--- a/doc/posix-functions/ctime_r.texi
+++ b/doc/posix-functions/ctime_r.texi
@@ -21,6 +21,9 @@ Portability problems not fixed by Gnulib:
 This function is missing on some platforms:
 mingw, MSVC 14.
 @item
+POSIX says this function is obsolescent and it is planned to be
+removed in a future version.
+@item
 This function may put more than 26 bytes into the argument buffer if an
 invalid year is passed.
 @end itemize
diff --git a/doc/posix-functions/encrypt.texi b/doc/posix-functions/encrypt.texi
index 5e1eb5d0d7..5a0aa7439f 100644
--- a/doc/posix-functions/encrypt.texi
+++ b/doc/posix-functions/encrypt.texi
@@ -19,4 +19,7 @@ NetBSD 5.0, OpenBSD 6.7, Minix 3.1.8, Cygwin 2.9, mingw, MSVC 14, Android 9.0.
 This function is not declared in @code{<unistd.h>}
 (without @code{-D_GNU_SOURCE}) on some platforms:
 glibc (at least 2.11--2.13).
+@item
+POSIX 202x says this function is obsolescent and it is planned to be
+removed in a future version.
 @end itemize
diff --git a/doc/posix-functions/ftw.texi b/doc/posix-functions/ftw.texi
index b880339a9e..b6e8581b4c 100644
--- a/doc/posix-functions/ftw.texi
+++ b/doc/posix-functions/ftw.texi
@@ -18,4 +18,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 FreeBSD 5.2.1, NetBSD 3.0, Minix 3.1.8, mingw, MSVC 14, Android 4.1.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/getitimer.texi b/doc/posix-functions/getitimer.texi
index 57e66568eb..1484366ed3 100644
--- a/doc/posix-functions/getitimer.texi
+++ b/doc/posix-functions/getitimer.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 mingw, MSVC 14.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/gets.texi b/doc/posix-functions/gets.texi
index 23ba18dc9d..bb8c907772 100644
--- a/doc/posix-functions/gets.texi
+++ b/doc/posix-functions/gets.texi
@@ -18,6 +18,9 @@ This function should never be used, because it can overflow any given buffer.
 This function is missing on some platforms:
 OpenBSD 6.7, Solaris 11.4.
 @item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
+@item
 When reading from a non-blocking pipe whose buffer is empty, this function
 fails with @code{errno} being set to @code{EINVAL} instead of @code{EAGAIN} on
 some platforms:
diff --git a/doc/posix-functions/gettimeofday.texi b/doc/posix-functions/gettimeofday.texi
index a05a448cda..5a262685bc 100644
--- a/doc/posix-functions/gettimeofday.texi
+++ b/doc/posix-functions/gettimeofday.texi
@@ -33,4 +33,7 @@ Portability problems not fixed by Gnulib:
 @item
 Behavior is non-portable if the second argument to @code{gettimeofday}
 is not @code{NULL}.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/inet_addr.texi b/doc/posix-functions/inet_addr.texi
index d1de9adf27..cfe9f9b254 100644
--- a/doc/posix-functions/inet_addr.texi
+++ b/doc/posix-functions/inet_addr.texi
@@ -16,6 +16,9 @@ Portability problems not fixed by Gnulib:
 This function is missing on some platforms:
 mingw, MSVC 14.
 @item
+POSIX 202x says this function is obsolescent and it is planned to be
+removed in a future version.
+@item
 On some old platforms, this function returns a @samp{struct in_addr} rather
 than a scalar type such as @samp{unsigned int} or @samp{unsigned long}.
 @end itemize
diff --git a/doc/posix-functions/inet_ntoa.texi b/doc/posix-functions/inet_ntoa.texi
index 1bd7ef5d1a..afe029ec28 100644
--- a/doc/posix-functions/inet_ntoa.texi
+++ b/doc/posix-functions/inet_ntoa.texi
@@ -16,6 +16,9 @@ Portability problems not fixed by Gnulib:
 This function is missing on some platforms:
 mingw, MSVC 14.
 @item
+POSIX 202x says this function is obsolescent and it is planned to be
+removed in a future version.
+@item
 The @code{inet_ntoa} function need not be reentrant, and consequently
 is not required to be thread safe.  Implementations of
 @code{inet_ntoa} typically write the timestamp into static buffer.
diff --git a/doc/posix-functions/isascii.texi b/doc/posix-functions/isascii.texi
index e9f58624a0..b46571d26e 100644
--- a/doc/posix-functions/isascii.texi
+++ b/doc/posix-functions/isascii.texi
@@ -16,6 +16,9 @@ OS X 10.8.
 
 Portability problems not fixed by Gnulib:
 @itemize
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
 
 Note: This function's behaviour depends on the locale, but requires special
diff --git a/doc/posix-functions/pthread_getconcurrency.texi b/doc/posix-functions/pthread_getconcurrency.texi
index 3aef4113f5..74210f552e 100644
--- a/doc/posix-functions/pthread_getconcurrency.texi
+++ b/doc/posix-functions/pthread_getconcurrency.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 NetBSD 9.0, Minix 3.1.8, mingw, MSVC 14, Android 9.0.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/pthread_setconcurrency.texi b/doc/posix-functions/pthread_setconcurrency.texi
index cb885c828a..e1205ff394 100644
--- a/doc/posix-functions/pthread_setconcurrency.texi
+++ b/doc/posix-functions/pthread_setconcurrency.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 NetBSD 9.0, Minix 3.1.8, mingw, MSVC 14, Android 9.0.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/rand_r.texi b/doc/posix-functions/rand_r.texi
index eedb8fb71b..669b680459 100644
--- a/doc/posix-functions/rand_r.texi
+++ b/doc/posix-functions/rand_r.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 Minix 3.1.8, mingw, MSVC 14, Android 4.4.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/setitimer.texi b/doc/posix-functions/setitimer.texi
index 939e6cc97d..cba471bd54 100644
--- a/doc/posix-functions/setitimer.texi
+++ b/doc/posix-functions/setitimer.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 mingw, MSVC 14.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/setkey.texi b/doc/posix-functions/setkey.texi
index 9f52aa0cc6..794e60f3d8 100644
--- a/doc/posix-functions/setkey.texi
+++ b/doc/posix-functions/setkey.texi
@@ -19,4 +19,7 @@ glibc 2.34, NetBSD 5.0, OpenBSD 6.7, Minix 3.1.8, Cygwin 2.9, mingw, MSVC 14, An
 This function is not declared in @code{<stdlib.h>}
 (without @code{-D_GNU_SOURCE}) on some platforms:
 glibc (at least 2.11--2.13).
+@item
+POSIX 202x says this function is obsolescent and it is planned to be
+removed in a future version.
 @end itemize
diff --git a/doc/posix-functions/setpgrp.texi b/doc/posix-functions/setpgrp.texi
index 46bfb78437..1a7e22df6d 100644
--- a/doc/posix-functions/setpgrp.texi
+++ b/doc/posix-functions/setpgrp.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 Minix 3.1.8, mingw, MSVC 14.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/sighold.texi b/doc/posix-functions/sighold.texi
index 66a0cf346d..3a926fbacb 100644
--- a/doc/posix-functions/sighold.texi
+++ b/doc/posix-functions/sighold.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 FreeBSD 6.0, OpenBSD 6.7, Minix 3.1.8, mingw, MSVC 14, Android 7.1.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/sigignore.texi b/doc/posix-functions/sigignore.texi
index 5b0879dfff..1e8ef235bf 100644
--- a/doc/posix-functions/sigignore.texi
+++ b/doc/posix-functions/sigignore.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 FreeBSD 6.0, OpenBSD 6.7, Minix 3.1.8, Cygwin 1.5.x, mingw, MSVC 14, Android 7.1.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/siginterrupt.texi b/doc/posix-functions/siginterrupt.texi
index a86fe5e875..36c82be8c4 100644
--- a/doc/posix-functions/siginterrupt.texi
+++ b/doc/posix-functions/siginterrupt.texi
@@ -15,6 +15,9 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 Minix 3.1.8, mingw, MSVC 14.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
 
 Note: POSIX recommends using @code{sigaction} with SA_RESTART instead of
diff --git a/doc/posix-functions/sigpause.texi b/doc/posix-functions/sigpause.texi
index 46ff40be5e..71377e63c8 100644
--- a/doc/posix-functions/sigpause.texi
+++ b/doc/posix-functions/sigpause.texi
@@ -17,4 +17,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 Minix 3.1.8, mingw, MSVC 14, Android 7.1.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/sigrelse.texi b/doc/posix-functions/sigrelse.texi
index f32e4e1b25..42f4665dc9 100644
--- a/doc/posix-functions/sigrelse.texi
+++ b/doc/posix-functions/sigrelse.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 FreeBSD 6.0, OpenBSD 6.7, Minix 3.1.8, mingw, MSVC 14, Android 7.1.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/sigset.texi b/doc/posix-functions/sigset.texi
index e269786d50..dba7838511 100644
--- a/doc/posix-functions/sigset.texi
+++ b/doc/posix-functions/sigset.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 FreeBSD 6.0, OpenBSD 6.7, Minix 3.1.8, Cygwin 1.5.x, mingw, MSVC 14, Android 7.1.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/tempnam.texi b/doc/posix-functions/tempnam.texi
index c4b767793e..e68b8d688c 100644
--- a/doc/posix-functions/tempnam.texi
+++ b/doc/posix-functions/tempnam.texi
@@ -16,6 +16,9 @@ Portability problems not fixed by Gnulib:
 This function is missing on some platforms:
 Minix 3.1.8.
 @item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
+@item
 This function is not appropriate for creating temporary files.  (It has
 security risks.)  Better use @code{mkstemp} instead.
 @end itemize
diff --git a/doc/posix-functions/toascii.texi b/doc/posix-functions/toascii.texi
index 9f5a3d3e40..396ea45221 100644
--- a/doc/posix-functions/toascii.texi
+++ b/doc/posix-functions/toascii.texi
@@ -16,4 +16,7 @@ OS X 10.8.
 
 Portability problems not fixed by Gnulib:
 @itemize
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/ulimit.texi b/doc/posix-functions/ulimit.texi
index 1b688efef4..e12808b9e3 100644
--- a/doc/posix-functions/ulimit.texi
+++ b/doc/posix-functions/ulimit.texi
@@ -15,4 +15,7 @@ Portability problems not fixed by Gnulib:
 @item
 This function is missing on some platforms:
 OpenBSD 6.7, Minix 3.1.8, Cygwin 2.9, mingw, MSVC 14, Android 9.0.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize
diff --git a/doc/posix-functions/utime.texi b/doc/posix-functions/utime.texi
index 32fbf369a5..4c0bc7f3ed 100644
--- a/doc/posix-functions/utime.texi
+++ b/doc/posix-functions/utime.texi
@@ -31,4 +31,7 @@ Solaris 9.
 This function cannot set full timestamp resolution.  Use
 @code{utimensat(AT_FDCWD,file,times,0)}, or the gnulib module @code{utimens},
 instead.
+@item
+POSIX says this function is obsolescent and it is planned to be
+removed in POSIX 202x.
 @end itemize