pivot_root.2: Relocate text on use cases and add text on purpose of pivot_root(2)

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

diff --git a/man2/pivot_root.2 b/man2/pivot_root.2
index 0428a5eb3ecc131defae06d055ca1883e3d95a31..db2c782828dd6eaefe02169efade22ef50fb42a3 100644 (file)
--- a/man2/pivot_root.2
+++ b/man2/pivot_root.2
@@ -25,15 +25,6 @@ The calling process must have the
 .B CAP_SYS_ADMIN
 capability in the user namespace that owns the caller's mount namespace.
 .PP
-A typical use of
-.BR pivot_root ()
-is during system startup, when the
-system mounts a temporary root filesystem (e.g., an \fBinitrd\fP), then
-mounts the real root filesystem, and eventually turns the latter into
-the current root of all relevant processes or threads.
-A modern use is to set up a root filesystem during
-the creation of a container.
-.PP
 .BR pivot_root ()
 may or may not change the current root and the current
 working directory of any processes or threads that
@@ -166,6 +157,24 @@ is Linux-specific and hence is not portable.
 Glibc does not provide a wrapper for this system call; call it using
 .BR syscall (2).
 .PP
+.BR pivot_root ()
+allows the caller to switch to a new root filesystem while at the same time
+placing the old root mount at a location under
+.I new_root
+from where it can subsequently be unmounted.
+(The fact that it moves all processes that have a root directory
+or current working directory on the old root filesystem to the
+new root filesystem frees the old root filesystem of users,
+allowing it to be unmounted more easily.)
+A typical use of
+.BR pivot_root ()
+is during system startup, when the
+system mounts a temporary root filesystem (e.g., an \fBinitrd\fP), then
+mounts the real root filesystem, and eventually turns the latter into
+the current root of all relevant processes or threads.
+A modern use is to set up a root filesystem during
+the creation of a container.
+.PP
 The rootfs (initial ramfs) cannot be
 .BR pivot_root ()ed.
 The recommended method of changing the root filesystem in this case is