Skip to contentSkip to conversation

SYNPOSIS: Use syscall() and fix includes

PATCH In review Alejandro Colomar 2 participants 30 messages Jun 12, 2021 – Jun 20, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

cover SYNPOSIS: Use syscall() and fix includes

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(-)
Signature · 1 line
2.32.0
#1 lore raw

PATCH 1/28 seccomp.2: Document why each header is needed

Cc Kees Cook <[email protected]>
Cc Tyler Hicks <[email protected]>
Cc Will Drewry <[email protected]>
Cc Michael Kerrisk <[email protected]>
---
 man2/seccomp.2 | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
man2/seccomp.2 +5 -5
index 35eb1dd1f..53f473a78 100644
@@ -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
Signature · 1 line
2.32.0
#2 lore raw

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

In reply to Alejandro Colomar
---
 man2/seccomp.2 | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)
man2/seccomp.2 +8 -6
index 53f473a78..a3421871f 100644
@@ -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
Signature · 1 line
2.32.0
#3 lore raw

PATCH 3/28 spu_create.2: Remove <sys/types.h>

In reply to Alejandro Colomar

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

---
 man2/spu_create.2 | 1 -
 1 file changed, 1 deletion(-)
man2/spu_create.2 +0 -1
index d192eb025..6541a6e9a 100644
@@ -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 \
Signature · 1 line
2.32.0
#4 lore raw

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

In reply to Alejandro Colomar
---
 man2/spu_create.2 | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)
man2/spu_create.2 +10 -8
index 6541a6e9a..746a86ed6 100644
@@ -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.
Signature · 1 line
2.32.0
#5 lore raw

PATCH 5/28 pipe.2: SYNOPSIS: Fix incorrect prototype

In reply to 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).

---
 man2/pipe.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/pipe.2 +1 -1
index 93fbd36f2..41a482f37 100644
@@ -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 ()
Signature · 1 line
2.32.0
#6 lore raw

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

In reply to Alejandro Colomar
---
 man2/spu_run.2 | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
man2/spu_run.2 +7 -5
index def974772..d5fdc2280 100644
@@ -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.
Signature · 1 line
2.32.0
#7 lore raw

PATCH 7/28 stat.2: SYNOPSIS: Fix includes

In reply to 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).

---
 man2/stat.2 | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
man2/stat.2 +1 -2
index d356ce15a..339920d71 100644
@@ -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 ,
Signature · 1 line
2.32.0
#8 lore raw

PATCH 8/28 statx.2: SYNOPSIS: Fix includes

In reply to 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>

---
 man2/statx.2 | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
man2/statx.2 +1 -2
index a14880630..62e86fb1b 100644
@@ -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 );
Signature · 1 line
2.32.0
#9 lore raw

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

In reply to Alejandro Colomar
---
 man2/subpage_prot.2 | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)
man2/subpage_prot.2 +9 -6
index dc07753b5..91bb789e1 100644
@@ -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
Signature · 1 line
2.32.0
#10 lore raw

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

In reply to 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.

---
 man2/swapon.2 | 1 -
 1 file changed, 1 deletion(-)
man2/swapon.2 +0 -1
index cebeb3cdb..07d5fe86c 100644
@@ -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 );
Signature · 1 line
2.32.0
#11 lore raw

PATCH 11/28 symlink.2: ffix

In reply to Alejandro Colomar
---
 man2/symlink.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/symlink.2 +1 -1
index b6744109e..87c25d5f4 100644
@@ -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 \
Signature · 1 line
2.32.0
#12 lore raw

PATCH 12/28 syscall.2: wfix + ffix

In reply to Alejandro Colomar
---
 man2/syscall.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/syscall.2 +1 -1
index 0b542ab10..abdf1c702 100644
@@ -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
Signature · 1 line
2.32.0
#13 lore raw

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

In reply to Alejandro Colomar
---
 man2/syslog.2 | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
man2/syslog.2 +6 -2
index b3b205172..46928df49 100644
@@ -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
Signature · 1 line
2.32.0
#14 lore raw

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

In reply to Alejandro Colomar
---
 man2/timer_create.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/timer_create.2 +1 -1
index 7f81914c2..9d3534570 100644
@@ -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 ,
Signature · 1 line
2.32.0
#15 lore raw

