[RFC] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

[RFC] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

[Alejandro Colomar]

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(-)

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

Re: [RFC] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

[Michael Kerrisk (man-pages)]

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 ()
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [RFC] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

[Alejandro Colomar (man-pages)]

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 ()
>>
> 
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[RFC v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

[Alejandro Colomar]

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

Re: [RFC v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

[Michael Kerrisk (man-pages)]

Hey Alex,

On 2/18/21 4:13 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
> 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>

This patch also changes madvise.2, I suppose accidentally.

I'm still not sure whether I consider this change worthwhile
for cases like this where the differences between the libc
wrapper and the syscall are minor enough to probably
be irrelevant to user-space programmers. But, if we do
add something like this, I thing a sentence or two
of English is desirable as well. Something like

   The kernel system call differs slightly from the glibc
   wrapper, in the addition of 'const' to two parameter
   declarations:
    
        syscall(...)

But, before we go down this track, I'd like to get a sense 
of how many cases there are like this where there are these
small differences between the glibc wrapper and the syscall
interface. I'm not meaning you should check every system call
now.  But maybe you can let me know something like: of the first
20 system calls I checked, there X system calls that had 
such differences.

Thanks,

Michael

> ---
>  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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [RFC v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

[Alejandro Colomar (man-pages)]

Hi Michael,

On 2/19/21 1:39 PM, Michael Kerrisk (man-pages) wrote:
> Hey Alex,
> 
> On 2/18/21 4:13 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
>> 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>
> 
> This patch also changes madvise.2, I suppose accidentally.

I forgot to change the commit msg.

I said in the previous email[1] that I'd add a syscall without wrapper 
to the RFC.

[1]: 
<https://lore.kernel.org/linux-man/938df2c0-04b5-f6a4-79c3-b8fe09973828@gmail.com/T/#mceefe007c2e4eb0419833583d893eb37dd02b235>

> 
> I'm still not sure whether I consider this change worthwhile
> for cases like this where the differences between the libc
> wrapper and the syscall are minor enough to probably
> be irrelevant to user-space programmers. But, if we do
> add something like this, I thing a sentence or two
> of English is desirable as well. Something like
> 
>     The kernel system call differs slightly from the glibc
>     wrapper, in the addition of 'const' to two parameter
>     declarations:
>      
>          syscall(...)
> 
> But, before we go down this track, I'd like to get a sense
> of how many cases there are like this where there are these
> small differences between the glibc wrapper and the syscall
> interface. I'm not meaning you should check every system call
> now.  But maybe you can let me know something like: of the first
> 20 system calls I checked, there X system calls that had
> such differences.

Don't worry, I'm first fixing the prototypes of man3.  This is only a 
prototype, and I'm not yet sure about which way is better to go.  I'm 
only showing ideas.

In a few days, I'll compare side to side the syscalls and their wrappers 
to see that.  If you want to have a look yourself, you can use these 
side by side:


  For reading the glibc wrappers:

  .../gnu/glibc$ man_lsfunc ../../linux/man-pages/man2 \
    |while read -r syscall; do
            echo "=============================  ${syscall}";
            grep_glibc_prototype ${syscall};
    done \
    |sed -e 's/\bextern //' -e 's/\b_*//g' \
    |less;

  For reading the kernel syscalls:

  .../linux/linux$ man_lsfunc ../man-pages/man2/ \
    |while read -r syscall; do
            echo "=============================  ${syscall}";
            grep_syscall ${syscall};
    done \
    |less;

Thanks,

Alex

> 
> Thanks,
> 
> Michael
> 
>> ---
>>   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
>>
> 
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [RFC v2] execve.2: SYNOPSIS: Document both glibc wrapper and kernel sycalls

[Alejandro Colomar (man-pages)]

Hi Michael,


Okay, after a few days of thinking, I'm not sure about what to do in 
some cases.

But I think we agree to use syscall(SYS_ ...) for syscalls with no 
wrapper (such as membarrier(2)).

Is that right?

I think it may be better to separate this into 2 sets of changes.

1)  Document syscalls without wrappers as syscall(SYS_ ...).
     We could already start with this.
     (Actually, after I finish fixing the prototypes in man3.)
     This change will be fast, because there aren't many of these.

2)  Do the rest, I don't know yet how.  We'll see.


Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[RFC v3 00/17] man2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Hi Michael,

This draft is more polished than my inital idea.

I changed only those functions without a wrapper.
If we decide later to do something different, we'll see.

Any thoughts?

Cheers,

Alex

P.S.: [RFC v3 15/17] doesn't exist :)

Alejandro Colomar (17):
  access.2: Use syscall(SYS_...); for system calls without a wrapper
  alloc_hugepages.2: Use syscall(SYS_...); for system calls without a
    wrapper
  arch_prctl.2: Use syscall(SYS_...); for system calls without a wrapper
  arch_prctl.2: SYNOPSIS: Remove unused includes
  capget.2: Use syscall(SYS_...); for system calls without a wrapper
  clone.2: Use syscall(SYS_...); for system calls without a wrapper
  delete_module.2: wfix
  epoll_wait.2: Use syscall(SYS_...); for system calls without a wrapper
  execveat.2: Use syscall(SYS_...); for system calls without a wrapper
  exit_group.2: Use syscall(SYS_...); for system calls without a wrapper
  futex.2: Use syscall(SYS_...); for system calls without a wrapper
  getdents.2: Use syscall(SYS_...); for system calls without a wrapper
  getunwind.2: Use syscall(SYS_...); for system calls without a wrapper
  get_robust_list.2: Use syscall(SYS_...); for system calls without a
    wrapper
  init_module.2: Use syscall(SYS_...); for system calls without a
    wrapper
  ioprio_set.2: Use syscall(SYS_...); for system calls without a wrapper

 man2/access.2          | 11 ++++++++---
 man2/alloc_hugepages.2 |  7 ++++---
 man2/arch_prctl.2      | 15 +++++----------
 man2/capget.2          | 18 ++++++++----------
 man2/clone.2           | 16 +++++-----------
 man2/delete_module.2   |  2 +-
 man2/epoll_wait.2      | 32 +++++++++++++++++++-------------
 man2/execveat.2        | 13 ++++---------
 man2/exit_group.2      |  5 +++--
 man2/futex.2           | 19 +++++++------------
 man2/get_robust_list.2 | 20 ++++++++------------
 man2/getdents.2        | 12 ++++++++----
 man2/getunwind.2       | 14 ++++----------
 man2/init_module.2     | 21 ++++++++++++---------
 man2/ioprio_set.2      | 14 ++++++--------
 15 files changed, 102 insertions(+), 117 deletions(-)

-- 
2.30.2

[RFC v3 01/17] access.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/access.2 | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/man2/access.2 b/man2/access.2
index 77ff2bd99..b662d07cf 100644
--- a/man2/access.2
+++ b/man2/access.2
@@ -49,15 +49,20 @@ access, faccessat, faccessat2 \- check user's permissions for a file
 .PP
 .BI "int access(const char *" pathname ", int " mode );
 .PP
