[PATCH 00/39] man2: SYNOPSIS: Fix headers, use syscall(), and other fixes

[PATCH 00/39] man2: SYNOPSIS: Fix headers, use syscall(), and other fixes

[Alejandro Colomar]

Hi Michael,

This is the second set of SYNOPSIS fixes, mostly about fixing the includes,
giving reasons why they are being included, and using syscall(SYS_...) when
needed.  Other minor fixes that I have noticed while doing this are also
included in this set.

After this set, about a 60% of man2 will be fixed.

As with the previous patch set, please review thoroughly.  I might have
overlooked something.  It looks good, but it's been a long time...

I must notice that there are a few discrepancies (see the last mails there):
<https://lore.kernel.org/linux-man/3d6feff0-f65b-f086-aa2a-be21ff90ccfe@gmail.com/T/#u>.

Cheers,

Alex



Alejandro Colomar (39):
  futex.2: Use syscall(SYS_...); for system calls without a wrapper
  getdents.2: Use syscall(SYS_...); for system calls without a wrapper
  ioctl_tty.2: Fix includes
  ioctl_userfaultfd.2: SYNOPSIS: Add <linux/userfaultfd.h>
  io_destroy.2: Use syscall(SYS_...); for system calls without a wrapper
  io_getevents.2: Use syscall(SYS_...); for system calls without a
    wrapper
  ioperm.2: Remove obvious comment
  ioprio_set.2: Use syscall(SYS_...); for system calls without a wrapper
  ipc.2: Use syscall(SYS_...); for system calls without a wrapper
  ipc.2: Add needed include
  kcmp.2: Use syscall(SYS_...); for system calls without a wrapper
  kcmp.2: tfix
  kexec_load.2: Use syscall(SYS_...); for system calls without a wrapper
  scripts/bash_aliases: man_lsfunc(): Extract syscall name from
    syscall(SYS_...)
  keyctl.2: Use syscall(SYS_...); for system calls without a glibc
    wrapper
  link.2: ffix
  llseek.2: Use syscall(SYS_...); for system calls without a wrapper
  lookup_dcookie.2: Use syscall(SYS_...); for system calls without a
    wrapper
  membarrier.2: Use syscall(SYS_...); for system calls without a wrapper
  mincore.2: Remove unused include
  mknod.2: Remove unused includes
  mmap2.2: Use syscall(SYS_...); for system calls without a wrapper
  modify_ldt.2: Use syscall(SYS_...); for system calls without a wrapper
  mq_getsetattr.2: Use syscall(SYS_...); for system calls without a
    wrapper
  alloc_hugepages.2, arch_prctl.2, capget.2, clone.2, delete_module.2,
    exit_group.2, get_robust_list.2, getunwind.2, init_module.2: Add
    note about the use of syscall(2)
  open.2: Remove unused <sys/stat.h>
  openat2.2: Use syscall(SYS_...); for system calls without a wrapper;
    fix includes too
  perf_event_open.2: Use syscall(SYS_...); for system calls without a
    wrapper
  pidfd_getfd.2: Use syscall(SYS_...); for system calls without a
    wrapper
  pidfd_open.2: Use syscall(SYS_...); for system calls without a wrapper
  pidfd_send_signal.2: Use syscall(SYS_...); for system calls without a
    wrapper. Fix includes too
  pipe.2: wfix
  pivot_root.2: Use syscall(SYS_...); for system calls without a wrapper
  poll.2: Remove <signal.h>
  process_madvise.2: Use syscall(SYS_...); for system calls without a
    wrapper. Fix includes too.
  quotactl.2: Better detail why <xfs/xqm.h> is included
  readdir.2: Use syscall(SYS_...); for system calls without a wrapper
  readlink.2: ffix
  reboot.2: Use syscall(SYS_...); for system calls without a wrapper

 man2/alloc_hugepages.2   |  5 +++++
 man2/arch_prctl.2        |  6 ++++++
 man2/capget.2            |  5 +++++
 man2/clone.2             |  6 ++++++
 man2/delete_module.2     |  6 ++++++
 man2/exit_group.2        |  6 ++++++
 man2/futex.2             | 21 +++++++++++----------
 man2/get_robust_list.2   |  5 +++++
 man2/getdents.2          | 20 +++++++++++++++-----
 man2/getunwind.2         |  6 ++++++
 man2/init_module.2       |  5 +++++
 man2/io_destroy.2        | 16 +++++++++-------
 man2/io_getevents.2      | 21 +++++++++++----------
 man2/ioctl_tty.2         |  6 +++---
 man2/ioctl_userfaultfd.2 |  1 +
 man2/ioperm.2            |  2 +-
 man2/ioprio_set.2        | 15 +++++++++------
 man2/ipc.2               | 19 ++++++++++++-------
 man2/kcmp.2              | 18 ++++++++++--------
 man2/kexec_load.2        | 24 +++++++++++++-----------
 man2/keyctl.2            | 17 +++++++----------
 man2/link.2              |  2 +-
 man2/llseek.2            | 13 +++++++------
 man2/lookup_dcookie.2    | 14 +++++++++-----
 man2/membarrier.2        | 16 ++++++++++------
 man2/mincore.2           |  1 -
 man2/mknod.2             |  2 --
 man2/mmap2.2             | 10 ++++++----
 man2/modify_ldt.2        | 15 ++++++++++-----
 man2/mq_getsetattr.2     | 15 ++++++---------
 man2/open.2              |  1 -
 man2/openat2.2           | 20 +++++++++++---------
 man2/perf_event_open.2   | 21 +++++++++++----------
 man2/pidfd_getfd.2       | 14 +++++++++-----
 man2/pidfd_open.2        | 13 ++++++++-----
 man2/pidfd_send_signal.2 | 16 ++++++++++------
 man2/pipe.2              |  4 ++--
 man2/pivot_root.2        | 14 +++++++++-----
 man2/poll.2              |  3 +--
 man2/process_madvise.2   | 20 ++++++++++++--------
 man2/quotactl.2          |  4 +++-
 man2/readdir.2           | 12 +++++++-----
 man2/readlink.2          |  2 +-
 man2/reboot.2            | 12 +++++++-----
 scripts/bash_aliases     |  1 +
 45 files changed, 293 insertions(+), 182 deletions(-)

-- 
2.31.1

[PATCH 01/39] 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 | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/man2/futex.2 b/man2/futex.2
index 389c25224..ada96c517 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -25,18 +25,22 @@ 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.
+glibc provides no wrapper for
+.BR futex (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR futex ()
@@ -1695,9 +1699,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.31.1

[PATCH 02/39] 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 | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/man2/getdents.2 b/man2/getdents.2
index ec00a73ba..df766b066 100644
--- a/man2/getdents.2
+++ b/man2/getdents.2
@@ -33,19 +33,29 @@
 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) */"
+.BR "#define _GNU_SOURCE" "           /* See feature_test_macros(7) */"
 .BR "#include <dirent.h>"
 .PP
 .BI "ssize_t getdents64(int " fd ", void *" dirp ", size_t " count );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for
-.BR getdents ();
-see NOTES.
+glibc provides no wrapper for
+.BR getdents (),
+necessitating the use of
+.BR syscall (2).
+.PP
+.IR Note :
+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.31.1

Re: [PATCH 02/39] getdents.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

See below.

