capabilities.7, user_namespaces.7: Minor tweaks (part 2) to Kir Kolyshkin's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/bpf.2

@@ -1212,7 +1212,7 @@ riscv (since Linux 5.1).
  * 4. print number of received TCP/UDP packets every second
  */
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     int sock, map_fd, prog_fd, key;
     long long value = 0, tcp_cnt, udp_cnt;

man2/copy_file_range.2

@@ -236,7 +236,7 @@ or server-side-copy (in the case of NFS).
 #include <unistd.h>
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     int fd_in, fd_out;
     struct stat stat;

man2/execve.2

@@ -346,7 +346,7 @@ will be invoked with the following arguments:
 .PP
 where
 .I pathname
-is the absolute pathname of the file specified as the first argument of
+is the pathname of the file specified as the first argument of
 .BR execve (),
 and
 .I arg...
@@ -882,6 +882,7 @@ argv[4]: world
 .BR ptrace (2),
 .BR exec (3),
 .BR fexecve (3),
+.BR getauxval (3),
 .BR getopt (3),
 .BR system (3),
 .BR capabilities (7),

man2/fallocate.2

@@ -81,7 +81,7 @@ Preallocating zeroed blocks beyond the end of the file in this manner
 is useful for optimizing append workloads.
 .PP
 If the
-.B FALLOC_FL_UNSHARE
+.B FALLOC_FL_UNSHARE_RANGE
 flag is specified in
 .IR mode ,
 shared file data extents will be made private to the file to guarantee

man2/membarrier.2

@@ -358,7 +358,7 @@ slow_path(int *read_a)
 }
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     int read_a, read_b;
 
@@ -444,7 +444,7 @@ slow_path(int *read_a)
 }
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     int read_a, read_b;
 

man2/perf_event_open.2

@@ -3762,7 +3762,7 @@ perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
 }
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     struct perf_event_attr pe;
     long long count;

man2/readv.2

@@ -243,7 +243,9 @@ If some data was successfully read, it will return the number of bytes read.
 If no bytes were read, it will return \-1 and set
 .IR errno
 to
-.BR EAGAIN .
+.BR EAGAIN
+(but see
+.BR BUGS ).
 Currently, this flag is meaningful only for
 .BR preadv2 ().
 .TP
@@ -425,6 +427,18 @@ iov[1].iov_len = strlen(str1);
 nwritten = writev(STDOUT_FILENO, iov, 2);
 .EE
 .in
+.SH BUGS
+Linux 5.9 and 5.10 have a bug where
+.BR preadv2()
+with the
+.BR RWF_NOWAIT
+flag may return 0 even when not at end of file.
+.\" See
+.\" <https://lore.kernel.org/linux-fsdevel/fea8b16d-5a69-40f9-b123-e84dcd6e8f2e@www.fastmail.com/T/#u>
+.\" The bug was introduced in
+.\"    efa8480a831 fs: RWF_NOWAIT should imply IOCB_NOIO
+.\"and fixed in
+.\"    06c0444290 mm/filemap.c: generic_file_buffered_read() now uses find_get_pages_contig
 .SH SEE ALSO
 .BR pread (2),
 .BR read (2),

man2/recv.2

@@ -196,7 +196,7 @@ number of the queued error.
 is the origin code of where the error originated.
 The other fields are protocol-specific.
 The macro
-.B SOCK_EE_OFFENDER
+.B SO_EE_OFFENDER
 returns a pointer to the address of the network object
 where the error originated from given a pointer to the ancillary message.
 If this address is not known, the

man2/seccomp.2