-.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
 .B #include <unistd.h>
 .PP
 .BI "int faccessat(int " dirfd ", const char *" pathname ", int " \
 mode ", int " flags );
                 /* But see C library/kernel differences, below */
 .PP
-.BI "int faccessat2(int " dirfd ", const char *" pathname ", int " \
-mode ", int " flags );
+.BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* For " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_faccessat2,"
+.BI "            int " dirfd ", const char *" pathname ", int " mode \
+", int " flags );
 .fi
 .PP
 .RS -4
-- 
2.30.2

[RFC v3 02/17] alloc_hugepages.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/alloc_hugepages.2 | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2
index 623eeab6e..a3a157725 100644
--- a/man2/alloc_hugepages.2
+++ b/man2/alloc_hugepages.2
@@ -27,11 +27,12 @@
 alloc_hugepages, free_hugepages \- allocate or free huge pages
 .SH SYNOPSIS
 .nf
-.BI "void *alloc_hugepages(int " key ", void *" addr ", size_t " len ,
-.BI "                      int " prot ", int " flag );
+.BI "void *syscall(SYS_alloc_hugepages, int " key ", void *" addr \
+", size_t " len ,
+.BI "              int " prot ", int " flag );
 .\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr,
 .\" unsigned long len, int prot, int flag);
