From ab2470cf4605e4a8ff488b5dd6528f00f762e207 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Wed, 19 Jul 2023 13:51:55 -0700 Subject: [PATCH] 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. --- ChangeLog | 24 +++++++++++++++++++ doc/posix-functions/_longjmp.texi | 6 +++-- doc/posix-functions/_setjmp.texi | 6 +++-- doc/posix-functions/_tolower.texi | 3 +++ doc/posix-functions/_toupper.texi | 3 +++ doc/posix-functions/asctime.texi | 3 +++ doc/posix-functions/asctime_r.texi | 3 +++ doc/posix-functions/ctime.texi | 3 +++ doc/posix-functions/ctime_r.texi | 3 +++ doc/posix-functions/encrypt.texi | 3 +++ doc/posix-functions/ftw.texi | 3 +++ doc/posix-functions/getitimer.texi | 3 +++ doc/posix-functions/gets.texi | 3 +++ doc/posix-functions/gettimeofday.texi | 3 +++ doc/posix-functions/inet_addr.texi | 3 +++ doc/posix-functions/inet_ntoa.texi | 3 +++ doc/posix-functions/isascii.texi | 3 +++ .../pthread_getconcurrency.texi | 3 +++ .../pthread_setconcurrency.texi | 3 +++ doc/posix-functions/rand_r.texi | 3 +++ doc/posix-functions/setitimer.texi | 3 +++ doc/posix-functions/setkey.texi | 3 +++ doc/posix-functions/setpgrp.texi | 3 +++ doc/posix-functions/sighold.texi | 3 +++ doc/posix-functions/sigignore.texi | 3 +++ doc/posix-functions/siginterrupt.texi | 3 +++ doc/posix-functions/sigpause.texi | 3 +++ doc/posix-functions/sigrelse.texi | 3 +++ doc/posix-functions/sigset.texi | 3 +++ doc/posix-functions/tempnam.texi | 3 +++ doc/posix-functions/toascii.texi | 3 +++ doc/posix-functions/ulimit.texi | 3 +++ doc/posix-functions/utime.texi | 3 +++ 33 files changed, 122 insertions(+), 4 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6a4d92d218..ec8cd5261d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,27 @@ +2023-07-19 Paul Eggert + + 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 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{} (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{} (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 -- 2.39.5