[PATCH 00/28] SYNPOSIS: Use syscall() and fix includes

[PATCH 00/28] SYNPOSIS: Use syscall() and fix includes

[Alejandro Colomar]

Hi Michael,

This is the last batch.  It includes the changes to seccomp.2, as you can see.
Actually, they are a resend of the last ones.  I found out that all of the
versions I sent you are identical...

Cheers,

Alex


Alejandro Colomar (28):
  seccomp.2: Document why each header is needed
  seccomp.2: Use syscall(SYS_...); for system calls without a wrapper
  spu_create.2: Remove <sys/types.h>
  spu_create.2: Use syscall(SYS_...), for system calls without a wrapper
  pipe.2: SYNOPSIS: Fix incorrect prototype
  spu_run.2: Use syscall(SYS_...), for system calls without a wrapper
  stat.2: SYNOPSIS: Fix includes
  statx.2: SYNOPSIS: Fix includes
  subpage_prot.2: Use syscall(SYS_...); for system calls without a
    wrapper
  swapon.2: SYNOPSIS: Fix includes
  symlink.2: ffix
  syscall.2: wfix + ffix
  syslog.2: Use syscall(SYS_...); for raw system calls
  timer_create.2: SYNOPSIS: Document why more than one header is needed
  s390_guarded_storage.2: tfix
  s390_runtime_instr.2: tfix
  s390_sthyi.2: tfix
  tkill.2: Use syscall(SYS_...); for system calls without a wrapper; fix
    includes too
  truncate.2: Remove <sys/types.h>
  umask.2: Remove <sys/types.h>
  unlink.2: ffix
  userfaultfd.2: Remove unused includes
  userfaultfd.2: Use syscall(SYS_...); for system calls without a
    wrapper; fix includes too
  utime.2: SYNOPSIS: Fix includes
  utimensat.2: ffix
  vmsplice.2: Remove unneeded include
  wait.2: Remove <sys/types.h>
  wait4.2: SYNOPSIS: Remove includes

 man2/pipe.2                 |  2 +-
 man2/s390_guarded_storage.2 |  2 +-
 man2/s390_runtime_instr.2   |  2 +-
 man2/s390_sthyi.2           |  2 +-
 man2/seccomp.2              | 24 +++++++++++++-----------
 man2/spu_create.2           | 19 ++++++++++---------
 man2/spu_run.2              | 12 +++++++-----
 man2/stat.2                 |  3 +--
 man2/statx.2                |  3 +--
 man2/subpage_prot.2         | 15 +++++++++------
 man2/swapon.2               |  1 -
 man2/symlink.2              |  2 +-
 man2/syscall.2              |  2 +-
 man2/syslog.2               |  8 ++++++--
 man2/timer_create.2         |  2 +-
 man2/tkill.2                | 22 +++++++++++++---------
 man2/truncate.2             |  1 -
 man2/umask.2                |  1 -
 man2/unlink.2               |  2 +-
 man2/userfaultfd.2          | 15 ++++++++-------
 man2/utime.2                |  1 -
 man2/utimensat.2            |  2 +-
 man2/vmsplice.2             |  1 -
 man2/wait.2                 |  1 -
 man2/wait4.2                |  3 ---
 25 files changed, 77 insertions(+), 71 deletions(-)

-- 
2.32.0

[PATCH 01/28] seccomp.2: Document why each header is needed

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: Kees Cook <keescook@chromium.org>
Cc: Tyler Hicks <tyhicks@canonical.com>
Cc: Will Drewry <wad@chromium.org>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man2/seccomp.2 | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/man2/seccomp.2 b/man2/seccomp.2
index 35eb1dd1f..53f473a78 100644
--- a/man2/seccomp.2
+++ b/man2/seccomp.2
@@ -31,11 +31,11 @@
 seccomp \- operate on Secure Computing state of the process
 .SH SYNOPSIS
 .nf
