[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 2/2] Document POSIX obsolescence
|
From: |
Bruno Haible |
|
Subject: |
Re: [PATCH 2/2] Document POSIX obsolescence |
|
Date: |
Thu, 20 Jul 2023 01:39:12 +0200 |
Paul Eggert wrote:
> Update as per draft 3 of POSIX 10003.1-202x.
It's good that you have access to this draft. I don't (paywall).
> + Document POSIX obsolescence
As a user, I would wonder "what shall we use instead?" (and for 'getttimeofday',
I really wondered). So, here's a patch to document a migration path. The info
is partially from POSIX, partially from the Linux man pages, and partially from
Gnulib.
2023-07-19 Bruno Haible <bruno@clisp.org>
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.
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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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