[PATCH v4 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[PATCH v4 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Alejandro Colomar]

Hello Michael,

I cleaned up the includes (add missing ones, remove unneeded ones,
...), explained why each of them is needed (except for the one
providing the prototype), a few ffixes, and changed prototypes to
use syscall() when there's no wrapper.

I thought of adding a new section 'LIBRARY', as in FreeBSD's
manual pages, instead of assuming glibc, and having non-standard
clarifications in NOTES for non-glibc functions; but that would be
for a future patch-set after this one.

I highly doubt that I can finish this before 5.12, so maybe you
prefer to start a new branch to not release 5.12 with a mix of
styles...; up to you :-)

I didn't separate the syscall() changes from the #include changes,
because in most cases one implies the other, so I considered this
as a SYNOPSIS general improvement.

Cheers,

Alex


Alejandro Colomar (35):
  system_data_types.7: Add 'struct sockaddr'
  sockaddr.3: New link to system_data_types(7)
  system_data_types.7: Add 'socklen_t'
  socklen_t.3: New link to system_data_types(7)
  access.2: Use syscall(SYS_...); for system calls without a wrapper
  add_key.2: Remove unused include
  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: Add missing include
  dup.2: SYNOPSIS: Use consistent comments through pages
  execveat.2: Use syscall(SYS_...); for system calls without a wrapper
  exit_group.2: Use 'noreturn' in prototypes
  exit_group.2: Use syscall(SYS_...); for system calls without a wrapper
  fanotify_init.2: Add comment: why more than one include is needed
  fcntl.2: Remove unused include
  futex.2: Use syscall(SYS_...); for system calls without a wrapper
  futimesat.2: ffix
  getdents.2: Use syscall(SYS_...); for system calls without a wrapper
  getpriority.2: Remove unused include
  getrlimit.2, getrusage.2: Remove unused include
  getunwind.2: Use syscall(SYS_...); for system calls without a wrapper
  get_robust_list.2: Use syscall(SYS_...); for system calls without a
    wrapper
  delete_module.2: Use syscall(SYS_...); for system calls without a
    wrapper
  init_module.2: Use syscall(SYS_...); for system calls without a
    wrapper
  io_cancel.2: Use syscall(SYS_...); for system calls without a wrapper
  ioctl_fat.2: Make clear why is each header exactly needed.
  ioctl_fat.2: ffix
  ioctl_ficlonerange.2: Make clear why is each header exactly needed.
  ioctl_fideduperange.2: Make clear why exactly is each header needed
  ioctl_fslabel.2: ffix
  ioctl_fslabel.2: Make clear why exactly is each header needed
  ioctl_getfsmap.2: Make clear why exactly is each header needed

 man2/access.2              | 11 +++++---
 man2/add_key.2             |  1 -
 man2/alloc_hugepages.2     |  7 ++---
 man2/arch_prctl.2          | 15 ++++-------
 man2/capget.2              | 20 +++++++-------
 man2/clone.2               | 17 +++++-------
 man2/delete_module.2       |  9 ++++---
 man2/dup.2                 |  2 +-
 man2/execveat.2            | 14 ++++------
 man2/exit_group.2          |  5 ++--
 man2/fanotify_init.2       |  2 +-
 man2/fcntl.2               |  1 -
 man2/futex.2               | 19 +++++---------
 man2/futimesat.2           |  2 +-
 man2/get_robust_list.2     | 19 ++++++--------
 man2/getdents.2            | 12 ++++++---
 man2/getpriority.2         | 13 ----------
 man2/getrlimit.2           |  1 -
 man2/getrusage.2           |  9 -------
 man2/getunwind.2           | 14 +++-------
 man2/init_module.2         | 20 ++++++--------
 man2/io_cancel.2           | 16 +++++-------
 man2/ioctl_fat.2           |  7 ++---
 man2/ioctl_ficlonerange.2  |  2 +-
 man2/ioctl_fideduperange.2 |  3 ++-
 man2/ioctl_fslabel.2       |  4 +--
 man2/ioctl_getfsmap.2      |  4 +--
 man3/sockaddr.3            |  1 +
 man3/socklen_t.3           |  1 +
 man7/system_data_types.7   | 53 ++++++++++++++++++++++++++++++++++++++
 30 files changed, 156 insertions(+), 148 deletions(-)
 create mode 100644 man3/sockaddr.3
 create mode 100644 man3/socklen_t.3

-- 
2.31.0

[PATCH v4 01/35] system_data_types.7: Add 'struct sockaddr'

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/system_data_types.7 | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 5648ae500..93c723a2f 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -1226,6 +1226,31 @@ and
 .I ssize_t
 types in this page.
 .RE
+.\"------------------------------------- sockaddr ---------------------/
+.TP
+.I sockaddr
+.RS
+.IR Include :
+.IR <sys/socket.h> .
+.PP
+.EX
+struct sockaddr {
+    sa_family_t sa_family; /* Address family */
+    char        sa_data[]; /* Socket address */
+};
+.EE
+.PP
+Describes a socket address.
+.PP
+.IR "Conforming to" :
+POSIX.1-2001 and later.
+.PP
+.IR "See also" :
+.BR accept (2),
+.BR getpeername (2),
+.BR getsockname (2),
+.BR socket (2)
+.RE
 .\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
-- 
2.31.0

[PATCH v4 02/35] sockaddr.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/sockaddr.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/sockaddr.3

diff --git a/man3/sockaddr.3 b/man3/sockaddr.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sockaddr.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.31.0

[PATCH v4 03/35] system_data_types.7: Add 'socklen_t'

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/system_data_types.7 | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 93c723a2f..e038aab1e 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -1251,6 +1251,34 @@ POSIX.1-2001 and later.
 .BR getsockname (2),
 .BR socket (2)
 .RE
+.\"------------------------------------- socklen_t --------------------/
+.TP
+.I socklen_t
+.RS
+.IR Include :
+.IR <sys/socket.h> .
+Alternatively,
+.IR <netdb.h> .
+.PP
+Describes the length of a socket address.
+According to POSIX,
+this shall be an integer type of at least 32 bits.
+.PP
+.IR "Conforming to" :
+POSIX.1-2001 and later.
+.PP
+.IR "See also" :
+.BR accept (2),
+.BR bind (2),
+.BR connect (2),
+.BR gethostbyaddr (2),
+.BR getnameinfo (2),
+.BR socket (2)
+.PP
+See also the
+.I sockaddr
+structure in this page.
+.RE
 .\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
-- 
2.31.0

[PATCH v4 04/35] socklen_t.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/socklen_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/socklen_t.3

diff --git a/man3/socklen_t.3 b/man3/socklen_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/socklen_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.31.0

[PATCH v4 05/35] 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 4a6e28db3..f24a73161 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>" "      /* Definition of " 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.31.0

[PATCH v4 06/35] add_key.2: Remove unused include

[Alejandro Colomar]

<sys/types.h> was only needed for size_t, AFAIK.  That is already
(and more precisely) documented in system_data_types(7).  Let's
remove it here, as it's not really needed for calling add_key().

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

diff --git a/man2/add_key.2 b/man2/add_key.2
index f3d803adf..dca44b8e7 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -14,7 +14,6 @@
 add_key \- add a key to the kernel's key management facility
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
 .B #include <keyutils.h>
 .PP
 .BI "key_serial_t add_key(const char *" type ", const char *" description ,
-- 
2.31.0

[PATCH v4 07/35] alloc_hugepages.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

The page didn't specify includes, and the syscalls are extint, so
instead of adding incomplete information about includes, just
leave it without any includes.

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 07193c542..cc76fc495 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.31.0

[PATCH v4 08/35] 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 1ddeca595..f8073d625 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.31.0

[PATCH v4 09/35] 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 f8073d625..7ae5b350c 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.31.0

[PATCH v4 10/35] 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 | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/man2/capget.2 b/man2/capget.2
index 6de51b72c..a2d897cc7 100644
--- a/man2/capget.2
+++ b/man2/capget.2
@@ -18,14 +18,17 @@
 capget, capset \- set/get capabilities of thread(s)
 .SH SYNOPSIS
 .nf
-.B #include <sys/capability.h>
+.RB "         /* Definition of " CAP_* " and " \
+_LINUX_CAPABILITY_* " constants */"
+.B #include <linux/capability.h>
+.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 +43,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 +242,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.31.0

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

[Alejandro Colomar]

The CLONE_* constants seem to be available from either
<linux/sched.h> or <sched.h>, and since clone3() already
includes <linux/sched.h> for 'struct clone_args', <sched.h>
is not really needed, AFAICS; however, to avoid confussion,
I also included <sched.h> for clone3() for consistency:

clone() is getting CLONE_* from <sched.h>, and it would confuse
the reader if clone3() got the same CLONE_* constants from a
different header.

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

diff --git a/man2/clone.2 b/man2/clone.2
index fa7d1103e..f455c97d8 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -56,13 +56,13 @@ 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 <sched.h>" "          /* Definition of " CLONE_* " constants */"
+.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 +1541,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.31.0

[PATCH v4 12/35] delete_module.2: Add missing include

[Alejandro Colomar]

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

diff --git a/man2/delete_module.2 b/man2/delete_module.2
index bb0a812a6..174ef04d2 100644
--- a/man2/delete_module.2
+++ b/man2/delete_module.2
@@ -27,6 +27,8 @@
 delete_module \- unload a kernel module
 .SH SYNOPSIS
 .nf
+.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
+.PP
 .BI "int delete_module(const char *" name ", unsigned int " flags );
 .fi
 .PP
-- 
2.31.0

[PATCH v4 13/35] dup.2: SYNOPSIS: Use consistent comments through pages

[Alejandro Colomar]

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

diff --git a/man2/dup.2 b/man2/dup.2
index 725b9d7d5..b9e0828b0 100644
--- a/man2/dup.2
+++ b/man2/dup.2
@@ -45,7 +45,7 @@ dup, dup2, dup3 \- duplicate a file descriptor
 .BI "int dup2(int " oldfd ", int " newfd );
 .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 dup3(int " oldfd ", int " newfd ", int " flags );
-- 
2.31.0

[PATCH v4 14/35] execveat.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Add <linux/fcntl.h>, which contains AT_* definitions used by
execveat().

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

diff --git a/man2/execveat.2 b/man2/execveat.2
index 855832765..c566f53df 100644
--- a/man2/execveat.2
+++ b/man2/execveat.2
@@ -28,15 +28,14 @@
 execveat \- execute program relative to a directory file descriptor
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
+.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 +208,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.31.0

[PATCH v4 15/35] exit_group.2: Use 'noreturn' in prototypes

[Alejandro Colomar]

This function never returns to its caller.

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

diff --git a/man2/exit_group.2 b/man2/exit_group.2
index d26ec8c70..4fd314262 100644
--- a/man2/exit_group.2
+++ b/man2/exit_group.2
@@ -29,7 +29,7 @@ exit_group \- exit all threads in a process
 .nf
 .B #include <linux/unistd.h>
 .PP
-.BI "void exit_group(int " status );
+.BI "noreturn void exit_group(int " status );
 .fi
 .SH DESCRIPTION
 This system call is equivalent to
