From patchwork Thu Feb 18 15:13:42 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: [RFC, v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls X-Patchwork-Submitter: =?utf-8?q?F=C4=81ng-ru=C3=AC_S=C3=B2ng_via_Libc-alpha?= X-Patchwork-Id: 49298 Message-Id: <20210218151341.51095-1-alx.manpages@gmail.com> To: mtk.manpages@gmail.com Cc: Alejandro Colomar , linux-man@vger.kernel.org, libc-alpha@sourceware.org, Florian Weimer , linux-kernel@vger.kernel.org Date: Thu, 18 Feb 2021 16:13:42 +0100 From: Alejandro Colomar via Libc-alpha List-Id: Libc-alpha mailing list 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 --- man2/execve.2 | 15 +++++++++++++-- man2/membarrier.2 | 14 +++++--------- 2 files changed, 18 insertions(+), 11 deletions(-) -- 2.30.1.721.g45526154a5 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 .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 " " /* For " SYS_* " constants */" +.B #include +.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 +.BR "#include " " /* For " MEMBARRIER_* " constants */" +.BR "#include " " /* For " SYS_* " constants */" +.B #include .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