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

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hello Michael,

A question below.

Cheers,

Alex

On 12/29/20 9:27 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex, Ganimedes.
> 
> In the subject line : s/non-existing/nonexistent/

Ok, I'll resend in a few minutes.

> 
> On Tue, 29 Dec 2020 at 15:43, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>>
>> From: Ganimedes Colomar <gacoan.linux@gmail.com>
>>
>> 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.
> 
> That seems fine.
> 
>> We didn't fix some of the obsolete syscalls (create_module(2)),
>> but if you prefer, we can fix those too.
> 
> I think it's okay to leave it.
> 
> The remainder of the patch looks good. The only reason that I'm not
> applying ir yet (and fixing the subject line myself) is that I wonder
> if the command I mentioned in response to the 0/2 mail might help you
> find other pages to include in the patch. Let me know.
> 
> Thanks,
> 
> Michael
> 
> 
> 
>>
>>
>> Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
>> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>> ---
>>
>> 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.

What about that?

$ man 2 syslog | sed -n /^SYNOPSIS/,/^DESCRIPTION/p |sed \$d
SYNOPSIS
       int syslog(int type, char *bufp, int len);
                       /* No wrapper provided in glibc */
<<<<< I think we should remove the above comment,
<<<<< or put it consistently everywhere else.
<<<<< What would you do?

       /* The glibc interface */
       #include <sys/klog.h>

       int klogctl(int type, char *bufp, int len);



>>
>> 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 ()
>> --
>> 2.29.2
>>
> 
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/