-.B #include <linux/seccomp.h>
-.B #include <linux/filter.h>
-.B #include <linux/audit.h>
-.B #include <linux/signal.h>
-.B #include <sys/ptrace.h>
+.BR "#include <linux/seccomp.h>" "  /* Definition of " SECCOMP_* " constants */"
+.BR "#include <linux/filter.h>" "   /* Definition of " "struct sock_fprog" " */"
+.BR "#include <linux/audit.h>" "    /* Definition of " AUDIT_* " constants */"
+.BR "#include <linux/signal.h>" "   /* Definition of " SIG* " constants */"
+.BR "#include <sys/ptrace.h>" "     /* Definition of " PTRACE_* " constants */"
 .\" Kees Cook noted: Anything that uses SECCOMP_RET_TRACE returns will
 .\"                  need <sys/ptrace.h>
 .PP
-- 
2.32.0

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

[Alejandro Colomar]

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

diff --git a/man2/seccomp.2 b/man2/seccomp.2
index 53f473a78..a3421871f 100644
--- a/man2/seccomp.2
+++ b/man2/seccomp.2
@@ -38,13 +38,18 @@ seccomp \- operate on Secure Computing state of the process
 .BR "#include <sys/ptrace.h>" "     /* Definition of " PTRACE_* " constants */"
 .\" Kees Cook noted: Anything that uses SECCOMP_RET_TRACE returns will
 .\"                  need <sys/ptrace.h>