-- 
2.31.0

[PATCH v4 16/35] exit_group.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

<linux/unistd.h> is not needed.  We need <unistd.h> for syscall(),
and <sys/syscall.h> for SYS_exit_group.

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 4fd314262..b512927d4 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 "noreturn void exit_group(int " status );
+.BI "noreturn void syscall(SYS_exit_group, int " status );
 .fi
 .SH DESCRIPTION
 This system call is equivalent to
-- 
2.31.0

[PATCH v4 17/35] fanotify_init.2: Add comment: why more than one include is needed

[Alejandro Colomar]

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

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 2418bbdd2..2b44fc6ec 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -26,7 +26,7 @@
 fanotify_init \- create and initialize fanotify group
 .SH SYNOPSIS
 .nf
-.B #include <fcntl.h>
+.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
 .B #include <sys/fanotify.h>
 .PP
 .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
-- 
2.31.0

[PATCH v4 18/35] fcntl.2: Remove unused include

[Alejandro Colomar]

I couldn't find a reason for including <unistd.h>.  All the macros
used by fcntl() are defined in <fcntl.h>.  For comparison, FreeBSD
and OpenBSD don't specify <unistd.h> in their manual pages.

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

diff --git a/man2/fcntl.2 b/man2/fcntl.2
index de87eec1f..7b5604e3a 100644
--- a/man2/fcntl.2
+++ b/man2/fcntl.2
@@ -69,7 +69,6 @@
 fcntl \- manipulate file descriptor
 .SH SYNOPSIS
 .nf
-.B #include <unistd.h>
 .B #include <fcntl.h>
 .PP
 .BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );"
-- 
2.31.0

[PATCH v4 19/35] 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 389c25224..7a19e50d2 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.31.0

[PATCH v4 20/35] futimesat.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/futimesat.2 b/man2/futimesat.2
index 6ac9a9200..86e941fe5 100644
--- a/man2/futimesat.2
+++ b/man2/futimesat.2
@@ -28,7 +28,7 @@ futimesat \- change timestamps of a file relative to a \
 directory file descriptor
 .SH SYNOPSIS
 .nf
-.B #include <fcntl.h>           /* Definition of AT_* constants */
+.BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
 .B #include <sys/time.h>
 .PP
 .BI "int futimesat(int " dirfd ", const char *" pathname ,
-- 
2.31.0

[PATCH v4 21/35] 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 ec00a73ba..6a9f4e04c 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.31.0

[PATCH v4 22/35] getpriority.2: Remove unused include

[Alejandro Colomar]

<sys/time.h> is not needed to get the function declaration nor any
constant used by the function.  It was only needed (before
POSIX.1) to get 'struct timeval', but that information would be
more suited for system_data_types(7), and not for this page.

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

diff --git a/man2/getpriority.2 b/man2/getpriority.2
index e3d518028..d6744989d 100644
--- a/man2/getpriority.2
+++ b/man2/getpriority.2
@@ -47,7 +47,6 @@
 getpriority, setpriority \- get/set program scheduling priority
 .SH SYNOPSIS
 .nf
-.B #include <sys/time.h>
 .B #include <sys/resource.h>
 .PP
 .BI "int getpriority(int " which ", id_t " who );
@@ -209,18 +208,6 @@ the real or effective user ID of the process \fIwho\fP.
 All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
 manner as Linux 2.6.12 and later.
-.PP
-Including
-.I <sys/time.h>
-is not required these days, but increases portability.
-(Indeed,
-.I <sys/resource.h>
-defines the
-.I rusage
-structure with fields of type
-.I struct timeval
-defined in
-.IR <sys/time.h> .)
 .\"
 .SS C library/kernel differences
 Within the kernel, nice values are actually represented
-- 
2.31.0

[PATCH v4 23/35] getrlimit.2, getrusage.2: Remove unused include

[Alejandro Colomar]

<sys/time.h> is not required by any of these function declaration
or macro definition used by these functions.  It's maybe (or maybe
not) needed by some tipe inside the rlimit structure, but that
info belongs to system_data_types(7), not here.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/getrlimit.2 | 1 -
 man2/getrusage.2 | 9 ---------
 2 files changed, 10 deletions(-)

diff --git a/man2/getrlimit.2 b/man2/getrlimit.2
index 444c50525..648fd3c85 100644
--- a/man2/getrlimit.2
+++ b/man2/getrlimit.2
@@ -66,7 +66,6 @@
 getrlimit, setrlimit, prlimit \- get/set resource limits
 .SH SYNOPSIS
 .nf
-.B #include <sys/time.h>
 .B #include <sys/resource.h>
 .PP
 .BI "int getrlimit(int " resource ", struct rlimit *" rlim );
diff --git a/man2/getrusage.2 b/man2/getrusage.2
index d3c0de8a0..85c4ffed1 100644
--- a/man2/getrusage.2
+++ b/man2/getrusage.2
@@ -41,7 +41,6 @@
 getrusage \- get resource usage
 .SH SYNOPSIS
 .nf
-.B #include <sys/time.h>
 .B #include <sys/resource.h>
 .PP
 .BI "int getrusage(int " who ", struct rusage *" usage );
@@ -230,14 +229,6 @@ is Linux-specific.
 Resource usage metrics are preserved across an
 .BR execve (2).
 .PP
-Including
-.I <sys/time.h>
-is not required these days, but increases portability.
-(Indeed,
-.I struct timeval
-is defined in
-.IR <sys/time.h> .)
-.PP
 In Linux kernel versions before 2.6.9, if the disposition of
 .B SIGCHLD
 is set to
-- 
2.31.0

[PATCH v4 24/35] 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 45535dccf..2c44506c7 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.31.0

[PATCH v4 25/35] get_robust_list.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2
index dd43cded2..b1368ddd3 100644
--- a/man2/get_robust_list.2
+++ b/man2/get_robust_list.2
@@ -32,16 +32,16 @@
 get_robust_list, set_robust_list \- get/set list of robust futexes
 .SH SYNOPSIS
 .nf
-.B #include <linux/futex.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:
@@ -138,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.31.0

[PATCH v4 26/35] delete_module.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/delete_module.2 b/man2/delete_module.2
index 174ef04d2..21c9e9d8d 100644
--- a/man2/delete_module.2
+++ b/man2/delete_module.2
@@ -28,12 +28,11 @@ delete_module \- unload a kernel module
 .SH SYNOPSIS
 .nf
 .BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.BR "#include <unistd.h>
 .PP
-.BI "int delete_module(const char *" name ", unsigned int " flags );
+.BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 The
 .BR delete_module ()
-- 
2.31.0

[PATCH v4 27/35] 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 | 20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/man2/init_module.2 b/man2/init_module.2
index e158ce9fa..13d1b7f0a 100644
--- a/man2/init_module.2
+++ b/man2/init_module.2
@@ -29,14 +29,15 @@
 init_module, finit_module \- load a kernel module
 .SH SYNOPSIS
 .nf
-.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 );
-.fi
+.BR "#include <linux/module.h>" "    /* Definition of " MODULE_* " 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_init_module, void *" module_image ", unsigned long " len ,
+.BI "            const char *" param_values );
+.BI "int syscall(SYS_finit_module, int " fd ", const char *" param_values ,
+.BI "            int " flags );
+.fi
 .SH DESCRIPTION
 .BR init_module ()
 loads an ELF image into kernel space,
@@ -268,11 +269,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.31.0

[PATCH v4 28/35] io_cancel.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 kernel syscall.

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

diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index e09984ecd..248fe5791 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -9,14 +9,13 @@
 io_cancel \- cancel an outstanding asynchronous I/O operation
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
+.BR "#include <linux/aio_abi.h>" "    /* Definition of needed types */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
-.BI "              struct io_event *" result );
+.BI "int syscall(SYS_io_cancel, aio_context_t " ctx_id ", struct iocb *" iocb ,
+.BI "            struct io_event *" result );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 .IR Note :
 this page describes the raw Linux system call interface.
@@ -68,10 +67,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_cancel ()
 wrapper function provided by
 .\" http://git.fedorahosted.org/git/?p=libaio.git
-- 
2.31.0

[PATCH v4 29/35] ioctl_fat.2: Make clear why is each header exactly needed.

[Alejandro Colomar]

Only the one that provides the prototype doesn't need a comment.

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

diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2
index 30e410280..ea50bf319 100644
--- a/man2/ioctl_fat.2
+++ b/man2/ioctl_fat.2
@@ -26,7 +26,8 @@
 ioctl_fat \- manipulating the FAT filesystem
 .SH SYNOPSIS
 .nf
-.B #include <linux/msdos_fs.h>
+.BR "#include <linux/msdos_fs.h>" "   /* Definition of [" V ] FAT_*
+.RB    "                               * and " ATTR_* " constants */"
 .B #include <sys/ioctl.h>
 .PP
 .BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t *" attr );
-- 
2.31.0

[PATCH v4 30/35] ioctl_fat.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2
index ea50bf319..daceafc83 100644
--- a/man2/ioctl_fat.2
+++ b/man2/ioctl_fat.2
@@ -34,9 +34,9 @@ ioctl_fat \- manipulating the FAT filesystem
 .BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr );
 .BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id );
 .BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH,"
-.BI "          struct __fat_dirent[2] " entry );
+.BI "          struct __fat_dirent " entry [2]);
 .BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT,"
-.BI "          struct __fat_dirent[2] " entry );
+.BI "          struct __fat_dirent " entry [2]);
 .fi
 .SH DESCRIPTION
 The
-- 
2.31.0

[PATCH v4 31/35] ioctl_ficlonerange.2: Make clear why is each header exactly needed.

[Alejandro Colomar]

Only the one that provides the prototype doesn't need a comment.

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

diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2
index 34c171941..75ab14bc4 100644
--- a/man2/ioctl_ficlonerange.2
+++ b/man2/ioctl_ficlonerange.2
@@ -25,8 +25,8 @@
 ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/fs.h>" "        /* Definition of " FICLONE* " constants */"
 .B #include <sys/ioctl.h>
-.B #include <linux/fs.h>
 .PP
 .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
 .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
-- 
2.31.0

[PATCH v4 32/35] ioctl_fideduperange.2: Make clear why exactly is each header needed

[Alejandro Colomar]

Only the include that provides the prototype doesn't need a comment.

