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

[Alejandro Colomar (man-pages)]

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@xxxxxxxxx>
>
> 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@xxxxxxxxx/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

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