On 5/11/21 5:55 AM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/getdents.2 | 20 +++++++++++++++-----
>  1 file changed, 15 insertions(+), 5 deletions(-)
> 
> diff --git a/man2/getdents.2 b/man2/getdents.2
> index ec00a73ba..df766b066 100644
> --- a/man2/getdents.2
> +++ b/man2/getdents.2
> @@ -33,19 +33,29 @@
>  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) */"
> +.BR "#define _GNU_SOURCE" "           /* See feature_test_macros(7) */"
>  .BR "#include <dirent.h>"
>  .PP
>  .BI "ssize_t getdents64(int " fd ", void *" dirp ", size_t " count );
>  .fi
>  .PP
>  .IR Note :
> -There is no glibc wrapper for
> -.BR getdents ();
> -see NOTES.
> +glibc provides no wrapper for
> +.BR getdents (),
> +necessitating the use of
> +.BR syscall (2).
> +.PP
> +.IR Note :
> +There is no definition of
> +.B struct linux_dirent

.I ...
(Fixed)

> +in glibc; see NOTES.
>  .SH DESCRIPTION
>  These are not the interfaces you are interested in.
>  Look at
> 

Cheers,

Michael

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

[PATCH 03/39] ioctl_tty.2: Fix includes

[Alejandro Colomar]

<sys/ioctl.h> is needed for the prototype of ioctl().  That header
also provides most of the constants used by the function.  Only a
few of those constants are not provided by that header, and need
<termios.h>; clarify which constants do need that include.

......

$ <man2/ioctl_tty.2 \
  sed -n '/^.SH DESCRIPTION/,/^.SH/p' \
  |grep -e '^\.B' -e TIOCM \
  |sed 's/^\.B[^ ]* //' \
  |awk '{print $1}' \
  |grep '^[[:upper:]]' \
  |grep -v -e '^CAP' -e '^E' -e '^SIG' -e '^O_' -e '^[TR]XD$' -e '^POLL' \
  |sort \
  |uniq \
  |while read f; do \
	find /usr/include/ -type f \
	|xargs grep -l "define\s$f" \
	|grep -q ioctl.*.h \
	||echo $f \
	|while read ff; do \
		echo "============ $ff"; \
		find /usr/include/ -type f \
		|xargs grep -n "define\s$ff"; \
	done; \
  done;
============ CLOCAL
/usr/include/asm-generic/termbits.h:142:#define CLOCAL	0004000
/usr/include/gphoto2/gphoto2-port-portability.h:127:#   define CLOCAL  0x00000800
/usr/include/x86_64-linux-gnu/bits/termios-c_cflag.h:34:#define CLOCAL	0004000
============ TCIFLUSH
/usr/include/asm-generic/termbits.h:191:#define	TCIFLUSH	0
/usr/include/x86_64-linux-gnu/bits/termios.h:70:#define	TCIFLUSH	0
============ TCIOFF
/usr/include/asm-generic/termbits.h:187:#define	TCIOFF		2
/usr/include/x86_64-linux-gnu/bits/termios.h:66:#define	TCIOFF		2
============ TCIOFLUSH
/usr/include/asm-generic/termbits.h:193:#define	TCIOFLUSH	2
/usr/include/x86_64-linux-gnu/bits/termios.h:72:#define	TCIOFLUSH	2
============ TCION
/usr/include/asm-generic/termbits.h:188:#define	TCION		3
/usr/include/x86_64-linux-gnu/bits/termios.h:67:#define	TCION		3
============ TCOFLUSH
/usr/include/asm-generic/termbits.h:192:#define	TCOFLUSH	1
/usr/include/x86_64-linux-gnu/bits/termios.h:71:#define	TCOFLUSH	1
============ TCOOFF
/usr/include/asm-generic/termbits.h:185:#define	TCOOFF		0
/usr/include/x86_64-linux-gnu/bits/termios.h:64:#define	TCOOFF		0
============ TCOON
/usr/include/asm-generic/termbits.h:186:#define	TCOON		1
/usr/include/x86_64-linux-gnu/bits/termios.h:65:#define	TCOON		1
============ TIOCREMOTE
============ TIOCSTART
============ TIOCSTOP
============ TIOCTTYGSTRUCT
============ TIOCUCNTL

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

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index badd58e50..c82690701 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -10,7 +10,9 @@
 ioctl_tty \- ioctls for terminals and serial lines
 .SH SYNOPSIS
 .nf
-.B "#include <termios.h>"
+.B #include <sys/ioctl.h>
+.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
+.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
 .PP
 .BI "int ioctl(int " fd ", int " cmd ", ...);"
 .fi
@@ -119,8 +121,6 @@ Window sizes are kept in the kernel, but not used by the kernel
 update the window size when the size of the virtual console changes,
 for example, by loading a new font).
 .PP
-The following constants and structure are defined in
-.IR <sys/ioctl.h> .
 .TP
 .B TIOCGWINSZ
 Argument:
-- 
2.31.1

[PATCH 04/39] ioctl_userfaultfd.2: SYNOPSIS: Add <linux/userfaultfd.h>

[Alejandro Colomar]

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

diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
index a3b8f737d..504f61d4b 100644
--- a/man2/ioctl_userfaultfd.2
+++ b/man2/ioctl_userfaultfd.2
@@ -31,6 +31,7 @@ ioctl_userfaultfd \- create a file descriptor for handling page faults in user
 space
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/userfaultfd.h>" "  /* Definition of " UFFD* " constants */"
 .B #include <sys/ioctl.h>
 .PP
 .BI "int ioctl(int " fd ", int " cmd ", ...);"
-- 
2.31.1

[PATCH 05/39] io_destroy.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

In this case there's a wrapper provided by libaio,
but this page documents the raw syscall.

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

diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index b439f1184..c9418336f 100644
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -9,13 +9,18 @@
 io_destroy \- destroy an asynchronous I/O context
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
+.BR "#include <linux/aio_abi.h>" "    /* Definition of " aio_context_t " */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int io_destroy(aio_context_t " ctx_id );
+.BI "int syscall(SYS_io_destroy, aio_context_t " ctx_id );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR io_destroy (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .IR Note :
 this page describes the raw Linux system call interface.
@@ -57,10 +62,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
 is Linux-specific and should not be used in programs
 that are intended to be portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call.
-You could invoke it using
-.BR syscall (2).
-But instead, you probably want to use the
+You probably want to use the
 .BR io_destroy ()
 wrapper function provided by
 .\" http://git.fedorahosted.org/git/?p=libaio.git
-- 
2.31.1

[PATCH 06/39] io_getevents.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

In this case there's a wrapper provided by libaio,
but this page documents the raw syscall.

Also remove <linux/time.h> from the includes: 'struct timespec'
is already documented in system_data_types(7), where the
information is more up to date.

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

diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index 87eefdd92..7c7e625bf 100644
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -9,16 +9,20 @@
 io_getevents \- read asynchronous I/O events from the completion queue
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/aio_abi.h>" "         /* Defines needed types */"
-.BR "#include <linux/time.h>" "            /* Defines 'struct timespec' */"
+.BR "#include <linux/aio_abi.h>" "    /* Definition of " *io_* " types */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
-.BI "                 struct io_event *" events \
-", struct timespec *" timeout );
+.BI "int syscall(SYS_io_getevents, aio_context_t " ctx_id ,
+.BI "            long " min_nr ", long " nr ", struct io_event *" events ,
+.BI "            struct timespec *" timeout );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR io_getevents (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .IR Note :
 this page describes the raw Linux system call interface.
@@ -94,10 +98,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
 is Linux-specific and should not be used in
 programs that are intended to be portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call.
-You could invoke it using
-.BR syscall (2).
-But instead, you probably want to use the
+You probably want to use the
 .BR io_getevents ()
 wrapper function provided by
 .\" http://git.fedorahosted.org/git/?p=libaio.git
-- 
2.31.1

[PATCH 07/39] ioperm.2: Remove obvious comment

[Alejandro Colomar]

Of course that is for the glibc wrapper.  As all of the other
pages that don't explicitly say otherwise.

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

diff --git a/man2/ioperm.2 b/man2/ioperm.2
index b13a0129e..7d4a4690a 100644
--- a/man2/ioperm.2
+++ b/man2/ioperm.2
@@ -36,7 +36,7 @@
 ioperm \- set port input/output permissions
 .SH SYNOPSIS
 .nf
-.BR "#include <sys/io.h>" " /* for glibc */"
+.B #include <sys/io.h>
 .PP
 .BI "int ioperm(unsigned long " from ", unsigned long " num ", int " turn_on );
 .fi
