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/