-.BI "int free_hugepages(void *" addr );
+.BI "int syscall(SYS_free_hugepages, void *" addr );
 .\" asmlinkage int sys_free_hugepages(unsigned long addr);
 .fi
 .SH DESCRIPTION
-- 
2.30.2

[RFC v3 03/17] arch_prctl.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/arch_prctl.2 | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
index f9a9dc39d..8706cd1ec 100644
--- a/man2/arch_prctl.2
+++ b/man2/arch_prctl.2
@@ -27,15 +27,14 @@
 arch_prctl \- set architecture-specific thread state
 .SH SYNOPSIS
 .nf
-.B #include <asm/prctl.h>
+.BR "#include <asm/prctl.h>" "        /* Definition of " ARCH_* " constants */"
 .B #include <sys/prctl.h>
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int arch_prctl(int " code ", unsigned long " addr );
-.BI "int arch_prctl(int " code ", unsigned long *" addr );
+.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long " addr );
+.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long *" addr );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 .BR arch_prctl ()
 sets architecture-specific process or thread state.
@@ -177,9 +176,6 @@ and
 in the same thread is dangerous, as they may overwrite each other's
 TLS entries.
 .PP
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 .I FS
 may be already used by the threading library.
 Programs that use
-- 
2.30.2

[RFC v3 04/17] arch_prctl.2: SYNOPSIS: Remove unused includes

[Alejandro Colomar]

AFAICS, there's no reason to include that.
All of the macros that this function uses
are already defined in the other headers.

Cc: glibc <libc-alpha@sourceware.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/arch_prctl.2 | 1 -
 1 file changed, 1 deletion(-)

diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
index 8706cd1ec..d1b9e16f9 100644
--- a/man2/arch_prctl.2
+++ b/man2/arch_prctl.2
@@ -28,7 +28,6 @@ arch_prctl \- set architecture-specific thread state
 .SH SYNOPSIS
 .nf
 .BR "#include <asm/prctl.h>" "        /* Definition of " ARCH_* " constants */"
-.B #include <sys/prctl.h>
 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
-- 
2.30.2

AW: [RFC v3 04/17] arch_prctl.2: SYNOPSIS: Remove unused includes

[Walter Harms]

I have learned the other way around:
#include <sys/prctl.h>
Is a general system header to use that may include
the asm/prctrl.h what should never be included by
userspace programms.

jm2c,
re,
 wh
________________________________________
Von: Alejandro Colomar <alx.manpages@gmail.com>
Gesendet: Samstag, 13. März 2021 20:25:14
An: mtk.manpages@gmail.com
Cc: Alejandro Colomar; linux-man@vger.kernel.org; libc-alpha@sourceware.org; linux-kernel@vger.kernel.org; Florian Weimer
Betreff: [RFC v3 04/17] arch_prctl.2: SYNOPSIS: Remove unused includes

WARNUNG: Diese E-Mail kam von außerhalb der Organisation. Klicken Sie nicht auf Links oder öffnen Sie keine Anhänge, es sei denn, Sie kennen den Absender und wissen, dass der Inhalt sicher ist.


AFAICS, there's no reason to include that.
All of the macros that this function uses
are already defined in the other headers.

Cc: glibc <libc-alpha@sourceware.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/arch_prctl.2 | 1 -
 1 file changed, 1 deletion(-)

diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
index 8706cd1ec..d1b9e16f9 100644
--- a/man2/arch_prctl.2
+++ b/man2/arch_prctl.2
@@ -28,7 +28,6 @@ arch_prctl \- set architecture-specific thread state
 .SH SYNOPSIS
 .nf
 .BR "#include <asm/prctl.h>" "        /* Definition of " ARCH_* " constants */"
-.B #include <sys/prctl.h>
 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
--
2.30.2

Re: AW: [RFC v3 04/17] arch_prctl.2: SYNOPSIS: Remove unused includes

[Alejandro Colomar (man-pages)]

Hi Walter,

On 3/15/21 7:00 PM, Walter Harms wrote:
> I have learned the other way around:
> #include <sys/prctl.h>
> Is a general system header to use that may include
> the asm/prctrl.h what should never be included by
> userspace programms.
> 

Are you sure that <sys/prctl.h> includes <asm/prctl.h>?

