[RFC,v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

Until now, the manual pages have (usually) documented only either
the glibc (or another library) wrapper for a syscall, or the
kernel syscall (this only when there's not a wrapper).

Let's document both prototypes, which many times are slightly
different.  This will solve a problem where documenting glibc
wrappers implied shadowing the documentation for the raw syscall.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/execve.2     | 15 +++++++++++++--
 man2/membarrier.2 | 14 +++++---------
 2 files changed, 18 insertions(+), 11 deletions(-)

Hey Alex,

On 2/18/21 4:13 PM, Alejandro Colomar wrote:
> Until now, the manual pages have (usually) documented only either
> the glibc (or another library) wrapper for a syscall, or the
> kernel syscall (this only when there's not a wrapper).
> 
> Let's document both prototypes, which many times are slightly
> different.  This will solve a problem where documenting glibc
> wrappers implied shadowing the documentation for the raw syscall.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

This patch also changes madvise.2, I suppose accidentally.

I'm still not sure whether I consider this change worthwhile
for cases like this where the differences between the libc
wrapper and the syscall are minor enough to probably
be irrelevant to user-space programmers. But, if we do
add something like this, I thing a sentence or two
of English is desirable as well. Something like

   The kernel system call differs slightly from the glibc
   wrapper, in the addition of 'const' to two parameter
   declarations:
    
        syscall(...)

But, before we go down this track, I'd like to get a sense 
of how many cases there are like this where there are these
small differences between the glibc wrapper and the syscall
interface. I'm not meaning you should check every system call
now.  But maybe you can let me know something like: of the first
20 system calls I checked, there X system calls that had 
such differences.

Thanks,

Michael

> ---
>  man2/execve.2     | 15 +++++++++++++--
>  man2/membarrier.2 | 14 +++++---------
>  2 files changed, 18 insertions(+), 11 deletions(-)
> 
> diff --git a/man2/execve.2 b/man2/execve.2
> index 027a0efd2..318c71c85 100644
> --- a/man2/execve.2
> +++ b/man2/execve.2
> @@ -41,8 +41,8 @@ execve \- execute program
>  .nf
>  .B #include <unistd.h>
>  .PP
> -.BI "int execve(const char *" pathname ", char *const " argv [],
> -.BI "           char *const " envp []);
> +.BI "int execve(const char *" pathname ",
> +.BI "           char *const " argv "[], char *const " envp []);
>  .fi
>  .SH DESCRIPTION
>  .BR execve ()
> @@ -772,6 +772,17 @@ Thus, this argument list was not directly usable in a further
>  .BR exec ()
>  call.
>  Since UNIX\ V7, both are NULL.
> +.SS C library/kernel differences
> +.RS 4
> +.nf
> +/* Kernel system call: */
> +.BR "#include <sys/syscall.h>" "        /* For " SYS_* " constants */"
> +.B #include <unistd.h>
> +.PP
> +.BI "int syscall(SYS_execve, const char *" pathname ,
> +.BI "            const char *const " argv "[], const char *const " envp []);
> +.fi
> +.RE
>  .\"
>  .\" .SH BUGS
>  .\" Some Linux versions have failed to check permissions on ELF
> diff --git a/man2/membarrier.2 b/man2/membarrier.2
> index 173195484..25d6add77 100644
> --- a/man2/membarrier.2
> +++ b/man2/membarrier.2
> @@ -28,13 +28,12 @@ membarrier \- issue memory barriers on a set of threads
>  .SH SYNOPSIS
>  .nf
>  .PP
> -.B #include <linux/membarrier.h>
> +.BR "#include <linux/membarrier.h>" "   /* For " MEMBARRIER_* " constants */"
> +.BR "#include <sys/syscall.h>" "        /* For " SYS_* " constants */"
> +.B #include <unistd.h>
>  .PP
> -.BI "int membarrier(int " cmd ", unsigned int " flags ", int " cpu_id );
> +.BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags ", int " cpu_id );
>  .fi
> -.PP
> -.IR Note :
> -There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
>  The
>  .BR membarrier ()
> @@ -295,7 +294,7 @@ was:
>  .PP
>  .in +4n
>  .EX
> -.BI "int membarrier(int " cmd ", int " flags );
> +.BI "int syscall(SYS_membarrier, int " cmd ", int " flags );
>  .EE
>  .in
>  .SH CONFORMING TO
> @@ -322,9 +321,6 @@ Examples where
>  .BR membarrier ()
>  can be useful include implementations
>  of Read-Copy-Update libraries and garbage collectors.
> -.PP
> -Glibc does not provide a wrapper for this system call; call it using
> -.BR syscall (2).
>  .SH EXAMPLES
>  Assuming a multithreaded application where "fast_path()" is executed
>  very frequently, and where "slow_path()" is executed infrequently, the
>

Hi Michael,

