From 031219ca32ea16ca20feb91e52a3b7e3ecc8e0cd Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Thu, 20 Jul 2023 01:35:10 +0200 Subject: [PATCH] Document migration path for obsolescent functions. * doc/glibc-functions/timespec_get.texi: Add reference to ISO C. * doc/posix-functions/_tolower.texi: Recommend use of tolower. * doc/posix-functions/_toupper.texi: Recommend use of toupper. * doc/posix-functions/asctime.texi: Recommend use of strftime. * doc/posix-functions/asctime_r.texi: Likewise. * doc/posix-functions/ctime.texi: Recommend use of localtime_r and strftime. * doc/posix-functions/ctime_r.texi: Likewise. * doc/posix-functions/ftw.texi: Recommend use of fts. * doc/posix-functions/getitimer.texi: Recommend use of timer_gettime. * doc/posix-functions/gets.texi: Recommend use of fgets. * doc/posix-functions/gettimeofday.texi: Recommend use of gettime or timespec_get. * doc/posix-functions/inet_addr.texi: Recommend use of inet_pton. * doc/posix-functions/inet_ntoa.texi: Recommend use of inet_ntop. * doc/posix-functions/pthread_getconcurrency.texi: Recommend no-op. * doc/posix-functions/pthread_setconcurrency.texi: Recommend no-op. * doc/posix-functions/rand_r.texi: Recommend use of random_r. * doc/posix-functions/setitimer.texi: Recommend use of timer_create and timer_settime. * doc/posix-functions/setpgrp.texi: Recommend use of setpgid or setsid. * doc/posix-functions/sighold.texi: Recommend use of sigprocmask. * doc/posix-functions/sigignore.texi: Recommend use of sigaction. * doc/posix-functions/siginterrupt.texi: Recommend use of sigaction. * doc/posix-functions/sigpause.texi: Recommend use of sigsuspend. * doc/posix-functions/sigrelse.texi: Recommend use of sigprocmask. * doc/posix-functions/sigset.texi: Recommend use of sigaction. * doc/posix-functions/tempnam.texi: Recommend use of mkstemp. * doc/posix-functions/ulimit.texi: Recommend use of getrlimit and setrlimit. * doc/posix-functions/utime.texi: Recommend use of utimens. --- ChangeLog | 35 +++++++++++++++++++ doc/glibc-functions/timespec_get.texi | 2 ++ doc/posix-functions/_tolower.texi | 1 + doc/posix-functions/_toupper.texi | 1 + doc/posix-functions/asctime.texi | 5 ++- doc/posix-functions/asctime_r.texi | 1 + doc/posix-functions/ctime.texi | 5 ++- doc/posix-functions/ctime_r.texi | 2 ++ doc/posix-functions/ftw.texi | 1 + doc/posix-functions/getitimer.texi | 1 + doc/posix-functions/gets.texi | 1 + doc/posix-functions/gettimeofday.texi | 3 ++ doc/posix-functions/inet_addr.texi | 1 + doc/posix-functions/inet_ntoa.texi | 1 + .../pthread_getconcurrency.texi | 1 + .../pthread_setconcurrency.texi | 1 + doc/posix-functions/rand_r.texi | 1 + doc/posix-functions/setitimer.texi | 1 + doc/posix-functions/setpgrp.texi | 1 + doc/posix-functions/sighold.texi | 1 + doc/posix-functions/sigignore.texi | 1 + doc/posix-functions/siginterrupt.texi | 1 + doc/posix-functions/sigpause.texi | 1 + doc/posix-functions/sigrelse.texi | 1 + doc/posix-functions/sigset.texi | 1 + doc/posix-functions/tempnam.texi | 1 + doc/posix-functions/ulimit.texi | 1 + doc/posix-functions/utime.texi | 1 + 28 files changed, 68 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index ec8cd5261d..8d6e3aab2e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,38 @@ +2023-07-19 Bruno Haible + + Document migration path for obsolescent functions. + * doc/glibc-functions/timespec_get.texi: Add reference to ISO C. + * doc/posix-functions/_tolower.texi: Recommend use of tolower. + * doc/posix-functions/_toupper.texi: Recommend use of toupper. + * doc/posix-functions/asctime.texi: Recommend use of strftime. + * doc/posix-functions/asctime_r.texi: Likewise. + * doc/posix-functions/ctime.texi: Recommend use of localtime_r and + strftime. + * doc/posix-functions/ctime_r.texi: Likewise. + * doc/posix-functions/ftw.texi: Recommend use of fts. + * doc/posix-functions/getitimer.texi: Recommend use of timer_gettime. + * doc/posix-functions/gets.texi: Recommend use of fgets. + * doc/posix-functions/gettimeofday.texi: Recommend use of gettime or + timespec_get. + * doc/posix-functions/inet_addr.texi: Recommend use of inet_pton. + * doc/posix-functions/inet_ntoa.texi: Recommend use of inet_ntop. + * doc/posix-functions/pthread_getconcurrency.texi: Recommend no-op. + * doc/posix-functions/pthread_setconcurrency.texi: Recommend no-op. + * doc/posix-functions/rand_r.texi: Recommend use of random_r. + * doc/posix-functions/setitimer.texi: Recommend use of timer_create and + timer_settime. + * doc/posix-functions/setpgrp.texi: Recommend use of setpgid or setsid. + * doc/posix-functions/sighold.texi: Recommend use of sigprocmask. + * doc/posix-functions/sigignore.texi: Recommend use of sigaction. + * doc/posix-functions/siginterrupt.texi: Recommend use of sigaction. + * doc/posix-functions/sigpause.texi: Recommend use of sigsuspend. + * doc/posix-functions/sigrelse.texi: Recommend use of sigprocmask. + * doc/posix-functions/sigset.texi: Recommend use of sigaction. + * doc/posix-functions/tempnam.texi: Recommend use of mkstemp. + * doc/posix-functions/ulimit.texi: Recommend use of getrlimit and + setrlimit. + * doc/posix-functions/utime.texi: Recommend use of utimens. + 2023-07-19 Paul Eggert Document POSIX obsolescence diff --git a/doc/glibc-functions/timespec_get.texi b/doc/glibc-functions/timespec_get.texi index 6f5b368d72..195351c392 100644 --- a/doc/glibc-functions/timespec_get.texi +++ b/doc/glibc-functions/timespec_get.texi @@ -2,6 +2,8 @@ @subsection @code{timespec_get} @findex timespec_get +ISO C23 specification:@* @url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf} section 7.29.2.6 + Gnulib module: timespec_get Portability problems fixed by Gnulib: diff --git a/doc/posix-functions/_tolower.texi b/doc/posix-functions/_tolower.texi index 8446eac3d6..381bc035e8 100644 --- a/doc/posix-functions/_tolower.texi +++ b/doc/posix-functions/_tolower.texi @@ -18,4 +18,5 @@ 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. +Use the function @code{tolower} instead. @end itemize diff --git a/doc/posix-functions/_toupper.texi b/doc/posix-functions/_toupper.texi index 8bcf922a02..1196e29792 100644 --- a/doc/posix-functions/_toupper.texi +++ b/doc/posix-functions/_toupper.texi @@ -18,4 +18,5 @@ 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. +Use the function @code{toupper} instead. @end itemize diff --git a/doc/posix-functions/asctime.texi b/doc/posix-functions/asctime.texi index d1a959d5c1..c212a76118 100644 --- a/doc/posix-functions/asctime.texi +++ b/doc/posix-functions/asctime.texi @@ -14,10 +14,9 @@ Portability problems not fixed by Gnulib: @itemize @item 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 +Likewise, POSIX says this function is obsolescent and it is planned to be removed in a future version. +Portable applications can use @code{strftime} (or even @code{sprintf}) instead. @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 df1b6c9264..3b19860363 100644 --- a/doc/posix-functions/asctime_r.texi +++ b/doc/posix-functions/asctime_r.texi @@ -23,6 +23,7 @@ mingw, MSVC 14. @item POSIX says this function is obsolescent and it is planned to be removed in a future version. +Use the function @code{strftime} (or even @code{sprintf}) instead. @item This function may put more than 26 bytes into the argument buffer if an invalid year is passed. diff --git a/doc/posix-functions/ctime.texi b/doc/posix-functions/ctime.texi index 3e8bfcb703..bab929c08c 100644 --- a/doc/posix-functions/ctime.texi +++ b/doc/posix-functions/ctime.texi @@ -17,12 +17,11 @@ Portability problems not fixed by Gnulib: @itemize @item This function is deprecated in C23. +Likewise, POSIX says this function is obsolescent and it is planned to be +removed in a future version. 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 b9ecc6177a..8b5dd136cc 100644 --- a/doc/posix-functions/ctime_r.texi +++ b/doc/posix-functions/ctime_r.texi @@ -23,6 +23,8 @@ mingw, MSVC 14. @item POSIX says this function is obsolescent and it is planned to be removed in a future version. +Use the functions @code{localtime_r} and @code{strftime} +(or even @code{sprintf}) instead. @item This function may put more than 26 bytes into the argument buffer if an invalid year is passed. diff --git a/doc/posix-functions/ftw.texi b/doc/posix-functions/ftw.texi index b6e8581b4c..5b61927775 100644 --- a/doc/posix-functions/ftw.texi +++ b/doc/posix-functions/ftw.texi @@ -21,4 +21,5 @@ 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. +Use the Gnulib module @code{fts} instead. @end itemize diff --git a/doc/posix-functions/getitimer.texi b/doc/posix-functions/getitimer.texi index 1484366ed3..64ce009f3e 100644 --- a/doc/posix-functions/getitimer.texi +++ b/doc/posix-functions/getitimer.texi @@ -18,4 +18,5 @@ mingw, MSVC 14. @item POSIX says this function is obsolescent and it is planned to be removed in POSIX 202x. +Use the function @code{timer_gettime} instead. @end itemize diff --git a/doc/posix-functions/gets.texi b/doc/posix-functions/gets.texi index bb8c907772..ecef336dcd 100644 --- a/doc/posix-functions/gets.texi +++ b/doc/posix-functions/gets.texi @@ -20,6 +20,7 @@ OpenBSD 6.7, Solaris 11.4. @item POSIX says this function is obsolescent and it is planned to be removed in POSIX 202x. +Use the function @code{fgets} instead. @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 diff --git a/doc/posix-functions/gettimeofday.texi b/doc/posix-functions/gettimeofday.texi index 5a262685bc..1cbe0ce847 100644 --- a/doc/posix-functions/gettimeofday.texi +++ b/doc/posix-functions/gettimeofday.texi @@ -36,4 +36,7 @@ is not @code{NULL}. @item POSIX says this function is obsolescent and it is planned to be removed in POSIX 202x. +Use the Gnulib module @code{gettime} or @code{timespec_get} instead. +(POSIX recommends to use the function @code{clock_gettime}, but there is +no corresponding Gnulib module for it yet.) @end itemize diff --git a/doc/posix-functions/inet_addr.texi b/doc/posix-functions/inet_addr.texi index cfe9f9b254..04c620994c 100644 --- a/doc/posix-functions/inet_addr.texi +++ b/doc/posix-functions/inet_addr.texi @@ -18,6 +18,7 @@ mingw, MSVC 14. @item POSIX 202x says this function is obsolescent and it is planned to be removed in a future version. +Use the function @code{inet_pton} instead. @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}. diff --git a/doc/posix-functions/inet_ntoa.texi b/doc/posix-functions/inet_ntoa.texi index afe029ec28..c181ea91fa 100644 --- a/doc/posix-functions/inet_ntoa.texi +++ b/doc/posix-functions/inet_ntoa.texi @@ -18,6 +18,7 @@ mingw, MSVC 14. @item POSIX 202x says this function is obsolescent and it is planned to be removed in a future version. +Use the function @code{inet_ntop} instead. @item The @code{inet_ntoa} function need not be reentrant, and consequently is not required to be thread safe. Implementations of diff --git a/doc/posix-functions/pthread_getconcurrency.texi b/doc/posix-functions/pthread_getconcurrency.texi index 74210f552e..31ba40700a 100644 --- a/doc/posix-functions/pthread_getconcurrency.texi +++ b/doc/posix-functions/pthread_getconcurrency.texi @@ -18,4 +18,5 @@ 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. +You can remove calls to this function. @end itemize diff --git a/doc/posix-functions/pthread_setconcurrency.texi b/doc/posix-functions/pthread_setconcurrency.texi index e1205ff394..6d3433aa41 100644 --- a/doc/posix-functions/pthread_setconcurrency.texi +++ b/doc/posix-functions/pthread_setconcurrency.texi @@ -18,4 +18,5 @@ 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. +You can remove calls to this function. @end itemize diff --git a/doc/posix-functions/rand_r.texi b/doc/posix-functions/rand_r.texi index 669b680459..1e0f150ef8 100644 --- a/doc/posix-functions/rand_r.texi +++ b/doc/posix-functions/rand_r.texi @@ -18,4 +18,5 @@ 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. +Use the function @code{random_r} from Gnulib module @code{random_r} instead. @end itemize diff --git a/doc/posix-functions/setitimer.texi b/doc/posix-functions/setitimer.texi index cba471bd54..985da03917 100644 --- a/doc/posix-functions/setitimer.texi +++ b/doc/posix-functions/setitimer.texi @@ -18,4 +18,5 @@ mingw, MSVC 14. @item POSIX says this function is obsolescent and it is planned to be removed in POSIX 202x. +Use the functions @code{timer_create} and @code{timer_settime} instead. @end itemize diff --git a/doc/posix-functions/setpgrp.texi b/doc/posix-functions/setpgrp.texi index 1a7e22df6d..29b155a588 100644 --- a/doc/posix-functions/setpgrp.texi +++ b/doc/posix-functions/setpgrp.texi @@ -18,4 +18,5 @@ Minix 3.1.8, mingw, MSVC 14. @item POSIX says this function is obsolescent and it is planned to be removed in POSIX 202x. +Use the function @code{setpgid} or @code{setsid} instead, as appropriate. @end itemize diff --git a/doc/posix-functions/sighold.texi b/doc/posix-functions/sighold.texi index 3a926fbacb..0d78d865ef 100644 --- a/doc/posix-functions/sighold.texi +++ b/doc/posix-functions/sighold.texi @@ -18,4 +18,5 @@ 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. +Use the function @code{sigprocmask} instead. @end itemize diff --git a/doc/posix-functions/sigignore.texi b/doc/posix-functions/sigignore.texi index 1e8ef235bf..058d3e7bc9 100644 --- a/doc/posix-functions/sigignore.texi +++ b/doc/posix-functions/sigignore.texi @@ -18,4 +18,5 @@ 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. +Use the function @code{sigaction} instead. @end itemize diff --git a/doc/posix-functions/siginterrupt.texi b/doc/posix-functions/siginterrupt.texi index 36c82be8c4..6f7da931c0 100644 --- a/doc/posix-functions/siginterrupt.texi +++ b/doc/posix-functions/siginterrupt.texi @@ -18,6 +18,7 @@ Minix 3.1.8, mingw, MSVC 14. @item POSIX says this function is obsolescent and it is planned to be removed in POSIX 202x. +Use the function @code{sigaction} instead. @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 71377e63c8..691e882cdb 100644 --- a/doc/posix-functions/sigpause.texi +++ b/doc/posix-functions/sigpause.texi @@ -20,4 +20,5 @@ 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. +Use the function @code{sigsuspend} instead. @end itemize diff --git a/doc/posix-functions/sigrelse.texi b/doc/posix-functions/sigrelse.texi index 42f4665dc9..59edec2e6b 100644 --- a/doc/posix-functions/sigrelse.texi +++ b/doc/posix-functions/sigrelse.texi @@ -18,4 +18,5 @@ 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. +Use the function @code{sigprocmask} instead. @end itemize diff --git a/doc/posix-functions/sigset.texi b/doc/posix-functions/sigset.texi index dba7838511..fcd864984f 100644 --- a/doc/posix-functions/sigset.texi +++ b/doc/posix-functions/sigset.texi @@ -18,4 +18,5 @@ 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. +Use the function @code{sigaction} instead. @end itemize diff --git a/doc/posix-functions/tempnam.texi b/doc/posix-functions/tempnam.texi index e68b8d688c..bb8a040878 100644 --- a/doc/posix-functions/tempnam.texi +++ b/doc/posix-functions/tempnam.texi @@ -18,6 +18,7 @@ Minix 3.1.8. @item POSIX says this function is obsolescent and it is planned to be removed in POSIX 202x. +Use the function @code{mkstemp} instead. @item This function is not appropriate for creating temporary files. (It has security risks.) Better use @code{mkstemp} instead. diff --git a/doc/posix-functions/ulimit.texi b/doc/posix-functions/ulimit.texi index e12808b9e3..ff172d2646 100644 --- a/doc/posix-functions/ulimit.texi +++ b/doc/posix-functions/ulimit.texi @@ -18,4 +18,5 @@ 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. +Use the functions @code{getrlimit} and @code{setrlimit} instead. @end itemize diff --git a/doc/posix-functions/utime.texi b/doc/posix-functions/utime.texi index 4c0bc7f3ed..ec89886099 100644 --- a/doc/posix-functions/utime.texi +++ b/doc/posix-functions/utime.texi @@ -34,4 +34,5 @@ instead. @item POSIX says this function is obsolescent and it is planned to be removed in POSIX 202x. +You can use Gnulib module @code{utimens} instead. @end itemize -- 2.39.5