+.BR "#include <sys/syscall.h>" "    /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int seccomp(unsigned int " operation ", unsigned int " flags \
-", void *" args );
+.BI "int syscall(SYS_seccomp, unsigned int " operation ", unsigned int " flags ,
+.BI "            void *" args );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR seccomp (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR seccomp ()
@@ -930,9 +935,6 @@ Tile (since Linux 4.3)
 PA-RISC (since Linux 4.6)
 .\" User mode Linux since Linux 4.6
 .PD
-.PP
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
 .\"
 .SS Caveats
 There are various subtleties to consider when applying seccomp filters
-- 
2.32.0

[PATCH 03/28] spu_create.2: Remove <sys/types.h>

[Alejandro Colomar]

It's only needed for getting 'mode_t'.
But that type is better documented in system_data_types(7).

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

diff --git a/man2/spu_create.2 b/man2/spu_create.2
index d192eb025..6541a6e9a 100644
--- a/man2/spu_create.2
+++ b/man2/spu_create.2
@@ -27,7 +27,6 @@
 spu_create \- create a new spu context
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
 .B #include <sys/spu.h>
 .PP
 .BI "int spu_create(const char *" pathname ", unsigned int " flags \
-- 
2.32.0

[PATCH 04/28] spu_create.2: Use syscall(SYS_...), for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/spu_create.2 b/man2/spu_create.2
index 6541a6e9a..746a86ed6 100644
--- a/man2/spu_create.2
+++ b/man2/spu_create.2
@@ -27,15 +27,20 @@
 spu_create \- create a new spu context
 .SH SYNOPSIS
 .nf
-.B #include <sys/spu.h>
+.BR "#include <sys/spu.h>" "          /* Definition of " SPU_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int spu_create(const char *" pathname ", unsigned int " flags \
-", mode_t " mode ,
-.BI "               int " neighbor_fd ");"
+.BI "int syscall(SYS_spu_create, const char *" pathname \
+", unsigned int " flags ,
+.BI "            mode_t " mode ", int " neighbor_fd );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR spu_create (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR spu_create ()
@@ -259,9 +264,6 @@ This call is Linux-specific and implemented only on the PowerPC
 architecture.
 Programs using this system call are not portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-Note however, that
 .BR spu_create ()
 is meant to be used from libraries that implement a more abstract
 interface to SPUs, not to be used from regular applications.
-- 
2.32.0

[PATCH 05/28] pipe.2: SYNOPSIS: Fix incorrect prototype

[Alejandro Colomar]

A function declarator with empty parentheses, which is not a
prototype, is an obsolescent feature of C (See C17 6.11.6.1), and
doesn't mean 0 parameters, but instead that no information about
the parameters is provided (See C17 6.5.2.2).

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

diff --git a/man2/pipe.2 b/man2/pipe.2
index 93fbd36f2..41a482f37 100644
--- a/man2/pipe.2
+++ b/man2/pipe.2
@@ -56,7 +56,7 @@ pipe, pipe2 \- create pipe
 .B struct fd_pair {
 .B "    long fd[2];"
 .B "};"
-.B struct fd_pair pipe();
+.B struct fd_pair pipe(void);
 .fi
 .SH DESCRIPTION
 .BR pipe ()
-- 
2.32.0

[PATCH 06/28] spu_run.2: Use syscall(SYS_...), for system calls without a wrapper

[Alejandro Colomar]

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

diff --git a/man2/spu_run.2 b/man2/spu_run.2
index def974772..d5fdc2280 100644
--- a/man2/spu_run.2
+++ b/man2/spu_run.2
@@ -28,13 +28,18 @@
 spu_run \- execute an SPU context
 .SH SYNOPSIS
 .nf
-.B #include <sys/spu.h>
+.BR "#include <sys/spu.h>" "          /* Definition of " SPU_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
 .BI "int spu_run(int " fd ", uint32_t *" npc ", uint32_t *" event );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR spu_run (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR spu_run ()
@@ -195,9 +200,6 @@ This call is Linux-specific and implemented only by the PowerPC
 architecture.
 Programs using this system call are not portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-Note however, that
 .BR spu_run ()
 is meant to be used from libraries that implement a more abstract
 interface to SPUs, not to be used from regular applications.
-- 
2.32.0

[PATCH 07/28] stat.2: SYNOPSIS: Fix includes

[Alejandro Colomar]

Remove <sys/types.h>; ffix too

<sys/types.h> is only needed for 'struct stat'.
That is better documented in system_data_types(7).

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

diff --git a/man2/stat.2 b/man2/stat.2
index d356ce15a..339920d71 100644
--- a/man2/stat.2
+++ b/man2/stat.2
@@ -41,7 +41,6 @@
 stat, fstat, lstat, fstatat \- get file status
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
 .B #include <sys/stat.h>
 .PP
 .BI "int stat(const char *restrict " pathname ,
@@ -50,7 +49,7 @@ stat, fstat, lstat, fstatat \- get file status
 .BI "int lstat(const char *restrict " pathname ,
 .BI "         struct stat *restrict " statbuf );
 .PP
-.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
 .B #include <sys/stat.h>
 .PP
 .BI "int fstatat(int " dirfd ", const char *restrict " pathname ,
-- 
2.32.0

[PATCH 08/28] statx.2: SYNOPSIS: Fix includes

[Alejandro Colomar]

<unistd.h> doesn't seem to be needed:
  AT_* constants come from <fcntl.h>
  STATX_* constants come from <sys/stat.h>
  'struct statx' comes from <sys/stat.h>

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

diff --git a/man2/statx.2 b/man2/statx.2
index a14880630..62e86fb1b 100644
--- a/man2/statx.2
+++ b/man2/statx.2
@@ -32,9 +32,8 @@
 statx \- get file status (extended)
 .SH SYNOPSIS
 .nf
+.BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
 .B #include <sys/stat.h>
-.B #include <unistd.h>
-.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
 .PP
 .BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags ,
 .BI "          unsigned int " mask ", struct statx *restrict " statxbuf );
-- 
2.32.0

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

[Alejandro Colomar]

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

diff --git a/man2/subpage_prot.2 b/man2/subpage_prot.2
index dc07753b5..91bb789e1 100644
--- a/man2/subpage_prot.2
+++ b/man2/subpage_prot.2
@@ -32,12 +32,18 @@
 subpage_prot \- define a subpage protection for an address range
 .SH SYNOPSIS
 .nf
-.BI "int subpage_prot(unsigned long " addr ", unsigned long " len \
-", uint32_t *" map );
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_subpage_prot, unsigned long " addr ", unsigned long " len ,
+.BI "            uint32_t *" map );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR subpage_prot (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 The PowerPC-specific
 .BR subpage_prot ()
@@ -96,9 +102,6 @@ No library support is provided.
 .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
 Normal page protections (at the 64-kB page level) also apply;
 the subpage protection mechanism is an additional constraint,
 so putting 0 in a 2-bit field won't allow writes to a page that is otherwise
-- 
2.32.0

[PATCH 10/28] swapon.2: SYNOPSIS: Fix includes

[Alejandro Colomar]

There seems to be no reason to include <unistd.h>.
<sys/swap.h> already provides both the function prototypes and the
SWAP_* constants.

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

diff --git a/man2/swapon.2 b/man2/swapon.2
index cebeb3cdb..07d5fe86c 100644
--- a/man2/swapon.2
+++ b/man2/swapon.2
@@ -44,7 +44,6 @@
 swapon, swapoff \- start/stop swapping to file/device
 .SH SYNOPSIS
 .nf
-.B #include <unistd.h>
 .B #include <sys/swap.h>
 .PP
 .BI "int swapon(const char *" path ", int " swapflags );
-- 
2.32.0

[PATCH 11/28] symlink.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/symlink.2 b/man2/symlink.2
index b6744109e..87c25d5f4 100644
--- a/man2/symlink.2
+++ b/man2/symlink.2
@@ -39,7 +39,7 @@ symlink, symlinkat \- make a new name for a file
 .PP
 .BI "int symlink(const char *" target ", const char *" linkpath );
 .PP
-.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
 .B #include <unistd.h>
 .PP
 .BI "int symlinkat(const char *" target ", int " newdirfd \
-- 
2.32.0

[PATCH 12/28] syscall.2: wfix + ffix

[Alejandro Colomar]

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

diff --git a/man2/syscall.2 b/man2/syscall.2
index 0b542ab10..abdf1c702 100644
--- a/man2/syscall.2
+++ b/man2/syscall.2
@@ -44,8 +44,8 @@
 syscall \- indirect system call
 .SH SYNOPSIS
 .nf
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
-.BR "#include <sys/syscall.h>   "  "/* For SYS_xxx definitions */"
 .PP
 .BI "long syscall(long " number ", ...);"
 .fi
-- 
2.32.0

[PATCH 13/28] syslog.2: Use syscall(SYS_...); for raw system calls

[Alejandro Colomar]

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

diff --git a/man2/syslog.2 b/man2/syslog.2
index b3b205172..46928df49 100644
--- a/man2/syslog.2
+++ b/man2/syslog.2
@@ -35,10 +35,14 @@ syslog, klogctl \- read and/or clear kernel message ring buffer;
 set console_loglevel
 .SH SYNOPSIS
 .nf
-.BI "int syslog(int " type ", char *" bufp ", int " len );
+.BR "#include <sys/klog.h>" "        /* Definition of " SYSLOG_* " constants */"
+.BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_syslog, int " type ", char *" bufp ", int " len );
 .PP
 /* The glibc interface */
-.B "#include <sys/klog.h>"
+.B #include <sys/klog.h>
 .PP
 .BI "int klogctl(int " type ", char *" bufp ", int " len );
 .fi
-- 
2.32.0

[PATCH 14/28] timer_create.2: SYNOPSIS: Document why more than one header is needed

[Alejandro Colomar]

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

diff --git a/man2/timer_create.2 b/man2/timer_create.2
index 7f81914c2..9d3534570 100644
--- a/man2/timer_create.2
+++ b/man2/timer_create.2
@@ -28,7 +28,7 @@
 timer_create \- create a POSIX per-process timer
 .SH SYNOPSIS
 .nf
-.B  #include <signal.h>
+.BR "#include <signal.h>" "           /* Definition of " SIGEV_* " constants */"
 .B  #include <time.h>
 .PP
 .BI "int timer_create(clockid_t " clockid ", struct sigevent *restrict " sevp ,
-- 
2.32.0

[PATCH 15/28] s390_guarded_storage.2: tfix

[Alejandro Colomar]

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

diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
index 747c45c3a..62b3ed913 100644
--- a/man2/s390_guarded_storage.2
+++ b/man2/s390_guarded_storage.2
@@ -38,7 +38,7 @@ s390_guarded_storage \- operations with z/Architecture guarded storage facility
 .PP
 .IR Note :
 glibc provides no wrapper for
-.BR s390_guarded_storage (2),
+.BR s390_guarded_storage (),
 necessitating the use of
 .BR syscall (2).
 .SH DESCRIPTION
-- 
2.32.0

[PATCH 16/28] s390_runtime_instr.2: tfix

[Alejandro Colomar]

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

diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
index 0685fde6c..a043cfd9a 100644
--- a/man2/s390_runtime_instr.2
+++ b/man2/s390_runtime_instr.2
@@ -36,7 +36,7 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
 .PP
 .IR Note :
 glibc provides no wrapper for
-.BR s390_runtime_instr (2),
+.BR s390_runtime_instr (),
 necessitating the use of
 .BR syscall (2).
 .SH DESCRIPTION
-- 
2.32.0

[PATCH 17/28] s390_sthyi.2: tfix

[Alejandro Colomar]

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

diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
index df4a91d5d..58e3230a9 100644
--- a/man2/s390_sthyi.2
+++ b/man2/s390_sthyi.2
@@ -38,7 +38,7 @@ s390_sthyi \- emulate STHYI instruction
 .PP
 .IR Note :
 glibc provides no wrapper for
-.BR s390_sthyi (2),
+.BR s390_sthyi (),
 necessitating the use of
 .BR syscall (2).
 .SH DESCRIPTION
-- 
2.32.0

[PATCH 18/28] tkill.2: Use syscall(SYS_...); for system calls without a wrapper; fix includes too

[Alejandro Colomar]

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

diff --git a/man2/tkill.2 b/man2/tkill.2
index a6752591b..6ff930e17 100644
--- a/man2/tkill.2
+++ b/man2/tkill.2
@@ -31,14 +31,22 @@
 tkill, tgkill \- send a signal to a thread
 .SH SYNOPSIS
 .nf
-.BI "int tkill(pid_t " tid ", int " sig );
-.BI "int tgkill(pid_t " tgid ", pid_t " tid ", int " sig );
+.BR "#include <signal.h>" "           /* Definition of " SIG* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_tkill, pid_t " tid ", int " sig );
+.PP
+.B #include <signal.h>
+.PP
+.BI "int tgkill, pid_t " tgid ", pid_t " tid ", int " sig );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for
-.BR tkill ();
-see NOTES.
+glibc provides no wrapper for
+.BR tkill (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .BR tgkill ()
 sends the signal
@@ -138,10 +146,6 @@ in
 .BR clone (2)
 for an explanation of thread groups.
 .PP
-Glibc does not provide a wrapper for
-.BR tkill ();
-call it using
-.BR syscall (2).
 Before glibc 2.30, there was also no wrapper function for
 .BR tgkill ().
 .SH SEE ALSO
-- 
2.32.0

[PATCH 19/28] truncate.2: Remove <sys/types.h>

[Alejandro Colomar]

'off_t', which is the only reason this might have been ever
needed, is provided by <unistd.h> since POSIX.1-2001.

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

diff --git a/man2/truncate.2 b/man2/truncate.2
index a882e41c7..ebe3c4ef4 100644
--- a/man2/truncate.2
+++ b/man2/truncate.2
@@ -46,7 +46,6 @@ truncate, ftruncate \- truncate a file to a specified length
 .SH SYNOPSIS
 .nf
 .B #include <unistd.h>
-.B #include <sys/types.h>
 .PP
 .BI "int truncate(const char *" path ", off_t " length );
 .BI "int ftruncate(int " fd ", off_t " length );
-- 
2.32.0

[PATCH 20/28] umask.2: Remove <sys/types.h>

[Alejandro Colomar]

'mode_t', which is the only reason this might have been ever
needed, is provided by <sys/stat.h> since POSIX.1-2001.

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

diff --git a/man2/umask.2 b/man2/umask.2
index 857a106a5..8a11c50e9 100644
--- a/man2/umask.2
+++ b/man2/umask.2
@@ -36,7 +36,6 @@
 umask \- set file mode creation mask
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
 .B #include <sys/stat.h>
 .PP
 .BI "mode_t umask(mode_t " mask );
-- 
2.32.0

[PATCH 21/28] unlink.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/unlink.2 b/man2/unlink.2
index 39a4ec974..6f4c187f8 100644
--- a/man2/unlink.2
+++ b/man2/unlink.2
@@ -39,7 +39,7 @@ unlink, unlinkat \- delete a name and possibly the file it refers to
 .PP
 .BI "int unlink(const char *" pathname );
 .PP
-.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
 .B #include <unistd.h>
 .PP
 .BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags );
-- 
2.32.0

[PATCH 22/28] userfaultfd.2: Remove unused includes

[Alejandro Colomar]

<sys/types.h> makes no sense for a function that only uses 'int'.
The flags used by this function are provided by <fcntl.h>
(or others), but not by <linux/userfaultfd.h>.

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

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index 593c189d8..e1a18a9d9 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -29,8 +29,6 @@
 userfaultfd \- create a file descriptor for handling page faults in user space
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
-.B #include <linux/userfaultfd.h>
 .PP
 .BI "int userfaultfd(int " flags );
 .fi