On 2/19/21 1:39 PM, Michael Kerrisk (man-pages) wrote:
> Hey Alex,
> 
> On 2/18/21 4:13 PM, Alejandro Colomar wrote:
>> Until now, the manual pages have (usually) documented only either
>> the glibc (or another library) wrapper for a syscall, or the
>> kernel syscall (this only when there's not a wrapper).
>>
>> Let's document both prototypes, which many times are slightly
>> different.  This will solve a problem where documenting glibc
>> wrappers implied shadowing the documentation for the raw syscall.
>>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> 
> This patch also changes madvise.2, I suppose accidentally.

I forgot to change the commit msg.

I said in the previous email[1] that I'd add a syscall without wrapper 
to the RFC.

[1]: 
<https://lore.kernel.org/linux-man/938df2c0-04b5-f6a4-79c3-b8fe09973828@gmail.com/T/#mceefe007c2e4eb0419833583d893eb37dd02b235>

> 
> I'm still not sure whether I consider this change worthwhile
> for cases like this where the differences between the libc
> wrapper and the syscall are minor enough to probably
> be irrelevant to user-space programmers. But, if we do
> add something like this, I thing a sentence or two
> of English is desirable as well. Something like
> 
>     The kernel system call differs slightly from the glibc
>     wrapper, in the addition of 'const' to two parameter
>     declarations:
>      
>          syscall(...)
> 
> But, before we go down this track, I'd like to get a sense
> of how many cases there are like this where there are these
> small differences between the glibc wrapper and the syscall
> interface. I'm not meaning you should check every system call
> now.  But maybe you can let me know something like: of the first
> 20 system calls I checked, there X system calls that had
> such differences.

Don't worry, I'm first fixing the prototypes of man3.  This is only a 
prototype, and I'm not yet sure about which way is better to go.  I'm 
only showing ideas.

In a few days, I'll compare side to side the syscalls and their wrappers 
to see that.  If you want to have a look yourself, you can use these 
side by side:


  For reading the glibc wrappers:

  .../gnu/glibc$ man_lsfunc ../../linux/man-pages/man2 \
    |while read -r syscall; do
            echo "=============================  ${syscall}";
            grep_glibc_prototype ${syscall};
    done \
    |sed -e 's/\bextern //' -e 's/\b_*//g' \
    |less;

  For reading the kernel syscalls:

  .../linux/linux$ man_lsfunc ../man-pages/man2/ \
    |while read -r syscall; do
            echo "=============================  ${syscall}";
            grep_syscall ${syscall};
    done \
    |less;

Thanks,

Alex

> 
> Thanks,
> 
> Michael
> 
>> ---
>>   man2/execve.2     | 15 +++++++++++++--
>>   man2/membarrier.2 | 14 +++++---------
>>   2 files changed, 18 insertions(+), 11 deletions(-)
>>
>> diff --git a/man2/execve.2 b/man2/execve.2
>> index 027a0efd2..318c71c85 100644
>> --- a/man2/execve.2
>> +++ b/man2/execve.2
>> @@ -41,8 +41,8 @@ execve \- execute program
>>   .nf
>>   .B #include <unistd.h>
>>   .PP
>> -.BI "int execve(const char *" pathname ", char *const " argv [],
>> -.BI "           char *const " envp []);
>> +.BI "int execve(const char *" pathname ",
>> +.BI "           char *const " argv "[], char *const " envp []);
>>   .fi
>>   .SH DESCRIPTION
>>   .BR execve ()
>> @@ -772,6 +772,17 @@ Thus, this argument list was not directly usable in a further
>>   .BR exec ()
>>   call.
>>   Since UNIX\ V7, both are NULL.
>> +.SS C library/kernel differences
>> +.RS 4
>> +.nf
>> +/* Kernel system call: */
>> +.BR "#include <sys/syscall.h>" "        /* For " SYS_* " constants */"
>> +.B #include <unistd.h>
>> +.PP
>> +.BI "int syscall(SYS_execve, const char *" pathname ,
>> +.BI "            const char *const " argv "[], const char *const " envp []);
>> +.fi
>> +.RE
>>   .\"
>>   .\" .SH BUGS
>>   .\" Some Linux versions have failed to check permissions on ELF
>> diff --git a/man2/membarrier.2 b/man2/membarrier.2
>> index 173195484..25d6add77 100644
>> --- a/man2/membarrier.2
>> +++ b/man2/membarrier.2
>> @@ -28,13 +28,12 @@ membarrier \- issue memory barriers on a set of threads
>>   .SH SYNOPSIS
>>   .nf
>>   .PP
>> -.B #include <linux/membarrier.h>
>> +.BR "#include <linux/membarrier.h>" "   /* For " MEMBARRIER_* " constants */"
>> +.BR "#include <sys/syscall.h>" "        /* For " SYS_* " constants */"
>> +.B #include <unistd.h>
>>   .PP
>> -.BI "int membarrier(int " cmd ", unsigned int " flags ", int " cpu_id );
>> +.BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags ", int " cpu_id );
>>   .fi
>> -.PP
>> -.IR Note :
>> -There is no glibc wrapper for this system call; see NOTES.
>>   .SH DESCRIPTION
>>   The
>>   .BR membarrier ()
>> @@ -295,7 +294,7 @@ was:
>>   .PP
>>   .in +4n
>>   .EX
>> -.BI "int membarrier(int " cmd ", int " flags );
>> +.BI "int syscall(SYS_membarrier, int " cmd ", int " flags );
>>   .EE
>>   .in
>>   .SH CONFORMING TO
>> @@ -322,9 +321,6 @@ Examples where
>>   .BR membarrier ()
>>   can be useful include implementations
>>   of Read-Copy-Update libraries and garbage collectors.
>> -.PP
>> -Glibc does not provide a wrapper for this system call; call it using
>> -.BR syscall (2).
>>   .SH EXAMPLES
>>   Assuming a multithreaded application where "fast_path()" is executed
>>   very frequently, and where "slow_path()" is executed infrequently, the
>>
> 
>

Hi Michael,


Okay, after a few days of thinking, I'm not sure about what to do in 
some cases.

But I think we agree to use syscall(SYS_ ...) for syscalls with no 
wrapper (such as membarrier(2)).

Is that right?

I think it may be better to separate this into 2 sets of changes.

1)  Document syscalls without wrappers as syscall(SYS_ ...).
     We could already start with this.
     (Actually, after I finish fixing the prototypes in man3.)
     This change will be fast, because there aren't many of these.

2)  Do the rest, I don't know yet how.  We'll see.


Thanks,

Alex