Also sort the includes alphabetically.

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

diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2
index 1df0628d0..e924ed248 100644
--- a/man2/ioctl_fideduperange.2
+++ b/man2/ioctl_fideduperange.2
@@ -25,8 +25,9 @@
 ioctl_fideduperange \- share some the data of one file with another file
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/fs.h>" "         /* Definition of " FIDEDUPERANGE
+.RB    "                               * and " FILE_DEDUPE_* " constants */"
 .B #include <sys/ioctl.h>
-.B #include <linux/fs.h>
 .PP
 .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg );
 .fi
-- 
2.31.0

[PATCH v4 33/35] ioctl_fslabel.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2
index 9f5e0dbbd..af17256f0 100644
--- a/man2/ioctl_fslabel.2
+++ b/man2/ioctl_fslabel.2
@@ -36,7 +36,7 @@ If a filesystem supports online label manipulation, these
 .BR ioctl (2)
 operations can be used to get or set the filesystem label for the filesystem
 on which
-.B fd
+.I fd
 resides.
 The
 .B FS_IOC_SETFSLABEL
-- 
2.31.0

[PATCH v4 34/35] ioctl_fslabel.2: Make clear why exactly is each header needed

[Alejandro Colomar]

Only the include that provides the prototype doesn't need a comment.

Also sort the includes alphabetically.

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

diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2
index af17256f0..30435e1e9 100644
--- a/man2/ioctl_fslabel.2
+++ b/man2/ioctl_fslabel.2
@@ -25,8 +25,8 @@
 ioctl_fslabel \- get or set a filesystem label
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/fs.h>" "       /* Definition of " *FSLABEL* " constants */"
 .B #include <sys/ioctl.h>
-.B #include <linux/fs.h>
 .PP
 .BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]);
 .BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]);
-- 
2.31.0

[PATCH v4 35/35] ioctl_getfsmap.2: Make clear why exactly is each header needed

[Alejandro Colomar]

<linux/fs.h> doesn't seem to be needed!
Only the include that provides the prototype doesn't need a comment.

Also sort the includes alphabetically.

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

diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2
index 4ff1c8a90..55a9ad620 100644
--- a/man2/ioctl_getfsmap.2
+++ b/man2/ioctl_getfsmap.2
@@ -25,9 +25,9 @@
 ioctl_getfsmap \- retrieve the physical layout of the filesystem
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/fsmap.h>" "  /* Definition of " FS_IOC_GETFSMAP ,
+.RB "                           * " FM?_OF_* ", and " *FMR_OWN_* " constants */"
 .B #include <sys/ioctl.h>
-.B #include <linux/fs.h>
-.B #include <linux/fsmap.h>
 .PP
 .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
 .fi
-- 
2.31.0

[PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Alejandro Colomar]

v5:
	- ffix 29/35, 32/35, and 35/35.  The rest are identical to v4.


Alejandro Colomar (35):
  system_data_types.7: Add 'struct sockaddr'
  sockaddr.3: New link to system_data_types(7)
  system_data_types.7: Add 'socklen_t'
  socklen_t.3: New link to system_data_types(7)
  access.2: Use syscall(SYS_...); for system calls without a wrapper
  add_key.2: Remove unused include
  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: Add missing include
  dup.2: SYNOPSIS: Use consistent comments through pages
  execveat.2: Use syscall(SYS_...); for system calls without a wrapper
  exit_group.2: Use 'noreturn' in prototypes
  exit_group.2: Use syscall(SYS_...); for system calls without a wrapper
  fanotify_init.2: Add comment: why more than one include is needed
  fcntl.2: Remove unused include
  futex.2: Use syscall(SYS_...); for system calls without a wrapper
  futimesat.2: ffix
  getdents.2: Use syscall(SYS_...); for system calls without a wrapper
  getpriority.2: Remove unused include
  getrlimit.2, getrusage.2: Remove unused include
  getunwind.2: Use syscall(SYS_...); for system calls without a wrapper
  get_robust_list.2: Use syscall(SYS_...); for system calls without a
    wrapper
  delete_module.2: Use syscall(SYS_...); for system calls without a
    wrapper
  init_module.2: Use syscall(SYS_...); for system calls without a
    wrapper
  io_cancel.2: Use syscall(SYS_...); for system calls without a wrapper
  ioctl_fat.2: Make clear why is each header exactly needed.
  ioctl_fat.2: ffix
  ioctl_ficlonerange.2: Make clear why is each header exactly needed.
  ioctl_fideduperange.2: Make clear why exactly is each header needed
  ioctl_fslabel.2: ffix
  ioctl_fslabel.2: Make clear why exactly is each header needed
  ioctl_getfsmap.2: Make clear why exactly is each header needed

 man2/access.2              | 11 +++++---
 man2/add_key.2             |  1 -
 man2/alloc_hugepages.2     |  7 ++---
 man2/arch_prctl.2          | 15 ++++-------
 man2/capget.2              | 20 +++++++-------
 man2/clone.2               | 17 +++++-------
 man2/delete_module.2       |  9 ++++---
 man2/dup.2                 |  2 +-
 man2/execveat.2            | 14 ++++------
 man2/exit_group.2          |  5 ++--
 man2/fanotify_init.2       |  2 +-
 man2/fcntl.2               |  1 -
 man2/futex.2               | 19 +++++---------
 man2/futimesat.2           |  2 +-
 man2/get_robust_list.2     | 19 ++++++--------
 man2/getdents.2            | 12 ++++++---
 man2/getpriority.2         | 13 ----------
 man2/getrlimit.2           |  1 -
 man2/getrusage.2           |  9 -------
 man2/getunwind.2           | 14 +++-------
 man2/init_module.2         | 20 ++++++--------
 man2/io_cancel.2           | 16 +++++-------
 man2/ioctl_fat.2           |  5 ++--
 man2/ioctl_ficlonerange.2  |  2 +-
 man2/ioctl_fideduperange.2 |  3 ++-
 man2/ioctl_fslabel.2       |  4 +--
 man2/ioctl_getfsmap.2      |  5 ++--
 man3/sockaddr.3            |  1 +
 man3/socklen_t.3           |  1 +
 man7/system_data_types.7   | 53 ++++++++++++++++++++++++++++++++++++++
 30 files changed, 156 insertions(+), 147 deletions(-)
 create mode 100644 man3/sockaddr.3
 create mode 100644 man3/socklen_t.3

-- 
2.31.0

[PATCH v5 01/35] system_data_types.7: Add 'struct sockaddr'

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/system_data_types.7 | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 5648ae500..93c723a2f 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -1226,6 +1226,31 @@ and
 .I ssize_t
 types in this page.
 .RE
+.\"------------------------------------- sockaddr ---------------------/
+.TP
+.I sockaddr
+.RS
+.IR Include :
+.IR <sys/socket.h> .
+.PP
+.EX
+struct sockaddr {
+    sa_family_t sa_family; /* Address family */
+    char        sa_data[]; /* Socket address */
+};
+.EE
+.PP
+Describes a socket address.
+.PP
+.IR "Conforming to" :
+POSIX.1-2001 and later.
+.PP
+.IR "See also" :
+.BR accept (2),
+.BR getpeername (2),
+.BR getsockname (2),
+.BR socket (2)
+.RE
 .\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
-- 
2.31.0

[PATCH v5 02/35] sockaddr.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/sockaddr.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/sockaddr.3

diff --git a/man3/sockaddr.3 b/man3/sockaddr.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sockaddr.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.31.0

[PATCH v5 03/35] system_data_types.7: Add 'socklen_t'

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/system_data_types.7 | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 93c723a2f..e038aab1e 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -1251,6 +1251,34 @@ POSIX.1-2001 and later.
 .BR getsockname (2),
 .BR socket (2)
 .RE
+.\"------------------------------------- socklen_t --------------------/
+.TP
+.I socklen_t
+.RS
+.IR Include :
+.IR <sys/socket.h> .
+Alternatively,
+.IR <netdb.h> .
+.PP
+Describes the length of a socket address.
+According to POSIX,
+this shall be an integer type of at least 32 bits.
+.PP
+.IR "Conforming to" :
+POSIX.1-2001 and later.
+.PP
+.IR "See also" :
+.BR accept (2),
+.BR bind (2),
+.BR connect (2),
+.BR gethostbyaddr (2),
+.BR getnameinfo (2),
+.BR socket (2)
+.PP
+See also the
+.I sockaddr
+structure in this page.
+.RE
 .\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
-- 
2.31.0

[PATCH v5 04/35] socklen_t.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/socklen_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/socklen_t.3

diff --git a/man3/socklen_t.3 b/man3/socklen_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/socklen_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.31.0

[PATCH v5 05/35] 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 4a6e28db3..f24a73161 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>" "      /* Definition of " 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.31.0

[PATCH v5 06/35] add_key.2: Remove unused include

[Alejandro Colomar]

<sys/types.h> was only needed for size_t, AFAIK.  That is already
(and more precisely) documented in system_data_types(7).  Let's
remove it here, as it's not really needed for calling add_key().

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

diff --git a/man2/add_key.2 b/man2/add_key.2
index f3d803adf..dca44b8e7 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -14,7 +14,6 @@
 add_key \- add a key to the kernel's key management facility
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
 .B #include <keyutils.h>
 .PP
 .BI "key_serial_t add_key(const char *" type ", const char *" description ,
-- 
2.31.0

[PATCH v5 07/35] alloc_hugepages.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

The page didn't specify includes, and the syscalls are extint, so
instead of adding incomplete information about includes, just
leave it without any includes.

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 07193c542..cc76fc495 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.31.0

[PATCH v5 08/35] 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 1ddeca595..f8073d625 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.31.0

[PATCH v5 09/35] 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 f8073d625..7ae5b350c 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.31.0

[PATCH v5 10/35] 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 | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/man2/capget.2 b/man2/capget.2
index 6de51b72c..a2d897cc7 100644
--- a/man2/capget.2
+++ b/man2/capget.2
@@ -18,14 +18,17 @@
 capget, capset \- set/get capabilities of thread(s)
 .SH SYNOPSIS
 .nf
-.B #include <sys/capability.h>
+.RB "         /* Definition of " CAP_* " and " \
+_LINUX_CAPABILITY_* " constants */"
+.B #include <linux/capability.h>
+.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 +43,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 +242,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.31.0

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

[Alejandro Colomar]

The CLONE_* constants seem to be available from either
<linux/sched.h> or <sched.h>, and since clone3() already
includes <linux/sched.h> for 'struct clone_args', <sched.h>
is not really needed, AFAICS; however, to avoid confussion,
I also included <sched.h> for clone3() for consistency:

clone() is getting CLONE_* from <sched.h>, and it would confuse
the reader if clone3() got the same CLONE_* constants from a
different header.

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

