From patchwork Sun Feb 14 13:39:07 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 42026 Return-Path: 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 ; 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 ; 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 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Alejandro Colomar via Libc-alpha From: Alejandro Colomar Reply-To: Alejandro Colomar Cc: Alejandro Colomar , linux-man@vger.kernel.org, libc-alpha@sourceware.org, linux-kernel@vger.kernel.org, Florian Weimer Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" 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 --- 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(-) 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 .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 +.B #include +.PP +.BI "int syscall(SYS_execve, const char *" pathname , +.BI " const char *const " argv "[], const char *const " envp []); .fi .SH DESCRIPTION .BR execve ()