user@debian:/usr/include$ grep -rn '\bARCH_'
asm-generic/statfs.h:42:#ifndef ARCH_PACK_STATFS64
asm-generic/statfs.h:43:#define ARCH_PACK_STATFS64
asm-generic/statfs.h:59:} ARCH_PACK_STATFS64;
asm-generic/statfs.h:65:#ifndef ARCH_PACK_COMPAT_STATFS64
asm-generic/statfs.h:66:#define ARCH_PACK_COMPAT_STATFS64
asm-generic/statfs.h:82:} ARCH_PACK_COMPAT_STATFS64;
x86_64-linux-gnu/asm/statfs.h:10:#define ARCH_PACK_COMPAT_STATFS64 
__attribute__((packed,aligned(4)))
x86_64-linux-gnu/asm/prctl.h:5:#define ARCH_SET_GS		0x1001
x86_64-linux-gnu/asm/prctl.h:6:#define ARCH_SET_FS		0x1002
x86_64-linux-gnu/asm/prctl.h:7:#define ARCH_GET_FS		0x1003
x86_64-linux-gnu/asm/prctl.h:8:#define ARCH_GET_GS		0x1004
x86_64-linux-gnu/asm/prctl.h:10:#define ARCH_GET_CPUID		0x1011
x86_64-linux-gnu/asm/prctl.h:11:#define ARCH_SET_CPUID		0x1012
x86_64-linux-gnu/asm/prctl.h:13:#define ARCH_MAP_VDSO_X32	0x2001
x86_64-linux-gnu/asm/prctl.h:14:#define ARCH_MAP_VDSO_32	0x2002
x86_64-linux-gnu/asm/prctl.h:15:#define ARCH_MAP_VDSO_64	0x2003
x86_64-linux-gnu/asm/auxvec.h:13:/* entries in ARCH_DLINFO: */
user@debian:/usr/include$ grep -rn 'asm/prctl.h'
user@debian:/usr/include$

At least on my system, no header seems to be including <asm/prctl.h>.

Thanks,

Alex



-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[RFC v3 05/17] capget.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/capget.2 | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/man2/capget.2 b/man2/capget.2
index ea504c28c..981645f90 100644
--- a/man2/capget.2
+++ b/man2/capget.2
@@ -18,14 +18,15 @@
 capget, capset \- set/get capabilities of thread(s)
 .SH SYNOPSIS
 .nf
-.B #include <sys/capability.h>
+.BR "#include <linux/capability.h>" " /* Definition of types and constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
-.BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
+.BI "int syscall(SYS_capget, cap_user_header_t " hdrp ,
+.BI "            cap_user_data_t " datap );
+.BI "int syscall(SYS_capset, cap_user_header_t " hdrp ,
+.BI "            const cap_user_data_t " datap );
 .fi
-.PP
-.IR Note :
-There are no glibc wrappers for these system calls; see NOTES.
 .SH DESCRIPTION
 These two system calls are the raw kernel interface for getting and
 setting thread capabilities.
@@ -40,7 +41,7 @@ The portable interfaces are
 .BR cap_set_proc (3)
 and
 .BR cap_get_proc (3);
-if possible, you should use those interfaces in applications.
+if possible, you should use those interfaces in applications; see NOTES.
 .\"
 .SS Current details
 Now that you have been warned, some current kernel details.
@@ -239,9 +240,6 @@ No such thread.
 .SH CONFORMING TO
 These system calls are Linux-specific.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 The portable interface to the capability querying and setting
 functions is provided by the
 .I libcap
-- 
2.30.2

[RFC v3 06/17] clone.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/clone.2 | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/man2/clone.2 b/man2/clone.2
index 11eb6c622..2f5ecac42 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -56,13 +56,12 @@ clone, __clone2, clone3 \- create a child process
 .PP
 /* For the prototype of the raw clone() system call, see NOTES */
 .PP
-.BI "long clone3(struct clone_args *" cl_args ", size_t " size );
-.fi
+.BR "#include <linux/sched.h>" "    /* Definition of " "struct clone_args" " */"
+.BR "#include <sys/syscall.h>" "    /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.IR Note :
-There is no glibc wrapper for
-.BR clone3 ();
-see NOTES.
+.BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size );
+.fi
 .SH DESCRIPTION
 These system calls
 create a new ("child") process, in a manner similar to
