Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Alejandro Colomar <alx.manpages@gmail.com>
To:     mtk.manpages@gmail.com
Cc:     Alejandro Colomar <alx.manpages@gmail.com>,
        linux-man@vger.kernel.org, libc-alpha@sourceware.org,
        Florian Weimer <fweimer@redhat.com>,
        linux-kernel@vger.kernel.org
Subject: [RFC v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls
Date:   Thu, 18 Feb 2021 16:13:42 +0100
Message-Id: <20210218151341.51095-1-alx.manpages@gmail.com>
In-Reply-To: <938df2c0-04b5-f6a4-79c3-b8fe09973828@gmail.com>
References: <938df2c0-04b5-f6a4-79c3-b8fe09973828@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

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>
---
 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
-- 
2.30.1.721.g45526154a5