Message ID | 20210214133907.157320-1-alx.manpages@gmail.com |
---|---|
State | Not applicable |
Headers |
Return-Path: <libc-alpha-bounces@sourceware.org> X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 9FC7D384B13D; Sun, 14 Feb 2021 13:48:03 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 9FC7D384B13D DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1613310483; bh=RbmGRai9khpzA9lGPDc0qiZjCQHwpScfyjwp7gSkoB8=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=jmqvZqhVFhF+NgLqrAa5Y5D2Mr+zlY4iLhy16lFah2+z80xJ0Gz0xYat8TV1CKsDT 20oSATM81TMi0QhbNkGIc61ZcwzBEhuoEnJ2IAV54gUb9uCKOUouXeDks+1+2R6Ixf ofFSYrUcfkMi6MrsdDfhHV3yoZIeRIzuZ9dkGmMQ= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by sourceware.org (Postfix) with ESMTPS id 271213858024 for <libc-alpha@sourceware.org>; Sun, 14 Feb 2021 13:48:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 271213858024 Received: by mail-wr1-x42b.google.com with SMTP id 7so5459689wrz.0 for <libc-alpha@sourceware.org>; Sun, 14 Feb 2021 05:48:01 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=RbmGRai9khpzA9lGPDc0qiZjCQHwpScfyjwp7gSkoB8=; b=nB7GDROkmDawd9cb8CBGeAc5RHPKniBx1NYIF946qIBhaXdJoeTHLZkyYqbKTijDTF +JjoAb1o3zJTn8mD61KxqgvpA2hD7eCTiSBEGRxLw4e7RDQBh34xLc0/ibgcGw4v4Vca bgBga6CqlEQlPd0uzQqiRQ+WASgMga0KuXfAWSK+SzgIjFjO/RZdGrCGu7NsJmEf3UTD PKM5mMlT1Uv7fR7u8oj48gTMgxR1qjGpZSemD8oK8mP09cJSxbZHNpSOgzkJDpacbKnM cnedX4EJizeGaF9ZLDs1RyzDSQ78GYWdrEOWO98ER3YBhx3x8OpNEQ7Ql5Bpk0VZlE2l PJ7Q== X-Gm-Message-State: AOAM533QkyaMihiK0jSOIAEXGzc3s3s36iX6O9WFX5dAd0iDWjqLHAv/ PHsNWztctVYZB1QKHbE7exo= X-Google-Smtp-Source: ABdhPJwE/OcdZtUsKR+ObA23qr6mcRPy6c1CFectqeWEng4CxUFZDkB3rh5LeQmOwL1/NObjx9CSpw== X-Received: by 2002:adf:f6d0:: with SMTP id y16mr14080936wrp.351.1613310480352; Sun, 14 Feb 2021 05:48:00 -0800 (PST) Received: from localhost.localdomain ([170.253.36.171]) by smtp.googlemail.com with ESMTPSA id z8sm18795278wrr.55.2021.02.14.05.47.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Feb 2021 05:47:59 -0800 (PST) To: mtk.manpages@gmail.com Subject: [RFC] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls Date: Sun, 14 Feb 2021 14:39:07 +0100 Message-Id: <20210214133907.157320-1-alx.manpages@gmail.com> X-Mailer: git-send-email 2.30.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-11.8 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list <libc-alpha.sourceware.org> List-Unsubscribe: <https://sourceware.org/mailman/options/libc-alpha>, <mailto:libc-alpha-request@sourceware.org?subject=unsubscribe> List-Archive: <https://sourceware.org/pipermail/libc-alpha/> List-Post: <mailto:libc-alpha@sourceware.org> List-Help: <mailto:libc-alpha-request@sourceware.org?subject=help> List-Subscribe: <https://sourceware.org/mailman/listinfo/libc-alpha>, <mailto:libc-alpha-request@sourceware.org?subject=subscribe> From: Alejandro Colomar via Libc-alpha <libc-alpha@sourceware.org> Reply-To: Alejandro Colomar <alx.manpages@gmail.com> Cc: Alejandro Colomar <alx.manpages@gmail.com>, linux-man@vger.kernel.org, libc-alpha@sourceware.org, linux-kernel@vger.kernel.org, Florian Weimer <fweimer@redhat.com> Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" <libc-alpha-bounces@sourceware.org> |
Series |
[RFC] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls
|
|
Commit Message
Alejandro Colomar
Feb. 14, 2021, 1:39 p.m. UTC
Until now, the manual pages have (usually) documented only either
the glibc (or another library) wrapper for a syscall, or the raw
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.
It will also be much clearer for the reader where the syscall
comes from (kernel? glibc? other?), by adding an explicit comment
at the beginning of the prototypes. This removes the need of
scrolling down to NOTES to see that info.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
Hi all,
This is a prototype for doing some important changes to the SYNOPSIS
of the man-pages.
The commit message above explains the idea quite well. A few details
that couldn't be shown on this commit are:
For cases where the wrapper is provided by a library other than glibc,
I'd simply change the comment. For example, for move_pages(2),
it would say /* libnuma wrapper function: */.
I think this would make the samll notes warning that there's no glibc
wrapper function deprecated (but we could keep them for some time and
decide that later).
While changing this, I'd also make sure that the headers are correct,
and clearly differentiate which headers are needed for the raw syscall
and for the wrapper function.
This change will probably take more than one release of the man-pages
to complete.
Any thoughts?
Thanks,
Alex
---
man2/execve.2 | 12 ++++++++++--
1 file changed, 10 insertions(+), 2 deletions(-)
Comments
Hi Alex, On 2/14/21 2:39 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 raw > 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. > > It will also be much clearer for the reader where the syscall > comes from (kernel? glibc? other?), by adding an explicit comment > at the beginning of the prototypes. This removes the need of > scrolling down to NOTES to see that info. > > Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> > --- > > Hi all, > > This is a prototype for doing some important changes to the SYNOPSIS > of the man-pages. > > The commit message above explains the idea quite well. A few details > that couldn't be shown on this commit are: > > For cases where the wrapper is provided by a library other than glibc, > I'd simply change the comment. For example, for move_pages(2), > it would say /* libnuma wrapper function: */. > > I think this would make the samll notes warning that there's no glibc > wrapper function deprecated (but we could keep them for some time and > decide that later). > > While changing this, I'd also make sure that the headers are correct, > and clearly differentiate which headers are needed for the raw syscall > and for the wrapper function. > > This change will probably take more than one release of the man-pages > to complete. > > Any thoughts? My first impression is that I'm not keen on this. We'll add extra text to all Section 2 pages, and in many (most?) cases the info will be redundant (i.e., the wrapper and the syscall() notation will express the same info). In other cases, I suspect the info will be largely irrelevant to the user. To take an example: to whom will the difference that you document below for execve() matter, how will it matter, and does it matter enough that we headline the info in the pages? I'd want cogent answers to those questions before considering a wide-ranging change. There are indeed cases where the wrapper API differs in significant ways from the syscall API (and these differences are usually captured in the " C library/kernel differences" subsections, such as for pselect()/pselect6() in select(2)). But I imagine that that is the case in only a smallish minority of the pages. And indeed there are a very few syscalls that have wrappers provided in another library. But it's a very small percentage I think, and best documented case by case in specific pages. The default presumption is that the wrapper is in the C library. There are other cases where I think it may be worthwhile considering the syscall() notation: 1. Where the system call has no wrapper. In that case, we might use the syscall() notation in the SYNOPISIS as both (a) a clear indication that there is no wrapper and (b) instructions to the reader about how to call the system call using syscall(). 2. In cases where there is a "significant" difference between the wrapper and the system call. In this case, we might also place the syscall() notation in the SYNOPSIS, or (perhaps more likely) in the NOTES Thanks, Michael > > Thanks, > > Alex > > --- > man2/execve.2 | 12 ++++++++++-- > 1 file changed, 10 insertions(+), 2 deletions(-) > > diff --git a/man2/execve.2 b/man2/execve.2 > index 639e3b4b9..87ff022ce 100644 > --- a/man2/execve.2 > +++ b/man2/execve.2 > @@ -39,10 +39,18 @@ > execve \- execute program > .SH SYNOPSIS > .nf > +/* Glibc wrapper function: */ > .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 []); > +.PP > + /* Raw system call: */ > +.B #include <sys/syscall.h> > +.B #include <unistd.h> > +.PP > +.BI "int syscall(SYS_execve, const char *" pathname , > +.BI " const char *const " argv "[], const char *const " envp []); > .fi > .SH DESCRIPTION > .BR execve () >
Hi Micahel, On 2/18/21 1:27 PM, Michael Kerrisk (man-pages) wrote: > Hi Alex, > > On 2/14/21 2:39 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 raw >> 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. >> >> It will also be much clearer for the reader where the syscall >> comes from (kernel? glibc? other?), by adding an explicit comment >> at the beginning of the prototypes. This removes the need of >> scrolling down to NOTES to see that info. >> >> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> >> --- >> >> Hi all, >> >> This is a prototype for doing some important changes to the SYNOPSIS >> of the man-pages. >> >> The commit message above explains the idea quite well. A few details >> that couldn't be shown on this commit are: >> >> For cases where the wrapper is provided by a library other than glibc, >> I'd simply change the comment. For example, for move_pages(2), >> it would say /* libnuma wrapper function: */. >> >> I think this would make the samll notes warning that there's no glibc >> wrapper function deprecated (but we could keep them for some time and >> decide that later). >> >> While changing this, I'd also make sure that the headers are correct, >> and clearly differentiate which headers are needed for the raw syscall >> and for the wrapper function. >> >> This change will probably take more than one release of the man-pages >> to complete. >> >> Any thoughts? > > My first impression is that I'm not keen on this. We'll add extra > text to all Section 2 pages, and in many (most?) cases the info > will be redundant (i.e., the wrapper and the syscall() notation > will express the same info). In other cases, I suspect the info > will be largely irrelevant to the user. To take an example: to > whom will the difference that you document below for execve() > matter, how will it matter, and does it matter enough that we > headline the info in the pages? I'd want cogent answers to > those questions before considering a wide-ranging change. It will matter to: 1) Users of old systems where the glibc wrapper is not yet present. 3) Users of some unicorn Linux distributions that use a C library different than glibc and may not have wrappers for some syscalls that glibc provides. 2) Library (libc) developers. Those won't have the glibc wrapper available for them, and will have to use syscall(2). The kernel syscall info would be highly valuable for them. However, the sum of them is probably not a big number of people. > > There are indeed cases where the wrapper API differs in > significant ways from the syscall API (and these differences > are usually captured in the " C library/kernel differences" > subsections, such as for pselect()/pselect6() in select(2)). > But I imagine that that is the case in only a smallish > minority of the pages. > > And indeed there are a very few syscalls that have wrappers > provided in another library. But it's a very small percentage > I think, and best documented case by case in specific pages. > The default presumption is that the wrapper is in the C library. Agree. > > There are other cases where I think it may be worthwhile > considering the syscall() notation: > > 1. Where the system call has no wrapper. In that case, we might > use the syscall() notation in the SYNOPISIS as both > (a) a clear indication that there is no wrapper and > (b) instructions to the reader about how to call the > system call using syscall(). Yes. > > 2. In cases where there is a "significant" difference between > the wrapper and the system call. In this case, we might > also place the syscall() notation in the SYNOPSIS, or > (perhaps more likely) in the NOTES Yes. I think it would be equally good to have the kernel syscall prototype in "C library/kernel ABI differences" in those cases where there is a glibc wrapper (even if it's quite different). It would be even better, as it would clearly mark the syscall(2) method as a second-class method, that should be avoided if possible. And also wouldn't add lines to the SYNOPSIS. However, we should probably have that subsection for all syscalls, including those where the prototype is very similar to the glibc one, to support those who need to use the kernel syscall, and provide them with the exact types that the kernel expects.(except for those unsupported by libraries, of course, which would have the syscall(SYS_xxx) prototype in the SYNOPSIS). I'll prepare a new RFC with this, with 2 pages: one with wrapper and one without wrapper. Thanks, Alex See also: <https://lwn.net/Articles/534682/> <https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source> > > Thanks, > > Michael > >> >> Thanks, >> >> Alex >> >> --- >> man2/execve.2 | 12 ++++++++++-- >> 1 file changed, 10 insertions(+), 2 deletions(-) >> >> diff --git a/man2/execve.2 b/man2/execve.2 >> index 639e3b4b9..87ff022ce 100644 >> --- a/man2/execve.2 >> +++ b/man2/execve.2 >> @@ -39,10 +39,18 @@ >> execve \- execute program >> .SH SYNOPSIS >> .nf >> +/* Glibc wrapper function: */ >> .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 []); >> +.PP >> + /* Raw system call: */ >> +.B #include <sys/syscall.h> >> +.B #include <unistd.h> >> +.PP >> +.BI "int syscall(SYS_execve, const char *" pathname , >> +.BI " const char *const " argv "[], const char *const " envp []); >> .fi >> .SH DESCRIPTION >> .BR execve () >> > >
diff --git a/man2/execve.2 b/man2/execve.2 index 639e3b4b9..87ff022ce 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -39,10 +39,18 @@ execve \- execute program .SH SYNOPSIS .nf +/* Glibc wrapper function: */ .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 []); +.PP + /* Raw system call: */ +.B #include <sys/syscall.h> +.B #include <unistd.h> +.PP +.BI "int syscall(SYS_execve, const char *" pathname , +.BI " const char *const " argv "[], const char *const " envp []); .fi .SH DESCRIPTION .BR execve ()