[PATCH 1/1] man/man7/pid_namespaces.7: Fix process/namespace hierarchy restrictions

setns() actually allows forking new processes directly into grandchild
PID namespaces, so the parent of a process can be in grandparent PID
namespace. Indeed, the only restriction in setns() is that the target
PID namespace needs to be a descendant (direct child or not) of the PID
namespace of the caller.

Additionally, that restriction is not a consequence of the paragraph
before: add a new paragraph break to remove the implication, and add the
actual reasoning (fork() APIs needs to be able to return a valid PID in
the namespace of their caller).

Signed-off-by: Matthieu Buffet <[email protected]>
---
 man/man7/pid_namespaces.7 | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/man/man7/pid_namespaces.7 b/man/man7/pid_namespaces.7
index f7e0aeded..39b9331ca 100644
--- a/man/man7/pid_namespaces.7
+++ b/man/man7/pid_namespaces.7
@@ -207,14 +207,20 @@ because doing so would change the caller's idea of its own PID
 (as reported by
 .BR getpid ()),
 which would break many applications and libraries.
-.P
 To put things another way:
 a process's PID namespace membership is determined when the process is created
 and cannot be changed thereafter.
-Among other things, this means that the parental relationship
-between processes mirrors the parental relationship between PID namespaces:
-the parent of a process is either in the same namespace
-or resides in the immediate parent PID namespace.
+.P
+Additionally, because
+.BR fork(2)
+and its variants need to return a meaningful new PID in the namespace of
+their caller, the parental relationship between processes needs to loosely
+mirror the parental relationship between PID namespaces. To that end,
+.BR setns (2)
+is restricted to only accept descendant PID namespaces (direct children or not).
+Thus, a process can only be forked in a direct child PID namespace, or in a
+grandchild PID namespace (in which case it will be assigned a PID in all
+ancestor namespaces).
 .P
 A process may call
 .BR unshare (2)
-- 
2.47.3