-- 
2.31.1

[PATCH 08/39] 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 | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2
index 91ec03f3b..c110725f0 100644
--- a/man2/ioprio_set.2
+++ b/man2/ioprio_set.2
@@ -26,12 +26,18 @@
 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 );
+.BR "#include <linux/ioprio.h>    " "/* Definition of " IOPRIO_* " constants */"
+.BR "#include <sys/syscall.h>     " "/* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_ioprio_get, int " which ", int " who );
+.BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio );
 .fi
 .PP
 .IR Note :
-There are no glibc wrappers for these system calls; see NOTES.
+glibc provides no wrappers for these system calls,
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR ioprio_get ()
@@ -199,9 +205,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.31.1

[PATCH 09/39] ipc.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/ipc.2 b/man2/ipc.2
index c0ba4651f..f505fa1c9 100644
--- a/man2/ipc.2
+++ b/man2/ipc.2
@@ -27,12 +27,20 @@
 ipc \- System V IPC system calls
 .SH SYNOPSIS
 .nf
-.BI "int ipc(unsigned int " call ", int " first ", unsigned long " second ,
-.BI "        unsigned long " third ", void *" ptr ", long " fifth );
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_ipc, unsigned int " call ", int " first ,
+.BI "            unsigned long " second ", unsigned long " third \
+", void *" ptr ,
+.BI "            long " fifth );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR ipc (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .BR ipc ()
 is a common kernel entry point for the System\ V IPC calls
@@ -56,10 +64,6 @@ system call; instead,
 .BR semctl (2),
 .BR shmctl (2),
 and so on really are implemented as separate system calls.
-.PP
-Glibc does not provide a wrapper for this system call;
-in the unlikely event that you want to call it directly, you can do so using
-.BR syscall (2).
 .SH SEE ALSO
 .BR msgctl (2),
 .BR msgget (2),
-- 
2.31.1

[PATCH 10/39] ipc.2: Add needed include

[Alejandro Colomar]

The constants needed for using this function are defined in
<linux/ipc.h>.  Add the include, even when those constants are not
mentioned in this manual page.

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

diff --git a/man2/ipc.2 b/man2/ipc.2
index f505fa1c9..4ce29ca69 100644
--- a/man2/ipc.2
+++ b/man2/ipc.2
@@ -27,6 +27,7 @@
 ipc \- System V IPC system calls
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/ipc.h>" "        /* Definition of needed constants */"
 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
-- 
2.31.1

[PATCH 11/39] kcmp.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/kcmp.2 b/man2/kcmp.2
index 3cc7f7d6f..b0994758a 100644
--- a/man2/kcmp.2
+++ b/man2/kcmp.2
@@ -30,14 +30,19 @@
 kcmp \- compare two processes to determine if they share a kernel resource
 .SH SYNOPSIS
 .nf
-.B #include <linux/kcmp.h>
+.BR "#include <linux/kcmp.h>" "       /* Definition of " KCMP_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int kcmp(pid_t " pid1 ", pid_t " pid2 ", int " type ,
-.BI "         unsigned long " idx1 ", unsigned long "  idx2 );
+.BI "int syscall(SYS_kcmp, pid_t " pid1 ", pid_t " pid2 ", int " type ,
+.BI "            unsigned long " idx1 ", unsigned long "  idx2 );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR kcmp (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR kcmp ()
@@ -303,9 +308,6 @@ system call first appeared in Linux 3.5.
 .BR kcmp ()
 is Linux-specific and should not be used in programs intended to be portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 Before Linux 5.12,
 this system call is available only if the kernel is configured with
 .BR CONFIG_CHECKPOINT_RESTORE ,
-- 
2.31.1

[PATCH 12/39] kcmp.2: tfix

[Alejandro Colomar]

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

diff --git a/man2/kcmp.2 b/man2/kcmp.2
index b0994758a..7acfa8ef8 100644
--- a/man2/kcmp.2
+++ b/man2/kcmp.2
@@ -311,7 +311,7 @@ is Linux-specific and should not be used in programs intended to be portable.
 Before Linux 5.12,
 this system call is available only if the kernel is configured with
 .BR CONFIG_CHECKPOINT_RESTORE ,
-since the original pupose the system call was for the
+since the original purpose of the system call was for the
 checkpoint/restore in user space (CRIU) feature.
 (The alternative to this system call would have been to expose suitable
 process information via the
-- 
2.31.1

[PATCH 13/39] kexec_load.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/kexec_load.2 b/man2/kexec_load.2
index 62a3e2006..74f142355 100644
--- a/man2/kexec_load.2
+++ b/man2/kexec_load.2
@@ -29,18 +29,23 @@
 kexec_load, kexec_file_load \- load a new kernel for later execution
 .SH SYNOPSIS
 .nf
-.B #include <linux/kexec.h>
+.BR "#include <linux/kexec.h>" "      /* Definition of " KEXEC_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "long kexec_load(unsigned long " entry ", unsigned long " nr_segments ,
-.BI "                struct kexec_segment *" segments ,
-.BI "                unsigned long " flags );
-.BI "long kexec_file_load(int " kernel_fd ", int " initrd_fd ,
-.BI "                unsigned long " cmdline_len ", const char *" cmdline ,
-.BI "                unsigned long " flags );
+.BI "long syscall(SYS_kexec_load, unsigned long " entry ,
+.BI "             unsigned long " nr_segments \
+", struct kexec_segment *" segments ,
+.BI "             unsigned long " flags );
+.BI "long syscall(SYS_kexec_file_load, int " kernel_fd ", int " initrd_fd ,
+.BI "             unsigned long " cmdline_len ", const char *" cmdline ,
+.BI "             unsigned long " flags );
 .fi
 .PP
 .IR Note :
-There are no glibc wrappers for these system calls; see NOTES.
+glibc provides no wrappers for these system calls,
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR kexec_load ()
@@ -332,9 +337,6 @@ The
 system call first appeared in Linux 3.17.
 .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).
 .SH SEE ALSO
 .BR reboot (2),
 .BR syscall (2),
-- 
2.31.1

[PATCH 14/39] scripts/bash_aliases: man_lsfunc(): Extract syscall name from syscall(SYS_...)

[Alejandro Colomar]

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

diff --git a/scripts/bash_aliases b/scripts/bash_aliases
index 358e2f37a..102c458d7 100644
--- a/scripts/bash_aliases
+++ b/scripts/bash_aliases
@@ -136,6 +136,7 @@ function man_lsfunc()
 	|sed_rm_ccomments \
 	|pcregrep -Mn '(?s)^ [\w ]+ \**\w+\([\w\s(,)[\]*]+?(...)?\s*\); *$' \
 	|grep '^[0-9]' \
+	|sed    's/syscall(SYS_\(\w*\),/\1(/' \
 	|sed -E 's/^[^(]+ \**(\w+)\(.*/\1/' \
 	|uniq;
 }