diff --git a/man2/clone.2 b/man2/clone.2
index fa7d1103e..f455c97d8 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -56,13 +56,13 @@ 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 <sched.h>" "          /* Definition of " CLONE_* " constants */"
+.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 +1541,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.31.0

[PATCH v5 12/35] delete_module.2: Add missing include

[Alejandro Colomar]

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

diff --git a/man2/delete_module.2 b/man2/delete_module.2
index bb0a812a6..174ef04d2 100644
--- a/man2/delete_module.2
+++ b/man2/delete_module.2
@@ -27,6 +27,8 @@
 delete_module \- unload a kernel module
 .SH SYNOPSIS
 .nf
+.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
+.PP
 .BI "int delete_module(const char *" name ", unsigned int " flags );
 .fi
 .PP
-- 
2.31.0

[PATCH v5 13/35] dup.2: SYNOPSIS: Use consistent comments through pages

[Alejandro Colomar]

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

diff --git a/man2/dup.2 b/man2/dup.2
index 725b9d7d5..b9e0828b0 100644
--- a/man2/dup.2
+++ b/man2/dup.2
@@ -45,7 +45,7 @@ dup, dup2, dup3 \- duplicate a file descriptor
 .BI "int dup2(int " oldfd ", int " newfd );
 .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 dup3(int " oldfd ", int " newfd ", int " flags );
-- 
2.31.0

[PATCH v5 14/35] execveat.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

Add <linux/fcntl.h>, which contains AT_* definitions used by
execveat().

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

diff --git a/man2/execveat.2 b/man2/execveat.2
index 855832765..c566f53df 100644
--- a/man2/execveat.2
+++ b/man2/execveat.2
@@ -28,15 +28,14 @@
 execveat \- execute program relative to a directory file descriptor
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
+.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 +208,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.31.0

[PATCH v5 15/35] exit_group.2: Use 'noreturn' in prototypes

[Alejandro Colomar]

This function never returns to its caller.

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

diff --git a/man2/exit_group.2 b/man2/exit_group.2
index d26ec8c70..4fd314262 100644
--- a/man2/exit_group.2
+++ b/man2/exit_group.2
@@ -29,7 +29,7 @@ exit_group \- exit all threads in a process
 .nf
 .B #include <linux/unistd.h>
 .PP
-.BI "void exit_group(int " status );
+.BI "noreturn void exit_group(int " status );
 .fi
 .SH DESCRIPTION
 This system call is equivalent to
-- 
2.31.0

[PATCH v5 16/35] exit_group.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

<linux/unistd.h> is not needed.  We need <unistd.h> for syscall(),
and <sys/syscall.h> for SYS_exit_group.

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 4fd314262..b512927d4 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 "noreturn void exit_group(int " status );
+.BI "noreturn void syscall(SYS_exit_group, int " status );
 .fi
 .SH DESCRIPTION
 This system call is equivalent to
-- 
2.31.0

[PATCH v5 17/35] fanotify_init.2: Add comment: why more than one include is needed

[Alejandro Colomar]

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

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 2418bbdd2..2b44fc6ec 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -26,7 +26,7 @@
 fanotify_init \- create and initialize fanotify group
 .SH SYNOPSIS
 .nf
-.B #include <fcntl.h>
+.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
 .B #include <sys/fanotify.h>
 .PP
 .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
-- 
2.31.0

[PATCH v5 18/35] fcntl.2: Remove unused include

[Alejandro Colomar]

I couldn't find a reason for including <unistd.h>.  All the macros
used by fcntl() are defined in <fcntl.h>.  For comparison, FreeBSD
and OpenBSD don't specify <unistd.h> in their manual pages.

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

diff --git a/man2/fcntl.2 b/man2/fcntl.2
index de87eec1f..7b5604e3a 100644
--- a/man2/fcntl.2
+++ b/man2/fcntl.2
@@ -69,7 +69,6 @@
 fcntl \- manipulate file descriptor
 .SH SYNOPSIS
 .nf
-.B #include <unistd.h>
 .B #include <fcntl.h>
 .PP
 .BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );"
-- 
2.31.0

[PATCH v5 19/35] 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 389c25224..7a19e50d2 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.31.0

[PATCH v5 20/35] futimesat.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/futimesat.2 b/man2/futimesat.2
index 6ac9a9200..86e941fe5 100644
--- a/man2/futimesat.2
+++ b/man2/futimesat.2
@@ -28,7 +28,7 @@ futimesat \- change timestamps of a file relative to a \
 directory file descriptor
 .SH SYNOPSIS
 .nf
-.B #include <fcntl.h>           /* Definition of AT_* constants */
+.BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
 .B #include <sys/time.h>
 .PP
 .BI "int futimesat(int " dirfd ", const char *" pathname ,
-- 
2.31.0

[PATCH v5 21/35] 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 ec00a73ba..6a9f4e04c 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.31.0

[PATCH v5 22/35] getpriority.2: Remove unused include

[Alejandro Colomar]

<sys/time.h> is not needed to get the function declaration nor any
constant used by the function.  It was only needed (before
POSIX.1) to get 'struct timeval', but that information would be
more suited for system_data_types(7), and not for this page.

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

diff --git a/man2/getpriority.2 b/man2/getpriority.2
index e3d518028..d6744989d 100644
--- a/man2/getpriority.2
+++ b/man2/getpriority.2
@@ -47,7 +47,6 @@
 getpriority, setpriority \- get/set program scheduling priority
 .SH SYNOPSIS
 .nf
-.B #include <sys/time.h>
 .B #include <sys/resource.h>
 .PP
 .BI "int getpriority(int " which ", id_t " who );
@@ -209,18 +208,6 @@ the real or effective user ID of the process \fIwho\fP.
 All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
 manner as Linux 2.6.12 and later.
-.PP
-Including
-.I <sys/time.h>
-is not required these days, but increases portability.
-(Indeed,
-.I <sys/resource.h>
-defines the
-.I rusage
-structure with fields of type
-.I struct timeval
-defined in
-.IR <sys/time.h> .)
 .\"
 .SS C library/kernel differences
 Within the kernel, nice values are actually represented
-- 
2.31.0

[PATCH v5 23/35] getrlimit.2, getrusage.2: Remove unused include

[Alejandro Colomar]

<sys/time.h> is not required by any of these function declaration
or macro definition used by these functions.  It's maybe (or maybe
not) needed by some tipe inside the rlimit structure, but that
info belongs to system_data_types(7), not here.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/getrlimit.2 | 1 -
 man2/getrusage.2 | 9 ---------
 2 files changed, 10 deletions(-)

diff --git a/man2/getrlimit.2 b/man2/getrlimit.2
index 444c50525..648fd3c85 100644
--- a/man2/getrlimit.2
+++ b/man2/getrlimit.2
@@ -66,7 +66,6 @@
 getrlimit, setrlimit, prlimit \- get/set resource limits
 .SH SYNOPSIS
 .nf
-.B #include <sys/time.h>
 .B #include <sys/resource.h>
 .PP
 .BI "int getrlimit(int " resource ", struct rlimit *" rlim );
diff --git a/man2/getrusage.2 b/man2/getrusage.2
index d3c0de8a0..85c4ffed1 100644
--- a/man2/getrusage.2
+++ b/man2/getrusage.2
@@ -41,7 +41,6 @@
 getrusage \- get resource usage
 .SH SYNOPSIS
 .nf
-.B #include <sys/time.h>
 .B #include <sys/resource.h>
 .PP
 .BI "int getrusage(int " who ", struct rusage *" usage );
@@ -230,14 +229,6 @@ is Linux-specific.
 Resource usage metrics are preserved across an
 .BR execve (2).
 .PP
-Including
-.I <sys/time.h>
-is not required these days, but increases portability.
-(Indeed,
-.I struct timeval
-is defined in
-.IR <sys/time.h> .)
-.PP
 In Linux kernel versions before 2.6.9, if the disposition of
 .B SIGCHLD
 is set to
-- 
2.31.0

[PATCH v5 24/35] 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 45535dccf..2c44506c7 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.31.0

[PATCH v5 25/35] get_robust_list.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2
index dd43cded2..b1368ddd3 100644
--- a/man2/get_robust_list.2
+++ b/man2/get_robust_list.2
@@ -32,16 +32,16 @@
 get_robust_list, set_robust_list \- get/set list of robust futexes
 .SH SYNOPSIS
 .nf
-.B #include <linux/futex.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:
@@ -138,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.31.0

[PATCH v5 26/35] delete_module.2: Use syscall(SYS_...); for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/delete_module.2 b/man2/delete_module.2
index 174ef04d2..21c9e9d8d 100644
--- a/man2/delete_module.2
+++ b/man2/delete_module.2
@@ -28,12 +28,11 @@ delete_module \- unload a kernel module
 .SH SYNOPSIS
 .nf
 .BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.BR "#include <unistd.h>
 .PP
-.BI "int delete_module(const char *" name ", unsigned int " flags );
+.BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 The
 .BR delete_module ()
-- 
2.31.0

[PATCH v5 27/35] 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 | 20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/man2/init_module.2 b/man2/init_module.2
index e158ce9fa..13d1b7f0a 100644
--- a/man2/init_module.2
+++ b/man2/init_module.2
@@ -29,14 +29,15 @@
 init_module, finit_module \- load a kernel module
 .SH SYNOPSIS
 .nf
-.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 );
-.fi
+.BR "#include <linux/module.h>" "    /* Definition of " MODULE_* " 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_init_module, void *" module_image ", unsigned long " len ,
+.BI "            const char *" param_values );
+.BI "int syscall(SYS_finit_module, int " fd ", const char *" param_values ,
+.BI "            int " flags );
+.fi
 .SH DESCRIPTION
 .BR init_module ()
 loads an ELF image into kernel space,
@@ -268,11 +269,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.31.0

[PATCH v5 28/35] io_cancel.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 kernel syscall.

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

diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index e09984ecd..248fe5791 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -9,14 +9,13 @@
 io_cancel \- cancel an outstanding asynchronous I/O operation
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
+.BR "#include <linux/aio_abi.h>" "    /* Definition of needed types */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
-.BI "              struct io_event *" result );
+.BI "int syscall(SYS_io_cancel, aio_context_t " ctx_id ", struct iocb *" iocb ,
+.BI "            struct io_event *" result );
 .fi
-.PP
-.IR Note :
-There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 .IR Note :
 this page describes the raw Linux system call interface.
@@ -68,10 +67,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_cancel ()
 wrapper function provided by
 .\" http://git.fedorahosted.org/git/?p=libaio.git
-- 
2.31.0

[PATCH v5 29/35] ioctl_fat.2: Make clear why is each header exactly needed.

[Alejandro Colomar]

