proc.5, namespaces.7: Move /proc/[pid]/{gid_map,uid_map} text from proc.5 to namespaces.7

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

man5/proc.5

@@ -1913,6 +1913,8 @@ The process must be in either the user namespace of the process
 or inside the parent user namespace of the process
 .IR pid .
 .RE
+For further details, see
+.BR namespaces (7).
 .TP
 .IR /proc/[pid]/wchan " (since Linux 2.6.0)"
 The symbolic name corresponding to the location

man7/namespaces.7

@@ -281,6 +281,137 @@ but is unprivileged for operations outside the namespace.
 
 Starting in Linux 3.8, unprivileged processes can create user namespaces.
 
+The
+.IR /proc/[pid]/uid_map
+and
+.IR /proc/[pid]/gid_map
+files (available since Linux 3.5)
+.\" commit 22d917d80e842829d0ca0a561967d728eb1d6303
+expose the mappings for user and group IDs
+inside the user namespace for the process
+.IR pid .
+The description here explains the details for
+.IR uid_map ;
+.IR gid_map
+is exactly the same,
+but each instance of "user ID" is replaced by "group ID".
+
+The
+.I uid_map
+file exposes the mapping of user IDs from the user namespace
+of the process
+.IR pid
+to the user namespace of the process that opened
+.IR uid_map
+(but see a qualification to this point below).
+In other words, processes that are in different user namespaces
+will potentially see different values when reading from a particular
+.I uid_map
+file, depending on the user ID mappings for the user namespaces
+of the reading processes.
+
+Each line in the file specifies a 1-to-1 mapping of a range of contiguous
+between two user namespaces.
+The specification in each line takes the form of
+three numbers delimited by white space.
+The first two numbers specify the starting user ID in 
+each user namespace.
+The third number specifies the length of the mapped range.
+In detail, the fields are interpreted as follows:
+.IP (1) 4
+The start of the range of user IDs in
+the user namespace of the process
+.IR pid .
+.IP (2)
+The start of the range of user
+IDs to which the user IDs specified by field one map.
+How field two is interpreted depends on whether the process that opened
+.I uid_map
+and the process
+.IR pid
+are in the same user namespace, as follows:
+.RS
+.IP a) 3
+If the two processes are in different user namespaces:
+field two is the start of a range of
+user IDs in the user namespace of the process that opened
+.IR uid_map .
+.IP b)
+If the two processes are in the same user namespace:
+field two is the start of the range of
+user IDs in the parent user namespace of the process
+.IR pid .
+(The "parent user namespace"
+is the user namespace of the process that created a user namespace
+via a call to
+.BR unshare (2)
+or
+.BR clone (2)
+with the 
+.BR CLONE_NEWUSER
+flag.)
+This case enables the opener of
+.I uid_map
+(the common case here is opening
+.IR /proc/self/uid_map )
+to see the mapping of user IDs into the user namespace of the process
+that created this user namespace.
+.RE
+.IP (3)
+The length of the range of user IDs that is mapped between the two
+user namespaces.
+.PP
+After the creation of a new user namespace, the
+.I uid_map
+file may be written to exactly once to specify
+the mapping of user IDs in the new user namespace.
+(An attempt to write more than once to the file fails with the error
+.BR EPERM .)
+
+The lines written to
+.IR uid_map
+must conform to the following rules:
+.IP * 3
+The three fields must be valid numbers,
+and the last field must be greater than 0.
+.IP *
+Lines are terminated by newline characters.
+.IP *
+There is an (arbitrary) limit on the number of lines in the file.
+As at Linux 3.8, the limit is five lines.
+.IP *
+The range of user IDs specified in each line cannot overlap with the ranges
+in any other lines.
+In the current implementation (Linux 3.8), this requirement is 
+satisfied by a simplistic implementation that imposes the further
+requirement that
+the values in both field 1 and field 2 of successive lines must be
+in ascending numerical order.
+.PP
+Writes that violate the above rules fail with the error
+.BR EINVAL .
+
+In order for a process to write to the
+.I /proc/[pid]/uid_map
+.RI ( /proc/[pid]/gid_map )
+file, the following requirements must be met:
+.IP * 3
+The process must have the
+.BR CAP_SETUID
+.RB ( CAP_SETGID )
+capability in the user namespace of the process
+.IR pid .
+.IP *
+The process must have the
+.BR CAP_SETUID
+.RB ( CAP_SETGID )
+capability in the parent user namespace.
+.IP *
+The process must be in either the user namespace of the process
+.I pid
+or inside the parent user namespace of the process
+.IR pid .
+
 .SS UTS namespaces (CLONE_NEWUTS)
 
 UTS namespaces provide isolation of two system identifiers: