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@xxxxxxxxx> --- 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 <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 () -- 2.30.0
