Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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/



[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux