capabilities.7: Add a reference to user_namespaces(7) for CAP_SETFCAP

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

man2/pidfd_open.2

@@ -49,8 +49,17 @@ the close-on-exec flag is set on the file descriptor.
 .PP
 The
 .I flags
-argument is reserved for future use;
-currently, this argument must be specified as 0.
+argument either has the value 0, or contains the following flag:
+.TP
+.BR PIDFD_NONBLOCK " (since Linux 5.10)"
+.\" commit 4da9af0014b51c8b015ed8c622440ef28912efe6
+Return a nonblocking file descriptor.
+If the process referred to by the file descriptor has not yet terminated,
+then an attempt to wait on the file descriptor using
+.BR waitid (2)
+will immediately return the error
+.BR EAGAIN
+rather than blocking.
 .SH RETURN VALUE
 On success,
 .BR pidfd_open ()
@@ -62,7 +71,7 @@ is set to indicate the error.
 .TP
 .B EINVAL
 .I flags
-is not 0.
+is not valid.
 .TP
 .B EINVAL
 .I pid

man2/sigaction.2

@@ -262,7 +262,7 @@ This flag is meaningful only when establishing a signal handler.
 .\" field was added in Linux 2.1.86.)
 .\"
 .TP
-.B SA_UNSUPPORTED
+.BR SA_UNSUPPORTED " (since Linux 5.11)"
 Used to dynamically probe for flag bit support.
 .IP
 If an attempt to register a handler succeeds with this flag set in

man2/syscalls.2

@@ -566,7 +566,7 @@ T}
 \fBpwritev2\fP(2)	4.6
 \fBquery_module\fP(2)	2.2	Removed in 2.6
 \fBquotactl\fP(2)	1.0
-\fBquotactl_path\fP(2)	5.13
+\fBquotactl_fd\fP(2)	5.14
 \fBread\fP(2)	1.0
 \fBreadahead\fP(2)	2.4.13
 \fBreaddir\fP(2)	1.0

man2/wait.2

@@ -419,6 +419,11 @@ On failure, each of these calls sets
 to indicate the error.
 .SH ERRORS
 .TP
+.B EAGAIN
+The PID file descriptor specified in
+.I id
+is nonblocking and the process that it refers to has not terminated.
+.TP
 .B ECHILD
 (for
 .BR wait ())

man7/capabilities.7

@@ -352,10 +352,9 @@ 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)).
+also needed to map user ID 0 in a new user namespace; see
+.BR user_namespaces (7)
+for details.
 .TP
 .B CAP_SETPCAP
 If file capabilities are supported (i.e., since Linux 2.6.24):

man7/user_namespaces.7

@@ -577,11 +577,47 @@ 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.
+If updating
+.IR /proc/[pid]/uid_map
+to create a mapping that maps UID 0 in the parent namespace,
+then one of the following must be true:
+.RS
+.IP * 3
+if writing process is in the parent user namespace,
+then it must have the
+.BR CAP_SETFCAP
+capability in that user namespace; or
+.IP *
+if the writing process is in the child user namespace,
+then the process that created the user namespace must have had the
+.BR CAP_SETFCAP
+capability when the namespace was created.
+.RE
+.IP
+This rule has been in place since
 .\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18
-If a writing process is root (i.e., UID 0) trying to map host user ID 0,
-it must have the
+Linux 5.12.
+It eliminates an earlier security bug whereby
+a UID 0 process that lacks the
 .B CAP_SETFCAP
-capability (since Linux 5.12).
+capability,
+which is needed to create a binary with namespaced file capabilities
+(as described in
+.BR capabilities (7)),
+could nevertheless create such a binary,
+by the following steps:
+.RS
+.IP * 3
+Create a new user namespace with the identity mapping
+(i.e., UID 0 in the new user namespace maps to UID 0 in the parent namespace),
+so that UID 0 in both namespaces is equivalent to the same root user ID.
+.IP *
+Since the child process has the
+.B CAP_SETFCAP
+capability, it could create a binary with namespaced file capabilities
+that would then be effective in the parent user namespace
+(because the root user IDs are the same in the two namespaces).
+.RE
 .IP 5.
 One of the following two cases applies:
 .RS