@@ -1199,7 +1199,7 @@ install_filter(int syscall_nr, int t_arch, int f_errno)
 }
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     if (argc < 5) {
         fprintf(stderr, "Usage: "

man2/seccomp_unotify.2

@@ -739,6 +739,22 @@ When allocating the file descriptor in the target,
 use the file descriptor number specified in the
 .I newfd
 field.
+.TP
+.BR SECCOMP_ADDFD_FLAG_SEND " (since Linux 5.14)"
+.\" commit 0ae71c7720e3ae3aabd2e8a072d27f7bd173d25c
+Perform the equivalent of
+.B SECCOMP_IOCTL_NOTIF_ADDFD
+plus
+.B SECCOMP_IOCTL_NOTIF_SEND
+as an atomic operation.
+On successful invocation, the target process's
+.I errno
+will be 0
+and the return value will be the file descriptor number
+that was allocated in the target.
+If allocating the file descriptor in the target fails,
+the target's system call continues to be blocked
+until a successful response is sent.
 .RE
 .TP
 .I srcfd
@@ -801,6 +817,13 @@ Allocating the file descriptor in the target would cause the target's
 limit to be exceeded (see
 .BR getrlimit (2)).
 .TP
+.B EBUSY
+If the flag
+.B SECCOMP_IOCTL_NOTIF_SEND
+is used, this means the operation can't proceed until other
+.B SECCOMP_IOCTL_NOTIF_ADDFD
+requests are processed.
+.TP
 .B EINPROGRESS
 The user-space notification specified in the
 .I id
@@ -1085,7 +1108,7 @@ Alternatively, in the
 example, the supervisor might use
 .BR poll (2)
 to monitor both the notification file descriptor
-(so as as to discover when the target's
+(so as to discover when the target's
 .BR accept (2)
 call has been interrupted) and the listening file descriptor
 (so as to know when a connection is available).
@@ -1150,6 +1173,14 @@ flag.
 .\" calls because it's impossible for the kernel to restart the call
 .\" with the right timeout value. I wonder what happens when those
 .\" system calls are restarted in the scenario we're discussing.)
+.PP
+Furthermore, if the supervisor response is a file descriptor
+added with
+.BR SECCOMP_IOCTL_NOTIF_ADDFD ,
+then the flag
+.B SECCOMP_ADDFD_FLAG_SEND
+can be used to atomically add the file descriptor and return that value,
+making sure no file descriptors are inadvertently leaked into the target.
 .SH BUGS
 If a
 .BR SECCOMP_IOCTL_NOTIF_RECV

man2/time.2

@@ -93,7 +93,7 @@ specified as NULL cannot fail with the error
 .BR EOVERFLOW ,
 even on ABIs where
 .I time_t
-is a signed 32-bit integer and the clock ticks past the time 2**31
+is a signed 32-bit integer and the clock reaches or exceeds 2**31 seconds
 (2038-01-19 03:14:08 UTC, ignoring leap seconds).
 (POSIX.1 permits, but does not require, the
 .B EOVERFLOW

man2/tkill.2

@@ -39,7 +39,7 @@ tkill, tgkill \- send a signal to a thread
 .PP
 .B #include <signal.h>
 .PP
-.BI "int tgkill, pid_t " tgid ", pid_t " tid ", int " sig );
+.BI "int tgkill(pid_t " tgid ", pid_t " tid ", int " sig );
 .fi
 .PP
 .IR Note :

man2/wait.2

@@ -455,6 +455,15 @@ was caught; see
 The
 .I options
 argument was invalid.
+.TP
+.B ESRCH
+(for
+.BR wait ()
+or
+.BR waitpid ())
+.I pid
+is equal to
+.BR INT_MIN .
 .SH CONFORMING TO
 SVr4, 4.3BSD, POSIX.1-2001.
 .SH NOTES

man3/bsearch.3

@@ -124,7 +124,7 @@ compmi(const void *m1, const void *m2)
 }
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     qsort(months, nr_of_months, sizeof(months[0]), compmi);
     for (int i = 1; i < argc; i++) {

man3/getauxval.3

@@ -287,6 +287,7 @@ could not be found from the case where the value corresponding to
 .I type
 was zero.
 .SH SEE ALSO
+.BR execve (2),
 .BR secure_getenv (3),
 .BR vdso (7),
 .BR ld\-linux.so (8)

man3/getopt.3

@@ -491,7 +491,7 @@ with most of its features.
 #include <getopt.h>
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     int c;
     int digit_optind = 0;

man3/getsubopt.3

@@ -160,7 +160,7 @@ The following program expects suboptions following a "\-o" option.
 #include <stdio.h>
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     enum {
         RO_OPT = 0,

man3/printf.3

@@ -115,7 +115,7 @@ is the same as
 except that it outputs to a file descriptor,
 .IR fd ,
 instead of to a
-.I stdio
+.BR stdio (3)
 stream.
 .PP
 The functions

man3/pthread_setname_np.3

@@ -180,7 +180,7 @@ threadfunc(void *parm)
 }
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     pthread_t thread;
     int rc;

man3/strlen.3

@@ -64,6 +64,11 @@ T}	Thread safety	MT-Safe
 .hy
 .ad
 .sp 1
+.SH NOTES
+In cases where the input buffer may not contain
+a terminating null byte,
+.BR strnlen (3)
+should be used instead.
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, C89, C99, C11, SVr4, 4.3BSD.
 .SH SEE ALSO

man3/strstr.3

@@ -61,6 +61,13 @@ but ignores the case of both arguments.
 .SH RETURN VALUE
 These functions return a pointer to the beginning of the
 located substring, or NULL if the substring is not found.
+.PP
+If
+.I needle
+is the empty string,
+the return value is always
+.I haystack
+itself.
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).

