From: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: linux-man@vger.kernel.org, libc-alpha@sourceware.org,
Florian Weimer <fweimer@redhat.com>,
linux-kernel@vger.kernel.org
Subject: Re: [RFC v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls
Date: Fri, 19 Feb 2021 13:56:37 +0100 [thread overview]
Message-ID: <ca34c574-72f1-f174-1de4-e2c1b7600640@gmail.com> (raw)
In-Reply-To: <db155b69-e58c-32c2-6fc7-89b8329fbf2c@gmail.com>
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/
next prev parent reply other threads:[~2021-02-19 12:57 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-02-14 13:39 [RFC] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls Alejandro Colomar
2021-02-18 12:27 ` Michael Kerrisk (man-pages)
2021-02-18 14:01 ` Alejandro Colomar (man-pages)
2021-02-18 15:13 ` [RFC v2] " Alejandro Colomar
2021-02-19 12:39 ` Michael Kerrisk (man-pages)
2021-02-19 12:56 ` Alejandro Colomar (man-pages) [this message]
2021-02-26 11:52 ` Alejandro Colomar (man-pages)
2021-03-13 19:25 ` [RFC v3 00/17] man2: Use syscall(SYS_...); for system calls without a wrapper Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 01/17] access.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 02/17] alloc_hugepages.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 03/17] arch_prctl.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 04/17] arch_prctl.2: SYNOPSIS: Remove unused includes Alejandro Colomar
2021-03-15 18:00 ` AW: " Walter Harms
2021-03-16 16:50 ` Alejandro Colomar (man-pages)
2021-03-13 19:25 ` [RFC v3 05/17] capget.2: Use syscall(SYS_...); for system calls without a wrapper Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 06/17] clone.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 07/17] delete_module.2: wfix Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 08/17] epoll_wait.2: Use syscall(SYS_...); for system calls without a wrapper Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 09/17] execveat.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 10/17] exit_group.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 11/17] futex.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 12/17] getdents.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 13/17] getunwind.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 14/17] get_robust_list.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 16/17] init_module.2: " Alejandro Colomar
2021-03-13 19:25 ` [RFC v3 17/17] ioprio_set.2: " Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ca34c574-72f1-f174-1de4-e2c1b7600640@gmail.com \
--to=alx.manpages@gmail.com \
--cc=fweimer@redhat.com \
--cc=libc-alpha@sourceware.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).