Only the one that provides the prototype doesn't need a comment.

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

diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2
index 30e410280..263738dad 100644
--- a/man2/ioctl_fat.2
+++ b/man2/ioctl_fat.2
@@ -26,6 +26,7 @@
 ioctl_fat \- manipulating the FAT filesystem
 .SH SYNOPSIS
 .nf
+.RB "         /* Definition of [" V ] FAT_* " and " ATTR_* " constants */"
 .B #include <linux/msdos_fs.h>
 .B #include <sys/ioctl.h>
 .PP
-- 
2.31.0

[PATCH v5 30/35] ioctl_fat.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2
index 263738dad..8914505c7 100644
--- a/man2/ioctl_fat.2
+++ b/man2/ioctl_fat.2
@@ -34,9 +34,9 @@ ioctl_fat \- manipulating the FAT filesystem
 .BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr );
 .BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id );
 .BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH,"
-.BI "          struct __fat_dirent[2] " entry );
+.BI "          struct __fat_dirent " entry [2]);
 .BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT,"
-.BI "          struct __fat_dirent[2] " entry );
+.BI "          struct __fat_dirent " entry [2]);
 .fi
 .SH DESCRIPTION
 The
-- 
2.31.0

[PATCH v5 31/35] ioctl_ficlonerange.2: Make clear why is each header exactly needed.

[Alejandro Colomar]

Only the one that provides the prototype doesn't need a comment.

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

diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2
index 34c171941..75ab14bc4 100644
--- a/man2/ioctl_ficlonerange.2
+++ b/man2/ioctl_ficlonerange.2
@@ -25,8 +25,8 @@
 ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/fs.h>" "        /* Definition of " FICLONE* " constants */"
 .B #include <sys/ioctl.h>
-.B #include <linux/fs.h>
 .PP
 .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
 .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
-- 
2.31.0

[PATCH v5 32/35] ioctl_fideduperange.2: Make clear why exactly is each header needed

[Alejandro Colomar]

Only the include that provides the prototype doesn't need a comment.

Also sort the includes alphabetically.

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

diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2
index 1df0628d0..82c7fdc28 100644
--- a/man2/ioctl_fideduperange.2
+++ b/man2/ioctl_fideduperange.2
@@ -25,8 +25,9 @@
 ioctl_fideduperange \- share some the data of one file with another file
 .SH SYNOPSIS
 .nf
-.B #include <sys/ioctl.h>
+.RB "         /* Definition of " FIDEDUPERANGE " and " FILE_DEDUPE_* " constants */"
 .B #include <linux/fs.h>
+.B #include <sys/ioctl.h>
 .PP
 .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg );
 .fi
-- 
2.31.0

[PATCH v5 33/35] ioctl_fslabel.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2
index 9f5e0dbbd..af17256f0 100644
--- a/man2/ioctl_fslabel.2
+++ b/man2/ioctl_fslabel.2
@@ -36,7 +36,7 @@ If a filesystem supports online label manipulation, these
 .BR ioctl (2)
 operations can be used to get or set the filesystem label for the filesystem
 on which
-.B fd
+.I fd
 resides.
 The
 .B FS_IOC_SETFSLABEL
-- 
2.31.0

[PATCH v5 34/35] ioctl_fslabel.2: Make clear why exactly is each header needed

[Alejandro Colomar]

Only the include that provides the prototype doesn't need a comment.

Also sort the includes alphabetically.

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

diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2
index af17256f0..30435e1e9 100644
--- a/man2/ioctl_fslabel.2
+++ b/man2/ioctl_fslabel.2
@@ -25,8 +25,8 @@
 ioctl_fslabel \- get or set a filesystem label
 .SH SYNOPSIS
 .nf
+.BR "#include <linux/fs.h>" "       /* Definition of " *FSLABEL* " constants */"
 .B #include <sys/ioctl.h>
-.B #include <linux/fs.h>
 .PP
 .BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]);
 .BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]);
-- 
2.31.0

[PATCH v5 35/35] ioctl_getfsmap.2: Make clear why exactly is each header needed

[Alejandro Colomar]

<linux/fs.h> doesn't seem to be needed!
Only the include that provides the prototype doesn't need a comment.

Also sort the includes alphabetically.

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

diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2
index 4ff1c8a90..f87fb5c7a 100644
--- a/man2/ioctl_getfsmap.2
+++ b/man2/ioctl_getfsmap.2
@@ -25,9 +25,10 @@
 ioctl_getfsmap \- retrieve the physical layout of the filesystem
 .SH SYNOPSIS
 .nf
-.B #include <sys/ioctl.h>
-.B #include <linux/fs.h>
+.RB " /* Definition of " FS_IOC_GETFSMAP ", " FM?_OF_* ", and " *FMR_OWN_* \
+" constants */"
 .B #include <linux/fsmap.h>
+.B #include <sys/ioctl.h>
 .PP
 .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
 .fi
-- 
2.31.0

Re: [PATCH v5 01/35] system_data_types.7: Add 'struct sockaddr'

[Michael Kerrisk (man-pages)]

Hello Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man7/system_data_types.7 | 25 +++++++++++++++++++++++++
>  1 file changed, 25 insertions(+)

Patch applied!

Thanks,

Michael

> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 5648ae500..93c723a2f 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -1226,6 +1226,31 @@ and
>  .I ssize_t
>  types in this page.
>  .RE
> +.\"------------------------------------- sockaddr ---------------------/
> +.TP
> +.I sockaddr
> +.RS
> +.IR Include :
> +.IR <sys/socket.h> .
> +.PP
> +.EX
> +struct sockaddr {
> +    sa_family_t sa_family; /* Address family */
> +    char        sa_data[]; /* Socket address */
> +};
> +.EE
> +.PP
> +Describes a socket address.
> +.PP
> +.IR "Conforming to" :
> +POSIX.1-2001 and later.
> +.PP
> +.IR "See also" :
> +.BR accept (2),
> +.BR getpeername (2),
> +.BR getsockname (2),
> +.BR socket (2)
> +.RE
>  .\"------------------------------------- ssize_t ----------------------/
>  .TP
>  .I ssize_t
> 


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

Re: [PATCH v5 03/35] system_data_types.7: Add 'socklen_t'

[Michael Kerrisk (man-pages)]

Hello Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man7/system_data_types.7 | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)


Patch applied.

Thanks,

Michael


> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 93c723a2f..e038aab1e 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -1251,6 +1251,34 @@ POSIX.1-2001 and later.
>  .BR getsockname (2),
>  .BR socket (2)
>  .RE
> +.\"------------------------------------- socklen_t --------------------/
> +.TP
> +.I socklen_t
> +.RS
> +.IR Include :
> +.IR <sys/socket.h> .
> +Alternatively,
> +.IR <netdb.h> .
> +.PP
> +Describes the length of a socket address.
> +According to POSIX,
> +this shall be an integer type of at least 32 bits.
> +.PP
> +.IR "Conforming to" :
> +POSIX.1-2001 and later.
> +.PP
> +.IR "See also" :
> +.BR accept (2),
> +.BR bind (2),
> +.BR connect (2),
> +.BR gethostbyaddr (2),
> +.BR getnameinfo (2),
> +.BR socket (2)
> +.PP
> +See also the
> +.I sockaddr
> +structure in this page.
> +.RE
>  .\"------------------------------------- ssize_t ----------------------/
>  .TP
>  .I ssize_t
> 


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

Re: [PATCH v5 04/35] socklen_t.3: New link to system_data_types(7)

[Michael Kerrisk (man-pages)]

Hello Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man3/socklen_t.3 | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 man3/socklen_t.3


Patch applied.

Thanks,

Michael


> diff --git a/man3/socklen_t.3 b/man3/socklen_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/socklen_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


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

Re: [PATCH v5 20/35] futimesat.2: ffix

[Michael Kerrisk (man-pages)]

Hello ALex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>


Patch applied.

Thanks,

Michael


> ---
>  man2/futimesat.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man2/futimesat.2 b/man2/futimesat.2
> index 6ac9a9200..86e941fe5 100644
> --- a/man2/futimesat.2
> +++ b/man2/futimesat.2
> @@ -28,7 +28,7 @@ futimesat \- change timestamps of a file relative to a \
>  directory file descriptor
>  .SH SYNOPSIS
>  .nf
> -.B #include <fcntl.h>           /* Definition of AT_* constants */
> +.BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
>  .B #include <sys/time.h>
>  .PP
>  .BI "int futimesat(int " dirfd ", const char *" pathname ,
> 


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

Re: [PATCH v5 15/35] exit_group.2: Use 'noreturn' in prototypes

[Michael Kerrisk (man-pages)]

Hi ALex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> This function never returns to its caller.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>


Patch applied.

Thanks,

Michael


> ---
>  man2/exit_group.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man2/exit_group.2 b/man2/exit_group.2
> index d26ec8c70..4fd314262 100644
> --- a/man2/exit_group.2
> +++ b/man2/exit_group.2
> @@ -29,7 +29,7 @@ exit_group \- exit all threads in a process
>  .nf
>  .B #include <linux/unistd.h>
>  .PP
> -.BI "void exit_group(int " status );
> +.BI "noreturn void exit_group(int " status );
>  .fi
>  .SH DESCRIPTION
>  This system call is equivalent to
> 


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

Re: [PATCH v5 18/35] fcntl.2: Remove unused include

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> I couldn't find a reason for including <unistd.h>.  All the macros
> used by fcntl() are defined in <fcntl.h>.  For comparison, FreeBSD
> and OpenBSD don't specify <unistd.h> in their manual pages.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>


Patch applied.

Thanks,

Michael


> ---
>  man2/fcntl.2 | 1 -
>  1 file changed, 1 deletion(-)
> 
> diff --git a/man2/fcntl.2 b/man2/fcntl.2
> index de87eec1f..7b5604e3a 100644
> --- a/man2/fcntl.2
> +++ b/man2/fcntl.2
> @@ -69,7 +69,6 @@
>  fcntl \- manipulate file descriptor
>  .SH SYNOPSIS
>  .nf
> -.B #include <unistd.h>
>  .B #include <fcntl.h>
>  .PP
>  .BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );"
> 


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

Re: [PATCH v5 23/35] getrlimit.2, getrusage.2: Remove unused include

[Michael Kerrisk (man-pages)]

Hi ALex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> <sys/time.h> is not required by any of these function declaration
> or macro definition used by these functions.  It's maybe (or maybe
> not) needed by some tipe inside the rlimit structure, but that
> info belongs to system_data_types(7), not here.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>


Patch applied.

Thanks,

Michael