man3/wcslen.3

@@ -56,6 +56,11 @@ T}	Thread safety	MT-Safe
 .hy
 .ad
 .sp 1
+.SH NOTES
+In cases where the input buffer may not contain
+a terminating null wide character,
+.BR wcsnlen (3)
+should be used instead.
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, C99.
 .SH SEE ALSO

man3/wordexp.3

@@ -240,7 +240,7 @@ is approximately that of "ls [a-c]*.c".
 #include <wordexp.h>
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     wordexp_t p;
     char **w;

man5/proc.5

@@ -5606,7 +5606,7 @@ first.
 .IR  /proc/sys/vm/sysctl_hugetlb_shm_group " (since Linux 2.6.7)"
 This writable file contains a group ID that is allowed
 to allocate memory using huge pages.
-If a process has a filesystem group ID or any supplememtary group ID that
+If a process has a filesystem group ID or any supplementary group ID that
 matches this group ID,
 then it can make huge-page allocations without holding the
 .BR CAP_IPC_LOCK

man7/ascii.7

@@ -48,7 +48,7 @@ C program \f(CW\(aq\eX\(aq\fP escapes are noted.
 .ft CW
 \}
 .TS
-l l l l l l l l.
+l l l l | l l l l.
 Oct	Dec	Hex	Char	Oct	Dec	Hex	Char
 _
 000	0	00	NUL \(aq\e0\(aq (null character)	100	64	40	@

man7/capabilities.7

@@ -215,7 +215,7 @@ Lock memory
 .BR shmctl (2));
 .IP *
 Allocate memory using huge pages
-.RB ( memfd_create (2)
+.RB ( memfd_create (2),
 .BR mmap (2),
 .BR shmctl (2)).
 .PD 0
@@ -349,6 +349,13 @@ write a group ID mapping in a user namespace (see
 .TP
 .BR CAP_SETFCAP " (since Linux 2.6.24)"
 Set arbitrary capabilities on a file.
+.IP
+.\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18
+Since Linux 5.12, this capability is
+also needed to map UID 0 (as in
+.IR "unshare \-Ur" ;
+see
+.BR unshare (1)).
 .TP
 .B CAP_SETPCAP
 If file capabilities are supported (i.e., since Linux 2.6.24):

man7/fanotify.7

@@ -1069,7 +1069,7 @@ $ \fBmkdir \-p /home/user/testdir\fP          # In another terminal
 #define BUF_SIZE 256
 
 int
-main(int argc, char **argv)
+main(int argc, char *argv[])
 {
     int fd, ret, event_fd, mount_fd;
     ssize_t len, path_len;

man7/namespaces.7

@@ -97,7 +97,7 @@ If the
 .I flags
 argument of the call specifies one or more of the
 .B CLONE_NEW*
-flags listed below, then new namespaces are created for each flag,
+flags listed above, then new namespaces are created for each flag,
 and the child process is made a member of those namespaces.
 (This system call also implements a number of features
 unrelated to namespaces.)
@@ -119,7 +119,7 @@ If the
 .I flags
 argument of the call specifies one or more of the
 .B CLONE_NEW*
-flags listed below, then new namespaces are created for each flag,
+flags listed above, then new namespaces are created for each flag,
 and the calling process is made a member of those namespaces.
 (This system call also implements a number of features
 unrelated to namespaces.)

man7/path_resolution.7

@@ -63,7 +63,7 @@ argument).
 The current working directory is inherited from the parent, and can
 be changed by use of the
 .BR chdir (2)
-system call.)
+system call.
 .PP
 Pathnames starting with a \(aq/\(aq character are called absolute pathnames.
 Pathnames not starting with a \(aq/\(aq are called relative pathnames.

man7/posixoptions.7

@@ -968,7 +968,7 @@ The following functions are present:
 .IR fcvt ()
 .IR ftime ()
 .IR gcvt ()
-.IR getcwd ()
+.IR getwd ()
 .IR index ()
 .IR mktemp ()
 .IR rindex ()

man7/user_namespaces.7

@@ -577,6 +577,12 @@ or be in the parent user namespace of the process
 The mapped user IDs (group IDs) must in turn have a mapping
 in the parent user namespace.
 .IP 4.
+.\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18
+If a writing process is root (i.e., UID 0) trying to map host user ID 0,
+it must have the
+.B CAP_SETFCAP
+capability (since Linux 5.12).
+.IP 5.
 One of the following two cases applies:
 .RS
 .IP * 3
@@ -1383,4 +1389,4 @@ main(int argc, char *argv[])
 .BR pid_namespaces (7)
 .PP
 The kernel source file
-.IR Documentation/namespaces/resource\-control.txt .
+.IR Documentation/admin\-guide/namespaces/resource\-control.rst .

man7/vdso.7

@@ -256,7 +256,6 @@ it's best to refer to the public documentation:
 http://docs.blackfin.uclinux.org/doku.php?id=linux\-kernel:fixed\-code
 .SS mips functions
 .\" See linux/arch/mips/vdso/vdso.ld.S
-.PP
 The table below lists the symbols exported by the vDSO.
 .if t \{\
 .ft CW
@@ -371,6 +370,7 @@ symbol	version
 _
 __kernel_clock_getres	LINUX_2.6.15
 __kernel_clock_gettime	LINUX_2.6.15
+__kernel_clock_gettime64	LINUX_5.11
 __kernel_datapage_offset	LINUX_2.6.15
 __kernel_get_syscall_map	LINUX_2.6.15
 __kernel_get_tbfreq	LINUX_2.6.15
@@ -386,7 +386,9 @@ __kernel_sync_dicache_p5	LINUX_2.6.15
 .ft P
 \}
 .PP
-The
+In kernel versions before Linux 5.6,
+.\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39
+the
 .B CLOCK_REALTIME_COARSE
 and
 .B CLOCK_MONOTONIC_COARSE
@@ -424,7 +426,9 @@ __kernel_sync_dicache_p5	LINUX_2.6.15
 .ft P
 \}
 .PP
-The
+In kernel versions before Linux 4.16,
+.\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1
+the
 .B CLOCK_REALTIME_COARSE
 and
 .B CLOCK_MONOTONIC_COARSE

scripts/bash_aliases

@@ -24,7 +24,7 @@ EX_USAGE=64;
 #	C
 
 #  sed_rm_ccomments()  removes C comments.
-# It can't handle multiple comments in a sinlge line correctly,
+# It can't handle multiple comments in a single line correctly,
 # nor mixed or embedded //... and /*...*/ comments.
 # Use as a filter (see man_lsfunc() in this file).