-- 
2.31.1

[PATCH 15/39] keyctl.2: Use syscall(SYS_...); for system calls without a glibc wrapper

[Alejandro Colomar]

Remove the libkeyutils prototype from the synopsis, which isn't
documented in the rest of the page, and as NOTES says, it's
probably better to use the various library functions.

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

diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 690781eea..7f5fcb951 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -30,22 +30,20 @@
 keyctl \- manipulate the kernel's key management facility
 .SH SYNOPSIS
 .nf
-.B #include <keyutils.h>
-.PP
-.BI "long keyctl(int " operation ", ...);"
-.PP
-.B "/* For direct call via syscall(2): */"
-.B #include <asm/unistd.h>
-.B #include <linux/keyctl.h>
+.BR "#include <linux/keyctl.h>" "     /* Definition of " KEY* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
-.BI "long syscall(__NR_keyctl, int " operation ", unsigned long " arg2 ,
+.BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 ,
 .BI "             unsigned long " arg3 ", unsigned long " arg4 ,
 .BI "             unsigned long " arg5 );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR keyctl (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .BR keyctl ()
 allows user-space programs to perform key manipulation.
@@ -1954,7 +1952,6 @@ This system call first appeared in Linux 2.6.10.
 .SH CONFORMING TO
 This system call is a nonstandard Linux extension.
 .SH NOTES
-Glibc does not provide a wrapper for this system call.
 A wrapper is provided in the
 .IR libkeyutils
 library.
-- 
2.31.1

[PATCH 16/39] link.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/link.2 b/man2/link.2
index 611cd6c13..c285ae896 100644
--- a/man2/link.2
+++ b/man2/link.2
@@ -38,7 +38,7 @@ link, linkat \- make a new name for a file
 .PP
 .BI "int link(const char *" oldpath ", const char *" newpath );
 .PP
-.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
 .B #include <unistd.h>
 .PP
 .BI "int linkat(int " olddirfd ", const char *" oldpath ,
-- 
2.31.1

[PATCH 17/39] llseek.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/llseek.2 b/man2/llseek.2
index 6a36fb6ea..87f45f219 100644
--- a/man2/llseek.2
+++ b/man2/llseek.2
@@ -31,15 +31,19 @@
 _llseek \- reposition read/write file offset
 .SH SYNOPSIS
 .nf
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
-.BI "int _llseek(unsigned int " fd ", unsigned long " offset_high ,
+.BI "int syscall(SYS__llseek, unsigned int " fd ", unsigned long " offset_high ,
 .BI "            unsigned long " offset_low ", loff_t *" result ,
 .BI "            unsigned int " whence );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR _llseek (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 Note: for information about the
 .BR llseek (3)
@@ -97,10 +101,7 @@ is invalid.
 This function is Linux-specific, and should not be used in programs
 intended to be portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call.
-To invoke it directly, use
-.BR syscall (2).
-However, you probably want to use the
+You probably want to use the
 .BR lseek (2)
 wrapper function instead.
 .SH SEE ALSO
-- 
2.31.1

[PATCH 18/39] lookup_dcookie.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/lookup_dcookie.2 b/man2/lookup_dcookie.2
index 2f0559707..6c178e367 100644
--- a/man2/lookup_dcookie.2
+++ b/man2/lookup_dcookie.2
@@ -29,11 +29,18 @@
 lookup_dcookie \- return a directory entry's path
 .SH SYNOPSIS
 .nf
-.BI "int lookup_dcookie(uint64_t " cookie ", char *" buffer ", size_t " len );
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_lookup_dcookie, uint64_t " cookie ", char *" buffer ,
+.BI "            size_t " len );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR lookup_dcookie (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 Look up the full path of the directory entry specified by the value
 .IR cookie .
@@ -92,8 +99,5 @@ It relies on a kernel driver to register cookies for directory entries.
 .PP
 The path returned may be suffixed by the string " (deleted)" if the directory
 entry has been removed.
-.PP
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
 .SH SEE ALSO
 .BR oprofile (1)
-- 
2.31.1

[PATCH 19/39] membarrier.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/membarrier.2 b/man2/membarrier.2
index 851f5d59f..fec82f228 100644
--- a/man2/membarrier.2
+++ b/man2/membarrier.2
@@ -28,13 +28,20 @@ membarrier \- issue memory barriers on a set of threads
 .SH SYNOPSIS
 .nf
 .PP
-.B #include <linux/membarrier.h>
+.BR "#include <linux/membarrier.h>" \
+" /* Definition of " MEMBARRIER_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " 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.
+glibc provides no wrapper for
+.BR membarrier (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR membarrier ()
@@ -322,9 +329,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.31.1

[PATCH 20/39] mincore.2: Remove unused include

[Alejandro Colomar]

AFAICS, there's no use for <unistd.h> here.  The prototype is
declared in <sys/mman.h>, and there are no constants needed.

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

diff --git a/man2/mincore.2 b/man2/mincore.2
index b816e10c6..38ee7d6fa 100644
--- a/man2/mincore.2
+++ b/man2/mincore.2
@@ -36,7 +36,6 @@
 mincore \- determine whether pages are resident in memory
 .SH SYNOPSIS
 .nf
-.B #include <unistd.h>
 .B #include <sys/mman.h>
 .PP
 .BI "int mincore(void *" addr ", size_t " length ", unsigned char *" vec );
-- 
2.31.1

[PATCH 21/39] mknod.2: Remove unused includes

[Alejandro Colomar]

All of the constants used by mknod() are dfined in <sys/stat.h>.

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

diff --git a/man2/mknod.2 b/man2/mknod.2
index f20d4aa66..1de3cd027 100644
--- a/man2/mknod.2
+++ b/man2/mknod.2
@@ -18,8 +18,6 @@ mknod, mknodat \- create a special or ordinary file
 .SH SYNOPSIS
 .nf
 .B #include <sys/stat.h>
-.B #include <fcntl.h>
-.B #include <unistd.h>
 .PP
 .BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev );
 .PP
-- 
2.31.1

[PATCH 22/39] mmap2.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/mmap2.2 b/man2/mmap2.2
index 6545a8f52..d579a285d 100644
--- a/man2/mmap2.2
+++ b/man2/mmap2.2
@@ -31,11 +31,13 @@
 mmap2 \- map files or devices into memory
 .SH SYNOPSIS
 .nf
-.B #include <sys/mman.h>
+.BR "#include <sys/mman.h>" "    /* Definition of " MAP_* " and " PROT_* " constants */"
+.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
+.BR "#include <unistd.h>
 .PP
-.BI "void *mmap2(unsigned long " addr ", unsigned long " length ,
-.BI "            unsigned long " prot ", unsigned long " flags ,
-.BI "            unsigned long " fd ", unsigned long " pgoffset );
+.BI "void *syscall(SYS_mmap2, unsigned long " addr ", unsigned long " length ,
+.BI "              unsigned long " prot ", unsigned long " flags ,
+.BI "              unsigned long " fd ", unsigned long " pgoffset );
 .fi
 .SH DESCRIPTION
 This is probably not the system call that you are interested in; instead, see
-- 
2.31.1

[PATCH 23/39] modify_ldt.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/modify_ldt.2 b/man2/modify_ldt.2
index 8ce9ed252..b67a67690 100644
--- a/man2/modify_ldt.2
+++ b/man2/modify_ldt.2
@@ -27,11 +27,19 @@
 modify_ldt \- get or set a per-process LDT entry
 .SH SYNOPSIS
 .nf