> ---
>  man2/getrlimit.2 | 1 -
>  man2/getrusage.2 | 9 ---------
>  2 files changed, 10 deletions(-)
> 
> diff --git a/man2/getrlimit.2 b/man2/getrlimit.2
> index 444c50525..648fd3c85 100644
> --- a/man2/getrlimit.2
> +++ b/man2/getrlimit.2
> @@ -66,7 +66,6 @@
>  getrlimit, setrlimit, prlimit \- get/set resource limits
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/time.h>
>  .B #include <sys/resource.h>
>  .PP
>  .BI "int getrlimit(int " resource ", struct rlimit *" rlim );
> diff --git a/man2/getrusage.2 b/man2/getrusage.2
> index d3c0de8a0..85c4ffed1 100644
> --- a/man2/getrusage.2
> +++ b/man2/getrusage.2
> @@ -41,7 +41,6 @@
>  getrusage \- get resource usage
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/time.h>
>  .B #include <sys/resource.h>
>  .PP
>  .BI "int getrusage(int " who ", struct rusage *" usage );
> @@ -230,14 +229,6 @@ is Linux-specific.
>  Resource usage metrics are preserved across an
>  .BR execve (2).
>  .PP
> -Including
> -.I <sys/time.h>
> -is not required these days, but increases portability.
> -(Indeed,
> -.I struct timeval
> -is defined in
> -.IR <sys/time.h> .)
> -.PP
>  In Linux kernel versions before 2.6.9, if the disposition of
>  .B SIGCHLD
>  is set to
> 


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

Re: [PATCH v5 12/35] delete_module.2: Add missing include

[Michael Kerrisk (man-pages)]

Hi ALex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/delete_module.2 | 2 ++
>  1 file changed, 2 insertions(+)


Patch applied.

Thanks,

Michael


> 
> diff --git a/man2/delete_module.2 b/man2/delete_module.2
> index bb0a812a6..174ef04d2 100644
> --- a/man2/delete_module.2
> +++ b/man2/delete_module.2
> @@ -27,6 +27,8 @@
>  delete_module \- unload a kernel module
>  .SH SYNOPSIS
>  .nf
> +.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
> +.PP
>  .BI "int delete_module(const char *" name ", unsigned int " flags );
>  .fi
>  .PP
> 


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

Re: [PATCH v5 22/35] getpriority.2: Remove unused include

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> <sys/time.h> is not needed to get the function declaration nor any
> constant used by the function.  It was only needed (before
> POSIX.1) to get 'struct timeval', but that information would be
> more suited for system_data_types(7), and not for this page.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied.

Thanks,

Michael


> ---
>  man2/getpriority.2 | 13 -------------
>  1 file changed, 13 deletions(-)
> 
> diff --git a/man2/getpriority.2 b/man2/getpriority.2
> index e3d518028..d6744989d 100644
> --- a/man2/getpriority.2
> +++ b/man2/getpriority.2
> @@ -47,7 +47,6 @@
>  getpriority, setpriority \- get/set program scheduling priority
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/time.h>
>  .B #include <sys/resource.h>
>  .PP
>  .BI "int getpriority(int " which ", id_t " who );
> @@ -209,18 +208,6 @@ the real or effective user ID of the process \fIwho\fP.
>  All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
>  4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
>  manner as Linux 2.6.12 and later.
> -.PP
> -Including
> -.I <sys/time.h>
> -is not required these days, but increases portability.
> -(Indeed,
> -.I <sys/resource.h>
> -defines the
> -.I rusage
> -structure with fields of type
> -.I struct timeval
> -defined in
> -.IR <sys/time.h> .)
>  .\"
>  .SS C library/kernel differences
>  Within the kernel, nice values are actually represented
> 


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

Re: [PATCH v5 17/35] fanotify_init.2: Add comment: why more than one include is needed

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/fanotify_init.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)


Patch applied.

Thanks,

Michael


> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index 2418bbdd2..2b44fc6ec 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -26,7 +26,7 @@
>  fanotify_init \- create and initialize fanotify group
>  .SH SYNOPSIS
>  .nf
> -.B #include <fcntl.h>
> +.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
>  .B #include <sys/fanotify.h>
>  .PP
>  .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
> 


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

Re: [PATCH v5 06/35] add_key.2: Remove unused include

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> <sys/types.h> was only needed for size_t, AFAIK.  That is already
> (and more precisely) documented in system_data_types(7).  Let's
> remove it here, as it's not really needed for calling add_key().
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied.

Thanks,

Michael

> ---
>  man2/add_key.2 | 1 -
>  1 file changed, 1 deletion(-)
> 
> diff --git a/man2/add_key.2 b/man2/add_key.2
> index f3d803adf..dca44b8e7 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -14,7 +14,6 @@
>  add_key \- add a key to the kernel's key management facility
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/types.h>
>  .B #include <keyutils.h>
>  .PP
>  .BI "key_serial_t add_key(const char *" type ", const char *" description ,
> 


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

Re: [PATCH v5 06/35] add_key.2: Remove unused include

[Michael Kerrisk (man-pages)]

Hello Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> <sys/types.h> was only needed for size_t, AFAIK.  That is already
> (and more precisely) documented in system_data_types(7).  Let's
> remove it here, as it's not really needed for calling add_key().
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks. Patch applied.

Cheers,

Michael

> ---
>  man2/add_key.2 | 1 -
>  1 file changed, 1 deletion(-)
> 
> diff --git a/man2/add_key.2 b/man2/add_key.2
> index f3d803adf..dca44b8e7 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -14,7 +14,6 @@
>  add_key \- add a key to the kernel's key management facility
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/types.h>
>  .B #include <keyutils.h>
>  .PP
>  .BI "key_serial_t add_key(const char *" type ", const char *" description ,
> 


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

Re: [PATCH v5 29/35] ioctl_fat.2: Make clear why is each header exactly needed.

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Only the one that provides the prototype doesn't need a comment.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/ioctl_fat.2 | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2
> index 30e410280..263738dad 100644
> --- a/man2/ioctl_fat.2
> +++ b/man2/ioctl_fat.2
> @@ -26,6 +26,7 @@
>  ioctl_fat \- manipulating the FAT filesystem
>  .SH SYNOPSIS
>  .nf
> +.RB "         /* Definition of [" V ] FAT_* " and " ATTR_* " constants */"
>  .B #include <linux/msdos_fs.h>
>  .B #include <sys/ioctl.h>
>  .PP

Patch applied. But, I reformatted in a manner more
typical of what I normally write. See my follow-on commit.

Thanks,

Michael




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

Re: [PATCH v5 30/35] ioctl_fat.2: ffix

[Michael Kerrisk (man-pages)]

Hi Alex,

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


Patch applied, but "ffix" ==> "tfix".

Thanks,

Michael


> 
> diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2
> index 263738dad..8914505c7 100644
> --- a/man2/ioctl_fat.2
> +++ b/man2/ioctl_fat.2
> @@ -34,9 +34,9 @@ ioctl_fat \- manipulating the FAT filesystem
>  .BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr );
>  .BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id );
>  .BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH,"
> -.BI "          struct __fat_dirent[2] " entry );
> +.BI "          struct __fat_dirent " entry [2]);
>  .BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT,"
> -.BI "          struct __fat_dirent[2] " entry );
> +.BI "          struct __fat_dirent " entry [2]);
>  .fi
>  .SH DESCRIPTION
>  The
> 


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

Re: [PATCH v5 34/35] ioctl_fslabel.2: Make clear why exactly is each header needed

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Only the include that provides the prototype doesn't need a comment.
> 
> Also sort the includes alphabetically.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>


Patch applied.

Thanks,

Michael


> ---
>  man2/ioctl_fslabel.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2
> index af17256f0..30435e1e9 100644
> --- a/man2/ioctl_fslabel.2
> +++ b/man2/ioctl_fslabel.2
> @@ -25,8 +25,8 @@
>  ioctl_fslabel \- get or set a filesystem label
>  .SH SYNOPSIS
>  .nf
> +.BR "#include <linux/fs.h>" "       /* Definition of " *FSLABEL* " constants */"
>  .B #include <sys/ioctl.h>
> -.B #include <linux/fs.h>
>  .PP
>  .BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]);
>  .BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]);
> 


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

Re: [PATCH v5 35/35] ioctl_getfsmap.2: Make clear why exactly is each header needed

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> <linux/fs.h> doesn't seem to be needed!
> Only the include that provides the prototype doesn't need a comment.
> 
> Also sort the includes alphabetically.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied. Again, I did of editing afterward.

Thanks,

Michael


> ---
>  man2/ioctl_getfsmap.2 | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2
> index 4ff1c8a90..f87fb5c7a 100644
> --- a/man2/ioctl_getfsmap.2
> +++ b/man2/ioctl_getfsmap.2
> @@ -25,9 +25,10 @@
>  ioctl_getfsmap \- retrieve the physical layout of the filesystem
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/ioctl.h>
> -.B #include <linux/fs.h>
> +.RB " /* Definition of " FS_IOC_GETFSMAP ", " FM?_OF_* ", and " *FMR_OWN_* \
> +" constants */"
>  .B #include <linux/fsmap.h>
> +.B #include <sys/ioctl.h>
>  .PP
>  .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
>  .fi
> 


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

Re: [PATCH v5 33/35] ioctl_fslabel.2: ffix

[Michael Kerrisk (man-pages)]

Hi ALex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/ioctl_fslabel.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)


Patch applied.

Thanks,

Michael


> diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2
> index 9f5e0dbbd..af17256f0 100644
> --- a/man2/ioctl_fslabel.2
> +++ b/man2/ioctl_fslabel.2
> @@ -36,7 +36,7 @@ If a filesystem supports online label manipulation, these
>  .BR ioctl (2)
>  operations can be used to get or set the filesystem label for the filesystem
>  on which
> -.B fd
> +.I fd
>  resides.
>  The
>  .B FS_IOC_SETFSLABEL
> 


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

Re: [PATCH v5 31/35] ioctl_ficlonerange.2: Make clear why is each header exactly needed.

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Only the one that provides the prototype doesn't need a comment.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied.

Thanks,

Michael


> ---
>  man2/ioctl_ficlonerange.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2
> index 34c171941..75ab14bc4 100644
> --- a/man2/ioctl_ficlonerange.2
> +++ b/man2/ioctl_ficlonerange.2
> @@ -25,8 +25,8 @@
>  ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file
>  .SH SYNOPSIS
>  .nf
> +.BR "#include <linux/fs.h>" "        /* Definition of " FICLONE* " constants */"
>  .B #include <sys/ioctl.h>
> -.B #include <linux/fs.h>
>  .PP
>  .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
>  .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
> 


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

Re: [PATCH v5 32/35] ioctl_fideduperange.2: Make clear why exactly is each header needed

[Michael Kerrisk (man-pages)]