-- 
2.32.0

[PATCH 23/28] userfaultfd.2: Use syscall(SYS_...); for system calls without a wrapper; fix includes too

[Alejandro Colomar]

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

diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2
index e1a18a9d9..cee7c01d2 100644
--- a/man2/userfaultfd.2
+++ b/man2/userfaultfd.2
@@ -29,12 +29,18 @@
 userfaultfd \- create a file descriptor for handling page faults in user space
 .SH SYNOPSIS
 .nf
+.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
 .PP
-.BI "int userfaultfd(int " flags );
+.BI "int syscall(SYS_userfaultfd, int " flags );
 .fi
 .PP
 .IR Note :
-There is no glibc wrapper for this system call; see NOTES.
+glibc provides no wrapper for
+.BR userfaultfd (),
+necessitating the use of
+.BR syscall (2).
 .SH DESCRIPTION
 .BR userfaultfd ()
 creates a new userfaultfd object that can be used for delegation of page-fault
@@ -573,9 +579,6 @@ non-page-fault events was added in Linux 4.11
 is Linux-specific and should not be used in programs intended to be
 portable.
 .SH NOTES
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2).
-.PP
 The userfaultfd mechanism can be used as an alternative to
 traditional user-space paging techniques based on the use of the
 .BR SIGSEGV
-- 
2.32.0

[PATCH 24/28] utime.2: SYNOPSIS: Fix includes

[Alejandro Colomar]

'struct utimbuf' is provided by <utime.h>.
There's no need for <sys/types.h>.

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

diff --git a/man2/utime.2 b/man2/utime.2
index 4995cf3ce..55ea8fc27 100644
--- a/man2/utime.2
+++ b/man2/utime.2
@@ -33,7 +33,6 @@
 utime, utimes \- change file last access and modification times
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
 .B #include <utime.h>
 .PP
 .BI "int utime(const char *" filename ", const struct utimbuf *" times );
-- 
2.32.0

[PATCH 25/28] utimensat.2: ffix

[Alejandro Colomar]

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

diff --git a/man2/utimensat.2 b/man2/utimensat.2
index 05b36c9e6..006677db8 100644
--- a/man2/utimensat.2
+++ b/man2/utimensat.2
@@ -28,7 +28,7 @@
 utimensat, futimens \- change file timestamps with nanosecond precision
 .SH SYNOPSIS
 .nf
-.B #include <fcntl.h>           /* Definition of AT_* constants */
+.BR "#include <fcntl.h>" "            /* Definition of " AT_* " constants */"
 .B #include <sys/stat.h>
 .PP
 .BI "int utimensat(int " dirfd ", const char *" pathname ,
-- 
2.32.0

[PATCH 26/28] vmsplice.2: Remove unneeded include

[Alejandro Colomar]

'struct iovec' is defined in <bits/types/struct_iovec.h>,
which is included by <sys/io.h>, but it is also included by
<bits/fcntl-linux.h>, which is in the end included by <fcntl.h>.
Given that we already include <fcntl.h>, we don't need any more
includes.

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

diff --git a/man2/vmsplice.2 b/man2/vmsplice.2
index 3fd9ff49f..9102c4c92 100644
--- a/man2/vmsplice.2
+++ b/man2/vmsplice.2
@@ -30,7 +30,6 @@ vmsplice \- splice user pages to/from a pipe
 .nf
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 .B #include <fcntl.h>
-.B #include <sys/uio.h>
 .PP
 .BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov ,
 .BI "                 size_t " nr_segs ", unsigned int " flags );
-- 
2.32.0

[PATCH 27/28] wait.2: Remove <sys/types.h>

[Alejandro Colomar]

The types that need <sys/types.h> are better documented in
system_data_types(7).  Let's keep only the includes for the
prototypes and the constants.

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

diff --git a/man2/wait.2 b/man2/wait.2
index 760f02f22..5ae955b3f 100644
--- a/man2/wait.2
+++ b/man2/wait.2
@@ -51,7 +51,6 @@
 wait, waitpid, waitid \- wait for process to change state
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
 .B #include <sys/wait.h>
 .PP
 .BI "pid_t wait(int *" "wstatus" );
-- 
2.32.0