@@ -1541,11 +1540,6 @@ One use of these systems calls
 is to implement threads: multiple flows of control in a program that
 run concurrently in a shared address space.
 .PP
-Glibc does not provide a wrapper for
-.BR clone3 ();
-call it using
-.BR syscall (2).
-.PP
 Note that the glibc
 .BR clone ()
 wrapper function makes some changes
-- 
2.30.2

[RFC v3 07/17] delete_module.2: wfix

[Alejandro Colomar]

Use the same wording as in delete_module(2) for this special case.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/delete_module.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man2/delete_module.2 b/man2/delete_module.2
index cb78cf484..50921d7ba 100644
--- a/man2/delete_module.2
+++ b/man2/delete_module.2
@@ -31,7 +31,7 @@ delete_module \- unload a kernel module
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+No declaration of this system call is provided in glibc headers; see NOTES.
 .SH DESCRIPTION
 The
 .BR delete_module ()
-- 
2.30.2

[RFC v3 08/17] epoll_wait.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/epoll_wait.2 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
index af4180df0..0f3cfe1d5 100644
--- a/man2/epoll_wait.2
+++ b/man2/epoll_wait.2
@@ -32,7 +32,13 @@ epoll_wait, epoll_pwait, epoll_pwait2 \- wait for an I/O event on an epoll file
 .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
 .BI "               int " maxevents ", int " timeout ,
 .BI "               const sigset_t *" sigmask );
-.BI "int epoll_pwait2(int " epfd ", struct epoll_event *" events ,
+.PP
+.BR "#include <linux/eventpoll.h>" \
+" /* Definition of " "struct epoll_event" " */"
+.BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_epoll_pwait2, int " epfd ", struct epoll_event *" events ,
 .BI "               int " maxevents ", const struct timespec *" timeout ,
 .BI "               const sigset_t *" sigmask );
 .\" FIXME: Check if glibc has added a wrapper for epoll_pwait2(),
-- 
2.30.2

[RFC v3 09/17] execveat.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/execveat.2 | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/man2/execveat.2 b/man2/execveat.2
index 499bf1b57..0d23cb39b 100644
--- a/man2/execveat.2
+++ b/man2/execveat.2
@@ -28,15 +28,13 @@
 execveat \- execute program relative to a directory file descriptor
 .SH SYNOPSIS
 .nf
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
-.BI "int execveat(int " dirfd ", const char *" pathname ,
-.BI "             const char *const " argv "[], const char *const " envp [],
-.BI "             int " flags );
+.BI "int syscall(SYS_execveat, int " dirfd ", const char *" pathname ,
+.BI "            const char *const " argv "[], const char *const " envp [],
+.BI "            int " flags );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=27364
 .SH DESCRIPTION
 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
@@ -209,9 +207,6 @@ the natural idiom when using
 is to set the close-on-exec flag on
 .IR dirfd .
 (But see BUGS.)
-.PP
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
 .SH BUGS
 The
 .B ENOENT
-- 
2.30.2

[RFC v3 10/17] exit_group.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/exit_group.2 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/man2/exit_group.2 b/man2/exit_group.2
index d26ec8c70..5bf207bd3 100644
--- a/man2/exit_group.2
+++ b/man2/exit_group.2
@@ -27,9 +27,10 @@
 exit_group \- exit all threads in a process
 .SH SYNOPSIS
 .nf
-.B #include <linux/unistd.h>
+.BR "#include <sys/syscall.h>" "       /* Definition of " SYS_* " constants */"
+.B #inlcude <unistd.h>
 .PP
-.BI "void exit_group(int " status );
+.BI "void syscall(SYS_exit_group, int " status );
 .fi
 .SH DESCRIPTION
 This system call is equivalent to
-- 
2.30.2

[RFC v3 11/17] futex.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

At the same time, document only headers that are required
for calling the function, or those that are specific to the
function:

<unistd.h> is required for the syscall() prototype.
<sys/syscall.h> is required for the syscall name SYS_xxx.
<linux/futex.h> is specific to this syscall.

However, uint32_t is generic enough that it shouldn't be
documented here.  The system_data_types(7) page already documents
it, and is more precise about it.  The same goes for timespec.