-.BI "int modify_ldt(int " func ", void *" ptr ", unsigned long " bytecount );
+.BR "#include <asm/ldt.h>" "         /* Definition of " "struct user_desc" " */"
+.BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_modify_ldt, int " func ", void *" ptr ,
+.BI "            unsigned long " bytecount );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR modify_ldt (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .BR modify_ldt ()
 reads or writes the local descriptor table (LDT) for a process.
@@ -168,9 +176,6 @@ is neither 0, 1, 2, nor 0x11.
 This call is Linux-specific and should not be used in programs intended
 to be portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 .BR modify_ldt ()
 should not be used for thread-local storage, as it slows down context
 switches and only supports a limited number of threads.
-- 
2.31.1

[PATCH 24/39] mq_getsetattr.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/mq_getsetattr.2 b/man2/mq_getsetattr.2
index 2f11b9d44..23dd2a8b9 100644
--- a/man2/mq_getsetattr.2
+++ b/man2/mq_getsetattr.2
@@ -27,14 +27,13 @@
 mq_getsetattr \- get/set message queue attributes
 .SH SYNOPSIS
 .nf
-.B #include <mqueue.h>
+.BR "#include <mqueue.h>" "           /* Definition of " "struct mq_attr" " */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int mq_getsetattr(mqd_t " mqdes ", const struct mq_attr *" newattr ,
-.BI "                  struct mq_attr *" oldattr );
+.BI "int syscall(SYS_mq_getsetattr, mqd_t " mqdes ,
+.BI "            const struct mq_attr *" newattr ", struct mq_attr *" oldattr );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 Do not use this system call.
 .PP
@@ -48,9 +47,7 @@ see the description of
 .SH CONFORMING TO
 This interface is nonstandard; avoid its use.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-(Actually, never call it unless you are writing a C library!)
+Never call it unless you are writing a C library!
 .SH SEE ALSO
 .BR mq_getattr (3),
 .BR mq_overview (7)
-- 
2.31.1

[PATCH 25/39] alloc_hugepages.2, arch_prctl.2, capget.2, clone.2, delete_module.2, exit_group.2, get_robust_list.2, getunwind.2, init_module.2: Add note about the use of syscall(2)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/alloc_hugepages.2 | 5 +++++
 man2/arch_prctl.2      | 6 ++++++
 man2/capget.2          | 5 +++++
 man2/clone.2           | 6 ++++++
 man2/delete_module.2   | 6 ++++++
 man2/exit_group.2      | 6 ++++++
 man2/get_robust_list.2 | 5 +++++
 man2/getunwind.2       | 6 ++++++
 man2/init_module.2     | 5 +++++
 9 files changed, 50 insertions(+)

diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2
index cc76fc495..47f9da6b0 100644
--- a/man2/alloc_hugepages.2
+++ b/man2/alloc_hugepages.2
@@ -35,6 +35,11 @@ alloc_hugepages, free_hugepages \- allocate or free huge pages
 .BI "int syscall(SYS_free_hugepages, void *" addr );
 .\" asmlinkage int sys_free_hugepages(unsigned long addr);
 .fi
+.PP
+.IR Note :
+glibc provides no wrappers for these system calls,
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The system calls
 .BR alloc_hugepages ()
diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
index 7ae5b350c..982416761 100644
--- a/man2/arch_prctl.2
+++ b/man2/arch_prctl.2
@@ -34,6 +34,12 @@ arch_prctl \- set architecture-specific thread state
 .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 :
+glibc provides no wrapper for
+.BR arch_prctl (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .BR arch_prctl ()
 sets architecture-specific process or thread state.
diff --git a/man2/capget.2 b/man2/capget.2
index 9dbc0404c..3ac05106f 100644
--- a/man2/capget.2
+++ b/man2/capget.2
@@ -28,6 +28,11 @@ capget, capset \- set/get capabilities of thread(s)
 .BI "int syscall(SYS_capset, cap_user_header_t " hdrp ,
 .BI "            const cap_user_data_t " datap );
 .fi
+.PP
+.IR Note :
+glibc provides no wrappers for these system calls,
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 These two system calls are the raw kernel interface for getting and
 setting thread capabilities.
diff --git a/man2/clone.2 b/man2/clone.2
index 04b4ec38c..e381da165 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -63,6 +63,12 @@ clone, __clone2, clone3 \- create a child process
 .PP
 .BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size );
 .fi
+.PP
+.IR Note :
+glibc provides no wrapper for
+.BR clone3 (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 These system calls
 create a new ("child") process, in a manner similar to
diff --git a/man2/delete_module.2 b/man2/delete_module.2
index 21c9e9d8d..3b14111c5 100644
--- a/man2/delete_module.2
+++ b/man2/delete_module.2
@@ -33,6 +33,12 @@ delete_module \- unload a kernel module
 .PP
 .BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags );
 .fi
+.PP
+.IR Note :
+glibc provides no wrapper for
+.BR delete_module (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR delete_module ()
diff --git a/man2/exit_group.2 b/man2/exit_group.2
index d197f1f2e..1533529f8 100644
--- a/man2/exit_group.2
+++ b/man2/exit_group.2
@@ -32,6 +32,12 @@ exit_group \- exit all threads in a process
 .PP
 .BI "noreturn void syscall(SYS_exit_group, int " status );
 .fi
+.PP
+.IR Note :
+glibc provides no wrapper for
+.BR exit_group (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 This system call is equivalent to
 .BR _exit (2)
diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2
index d1b1c59bc..66b27d905 100644
--- a/man2/get_robust_list.2
+++ b/man2/get_robust_list.2
@@ -42,6 +42,11 @@ get_robust_list, set_robust_list \- get/set list of robust futexes
 .BI "long syscall(SYS_set_robust_list,"
 .BI "             struct robust_list_head *" head ", size_t " len );
 .fi
+.PP
+.IR Note :
+glibc provides no wrappers for these system calls,
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 These system calls deal with per-thread robust futex lists.
 These lists are managed in user space:
diff --git a/man2/getunwind.2 b/man2/getunwind.2
index 403bd7770..0935497c6 100644
--- a/man2/getunwind.2
+++ b/man2/getunwind.2
@@ -35,6 +35,12 @@ getunwind \- copy the unwind data to caller's buffer
 .PP
 .BI "long syscall(SYS_getunwind, void " *buf ", size_t " buf_size );
 .fi
+.PP
+.IR Note :
+glibc provides no wrapper for
+.BR getunwind (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .I Note: this system call is obsolete.
 .PP
diff --git a/man2/init_module.2 b/man2/init_module.2
index 13d1b7f0a..aac0c6631 100644
--- a/man2/init_module.2
+++ b/man2/init_module.2
@@ -38,6 +38,11 @@ init_module, finit_module \- load a kernel module
 .BI "int syscall(SYS_finit_module, int " fd ", const char *" param_values ,
 .BI "            int " flags );
 .fi
+.PP
+.IR Note :
+glibc provides no wrappers for these system calls,
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .BR init_module ()
 loads an ELF image into kernel space,
-- 
2.31.1

[PATCH 26/39] open.2: Remove unused <sys/stat.h>

[Alejandro Colomar]

I can't see a reason to include it.  <fcntl.h> provides O_*
constants for 'flags', S_* constants for 'mode', and mode_t.

Probably a long time ago, some of those weren't defined in
<fcntl.h>, and both headers needed to be included, or maybe it's
a historical error.

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

diff --git a/man2/open.2 b/man2/open.2
index bac1ee806..1bcd995f4 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -53,7 +53,6 @@
 open, openat, creat \- open and possibly create a file
 .SH SYNOPSIS
 .nf
