Hi Michael, a few comments below. Cheers, Alex On 12/29/20 3:39 PM, Alejandro Colomar wrote: > From: Ganimedes Colomar <gacoan.linux@xxxxxxxxx> > > To easily distinguish documentation about glibc wrappers from > documentation about kernel syscalls, let's have a normalized > 'Note' in the SYNOPSIS, and a further explanation in the page body > (NOTES in most of them), as already happened in many (but not all) > of the manual pages for syscalls without a wrapper. Furthermore, > let's normalize the messages, following membarrier.2 (because it's > already quite extended), so that it's easy to use grep to find > those pages. > > To find these pages, we used: > $ grep -rn wrapper man? | sort -V > and > $ grep -rni support.*glibc | sort -V > > delete_module.2, init_module.2: glibc 2.23 is no longer > maintained, so we changed the notes about wrappers, to say that > there are no glibc wrappers for these system calls; see NOTES. > > We didn't fix some of the obsolete syscalls (create_module(2)), > but if you prefer, we can fix those too. That shouldn't be in the commit msg, but in the email :) > > > Signed-off-by: Ganimedes Colomar <gacoan.linux@xxxxxxxxx> > Cowritten-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> > Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> > --- > > Hi Michael, > > Some comment: > > syslog.2: Isn't the comment in SYNOPSIS wrong? > There _is_ a wrapper, which is documented just below that line. > It just has a different name. Normally, syscalls that do have a wrapper but with a different name, there's no note saying that there is no wrapper (see eventfd(2)). Your thoughts? > > Cheers, > > Alex > > man2/add_key.2 | 3 ++- > man2/arch_prctl.2 | 3 +++ > man2/clone.2 | 2 +- > man2/delete_module.2 | 2 +- > man2/init_module.2 | 6 +----- > man2/keyctl.2 | 3 ++- > man2/pidfd_getfd.2 | 3 +++ > man2/pidfd_open.2 | 3 +++ > man2/pidfd_send_signal.2 | 2 ++ > man2/request_key.2 | 3 ++- > man2/s390_guarded_storage.2 | 3 +++ > man2/s390_pci_mmio_write.2 | 3 +++ > man2/s390_runtime_instr.2 | 3 +++ > man2/s390_sthyi.2 | 3 +++ > 14 files changed, 32 insertions(+), 10 deletions(-) > > diff --git a/man2/add_key.2 b/man2/add_key.2 > index 1476b7d85..7c20de777 100644 > --- a/man2/add_key.2 > +++ b/man2/add_key.2 > @@ -22,7 +22,8 @@ add_key \- add a key to the kernel's key management facility > .BI " key_serial_t " keyring ");" > .fi > .PP > -No glibc wrapper is provided for this system call; see NOTES. > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > .BR add_key () > creates or updates a key of the given > diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2 > index 97d5a2fe5..e8a6da391 100644 > --- a/man2/arch_prctl.2 > +++ b/man2/arch_prctl.2 > @@ -33,6 +33,9 @@ arch_prctl \- set architecture-specific thread state > .BI "int arch_prctl(int " code ", unsigned long " addr ); > .BI "int arch_prctl(int " code ", unsigned long *" addr ); > .fi > +.PP > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > .BR arch_prctl () > sets architecture-specific process or thread state. > diff --git a/man2/clone.2 b/man2/clone.2 > index 0114668ea..0d6565b5d 100644 > --- a/man2/clone.2 > +++ b/man2/clone.2 > @@ -60,7 +60,7 @@ clone, __clone2, clone3 \- create a child process > .fi > .PP > .IR Note : > -There is not yet a glibc wrapper for > +There is no glibc wrapper for > .BR clone3 (); > see NOTES. > .SH DESCRIPTION > diff --git a/man2/delete_module.2 b/man2/delete_module.2 > index daa15faa2..e63545d51 100644 > --- a/man2/delete_module.2 > +++ b/man2/delete_module.2 > @@ -31,7 +31,7 @@ delete_module \- unload a kernel module > .fi > .PP > .IR Note : > -No declaration of this system call is provided in glibc headers; see NOTES. > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > The > .BR delete_module () > diff --git a/man2/init_module.2 b/man2/init_module.2 > index c2675db97..00cf4e948 100644 > --- a/man2/init_module.2 > +++ b/man2/init_module.2 > @@ -37,11 +37,7 @@ init_module, finit_module \- load a kernel module > .fi > .PP > .IR Note : > -glibc provides no header file declaration of > -.BR init_module () > -and no wrapper function for > -.BR finit_module (); > -see NOTES. > +There are no glibc wrappers for these system calls; see NOTES. > .SH DESCRIPTION > .BR init_module () > loads an ELF image into kernel space, > diff --git a/man2/keyctl.2 b/man2/keyctl.2 > index 6bf07972d..f37cae8df 100644 > --- a/man2/keyctl.2 > +++ b/man2/keyctl.2 > @@ -45,7 +45,8 @@ keyctl \- manipulate the kernel's key management facility > .BI " __kernel_ulong_t " arg5 ); > .fi > .PP > -No glibc wrapper is provided for this system call; see NOTES. > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > .BR keyctl () > allows user-space programs to perform key manipulation. > diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2 > index 1a69c8238..9312b6f92 100644 > --- a/man2/pidfd_getfd.2 > +++ b/man2/pidfd_getfd.2 > @@ -29,6 +29,9 @@ pidfd_getfd \- obtain a duplicate of another process's file descriptor > .nf > .BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags ); > .fi > +.PP > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > The > .BR pidfd_getfd () > diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2 > index 5b99460e1..1b0c5e0d4 100644 > --- a/man2/pidfd_open.2 > +++ b/man2/pidfd_open.2 > @@ -31,6 +31,9 @@ pidfd_open \- obtain a file descriptor that refers to a process > .PP > .BI "int pidfd_open(pid_t " pid ", unsigned int " flags ); > .fi > +.PP > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > The > .BR pidfd_open () > diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2 > index 6670cf357..ffbfd1796 100644 > --- a/man2/pidfd_send_signal.2 > +++ b/man2/pidfd_send_signal.2 > @@ -32,6 +32,8 @@ pidfd_send_signal \- send a signal to a process specified by a file descriptor > .BI "int pidfd_send_signal(int " pidfd ", int " sig ", siginfo_t *" info , > .BI " unsigned int " flags ); > .fi > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > The > .BR pidfd_send_signal () > diff --git a/man2/request_key.2 b/man2/request_key.2 > index 86f76e43d..6b041d0c4 100644 > --- a/man2/request_key.2 > +++ b/man2/request_key.2 > @@ -22,7 +22,8 @@ request_key \- request a key from the kernel's key management facility > .BI " key_serial_t " dest_keyring ");" > .fi > .PP > -No glibc wrapper is provided for this system call; see NOTES. > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > .BR request_key () > attempts to find a key of the given > diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2 > index b3aef858f..c3ab3bc85 100644 > --- a/man2/s390_guarded_storage.2 > +++ b/man2/s390_guarded_storage.2 > @@ -31,6 +31,9 @@ s390_guarded_storage \- operations with z/Architecture guarded storage facility > .PP > .BI "int s390_guarded_storage(int " command ", struct gs_cb *" gs_cb ");" > .fi > +.PP > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > The > .BR s390_guarded_storage () > diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2 > index 802142987..2ccd630ab 100644 > --- a/man2/s390_pci_mmio_write.2 > +++ b/man2/s390_pci_mmio_write.2 > @@ -35,6 +35,9 @@ MMIO memory page > .BI "int s390_pci_mmio_read(unsigned long " mmio_addr "," > .BI " void *" user_buffer ", size_t " length ");" > .fi > +.PP > +.IR Note : > +There are no glibc wrappers for these system calls; see NOTES. > .SH DESCRIPTION > The > .BR s390_pci_mmio_write () > diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2 > index 558e9c99d..0f4a704de 100644 > --- a/man2/s390_runtime_instr.2 > +++ b/man2/s390_runtime_instr.2 > @@ -31,6 +31,9 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation > .PP > .BI "int s390_runtime_instr(int " command ", int " signum ");" > .fi > +.PP > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > The > .BR s390_runtime_instr () > diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2 > index 2ff06051a..70871286b 100644 > --- a/man2/s390_sthyi.2 > +++ b/man2/s390_sthyi.2 > @@ -32,6 +32,9 @@ s390_sthyi \- emulate STHYI instruction > .BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer "," > .BI " uint64_t *" return_code ", unsigned long " flags ");" > .fi > +.PP > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > The > .BR s390_sthyi () > -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