As a general rule a man[23] page should document the header that
includes the prototype, and all of the headers that define macros
that should be used with the call.  However, the information about
types should be restricted to system_data_types(7) (and that page
should probably be improved by adding types), except for types
that are very specific to the call.  Otherwise, we're duplicating
info and it's then harder to maintain, and probably outdated in
the future.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/futex.2 | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/man2/futex.2 b/man2/futex.2
index e698178d2..a2486628b 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -25,18 +25,16 @@ futex \- fast user-space locking
 .SH SYNOPSIS
 .nf
 .PP
-.B #include <linux/futex.h>
-.B #include <stdint.h>
-.B #include <sys/time.h>
+.BR "#include <linux/futex.h>" "      /* Definition of " FUTEX_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "long futex(uint32_t *" uaddr ", int " futex_op ", uint32_t " val ,
-.BI "          const struct timespec *" timeout , \
+.BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \
+", uint32_t " val ,
+.BI "             const struct timespec *" timeout , \
 " \fR  /* or: \fBuint32_t \fIval2\fP */"
-.BI "          uint32_t *" uaddr2 ", uint32_t " val3 );
+.BI "             uint32_t *" uaddr2 ", uint32_t " val3 );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 The
 .BR futex ()
@@ -1695,9 +1693,6 @@ and a sixth argument was added in Linux 2.6.7.
 .SH CONFORMING TO
 This system call is Linux-specific.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 Several higher-level programming abstractions are implemented via futexes,
 including POSIX semaphores and
 various POSIX threads synchronization mechanisms
-- 
2.30.2

[RFC v3 12/17] getdents.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/getdents.2 | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/man2/getdents.2 b/man2/getdents.2
index ba41e0be8..7d5b0e01c 100644
--- a/man2/getdents.2
+++ b/man2/getdents.2
@@ -33,7 +33,11 @@
 getdents, getdents64 \- get directory entries
 .SH SYNOPSIS
 .nf
-.BI "long getdents(unsigned int " fd ", struct linux_dirent *" dirp ,
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "long syscall(SYS_getdents, unsigned int " fd \
+", struct linux_dirent *" dirp ,
 .BI "             unsigned int " count );
 .PP
 .BR "#define _GNU_SOURCE" "        /* See feature_test_macros(7) */"
@@ -43,9 +47,9 @@ getdents, getdents64 \- get directory entries
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for
-.BR getdents ();
-see NOTES.
+There is no definition of
+.B struct linux_dirent
+in glibc; see NOTES.
 .SH DESCRIPTION
 These are not the interfaces you are interested in.
 Look at
-- 
2.30.2

[RFC v3 13/17] getunwind.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/getunwind.2 | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/man2/getunwind.2 b/man2/getunwind.2
index 9a58f43e4..3490a0617 100644
--- a/man2/getunwind.2
+++ b/man2/getunwind.2
@@ -29,16 +29,14 @@
 getunwind \- copy the unwind data to caller's buffer
 .SH SYNOPSIS
 .nf
-.B #include <syscall.h>
 .B #include <linux/unwind.h>
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #inlcude <unistd.h>
 .PP
-.BI "long getunwind(void " *buf ", size_t " buf_size );
+.BI "long syscall(SYS_getunwind, void " *buf ", size_t " buf_size );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
-.I Note: this function is obsolete.
+.I Note: this system call is obsolete.
 .PP
 The
 IA-64-specific
@@ -102,9 +100,5 @@ and is available only on the IA-64 architecture.
 This system call has been deprecated.
 The modern way to obtain the kernel's unwind data is via the
 .BR vdso (7).
-.PP
-Glibc does not provide a wrapper for this system call;
-in the unlikely event that you want to call it, use
-.BR syscall (2).
 .SH SEE ALSO
 .BR getauxval (3)
-- 
2.30.2

[RFC v3 14/17] get_robust_list.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Also remove unused includes.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/get_robust_list.2 | 20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2
index b1ae42dbd..9c8f14443 100644
--- a/man2/get_robust_list.2
+++ b/man2/get_robust_list.2
@@ -32,17 +32,16 @@
 get_robust_list, set_robust_list \- get/set list of robust futexes
 .SH SYNOPSIS
 .nf