-.B #include <sys/stat.h>
 .B #include <fcntl.h>
 .PP
 .BI "int open(const char *" pathname ", int " flags );
-- 
2.31.1

Re: [PATCH 26/39] open.2: Remove unused <sys/stat.h>

[Alejandro Colomar (man-pages)]

On 5/10/21 7:55 PM, Alejandro Colomar wrote:
> I can't see a reason to include it.  <fcntl.h> provides O_*
> constants for 'flags', S_* constants for 'mode', and mode_t.
> 
> Probably a long time ago, some of those weren't defined in
> <fcntl.h>, and both headers needed to be included, or maybe it's
> a historical error.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Drop this one, please.  (We discussed it yesterday.)

> ---
>   man2/open.2 | 1 -
>   1 file changed, 1 deletion(-)
> 
> diff --git a/man2/open.2 b/man2/open.2
> index bac1ee806..1bcd995f4 100644
> --- a/man2/open.2
> +++ b/man2/open.2
> @@ -53,7 +53,6 @@
>   open, openat, creat \- open and possibly create a file
>   .SH SYNOPSIS
>   .nf
> -.B #include <sys/stat.h>
>   .B #include <fcntl.h>
>   .PP
>   .BI "int open(const char *" pathname ", int " flags );
> 


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

Re: [PATCH 26/39] open.2: Remove unused <sys/stat.h>

[Michael Kerrisk (man-pages)]

On 5/11/21 6:02 AM, Alejandro Colomar (man-pages) wrote:
> On 5/10/21 7:55 PM, Alejandro Colomar wrote:
>> I can't see a reason to include it.  <fcntl.h> provides O_*
>> constants for 'flags', S_* constants for 'mode', and mode_t.
>>
>> Probably a long time ago, some of those weren't defined in
>> <fcntl.h>, and both headers needed to be included, or maybe it's
>> a historical error.
>>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> 
> Drop this one, please.  (We discussed it yesterday.)

Okay.

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

[PATCH 27/39] openat2.2: Use syscall(SYS_...); for system calls without a wrapper; fix includes too

[Alejandro Colomar]

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

diff --git a/man2/openat2.2 b/man2/openat2.2
index 1662bd066..efa840206 100644
--- a/man2/openat2.2
+++ b/man2/openat2.2
@@ -26,16 +26,21 @@
 openat2 \- open and possibly create a file (extended)
 .SH SYNOPSIS
 .nf
-.B #include <sys/stat.h>
-.B #include <fcntl.h>
-.B #include <linux/openat2.h>
+.BR "#include <fcntl.h>" \
+"          /* Definition of " O_* " and " S_* " constants */"
+.BR "#include <linux/openat2.h>" "  /* Definition of " RESOLVE_* " constants */"
+.BR "#include <sys/syscall.h>" "    /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "long openat2(int " dirfd ", const char *" pathname ,
-.BI "            struct open_how *" how ", size_t " size );
+.BI "long syscall(SYS_openat2, int " dirfd ", const char *" pathname ,
+.BI "             struct open_how *" how ", size_t " size );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR openat2 (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR openat2 ()
@@ -494,9 +499,6 @@ The semantics of
 were modeled after FreeBSD's
 .BR O_BENEATH .
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.\"
 .SS Extensibility
 In order to allow for future extensibility,
 .BR openat2 ()
-- 
2.31.1

[PATCH 28/39] perf_event_open.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index 1d5d1aada..3bfc7c103 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -29,16 +29,21 @@
 perf_event_open \- set up performance monitoring
 .SH SYNOPSIS
 .nf
-.B #include <linux/perf_event.h>
-.B #include <linux/hw_breakpoint.h>
+.BR "#include <linux/perf_event.h>" "    /* Definition of " PERF_* " constants */"
+.BR "#include <linux/hw_breakpoint.h>" " /* Definition of " HW_* " constants */"
+.BR "#include <sys/syscall.h>" "         /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int perf_event_open(struct perf_event_attr *" attr ,
-.BI "                    pid_t " pid ", int " cpu ", int " group_fd ,
-.BI "                    unsigned long " flags  );
+.BI "int syscall(SYS_perf_event_open, struct perf_event_attr *" attr ,
+.BI "            pid_t " pid ", int " cpu ", int " group_fd \
+", unsigned long " flags  );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR perf_event_open (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 Given a list of parameters,
 .BR perf_event_open ()
@@ -3641,10 +3646,6 @@ This
 system call Linux-specific
 and should not be used in programs intended to be portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-See the example below.
-.PP
 The official way of knowing if
 .BR perf_event_open ()
 support is enabled is checking
-- 
2.31.1

[PATCH 29/39] pidfd_getfd.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
index a4bf5bfa1..71d7ae4db 100644
--- a/man2/pidfd_getfd.2
+++ b/man2/pidfd_getfd.2
@@ -27,11 +27,18 @@
 pidfd_getfd \- obtain a duplicate of another process's file descriptor
 .SH SYNOPSIS
 .nf
-.BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd ,
+.BI "            unsigned int " flags );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR pidfd_getfd (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR pidfd_getfd ()
@@ -121,9 +128,6 @@ first appeared in Linux 5.6.
 .BR pidfd_getfd ()
 is Linux specific.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 For a description of PID file descriptors, see
 .BR pidfd_open (2).
 .PP
-- 
2.31.1

[PATCH 30/39] pidfd_open.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
index d0bb1769b..cb91ce71f 100644
--- a/man2/pidfd_open.2
+++ b/man2/pidfd_open.2
@@ -27,11 +27,17 @@
 pidfd_open \- obtain a file descriptor that refers to a process
 .SH SYNOPSIS
 .nf
-.BI "int pidfd_open(pid_t " pid ", unsigned int " flags );
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_pidfd_open, pid_t " pid ", unsigned int " flags );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR pidfd_open (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR pidfd_open ()
@@ -89,9 +95,6 @@ first appeared in Linux 5.3.
 .BR pidfd_open ()
 is Linux specific.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 The following code sequence can be used to obtain a file descriptor
 for the child of
 .BR fork (2):
-- 
2.31.1

[PATCH 31/39] pidfd_send_signal.2: Use syscall(SYS_...); for system calls without a wrapper. Fix includes too

[Alejandro Colomar]

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

diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
index b025e22a0..12412c6d8 100644
--- a/man2/pidfd_send_signal.2
+++ b/man2/pidfd_send_signal.2
@@ -27,14 +27,21 @@
 pidfd_send_signal \- send a signal to a process specified by a file descriptor
 .SH SYNOPSIS
 .nf
-.B "#include <signal.h>"
+.BR "#include <linux/signal.h>" "     /* Definition of " SIG* " constants */"
+.BR "#include <signal.h>" "           /* Definition of " SI_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int pidfd_send_signal(int " pidfd ", int " sig ", siginfo_t *" info ,
+.BI "int syscall(SYS_pidfd_send_signal, int " pidfd ", int " sig \
+", siginfo_t *" info ,
 .BI "                      unsigned int " flags );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR pidfd_send_signal (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR pidfd_send_signal ()
@@ -136,9 +143,6 @@ first appeared in Linux 5.1.
 .BR pidfd_send_signal ()
 is Linux specific.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.\"
 .SS PID file descriptors
 The
 .I pidfd
-- 
2.31.1

[PATCH 32/39] pipe.2: wfix

[Alejandro Colomar]

For consistency with other pages.

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

diff --git a/man2/pipe.2 b/man2/pipe.2
index 9ac0341cf..93fbd36f2 100644
--- a/man2/pipe.2
+++ b/man2/pipe.2
@@ -40,10 +40,10 @@ pipe, pipe2 \- create pipe
 .nf
 .B #include <unistd.h>
 .PP
-.BI "int pipe(int " pipefd "[2]);"
+.BI "int pipe(int " pipefd [2]);
 .PP
 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