Hi ALex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Only the include that provides the prototype doesn't need a comment.
> 
> Also sort the includes alphabetically.

Patch applied. Again, some minor edits afterward.

Thanks,

Michael


> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/ioctl_fideduperange.2 | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2
> index 1df0628d0..82c7fdc28 100644
> --- a/man2/ioctl_fideduperange.2
> +++ b/man2/ioctl_fideduperange.2
> @@ -25,8 +25,9 @@
>  ioctl_fideduperange \- share some the data of one file with another file
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/ioctl.h>
> +.RB "         /* Definition of " FIDEDUPERANGE " and " FILE_DEDUPE_* " constants */"
>  .B #include <linux/fs.h>
> +.B #include <sys/ioctl.h>
>  .PP
>  .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg );
>  .fi
> 


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

Re: [PATCH v5 05/35] access.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

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

Patch applied.

Thanks,

Michael


> diff --git a/man2/access.2 b/man2/access.2
> index 4a6e28db3..f24a73161 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>" "      /* Definition of " 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
> 


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

Re: [PATCH v5 07/35] alloc_hugepages.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi ALex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> The page didn't specify includes, and the syscalls are extint, so
> instead of adding incomplete information about includes, just
> leave it without any includes.


Patch applied.

Thanks,

Michael


> 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 07193c542..cc76fc495 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
> 


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

Re: [PATCH v5 08/35] arch_prctl.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

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


Patch applied.

Thanks,

Michael


> diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
> index 1ddeca595..f8073d625 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
> 


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

Re: [PATCH v5 09/35] arch_prctl.2: SYNOPSIS: Remove unused includes

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> AFAICS, there's no reason to include that.
> All of the macros that this function uses
> are already defined in the other headers.

I suspect it was a case of cut-and-paste (from prctl.2) long ago 
when the page was written. Patch applied.

Thanks,

Michael


> 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 f8073d625..7ae5b350c 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
> 


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

Re: [PATCH v5 10/35] capget.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/capget.2 | 20 ++++++++++----------
>  1 file changed, 10 insertions(+), 10 deletions(-)

Patch applied. Again, some minor follow-up edits.

Thanks,

Michael



> diff --git a/man2/capget.2 b/man2/capget.2
> index 6de51b72c..a2d897cc7 100644
> --- a/man2/capget.2
> +++ b/man2/capget.2
> @@ -18,14 +18,17 @@
>  capget, capset \- set/get capabilities of thread(s)
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/capability.h>
> +.RB "         /* Definition of " CAP_* " and " \
> +_LINUX_CAPABILITY_* " constants */"
> +.B #include <linux/capability.h>
> +.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 +43,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 +242,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
> 


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

Re: [PATCH v5 11/35] clone.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> The CLONE_* constants seem to be available from either
> <linux/sched.h> or <sched.h>, and since clone3() already
> includes <linux/sched.h> for 'struct clone_args', <sched.h>
> is not really needed, AFAICS; however, to avoid confussion,
> I also included <sched.h> for clone3() for consistency:

I think that's a good decision.

> clone() is getting CLONE_* from <sched.h>, and it would confuse
> the reader if clone3() got the same CLONE_* constants from a
> different header.

Agreed.

Patch applied.

Thanks,

Michael


> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/clone.2 | 17 ++++++-----------
>  1 file changed, 6 insertions(+), 11 deletions(-)
> 
> diff --git a/man2/clone.2 b/man2/clone.2
> index fa7d1103e..f455c97d8 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -56,13 +56,13 @@ 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 <sched.h>" "          /* Definition of " CLONE_* " constants */"
> +.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 +1541,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
> 


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

Re: [PATCH v5 13/35] dup.2: SYNOPSIS: Use consistent comments through pages

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/dup.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Patch applied.

Thanks,

Michael


> diff --git a/man2/dup.2 b/man2/dup.2
> index 725b9d7d5..b9e0828b0 100644
> --- a/man2/dup.2
> +++ b/man2/dup.2
> @@ -45,7 +45,7 @@ dup, dup2, dup3 \- duplicate a file descriptor
>  .BI "int dup2(int " oldfd ", int " newfd );
>  .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 dup3(int " oldfd ", int " newfd ", int " flags );
> 


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

Re: [PATCH v5 14/35] execveat.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Add <linux/fcntl.h>, which contains AT_* definitions used by
> execveat().
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied.

Thanks,

Michael


> ---
>  man2/execveat.2 | 14 +++++---------
>  1 file changed, 5 insertions(+), 9 deletions(-)
> 
> diff --git a/man2/execveat.2 b/man2/execveat.2
> index 855832765..c566f53df 100644
> --- a/man2/execveat.2
> +++ b/man2/execveat.2
> @@ -28,15 +28,14 @@
>  execveat \- execute program relative to a directory file descriptor
>  .SH SYNOPSIS
>  .nf
> +.BR "#include <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
> +.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 +208,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
> 


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

Re: [PATCH v5 16/35] exit_group.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> <linux/unistd.h> is not needed.  We need <unistd.h> for syscall(),
> and <sys/syscall.h> for SYS_exit_group.
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Patch applied.

Thanks,

Michael


> ---
>  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 4fd314262..b512927d4 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 "noreturn void exit_group(int " status );
> +.BI "noreturn void syscall(SYS_exit_group, int " status );
>  .fi
>  .SH DESCRIPTION
>  This system call is equivalent to
> 


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

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

[Michael Kerrisk (man-pages)]

Hi Alex,

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

Patch applied.

Thanks,

Michael


> diff --git a/man2/getdents.2 b/man2/getdents.2
> index ec00a73ba..6a9f4e04c 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
> 


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

Re: [PATCH v5 24/35] getunwind.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

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


Patch applied.

Thanks,

Michael


> diff --git a/man2/getunwind.2 b/man2/getunwind.2
> index 45535dccf..2c44506c7 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)
> 


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

Re: [PATCH v5 25/35] get_robust_list.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi ALex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/get_robust_list.2 | 19 ++++++++-----------
>  1 file changed, 8 insertions(+), 11 deletions(-)

Patch applied.

Thanks,

Michael


> diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2
> index dd43cded2..b1368ddd3 100644
> --- a/man2/get_robust_list.2
> +++ b/man2/get_robust_list.2
> @@ -32,16 +32,16 @@
>  get_robust_list, set_robust_list \- get/set list of robust futexes
>  .SH SYNOPSIS
>  .nf
> -.B #include <linux/futex.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:
> @@ -138,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
> 


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

Re: [PATCH v5 26/35] delete_module.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi ALex,

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

Patch applied.

Thanks,

Michael


> diff --git a/man2/delete_module.2 b/man2/delete_module.2
> index 174ef04d2..21c9e9d8d 100644
> --- a/man2/delete_module.2
> +++ b/man2/delete_module.2
> @@ -28,12 +28,11 @@ delete_module \- unload a kernel module
>  .SH SYNOPSIS
>  .nf
>  .BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
> +.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
> +.BR "#include <unistd.h>
>  .PP
> -.BI "int delete_module(const char *" name ", unsigned int " flags );
> +.BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags );
>  .fi
> -.PP
> -.IR Note :
> -There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
>  The
>  .BR delete_module ()
> 


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

Re: [PATCH v5 27/35] init_module.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/init_module.2 | 20 ++++++++------------
>  1 file changed, 8 insertions(+), 12 deletions(-)


Patch applied.

Thanks,

Michael


> diff --git a/man2/init_module.2 b/man2/init_module.2
> index e158ce9fa..13d1b7f0a 100644
> --- a/man2/init_module.2
> +++ b/man2/init_module.2
> @@ -29,14 +29,15 @@
>  init_module, finit_module \- load a kernel module
>  .SH SYNOPSIS
>  .nf
> -.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 );
> -.fi
> +.BR "#include <linux/module.h>" "    /* Definition of " MODULE_* " 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_init_module, void *" module_image ", unsigned long " len ,
> +.BI "            const char *" param_values );
> +.BI "int syscall(SYS_finit_module, int " fd ", const char *" param_values ,
> +.BI "            int " flags );
> +.fi
>  .SH DESCRIPTION
>  .BR init_module ()
>  loads an ELF image into kernel space,
> @@ -268,11 +269,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
> 


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

Re: [PATCH v5 28/35] io_cancel.2: Use syscall(SYS_...); for system calls without a wrapper

[Michael Kerrisk (man-pages)]

Hi  Alex.

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> In this case there's a wrapper provided by libaio,
> but this page documents the raw kernel syscall.

Okay.

Patch applied.

Thanks,

Michael


> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/io_cancel.2 | 16 ++++++----------
>  1 file changed, 6 insertions(+), 10 deletions(-)
> 
> diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
> index e09984ecd..248fe5791 100644
> --- a/man2/io_cancel.2
> +++ b/man2/io_cancel.2
> @@ -9,14 +9,13 @@
>  io_cancel \- cancel an outstanding asynchronous I/O operation
>  .SH SYNOPSIS
>  .nf
> -.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
> +.BR "#include <linux/aio_abi.h>" "    /* Definition of needed types */"
> +.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
> +.B #include <unistd.h>
>  .PP
> -.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
> -.BI "              struct io_event *" result );
> +.BI "int syscall(SYS_io_cancel, aio_context_t " ctx_id ", struct iocb *" iocb ,
> +.BI "            struct io_event *" result );
>  .fi
> -.PP
> -.IR Note :
> -There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
>  .IR Note :
>  this page describes the raw Linux system call interface.
> @@ -68,10 +67,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_cancel ()
>  wrapper function provided by
>  .\" http://git.fedorahosted.org/git/?p=libaio.git
> 


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

Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Michael Kerrisk (man-pages)]

Hi Alex,

