[PATCH 13/15] Manual pages: cap_get_proc.3: Update description of capsetp()

[Michael Kerrisk (man-pages)]

The details currently provided for capsetp() were current before 2008,
but ceased to be accurate with the 2008 addition of VFS file
capabilities in 2008. Update the text accordingly.

At the same time, add a subheading, a few paragraph breaks, and a few
other wording tweaks to make the description of capgetp() and capsetp()
more readable.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages at gmail.com>
---
 doc/cap_get_proc.3 | 40 +++++++++++++++++++++++++++-------------
 1 file changed, 27 insertions(+), 13 deletions(-)

diff --git a/doc/cap_get_proc.3 b/doc/cap_get_proc.3
index fce8f59..40475fd 100644
--- a/doc/cap_get_proc.3
+++ b/doc/cap_get_proc.3
@@ -251,7 +251,7 @@ or,
 When linked this way, due to linker magic, libcap uses
 .BR psx_syscall "(3) and " psx_syscall6 (3)
 to perform state setting system calls.
-.PP
+.SS capgetp() and capsetp()
 The library also supports the deprecated functions:
 .PP
 .BI "int capgetp(pid_t " pid ", cap_t " cap_d );
@@ -264,14 +264,20 @@ capabilities in a pre-allocated
 .IR cap_d .
 See
 .BR cap_init ()
-for information on allocating an empty capability set. This function,
-.BR capgetp (),
-is deprecated, you should use
+for information on allocating an empty capability set. This function
+is deprecated; you should use
 .BR cap_get_pid ().
 .PP
 .BR capsetp ()
-attempts to set the capabilities of some other process(es),
-.IR pid . 
+attempts to set the capabilities of the calling porcess or of
+some other process(es),
+.IR pid .
+Note that setting capabilities of another process is only possible on older
+kernels that do not provide VFS support for setting file capabilities.
+See
+.BR capset (2)
+for information on which kernels provide such support.
+.PP
 If
 .I pid
 is positive it refers to a specific process;  if it is zero, it refers
@@ -280,29 +286,37 @@ calling process and process '1' (typically
 .BR init (8));
 other negative values refer to the
 .I \-pid
-process group.  In order to use this function, the kernel must support
+process group.
+.PP
+In order to use this function, the kernel must support
 it and the calling process must have
 .B CAP_SETPCAP
 raised in its Effective capability set. The capabilities set in the
 target process(es) are those contained in
 .IR cap_d .
+.PP
 Kernels that support filesystem capabilities redefine the semantics of
 .B CAP_SETPCAP
-and on such systems this function will always fail for any target not
+and on such systems,
+.BR capsetp ()
+will always fail for any target not
 equal to the calling process.
 .BR capsetp ()
 returns zero for success, and \-1 on failure.
-
-Where supported by the kernel, the function
+.PP
+On kernels where it is (was) supported,
 .BR capsetp ()
 should be used with care.  It existed, primarily, to overcome an early
 lack of support for capabilities in the filesystems supported by
-Linux.  Note that, by default, the only processes that have
+Linux.  Note that on older kernels where
+.BR capsetp ()
+could be used to set the capabilities of another process,
+the only processes that had
 .B CAP_SETPCAP
-available to them are processes started as a kernel thread.
+available to them by default were processes started as kernel threads.
 (Typically this includes
 .BR init (8),
-kflushd and kswapd.) You will need to recompile the kernel to modify
+kflushd and kswapd.) A kernel recompilation was needed to modify
 this default.
 .SH EXAMPLE
 The code segment below raises the
-- 
2.26.2