-.BR "#include <fcntl.h>" "              /* Obtain O_* constant definitions */"
+.BR "#include <fcntl.h>" "              /* Definition of " O_* " constants */"
 .B #include <unistd.h>
 .PP
 .BI "int pipe2(int " pipefd "[2], int " flags );
-- 
2.31.1

[PATCH 33/39] pivot_root.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/pivot_root.2 b/man2/pivot_root.2
index e0c34c450..c301c2e4a 100644
--- a/man2/pivot_root.2
+++ b/man2/pivot_root.2
@@ -29,11 +29,18 @@
 pivot_root \- change the root mount
 .SH SYNOPSIS
 .nf
-.BI "int pivot_root(const char *" new_root ", const char *" put_old );
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_pivot_root, const char *" new_root \
+", const char *" put_old );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR pivot_root (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .BR pivot_root ()
 changes the root mount in the mount namespace of the calling process.
@@ -168,9 +175,6 @@ was introduced in Linux 2.3.41.
 .BR pivot_root ()
 is Linux-specific and hence is not portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 A command-line interface for this system call is provided by
 .BR pivot_root (8).
 .PP
-- 
2.31.1

[PATCH 34/39] poll.2: Remove <signal.h>

[Alejandro Colomar]

It is only used for providing 'sigset_t'.  We're only documenting
(with some exceptions) the includes needed for constants and the
prototype itself.  And 'sigset_t' is better documented in
system_data_types(7).  Remove that include.

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

diff --git a/man2/poll.2 b/man2/poll.2
index 8622e7c7a..205468f3e 100644
--- a/man2/poll.2
+++ b/man2/poll.2
@@ -37,11 +37,10 @@ poll, ppoll \- wait for some event on a file descriptor
 .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
 .PP
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
-.B #include <signal.h>
 .B #include <poll.h>
 .PP
 .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ,
-.BI "         const struct timespec *" tmo_p ", const sigset_t *" sigmask );
+.BI "          const struct timespec *" tmo_p ", const sigset_t *" sigmask );
 .fi
 .SH DESCRIPTION
 .BR poll ()
-- 
2.31.1

[PATCH 35/39] process_madvise.2: Use syscall(SYS_...); for system calls without a wrapper. Fix includes too.

[Alejandro Colomar]

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

diff --git a/man2/process_madvise.2 b/man2/process_madvise.2
index e2b8c16ac..0cdcf9c9a 100644
--- a/man2/process_madvise.2
+++ b/man2/process_madvise.2
@@ -30,15 +30,22 @@
 process_madvise \- give advice about use of memory to a process
 .SH SYNOPSIS
 .nf
-.B #include <sys/uio.h>
+.BR "#include <sys/mman.h>" "      /* Definition of " MADV_* " constants */"
+.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
+.BR "#include <sys/uio.h>" "       /* Definition of " "struct iovec" " type */"
+.B #include <unistd.h>
 .PP
-.BI "ssize_t process_madvise(int " pidfd ", const struct iovec *" iovec ,
-.BI "                        size_t " vlen ", int " advice ,
-.BI "                        unsigned int " flags ");"
+.BI "ssize_t syscall(SYS_process_madvise, int " pidfd ,
+.BI "                const struct iovec *" iovec ", size_t " vlen \
+", int " advice ,
+.BI "                unsigned int " flags ");"
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR process_madvise (),
+necessitating the use of
+.BR syscall (2).
 .\" FIXME: See <https://sourceware.org/bugzilla/show_bug.cgi?id=27380>
 .SH DESCRIPTION
 The
@@ -205,9 +212,6 @@ configuration option.
 The
 .BR process_madvise ()
 system call is Linux-specific.
-.SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
 .SH SEE ALSO
 .BR madvise (2),
 .BR pidfd_open (2),
-- 
2.31.1

[PATCH 36/39] quotactl.2: Better detail why <xfs/xqm.h> is included

[Alejandro Colomar]

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

diff --git a/man2/quotactl.2 b/man2/quotactl.2
index 63a493231..d22d8c584 100644
--- a/man2/quotactl.2
+++ b/man2/quotactl.2
@@ -30,7 +30,9 @@ quotactl \- manipulate disk quotas
 .SH SYNOPSIS
 .nf
 .B #include <sys/quota.h>
-.B #include <xfs/xqm.h> /* for XFS quotas */
+.BR "#include <xfs/xqm.h>" " /* Definition of " Q_X* " and " XFS_QUOTA_* \
+" constants"
+.RB    "                        (or " <linux/dqblk_xfs.h> "; see NOTES) */"
 .PP
 .BI "int quotactl(int " cmd ", const char *" special ", int " id \
 ", caddr_t " addr );
-- 
2.31.1

[PATCH 37/39] readdir.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/readdir.2 b/man2/readdir.2
index f4bd5bdf7..fde142413 100644
--- a/man2/readdir.2
+++ b/man2/readdir.2
@@ -32,13 +32,17 @@
 readdir \- read directory entry
 .SH SYNOPSIS
 .nf
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int readdir(unsigned int " fd ", struct old_linux_dirent *" dirp ","
-.BI "            unsigned int " count );
+.BI "int syscall(SYS_readdir, unsigned int " fd ,
+.BI "            struct old_linux_dirent *" dirp ", unsigned int " count );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+There is no definition of
+.BR "struct old_linux_dirent" ;
+see NOTES.
 .SH DESCRIPTION
 This is not the function you are interested in.
 Look at
@@ -116,8 +120,6 @@ File descriptor does not refer to a directory.
 .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).
 You will need to define the
 .I old_linux_dirent
 structure yourself.
-- 
2.31.1

[PATCH 38/39] readlink.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/readlink.2 b/man2/readlink.2
index 8f53f8866..7387ee4e0 100644
--- a/man2/readlink.2
+++ b/man2/readlink.2
@@ -51,7 +51,7 @@ readlink, readlinkat \- read value of a symbolic link
 .BI "ssize_t readlink(const char *restrict " pathname ", char *restrict " buf ,
 .BI "                 size_t " bufsiz );
 .PP
-.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BR "#include <fcntl.h>            " "/* Definition of " AT_* " constants */"
 .B #include <unistd.h>
 .PP
 .BI "ssize_t readlinkat(int " dirfd ", const char *restrict " pathname ,
-- 
2.31.1

[PATCH 39/39] reboot.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Explain also why are headers needed.
And some ffix.

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

diff --git a/man2/reboot.2 b/man2/reboot.2
index 8a9da5904..74e8f5caa 100644
--- a/man2/reboot.2
+++ b/man2/reboot.2
@@ -30,21 +30,23 @@
 reboot \- reboot or enable/disable Ctrl-Alt-Del
 .SH SYNOPSIS
 .nf
-/* Since kernel version 2.1.30 there are symbolic names LINUX_REBOOT_*
+.RB "/* Since kernel version 2.1.30 there are symbolic names " LINUX_REBOOT_*
    for the constants and a fourth argument to the call: */
 .PP
+.BR "#include <linux/reboot.h>  " \
+"/* Definition of " LINUX_REBOOT_* " constants */"
+.BR "#include <sys/syscall.h>   " "/* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
-.B #include <linux/reboot.h>
 .PP