PATCH 15/28 s390_guarded_storage.2: tfix

In reply to Alejandro Colomar
---
 man2/s390_guarded_storage.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/s390_guarded_storage.2 +1 -1
index 747c45c3a..62b3ed913 100644
@@ -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
Signature · 1 line
2.32.0
#16 lore raw

PATCH 16/28 s390_runtime_instr.2: tfix

In reply to Alejandro Colomar
---
 man2/s390_runtime_instr.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/s390_runtime_instr.2 +1 -1
index 0685fde6c..a043cfd9a 100644
@@ -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
Signature · 1 line
2.32.0
#17 lore raw

PATCH 17/28 s390_sthyi.2: tfix

In reply to Alejandro Colomar
---
 man2/s390_sthyi.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/s390_sthyi.2 +1 -1
index df4a91d5d..58e3230a9 100644
@@ -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
Signature · 1 line
2.32.0
#18 lore raw

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

In reply to Alejandro Colomar
---
 man2/tkill.2 | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)
man2/tkill.2 +13 -9
index a6752591b..6ff930e17 100644
@@ -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
Signature · 1 line
2.32.0
#19 lore raw

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

In reply to Alejandro Colomar

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

---
 man2/truncate.2 | 1 -
 1 file changed, 1 deletion(-)
man2/truncate.2 +0 -1
index a882e41c7..ebe3c4ef4 100644
@@ -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 );
Signature · 1 line
2.32.0
#20 lore raw

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

In reply to 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.

---
 man2/umask.2 | 1 -
 1 file changed, 1 deletion(-)
man2/umask.2 +0 -1
index 857a106a5..8a11c50e9 100644
@@ -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 );
Signature · 1 line
2.32.0
#21 lore raw

PATCH 21/28 unlink.2: ffix

In reply to Alejandro Colomar
---
 man2/unlink.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/unlink.2 +1 -1
index 39a4ec974..6f4c187f8 100644
@@ -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 );
Signature · 1 line
2.32.0
#22 lore raw

PATCH 22/28 userfaultfd.2: Remove unused includes

In reply to 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>.

---
 man2/userfaultfd.2 | 2 --
 1 file changed, 2 deletions(-)
man2/userfaultfd.2 +0 -2
index 593c189d8..e1a18a9d9 100644
@@ -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
Signature · 1 line
2.32.0
#23 lore raw

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

In reply to Alejandro Colomar
---
 man2/userfaultfd.2 | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)
man2/userfaultfd.2 +8 -5
index e1a18a9d9..cee7c01d2 100644
@@ -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
Signature · 1 line
2.32.0
#24 lore raw

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

In reply to Alejandro Colomar

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

---
 man2/utime.2 | 1 -
 1 file changed, 1 deletion(-)
man2/utime.2 +0 -1
index 4995cf3ce..55ea8fc27 100644
@@ -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 );
Signature · 1 line
2.32.0
#25 lore raw

PATCH 25/28 utimensat.2: ffix

In reply to Alejandro Colomar
---
 man2/utimensat.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/utimensat.2 +1 -1
index 05b36c9e6..006677db8 100644
@@ -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 ,
Signature · 1 line
2.32.0
#26 lore raw

PATCH 26/28 vmsplice.2: Remove unneeded include

In reply to 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.

---
 man2/vmsplice.2 | 1 -
 1 file changed, 1 deletion(-)
man2/vmsplice.2 +0 -1
index 3fd9ff49f..9102c4c92 100644
@@ -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 );
Signature · 1 line
2.32.0
#27 lore raw

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

In reply to 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.

---
 man2/wait.2 | 1 -
 1 file changed, 1 deletion(-)
man2/wait.2 +0 -1
index 760f02f22..5ae955b3f 100644
@@ -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" );
Signature · 1 line
2.32.0
#28 lore raw

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

In reply to Alejandro Colomar

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

---
 man2/wait4.2 | 3 ---
 1 file changed, 3 deletions(-)
man2/wait4.2 +0 -3
index 53fb8f639..3bd60367e 100644
@@ -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 );
Signature · 1 line
2.32.0
#29 lore raw
In reply to Alejandro Colomar

Hi Alex,

Quoted 35 lines · 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

Quoted 8 lines

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

Quoted 27 lines
 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(-)
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/