Messages in this thread Patch in this message | | | Subject | Re: [RFC v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls | From | "Alejandro Colomar (man-pages)" <> | Date | Fri, 19 Feb 2021 13:56:37 +0100 |
| |
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 >> > >
-- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
| |