[PATCH 28/28] wait4.2: SYNOPSIS: Remove includes

[Alejandro Colomar]

Don't document includes that provide types; only those that
provide prototypes and constants.

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

diff --git a/man2/wait4.2 b/man2/wait4.2
index 53fb8f639..3bd60367e 100644
--- a/man2/wait4.2
+++ b/man2/wait4.2
@@ -35,9 +35,6 @@
 wait3, wait4 \- wait for process to change state, BSD style
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
-.B #include <sys/time.h>
-.B #include <sys/resource.h>
 .B #include <sys/wait.h>
 .PP
 .BI "pid_t wait3(int *" "wstatus" ", int " options ", struct rusage *" rusage );
-- 
2.32.0

Re: [PATCH 00/28] SYNPOSIS: Use syscall() and fix includes

[Michael Kerrisk (man-pages)]

Hi Alex,

On 6/12/21 8:31 PM, Alejandro Colomar wrote:
> Hi Michael,
> 
> This is the last batch.  It includes the changes to seccomp.2, as you can see.
> Actually, they are a resend of the last ones.  I found out that all of the
> versions I sent you are identical...
> 
> Cheers,
> 
> Alex
> 
> 
> Alejandro Colomar (28):
>   seccomp.2: Document why each header is needed
>   seccomp.2: Use syscall(SYS_...); for system calls without a wrapper
>   spu_create.2: Remove <sys/types.h>
>   spu_create.2: Use syscall(SYS_...), for system calls without a wrapper
>   pipe.2: SYNOPSIS: Fix incorrect prototype
>   spu_run.2: Use syscall(SYS_...), for system calls without a wrapper
>   stat.2: SYNOPSIS: Fix includes
>   statx.2: SYNOPSIS: Fix includes
>   subpage_prot.2: Use syscall(SYS_...); for system calls without a
>     wrapper
>   swapon.2: SYNOPSIS: Fix includes
>   symlink.2: ffix
>   syscall.2: wfix + ffix
>   syslog.2: Use syscall(SYS_...); for raw system calls
>   timer_create.2: SYNOPSIS: Document why more than one header is needed
>   s390_guarded_storage.2: tfix
>   s390_runtime_instr.2: tfix
>   s390_sthyi.2: tfix
>   tkill.2: Use syscall(SYS_...); for system calls without a wrapper; fix
>     includes too
>   truncate.2: Remove <sys/types.h>
>   umask.2: Remove <sys/types.h>
>   unlink.2: ffix
>   userfaultfd.2: Remove unused includes
>   userfaultfd.2: Use syscall(SYS_...); for system calls without a
>     wrapper; fix includes too
>   utime.2: SYNOPSIS: Fix includes
>   utimensat.2: ffix
>   vmsplice.2: Remove unneeded include
>   wait.2: Remove <sys/types.h>
>   wait4.2: SYNOPSIS: Remove includes

Thanks. I have applied all of these patches.

Cheers,

Michael

>  man2/pipe.2                 |  2 +-
>  man2/s390_guarded_storage.2 |  2 +-
>  man2/s390_runtime_instr.2   |  2 +-
>  man2/s390_sthyi.2           |  2 +-
>  man2/seccomp.2              | 24 +++++++++++++-----------
>  man2/spu_create.2           | 19 ++++++++++---------
>  man2/spu_run.2              | 12 +++++++-----
>  man2/stat.2                 |  3 +--
>  man2/statx.2                |  3 +--
>  man2/subpage_prot.2         | 15 +++++++++------
>  man2/swapon.2               |  1 -
>  man2/symlink.2              |  2 +-
>  man2/syscall.2              |  2 +-
>  man2/syslog.2               |  8 ++++++--
>  man2/timer_create.2         |  2 +-
>  man2/tkill.2                | 22 +++++++++++++---------
>  man2/truncate.2             |  1 -
>  man2/umask.2                |  1 -
>  man2/unlink.2               |  2 +-
>  man2/userfaultfd.2          | 15 ++++++++-------
>  man2/utime.2                |  1 -
>  man2/utimensat.2            |  2 +-
>  man2/vmsplice.2             |  1 -
>  man2/wait.2                 |  1 -
>  man2/wait4.2                |  3 ---
>  25 files changed, 77 insertions(+), 71 deletions(-)
> 


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