-.BI "int reboot(int " magic ", int " magic2 ", int " cmd ", void *" arg );
+.BI "int syscall(SYS_reboot, int " magic ", int " magic2 ", int " cmd ", void *" arg );
 .PP
 /* Under glibc and most alternative libc's (including uclibc, dietlibc,
    musl and a few others), some of the constants involved have gotten
-   symbolic names RB_*, and the library call is a 1-argument
+.RB "   symbolic names " RB_* ", and the library call is a 1-argument"
    wrapper around the system call: */
 .PP
+.BR "#include <sys/reboot.h>    " "/* Definition of " RB_* " constants */"
 .B #include <unistd.h>
-.B #include <sys/reboot.h>
 .PP
 .BI "int reboot(int " cmd );
 .fi
-- 
2.31.1

Re: [PATCH 39/39] reboot.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar (man-pages)]

On 5/10/21 7:55 PM, Alejandro Colomar wrote:
> Explain also why are headers needed.

s/are headers/headers are/

> And some ffix.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>


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

Re: [PATCH 39/39] reboot.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

On 5/11/21 6:02 AM, Alejandro Colomar (man-pages) wrote:
> On 5/10/21 7:55 PM, Alejandro Colomar wrote:
>> Explain also why are headers needed.
> 
> s/are headers/headers are/

Done.


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

Re: [PATCH 00/39] man2: SYNOPSIS: Fix headers, use syscall(), and other fixes

[Michael Kerrisk (man-pages)]

Hello Alex,

On 5/11/21 5:55 AM, Alejandro Colomar wrote:
> 
> Hi Michael,
> 
> This is the second set of SYNOPSIS fixes, mostly about fixing the includes,
> giving reasons why they are being included, and using syscall(SYS_...) when
> needed.  Other minor fixes that I have noticed while doing this are also
> included in this set.
> 
> After this set, about a 60% of man2 will be fixed.
> 
> As with the previous patch set, please review thoroughly.  I might have
> overlooked something.  It looks good, but it's been a long time...

Things looked okay to me. I dropped the patch you asked me
to drop, and made a formatting after the getdents.2 patch

> I must notice that there are a few discrepancies (see the last mails there):
> <https://lore.kernel.org/linux-man/3d6feff0-f65b-f086-aa2a-be21ff90ccfe@gmail.com/T/#u>.

Yep. I real the discussion. I think I'm okay with your choice.

I've applied all of the patches.

Thanks,

Michael

> Alejandro Colomar (39):
>   futex.2: Use syscall(SYS_...); for system calls without a wrapper
>   getdents.2: Use syscall(SYS_...); for system calls without a wrapper
>   ioctl_tty.2: Fix includes
>   ioctl_userfaultfd.2: SYNOPSIS: Add <linux/userfaultfd.h>
>   io_destroy.2: Use syscall(SYS_...); for system calls without a wrapper
>   io_getevents.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   ioperm.2: Remove obvious comment
>   ioprio_set.2: Use syscall(SYS_...); for system calls without a wrapper
>   ipc.2: Use syscall(SYS_...); for system calls without a wrapper
>   ipc.2: Add needed include
>   kcmp.2: Use syscall(SYS_...); for system calls without a wrapper
>   kcmp.2: tfix
>   kexec_load.2: Use syscall(SYS_...); for system calls without a wrapper
>   scripts/bash_aliases: man_lsfunc(): Extract syscall name from
>     syscall(SYS_...)
>   keyctl.2: Use syscall(SYS_...); for system calls without a glibc
>     wrapper
>   link.2: ffix
>   llseek.2: Use syscall(SYS_...); for system calls without a wrapper
>   lookup_dcookie.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   membarrier.2: Use syscall(SYS_...); for system calls without a wrapper
>   mincore.2: Remove unused include
>   mknod.2: Remove unused includes
>   mmap2.2: Use syscall(SYS_...); for system calls without a wrapper
>   modify_ldt.2: Use syscall(SYS_...); for system calls without a wrapper
>   mq_getsetattr.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   alloc_hugepages.2, arch_prctl.2, capget.2, clone.2, delete_module.2,
>     exit_group.2, get_robust_list.2, getunwind.2, init_module.2: Add
>     note about the use of syscall(2)
>   open.2: Remove unused <sys/stat.h>
>   openat2.2: Use syscall(SYS_...); for system calls without a wrapper;
>     fix includes too
>   perf_event_open.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   pidfd_getfd.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   pidfd_open.2: Use syscall(SYS_...); for system calls without a wrapper
>   pidfd_send_signal.2: Use syscall(SYS_...); for system calls without a
>     wrapper. Fix includes too
>   pipe.2: wfix
>   pivot_root.2: Use syscall(SYS_...); for system calls without a wrapper
>   poll.2: Remove <signal.h>
>   process_madvise.2: Use syscall(SYS_...); for system calls without a
>     wrapper. Fix includes too.
>   quotactl.2: Better detail why <xfs/xqm.h> is included
>   readdir.2: Use syscall(SYS_...); for system calls without a wrapper
>   readlink.2: ffix
>   reboot.2: Use syscall(SYS_...); for system calls without a wrapper
> 
>  man2/alloc_hugepages.2   |  5 +++++
>  man2/arch_prctl.2        |  6 ++++++
>  man2/capget.2            |  5 +++++
>  man2/clone.2             |  6 ++++++
>  man2/delete_module.2     |  6 ++++++
>  man2/exit_group.2        |  6 ++++++
>  man2/futex.2             | 21 +++++++++++----------
>  man2/get_robust_list.2   |  5 +++++
>  man2/getdents.2          | 20 +++++++++++++++-----
>  man2/getunwind.2         |  6 ++++++
>  man2/init_module.2       |  5 +++++
>  man2/io_destroy.2        | 16 +++++++++-------
>  man2/io_getevents.2      | 21 +++++++++++----------
>  man2/ioctl_tty.2         |  6 +++---
>  man2/ioctl_userfaultfd.2 |  1 +
>  man2/ioperm.2            |  2 +-
>  man2/ioprio_set.2        | 15 +++++++++------
>  man2/ipc.2               | 19 ++++++++++++-------
>  man2/kcmp.2              | 18 ++++++++++--------
>  man2/kexec_load.2        | 24 +++++++++++++-----------
>  man2/keyctl.2            | 17 +++++++----------
>  man2/link.2              |  2 +-
>  man2/llseek.2            | 13 +++++++------
>  man2/lookup_dcookie.2    | 14 +++++++++-----
>  man2/membarrier.2        | 16 ++++++++++------
>  man2/mincore.2           |  1 -
>  man2/mknod.2             |  2 --
>  man2/mmap2.2             | 10 ++++++----
>  man2/modify_ldt.2        | 15 ++++++++++-----
>  man2/mq_getsetattr.2     | 15 ++++++---------
>  man2/open.2              |  1 -
>  man2/openat2.2           | 20 +++++++++++---------
>  man2/perf_event_open.2   | 21 +++++++++++----------
>  man2/pidfd_getfd.2       | 14 +++++++++-----
>  man2/pidfd_open.2        | 13 ++++++++-----
>  man2/pidfd_send_signal.2 | 16 ++++++++++------
>  man2/pipe.2              |  4 ++--
>  man2/pivot_root.2        | 14 +++++++++-----
>  man2/poll.2              |  3 +--
>  man2/process_madvise.2   | 20 ++++++++++++--------
>  man2/quotactl.2          |  4 +++-
>  man2/readdir.2           | 12 +++++++-----
>  man2/readlink.2          |  2 +-
>  man2/reboot.2            | 12 +++++++-----
>  scripts/bash_aliases     |  1 +
>  45 files changed, 293 insertions(+), 182 deletions(-)
> 


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