On 4/4/21 1:58 PM, Alejandro Colomar wrote:
> 
> v5:
> 	- ffix 29/35, 32/35, and 35/35.  The rest are identical to v4.
> 
> 
> Alejandro Colomar (35):
>   system_data_types.7: Add 'struct sockaddr'
>   sockaddr.3: New link to system_data_types(7)
>   system_data_types.7: Add 'socklen_t'
>   socklen_t.3: New link to system_data_types(7)
>   access.2: Use syscall(SYS_...); for system calls without a wrapper
>   add_key.2: Remove unused include
>   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: Add missing include
>   dup.2: SYNOPSIS: Use consistent comments through pages
>   execveat.2: Use syscall(SYS_...); for system calls without a wrapper
>   exit_group.2: Use 'noreturn' in prototypes
>   exit_group.2: Use syscall(SYS_...); for system calls without a wrapper
>   fanotify_init.2: Add comment: why more than one include is needed
>   fcntl.2: Remove unused include
>   futex.2: Use syscall(SYS_...); for system calls without a wrapper
>   futimesat.2: ffix
>   getdents.2: Use syscall(SYS_...); for system calls without a wrapper
>   getpriority.2: Remove unused include
>   getrlimit.2, getrusage.2: Remove unused include
>   getunwind.2: Use syscall(SYS_...); for system calls without a wrapper
>   get_robust_list.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   delete_module.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   init_module.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   io_cancel.2: Use syscall(SYS_...); for system calls without a wrapper
>   ioctl_fat.2: Make clear why is each header exactly needed.
>   ioctl_fat.2: ffix
>   ioctl_ficlonerange.2: Make clear why is each header exactly needed.
>   ioctl_fideduperange.2: Make clear why exactly is each header needed
>   ioctl_fslabel.2: ffix
>   ioctl_fslabel.2: Make clear why exactly is each header needed
>   ioctl_getfsmap.2: Make clear why exactly is each header needed
So, I think I'm okay with the syscall() changes in the SYNOPSIS.
It might just take me a moment to get used to them. However, I do
wonder if it is worth retaining a comment in the SYSNOPSIS, 
something like:

   SYNOPSIS
       #include <asm/prctl.h>        /* Definition of ARCH_* constants */
       #include <sys/syscall.h>      /* Definition of SYS_* constants */
       #include <unistd.h>

       int syscall(SYS_arch_prctl, int code, unsigned long addr);
       int syscall(SYS_arch_prctl, int code, unsigned long *addr);

       Note: glibc provides no wrapper for arch_prctl(), necessitating
       the use of syscall(2).

Without something like this, the reader may be puzzled at the use of
syscall().

What do you think?

Thanks,

Michael

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

Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Alejandro Colomar (man-pages)]

Hi Michael,

On 4/5/21 1:49 PM, Michael Kerrisk (man-pages) wrote:
> So, I think I'm okay with the syscall() changes in the SYNOPSIS.
> It might just take me a moment to get used to them. However, I do
> wonder if it is worth retaining a comment in the SYSNOPSIS,
> something like:
> 
>     SYNOPSIS
>         #include <asm/prctl.h>        /* Definition of ARCH_* constants */
>         #include <sys/syscall.h>      /* Definition of SYS_* constants */
>         #include <unistd.h>
> 
>         int syscall(SYS_arch_prctl, int code, unsigned long addr);
>         int syscall(SYS_arch_prctl, int code, unsigned long *addr);
> 
>         Note: glibc provides no wrapper for arch_prctl(), necessitating
>         the use of syscall(2).
> 
> Without something like this, the reader may be puzzled at the use of
> syscall().
> 
> What do you think?

Yes.  I had doubts, and you confirmed them.  I'll add that.

Thanks,

Alex

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

Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Alejandro Colomar (man-pages)]

On 4/11/21 9:23 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> On 4/5/21 1:49 PM, Michael Kerrisk (man-pages) wrote:
>> So, I think I'm okay with the syscall() changes in the SYNOPSIS.
>> It might just take me a moment to get used to them. However, I do
>> wonder if it is worth retaining a comment in the SYSNOPSIS,
>> something like:
>>
>>     SYNOPSIS
>>         #include <asm/prctl.h>        /* Definition of ARCH_* 
>> constants */
>>         #include <sys/syscall.h>      /* Definition of SYS_* constants */
>>         #include <unistd.h>
>>
>>         int syscall(SYS_arch_prctl, int code, unsigned long addr);
>>         int syscall(SYS_arch_prctl, int code, unsigned long *addr);
>>
>>         Note: glibc provides no wrapper for arch_prctl(), necessitating
>>         the use of syscall(2).

I'm not sure what text to write in cases such as faccessat2(2).  Could 
you have a look at that?

There's actually a wrapper, but it's faccessat(2).

>>
>> Without something like this, the reader may be puzzled at the use of
>> syscall().
>>
>> What do you think?
> 
> Yes.  I had doubts, and you confirmed them.  I'll add that.
> 

Thanks,

Alex

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

Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Florian Weimer]

* Michael Kerrisk via Libc-alpha:

> So, I think I'm okay with the syscall() changes in the SYNOPSIS.
> It might just take me a moment to get used to them. However, I do
> wonder if it is worth retaining a comment in the SYSNOPSIS, 
> something like:
>
>    SYNOPSIS
>        #include <asm/prctl.h>        /* Definition of ARCH_* constants */
>        #include <sys/syscall.h>      /* Definition of SYS_* constants */
>        #include <unistd.h>
>
>        int syscall(SYS_arch_prctl, int code, unsigned long addr);
>        int syscall(SYS_arch_prctl, int code, unsigned long *addr);
>
>        Note: glibc provides no wrapper for arch_prctl(), necessitating
>        the use of syscall(2).
>
> Without something like this, the reader may be puzzled at the use of
> syscall().
>
> What do you think?

Would it be possible to use real C syntax?

  int code;
  unsigned long addr;
  int result;
  result = syscall (SYS_arch_prctl, code, addr);
  result = syscall (SYS_arch_prctl, code, &addr);

Or perhaps omit the result variable:

  int code;
  unsigned long addr;
  syscall (SYS_arch_prctl, code, addr);

Thanks,
Florian

Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Jakub Wilk]

* Florian Weimer <fweimer@redhat.com>, 2021-04-12, 08:17:
>>    SYNOPSIS
>>        #include <asm/prctl.h>        /* Definition of ARCH_* constants */
>>        #include <sys/syscall.h>      /* Definition of SYS_* constants */
>>        #include <unistd.h>
>>
>>        int syscall(SYS_arch_prctl, int code, unsigned long addr);
>>        int syscall(SYS_arch_prctl, int code, unsigned long *addr);
>>
>>        Note: glibc provides no wrapper for arch_prctl(), necessitating
>>        the use of syscall(2).
>>
>> Without something like this, the reader may be puzzled at the use of
>> syscall().
>>
>> What do you think?
>
>Would it be possible to use real C syntax?

Seconded.

>  int code;
>  unsigned long addr;
>  int result;
>  result = syscall (SYS_arch_prctl, code, addr);
>  result = syscall (SYS_arch_prctl, code, &addr);
>
>Or perhaps omit the result variable:
>
>  int code;
>  unsigned long addr;
>  syscall (SYS_arch_prctl, code, addr);

Or, more succinctly, put the types in comments:

   syscall(SYS_arch_prctl, /* int */ code, /* unsigned long */ addr);

-- 
Jakub Wilk

Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Alejandro Colomar (man-pages)]

Hi Florian,

On 4/12/21 8:17 AM, Florian Weimer wrote:
> * Michael Kerrisk via Libc-alpha:
> 
>> So, I think I'm okay with the syscall() changes in the SYNOPSIS.
>> It might just take me a moment to get used to them. However, I do
>> wonder if it is worth retaining a comment in the SYSNOPSIS,
>> something like:
>>
>>     SYNOPSIS
>>         #include <asm/prctl.h>        /* Definition of ARCH_* constants */
>>         #include <sys/syscall.h>      /* Definition of SYS_* constants */
>>         #include <unistd.h>
>>
>>         int syscall(SYS_arch_prctl, int code, unsigned long addr);
>>         int syscall(SYS_arch_prctl, int code, unsigned long *addr);
>>
>>         Note: glibc provides no wrapper for arch_prctl(), necessitating
>>         the use of syscall(2).
>>
>> Without something like this, the reader may be puzzled at the use of
>> syscall().
>>
>> What do you think?
> 
> Would it be possible to use real C syntax?
> 
>    int code;
>    unsigned long addr;
>    int result;
>    result = syscall (SYS_arch_prctl, code, addr);
>    result = syscall (SYS_arch_prctl, code, &addr);

I think that adds too many lines, and doesn't add much value.  Yes, it 
provides pure C syntax, which might be a bit easier to understand, but 
is it worth it?

I followed the syntax already used by some manual pages such as the 
ioctl_*(2) pages (see ioctl_fat(2) for example), although I must admit 
it was a bit rare the first time I saw it; but I think it's a good 
compromise between being short and providing information.

I think the EXAMPLES section can better clarify how to use the function 
if there're any doubts.

> 
> Or perhaps omit the result variable:
> 
>    int code;
>    unsigned long addr;
>    syscall (SYS_arch_prctl, code, addr);

That wouldn't provide the reader with the info about which type should 
he expect as return; the most important part being the signedness of the 
type.

On 4/12/21 8:39 AM, Jakub Wilk wrote:
 >>
 >
 > Or, more succinctly, put the types in comments:
 >
 >    syscall(SYS_arch_prctl, /* int */ code, /* unsigned long */ addr);

I'm not sure.  I see the point in doing this, but I think I prefer my 
version, because it has less noise.  But I might be a bit biased :)


Thanks,

Alex

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

Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Florian Weimer]

* Alejandro Colomar:

>> Or, more succinctly, put the types in comments:
>>
>>    syscall(SYS_arch_prctl, /* int */ code, /* unsigned long */ addr);
>
> I'm not sure.  I see the point in doing this, but I think I prefer my
> version, because it has less noise.  But I might be a bit biased :)

Not everyone is deeply familiar with C syntax.  Anyone who uses the
example literally will be disappointed.

Thanks,
Florian

Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Alejandro Colomar (man-pages)]

Hi Florian,

On 4/21/21 7:41 AM, Florian Weimer wrote:
> * Alejandro Colomar:
> 
>>> Or, more succinctly, put the types in comments:
>>>
>>>     syscall(SYS_arch_prctl, /* int */ code, /* unsigned long */ addr);
>>
>> I'm not sure.  I see the point in doing this, but I think I prefer my
>> version, because it has less noise.  But I might be a bit biased :)
> 
> Not everyone is deeply familiar with C syntax.  Anyone who uses the
> example literally will be disappointed.

I've been thinking about this for some days.  Although this syntax has 
become very familiar to me with time, I agree that the first times I saw 
it, it looked somewhat weird.  Each of the three variants (yours, 
Jakub's, and mine (which is actually not mine, but one already present 
in some pages)) has some good advantages and some disadvantages.

But the manual pages have been using the syntax I proposed, for those 
cases where a constant is to be used always, so in doubt, as I'm right 
now, I'll opt for that one.

Also, those system calls without a wrapper are probably rare enough so 
that people that need them probably know enough of C to understand the 
syntax.  I, for example, first had to use one of those, membarrier(2), 
after around 7 years of C programming.  I remember being surprised by 
not having the prototype and having to declare it myself (the SYNOPSIS 
was a bit buggy by that time).  But by completely reading the page and 
especially the EXAMPLES section, I think one can learn how to use it. 
Reading syscall(2) also helps.

I'll keep my proposed syntax.

Nevertheless, thanks for suggesting alternatives, and giving your 
reasons.  I'll keep thinking about it and see if I come with something 
better.

Thanks,

Alex

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