-.B #include <linux/futex.h>
-.B #include <sys/types.h>
-.B #include <syscall.h>
+.BR "#include <linux/futex.h>" \
+"    /* Definition of " "struct robust_list_head" " */"
+.BR "#include <sys/syscall.h>" "    /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "long get_robust_list(int " pid ", struct robust_list_head **" head_ptr ,
-.BI "                     size_t *" len_ptr );
-.BI "long set_robust_list(struct robust_list_head *" head ", size_t " len );
+.BI "long syscall(SYS_get_robust_list, int " pid ,
+.BI "             struct robust_list_head **" head_ptr ", size_t *" len_ptr );
+.BI "long syscall(SYS_set_robust_list,"
+.BI "             struct robust_list_head *" head ", size_t " len );
 .fi
-.PP
-.IR Note :
-There are no glibc wrappers for these system calls; see NOTES.
 .SH DESCRIPTION
 These system calls deal with per-thread robust futex lists.
 These lists are managed in user space:
@@ -139,9 +138,6 @@ could be found.
 These system calls were added in Linux 2.6.17.
 .SH NOTES
 These system calls are not needed by normal applications.
-No support for them is provided in glibc.
-In the unlikely event that you want to call them directly, use
-.BR syscall (2).
 .PP
 A thread can have only one robust futex list;
 therefore applications that wish
-- 
2.30.2

[RFC v3 16/17] init_module.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/init_module.2 | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/man2/init_module.2 b/man2/init_module.2
index 31229ea93..9bc2080a3 100644
--- a/man2/init_module.2
+++ b/man2/init_module.2
@@ -29,14 +29,22 @@
 init_module, finit_module \- load a kernel module
 .SH SYNOPSIS
 .nf
+.PP
 .BI "int init_module(void *" module_image ", unsigned long " len ,
-.BI "                const char *" param_values );
-.BI "int finit_module(int " fd ", const char *" param_values ,
-.BI "                 int " flags );
+.BI "            const char *" param_values );
+.PP
+.BR "#include <linux/module.h>" "    /* Definition of " MODULE_* " constants */"
+.BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_finit_module, int " fd ", const char *" param_values ,
+.BI "            int " flags );
 .fi
 .PP
 .IR Note :
-There are no glibc wrappers for these system calls; see NOTES.
+No declaration of
+.BR init_module ()
+is provided in glibc headers; see NOTES.
 .SH DESCRIPTION
 .BR init_module ()
 loads an ELF image into kernel space,
@@ -268,11 +276,6 @@ manually declare the interface in your code;
 alternatively, you can invoke the system call using
 .BR syscall (2).
 .PP
-Glibc does not provide a wrapper for
-.BR finit_module ();
-call it using
-.BR syscall (2).
-.PP
 Information about currently loaded modules can be found in
 .IR /proc/modules
 and in the file trees under the per-module subdirectories under
-- 
2.30.2

[RFC v3 17/17] ioprio_set.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/ioprio_set.2 | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2
index 91ec03f3b..f0c914ab0 100644
--- a/man2/ioprio_set.2
+++ b/man2/ioprio_set.2
@@ -26,12 +26,13 @@
 ioprio_get, ioprio_set \- get/set I/O scheduling class and priority
 .SH SYNOPSIS
 .nf
-.BI "int ioprio_get(int " which ", int " who );
-.BI "int ioprio_set(int " which ", int " who ", int " ioprio );
-.fi
+.BR "#include <linux/ioprio.h>" "    /* Definition of " IOPRIO_* " constants */"
+.BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.IR Note :
-There are no glibc wrappers for these system calls; see NOTES.
+.BI "int syscall(SYS_ioprio_get, int " which ", int " who );
+.BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio );
+.fi
 .SH DESCRIPTION
 The
 .BR ioprio_get ()
@@ -199,9 +200,6 @@ kernel 2.6.13.
 .SH CONFORMING TO
 These system calls are Linux-specific.
 .SH NOTES
-Glibc does not provide a wrapper for these system calls; call them using
-.BR syscall (2).
-.PP
 Two or more processes or threads can share an I/O context.
 This will be the case when
 .BR clone (2)
-- 
2.30.2