Hello Michael,
I added the C2X [[deprecated]] attribute to the prototypes of some
system calls. All of the cases where I added that were already
marked as deprecated or obsolete somewhere in the manual page,
so this is just about uniformity and visual effect rather than
a new deprecation notice.
There are cases where the syscalls have been simply removed, and
so they are obviously not to be used any more.
There are cases where some implementation (not necessarily Linux)
is dangerous.
In some other cases, the functions have been obsoleted by POSIX,
but are still there in Linux without any deprecation notices.
In these cases, if there's no clear replacement, or if the
replacement is not a straight drop-in, or if the replacement adds
more complexity, I didn't add the [[deprecated]] attribute.
A list of the system calls that I skipped in this patch set:
- utime(2)
Many filesystems have 1 second resolution, so it makes
sense to use it in those cases. git(1) for example uses
utime(2) consistently. Although deprecated by POSIX, it
is still part of POSIX; if it ever removes it, we can
reconsider.
- setpgrp(2) (the POSIX/SysV version)
POSIX deprecated it (not yet removed), but the manual page
doesn't mention any replacement.
Cheers,
Alex
---
Alejandro Colomar (22):
bdflush.2: SYNOPSIS: Mark as [[deprecated]]
create_module.2: SYNOPSIS: Mark as [[deprecated]]
get_kernel_syms.2: SYNOPSIS: Mark as [[deprecated]]
getunwind.2: SYNOPSIS: Mark as [[deprecated]]
iopl.2: SYNOPSIS: Mark as [[deprecated]]
query_module.2: SYNOPSIS: Mark as [[deprecated]]
remap_file_pages.2: SYNOPSIS: Mark as [[deprecated]]
sigprocmask.2: SYNOPSIS: Mark the legacy system call as [[deprecated]]
statfs.2: SYNOPSIS: Mark as [[deprecated]]
stime.2: SYNOPSIS: Mark as [[deprecated]]
ustat.2: SYNOPSIS: Mark as [[deprecated]]
pthread_mutex_consistent.3: Mark *_np() old function as [[deprecated]]
sysctl.2: SYNOPSIS: Mark as [[deprecated]]
vfork.2: SYNOPSIS: Mark as [[deprecated]]
tkill.2: SYNOPSIS: Mark tkill() as [[deprecated]]
sgetmask.2: SYNOPSIS: Mark as [[deprecated]]
getitimer.2: SYNOPSIS: Mark as [[deprecated]]
futimesat.2: SYNOPSIS: Mark as [[deprecated]]
gettimeofday.2: SYNOPSIS: Mark as [[deprecated]]
setpgid.2: SYNOPSIS: Mark BSD versions of getpgrp() and setpgrp() as
[[deprecated]]
sysfs.2: SYNOPSIS: Mark as [[deprecated]]
uselib.2: SYNOPSIS: Mark as [[deprecated]]
man2/bdflush.2 | 4 ++--
man2/create_module.2 | 2 +-
man2/futimesat.2 | 4 ++--
man2/get_kernel_syms.2 | 2 +-
man2/getitimer.2 | 7 ++++---
man2/gettimeofday.2 | 8 ++++----
man2/getunwind.2 | 3 ++-
man2/iopl.2 | 2 +-
man2/query_module.2 | 5 +++--
man2/remap_file_pages.2 | 5 +++--
man2/setpgid.2 | 8 ++++----
man2/sgetmask.2 | 4 ++--
man2/sigprocmask.2 | 12 +++++++-----
man2/statfs.2 | 4 ++--
man2/stime.2 | 2 +-
man2/sysctl.2 | 2 +-
man2/sysfs.2 | 6 +++---
man2/tkill.2 | 2 +-
man2/uselib.2 | 2 +-
man2/ustat.2 | 2 +-
man2/vfork.2 | 2 +-
man3/pthread_mutex_consistent.3 | 1 +
22 files changed, 48 insertions(+), 41 deletions(-)
--
2.33.1
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/sigprocmask.2 | 12 +++++++-----
1 file changed, 7 insertions(+), 5 deletions(-)
diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2
index b82386f14..6d961f84f 100644
--- a/man2/sigprocmask.2
+++ b/man2/sigprocmask.2
@@ -35,7 +35,7 @@ sigprocmask, rt_sigprocmask \- examine and change blocked signals
.nf
/* Prototype for the glibc wrapper function */
.BI "int sigprocmask(int " how ", const sigset_t *restrict " set ,
-.BI " sigset_t *restrict " oldset );
+.BI " sigset_t *restrict " oldset );
.PP
.BR "#include <signal.h>" " /* Definition of " SIG_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
@@ -43,11 +43,13 @@ sigprocmask, rt_sigprocmask \- examine and change blocked signals
.PP
/* Prototype for the underlying system call */
.BI "int syscall(SYS_rt_sigprocmask, int " how ", const kernel_sigset_t *" set ,
-.BI " kernel_sigset_t *" oldset ", size_t " sigsetsize );
+.BI " kernel_sigset_t *" oldset \
+", size_t " sigsetsize );
.PP
-/* Prototype for the legacy system call (deprecated) */
-.BI "int syscall(SYS_sigprocmask, int " how ", const old_kernel_sigset_t *" set ,
-.BI " old_kernel_sigset_t *" oldset );
+/* Prototype for the legacy system call */
+.BI "[[deprecated]] int syscall(SYS_sigprocmask, int " how ,
+.BI " const old_kernel_sigset_t *" set ,
+.BI " old_kernel_sigset_t *" oldset );
.fi
.PP
.RS -4
--
2.33.1
LSB deprecated these syscalls in favor of [f]statvfs(3).
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/statfs.2 | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/man2/statfs.2 b/man2/statfs.2
index 77abd7e4b..92dd83460 100644
--- a/man2/statfs.2
+++ b/man2/statfs.2
@@ -32,8 +32,8 @@ statfs, fstatfs \- get filesystem statistics
.nf
.BR "#include <sys/vfs.h> " "/* or <sys/statfs.h> */"
.PP
-.BI "int statfs(const char *" path ", struct statfs *" buf );
-.BI "int fstatfs(int " fd ", struct statfs *" buf );
+.BI "[[deprecated]] int statfs(const char *" path ", struct statfs *" buf );
+.BI "[[deprecated]] int fstatfs(int " fd ", struct statfs *" buf );
.fi
.SH DESCRIPTION
The
--
2.33.1
This syscall was removed from glibc 2.31 for newly linked
programs.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/stime.2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man2/stime.2 b/man2/stime.2
index 4aaa6c775..5d40495d0 100644
--- a/man2/stime.2
+++ b/man2/stime.2
@@ -34,7 +34,7 @@ stime \- set time
.nf
.B #include <time.h>
.PP
-.BI "int stime(const time_t *" t );
+.BI "[[deprecated]] int stime(const time_t *" t );
.fi
.PP
.RS -4
--
2.33.1
Glibc 2.28 removed the wrapper for this syscall.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/ustat.2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man2/ustat.2 b/man2/ustat.2
index cb26ab23e..6079861ad 100644
--- a/man2/ustat.2
+++ b/man2/ustat.2
@@ -36,7 +36,7 @@ ustat \- get filesystem statistics
.BR "#include <unistd.h>" " /* libc[45] */"
.BR "#include <ustat.h>" " /* glibc2 */"
.PP
-.BI "int ustat(dev_t " dev ", struct ustat *" ubuf );
+.BI "[[deprecated]] int ustat(dev_t " dev ", struct ustat *" ubuf );
.fi
.SH DESCRIPTION
.BR ustat ()
--
2.33.1
tkill(2) has been superseeded by tgkill(2).
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/tkill.2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man2/tkill.2 b/man2/tkill.2
index 6e1afcd36..8a6c45380 100644
--- a/man2/tkill.2
+++ b/man2/tkill.2
@@ -35,7 +35,7 @@ tkill, tgkill \- send a signal to a thread
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.PP
-.BI "int syscall(SYS_tkill, pid_t " tid ", int " sig );
+.BI "[[deprecated]] int syscall(SYS_tkill, pid_t " tid ", int " sig );
.PP
.B #include <signal.h>
.PP
--
2.33.1
Signed-off-by: Alejandro Colomar <[email protected]>
---
man3/pthread_mutex_consistent.3 | 1 +
1 file changed, 1 insertion(+)
diff --git a/man3/pthread_mutex_consistent.3 b/man3/pthread_mutex_consistent.3
index c4963582b..ab280e961 100644
--- a/man3/pthread_mutex_consistent.3
+++ b/man3/pthread_mutex_consistent.3
@@ -85,6 +85,7 @@ glibc defined the following equivalent nonstandard function if
was defined:
.PP
.nf
+.B [[deprecated]]
.BI "int pthread_mutex_consistent_np(const pthread_mutex_t *" mutex );
.fi
.PP
--
2.33.1
Use sigprocmask(2) instead.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/sgetmask.2 | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/man2/sgetmask.2 b/man2/sgetmask.2
index 59b58ceaf..37452ec05 100644
--- a/man2/sgetmask.2
+++ b/man2/sgetmask.2
@@ -30,8 +30,8 @@ sgetmask, ssetmask \- manipulation of signal mask (obsolete)
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.PP
-.B "long syscall(SYS_sgetmask, void);"
-.BI "long syscall(SYS_ssetmask, long " newmask );
+.B [[deprecated]] long syscall(SYS_sgetmask, void);
+.BI "[[deprecated]] long syscall(SYS_ssetmask, long " newmask );
.fi
.PP
.IR Note :
--
2.33.1
The BSD version of getpgrp(2) was superseeded by the POSIX one.
The BSD version of setpgrp(2) was superseeded by the POSIX one.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/setpgid.2 | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/man2/setpgid.2 b/man2/setpgid.2
index f3be0eef4..2f09b246e 100644
--- a/man2/setpgid.2
+++ b/man2/setpgid.2
@@ -55,11 +55,11 @@ setpgid, getpgid, setpgrp, getpgrp \- set/get process group
.BI "int setpgid(pid_t " pid ", pid_t " pgid );
.BI "pid_t getpgid(pid_t " pid );
.PP
-.BR "pid_t getpgrp(void);" " /* POSIX.1 version */"
-.BI "pid_t getpgrp(pid_t " pid ");\fR /* BSD version */"
+.BR "pid_t getpgrp(void);" " /* POSIX.1 version */"
+.BI "[[deprecated]] pid_t getpgrp(pid_t " pid ");\fR /* BSD version */"
.PP
-.BR "int setpgrp(void);" " /* System V version */"
-.BI "int setpgrp(pid_t " pid ", pid_t " pgid ");\fR /* BSD version */"
+.BR "int setpgrp(void);" " /* System V version */"
+.BI "[[deprecated]] int setpgrp(pid_t " pid ", pid_t " pgid ");\fR /* BSD version */"
.fi
.PP
.RS -4
--
2.33.1
Use clock_gettime(2) instead.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/gettimeofday.2 | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2
index 8101e311d..f4b7189d7 100644
--- a/man2/gettimeofday.2
+++ b/man2/gettimeofday.2
@@ -44,10 +44,10 @@ gettimeofday, settimeofday \- get / set time
.nf
.B #include <sys/time.h>
.PP
-.BI "int gettimeofday(struct timeval *restrict " tv ,
-.BI " struct timezone *restrict " tz );
-.BI "int settimeofday(const struct timeval *" tv ,
-.BI " const struct timezone *" tz );
+.BI "[[deprecated]] int gettimeofday(struct timeval *restrict " tv ,
+.BI " struct timezone *restrict " tz );
+.BI "[[deprecated]] int settimeofday(const struct timeval *" tv ,
+.BI " const struct timezone *" tz );
.fi
.PP
.RS -4
--
2.33.1
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/uselib.2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man2/uselib.2 b/man2/uselib.2
index f6feca9f0..32417c9d2 100644
--- a/man2/uselib.2
+++ b/man2/uselib.2
@@ -35,7 +35,7 @@ uselib \- load shared library
.nf
.B #include <unistd.h>
.PP
-.BI "int uselib(const char *" library );
+.BI "[[deprecated]] int uselib(const char *" library );
.fi
.PP
.IR Note :
--
2.33.1
This syscall was removed in Linux 2.6.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/query_module.2 | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/man2/query_module.2 b/man2/query_module.2
index ef8d803ee..4e657189c 100644
--- a/man2/query_module.2
+++ b/man2/query_module.2
@@ -14,8 +14,9 @@ query_module \- query the kernel for various bits pertaining to modules
.nf
.B #include <linux/module.h>
.PP
-.BI "int query_module(const char *" name ", int " which ", void *" buf ,
-.BI " size_t " bufsize ", size_t *" ret );
+.BI "[[deprecated]] int query_module(const char *" name ", int " which \
+", void *" buf ,
+.BI " size_t " bufsize ", size_t *" ret );
.fi
.PP
.IR Note :
--
2.33.1
Since 4.2BSD this syscall was called to be eliminated.
POSIX removed it.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/vfork.2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man2/vfork.2 b/man2/vfork.2
index cd59a374f..655781c1d 100644
--- a/man2/vfork.2
+++ b/man2/vfork.2
@@ -33,7 +33,7 @@ vfork \- create a child process and block parent
.nf
.B #include <unistd.h>
.PP
-.B pid_t vfork(void);
+.B [[deprecated]] pid_t vfork(void);
.fi
.PP
.RS -4
--
2.33.1
This syscall no longer exists!
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/sysctl.2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man2/sysctl.2 b/man2/sysctl.2
index 2188389dc..46b189243 100644
--- a/man2/sysctl.2
+++ b/man2/sysctl.2
@@ -35,7 +35,7 @@ sysctl \- read/write system parameters
.B #include <unistd.h>
.B #include <linux/sysctl.h>
.PP
-.BI "int _sysctl(struct __sysctl_args *" args );
+.BI "[[deprecated]] int _sysctl(struct __sysctl_args *" args );
.fi
.SH DESCRIPTION
.B This system call no longer exists on current kernels!
--
2.33.1
Use utimensat(2) instead.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/futimesat.2 | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/man2/futimesat.2 b/man2/futimesat.2
index 40d352c56..c1ceb7687 100644
--- a/man2/futimesat.2
+++ b/man2/futimesat.2
@@ -31,8 +31,8 @@ directory file descriptor
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <sys/time.h>
.PP
-.BI "int futimesat(int " dirfd ", const char *" pathname ,
-.BI " const struct timeval " times [2]);
+.BI "[[deprecated]] int futimesat(int " dirfd ", const char *" pathname ,
+.BI " const struct timeval " times [2]);
.fi
.PP
.RS -4
--
2.33.1
POSIX deprecates them and recommends the almost identical
timer_[gs]ettime(2). Those use 'struct timespec' instead of
'struct timeval'.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/getitimer.2 | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/man2/getitimer.2 b/man2/getitimer.2
index 7d74df174..9c9ad1978 100644
--- a/man2/getitimer.2
+++ b/man2/getitimer.2
@@ -17,9 +17,10 @@ getitimer, setitimer \- get or set value of an interval timer
.nf
.B #include <sys/time.h>
.PP
-.BI "int getitimer(int " which ", struct itimerval *" curr_value );
-.BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
-.BI " struct itimerval *restrict " old_value );
+.BI "[[deprecated]] int getitimer(int " which ", struct itimerval *" curr_value );
+.BI "[[deprecated]] int setitimer(int " which ,
+.BI " const struct itimerval *restrict " new_value ,
+.BI " struct itimerval *restrict " old_value );
.fi
.SH DESCRIPTION
These system calls provide access to interval timers, that is,
--
2.33.1
Use proc(5) instead.
Signed-off-by: Alejandro Colomar <[email protected]>
---
man2/sysfs.2 | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/man2/sysfs.2 b/man2/sysfs.2
index 0bf2a60c0..10a4f0d43 100644
--- a/man2/sysfs.2
+++ b/man2/sysfs.2
@@ -29,9 +29,9 @@
sysfs \- get filesystem type information
.SH SYNOPSIS
.nf
-.BI "int sysfs(int " option ", const char *" fsname );
-.BI "int sysfs(int " option ", unsigned int " fs_index ", char *" buf );
-.BI "int sysfs(int " option );
+.BI "[[deprecated]] int sysfs(int " option ", const char *" fsname );
+.BI "[[deprecated]] int sysfs(int " option ", unsigned int " fs_index ", char *" buf );
+.BI "[[deprecated]] int sysfs(int " option );
.fi
.SH DESCRIPTION
.BR "Note" :
--
2.33.1
[jc: moved everybody else to bcc]
Please do not spam the git mailing list with these manual page update
patches. We may be interested in the final contents of the manual
pages, we appreciate the work done by the linux-man project, but we
already have our share of patch traffic on this list that people are
swamped with.
2021年10月30日(土) 14:32 Alejandro Colomar <[email protected]>:
>
> Hello Michael,
>
> I added the C2X [[deprecated]] attribute to the prototypes of some
> system calls. All of the cases where I added that were already
> marked as deprecated or obsolete somewhere in the manual page,
> so this is just about uniformity and visual effect rather than
> a new deprecation notice.
>
> There are cases where the syscalls have been simply removed, and
> so they are obviously not to be used any more.
>
> There are cases where some implementation (not necessarily Linux)
> is dangerous.
>
> In some other cases, the functions have been obsoleted by POSIX,
> but are still there in Linux without any deprecation notices.
> In these cases, if there's no clear replacement, or if the
> replacement is not a straight drop-in, or if the replacement adds
> more complexity, I didn't add the [[deprecated]] attribute.
>
> A list of the system calls that I skipped in this patch set:
>
> - utime(2)
> Many filesystems have 1 second resolution, so it makes
> sense to use it in those cases. git(1) for example uses
> utime(2) consistently. Although deprecated by POSIX, it
> is still part of POSIX; if it ever removes it, we can
> reconsider.
>
> - setpgrp(2) (the POSIX/SysV version)
> POSIX deprecated it (not yet removed), but the manual page
> doesn't mention any replacement.
>
> Cheers,
>
> Alex
>
>
> ---
>
> Alejandro Colomar (22):
> bdflush.2: SYNOPSIS: Mark as [[deprecated]]
> create_module.2: SYNOPSIS: Mark as [[deprecated]]
> get_kernel_syms.2: SYNOPSIS: Mark as [[deprecated]]
> getunwind.2: SYNOPSIS: Mark as [[deprecated]]
> iopl.2: SYNOPSIS: Mark as [[deprecated]]
> query_module.2: SYNOPSIS: Mark as [[deprecated]]
> remap_file_pages.2: SYNOPSIS: Mark as [[deprecated]]
> sigprocmask.2: SYNOPSIS: Mark the legacy system call as [[deprecated]]
> statfs.2: SYNOPSIS: Mark as [[deprecated]]
> stime.2: SYNOPSIS: Mark as [[deprecated]]
> ustat.2: SYNOPSIS: Mark as [[deprecated]]
> pthread_mutex_consistent.3: Mark *_np() old function as [[deprecated]]
> sysctl.2: SYNOPSIS: Mark as [[deprecated]]
> vfork.2: SYNOPSIS: Mark as [[deprecated]]
> tkill.2: SYNOPSIS: Mark tkill() as [[deprecated]]
> sgetmask.2: SYNOPSIS: Mark as [[deprecated]]
> getitimer.2: SYNOPSIS: Mark as [[deprecated]]
> futimesat.2: SYNOPSIS: Mark as [[deprecated]]
> gettimeofday.2: SYNOPSIS: Mark as [[deprecated]]
> setpgid.2: SYNOPSIS: Mark BSD versions of getpgrp() and setpgrp() as
> [[deprecated]]
> sysfs.2: SYNOPSIS: Mark as [[deprecated]]
> uselib.2: SYNOPSIS: Mark as [[deprecated]]
>
> man2/bdflush.2 | 4 ++--
> man2/create_module.2 | 2 +-
> man2/futimesat.2 | 4 ++--
> man2/get_kernel_syms.2 | 2 +-
> man2/getitimer.2 | 7 ++++---
> man2/gettimeofday.2 | 8 ++++----
> man2/getunwind.2 | 3 ++-
> man2/iopl.2 | 2 +-
> man2/query_module.2 | 5 +++--
> man2/remap_file_pages.2 | 5 +++--
> man2/setpgid.2 | 8 ++++----
> man2/sgetmask.2 | 4 ++--
> man2/sigprocmask.2 | 12 +++++++-----
> man2/statfs.2 | 4 ++--
> man2/stime.2 | 2 +-
> man2/sysctl.2 | 2 +-
> man2/sysfs.2 | 6 +++---
> man2/tkill.2 | 2 +-
> man2/uselib.2 | 2 +-
> man2/ustat.2 | 2 +-
> man2/vfork.2 | 2 +-
> man3/pthread_mutex_consistent.3 | 1 +
> 22 files changed, 48 insertions(+), 41 deletions(-)
>
> --
> 2.33.1
>