cap_iab.3 doc fixes and cleanup

Signed-off-by: Andrew G. Morgan <morgan@kernel.org>

1 files changed, 31 insertions, 34 deletions

diff --git a/doc/cap_iab.3 b/doc/cap_iab.3
index ebcc87f..a0ec988 100644
--- a/doc/cap_iab.3
+++ b/doc/cap_iab.3
@@ -1,4 +1,4 @@
-.TH CAP_IAB 3 "2021-08-29" "" "Linux Programmer's Manual"
+.TH CAP_IAB 3 "2021-09-01" "" "Linux Programmer's Manual"
 .SH NAME
 .nf
 #include <sys/capability.h>
@@ -36,29 +36,26 @@ inheritable process capability vectors: Inh, Amb and Bound. This
 \fIcap_iab_t\fP combine to pass capabilities from one process to
 another through
 .BR execve (2)
-system calls. The convolution rules using the IAB set are a fail over
+system calls. The convolution rules using the IAB tuple are a fail over
 set of rules when the executed file has no configured
 \fIfile-capabilities\fP.
 .PP
 There are some constraints enforced by the kernel with respect to the
-three components of an IAB set and the Permitted process capability
+three components of an IAB tuple and the Permitted process capability
 flag. They are: the Inh vector is entirely equal to the process
 Inheritable flag at all times; the the Amb vector contains no more
 capability values than the intersection of the Inh vector and the
-Permitted flag for the process; no Amb value blocked in the Bound
-Vector will survive
-.BR execve (2);
-and the Bound (or \fIblocked\fP) vector is the twos-complement of the
-process bounding set.
+Permitted flag for the process; and the Bound (or \fIblocked\fP)
+vector is the twos-complement of the process bounding vector.
 .PP
-In some environments, it is considered desirable to naively inherit
-capabilities. That is pass capabilities, independent of the status of
-the executed binary, from parent to child through exec* system
-calls. The surviving capabilities become the Permitted flag for the
-post-exec process. This method of inheritance differs significantly
-from the handshake inheritance between pre-exec* process and
-file-capability bestowed executable of the traditional capability
-mechanism.
+In some environments, it is considered desirable to \fInaively\fP
+inherit capabilities. That is pass capabilities, independent of the
+status of the executed binary, from parent to child through
+\fBexec*\fP system calls. The surviving capabilities become the
+Permitted flag for the post-exec process. This method of inheritance
+differs significantly from the handshake inheritance between a
+pre-exec* process and a file-capability bestowed executable of the
+traditional (POSIX.1e) capability mechanism.
 .PP
 The convolution rules for IAB style inheritance are: I'=I; A'=A&I;
 P'=A&I&P. Where P etc are the pre-exec values and P' etc are the
@@ -66,12 +63,13 @@ post-exec values.
 .PP
 With an understanding of these convolution rules, we can explain how
 .BR libcap (3)
-support for the IAB set is managed: the IAB API.
+support for the IAB tuple is managed: the IAB API.
 .PP
 .BR cap_iab_init ()
 returns an empty IAB value. That is a \fImostly-harmless\fP tuple. It
-will not block and capabilities through exec, but it won't bestow any
-either. The returned cap_iab_t should be freed with
+will not block any Permitted file capabilities through exec, but it
+won't bestow any either. The returned \fIcap_iab_t\fP should be freed
+with
 .BR cap_free (3).
 .sp
 .BR cap_iab_get_proc ()
@@ -91,13 +89,13 @@ process requires CAP_SETPCAP raised in the E flag and a superset of P
 and I values over those in the A vectors.
 .sp
 .BR cap_iab_to_text ()
-will convert an IAB set to a canonical text representation. The
+will convert an IAB tuple to a canonical text representation. The
 representation is slightly redundant but libcap will try to generate
 as short a representation as it is able.
 .sp
 .BR cap_iab_from_text ()
-generates an IAB set from a text string (likely generated by the
-previous function). The returned IAB set should be freed with
+generates an IAB tuple from a text string (likely generated by the
+previous function). The returned IAB tuple should be freed with
 .BR cap_free (3).
 .sp
 The text format accepted by
@@ -118,19 +116,18 @@ vector.
 .sp
 .BR cap_iab_compare ()
 can be used to compare two cap_iab_t tuples. When the return value is
-non-zero, the macro
-.B CAP_IAB_DIFFERS
-.RI ( status ", " vector )
+non-zero, the macro \fBCAP_IAB_DIFFERS\fR(\fIstatus\fR, \fIvector\fR)
 evaluates to non-zero if the returned status differs in its
 .I vector
 components.
 .sp
 .BR cap_iab_set_vector ()
 can be used to set a specific vector value to the enable setting.
+.sp
 .BR cap_iab_fill ()
 can be used to wholesale copy a cap_t flag value into the vec vector
-of the IAB set. Copying into Amb in this way may implicitly raise Inh
-values in the IAB set. Similarly copying into the Inh vector may
+of the IAB tuple. Copying into Amb in this way may implicitly raise Inh
+values in the IAB tuple. Similarly copying into the Inh vector may
 implicitly lower Amb values that are not present in the resulting Inh
 vector.
 .SH "ERRORS"
@@ -143,10 +140,10 @@ In the case of error consult \fIerrno\fP.
 .SH "NOTES"
 .PP
 Unlike the traditional \fIcap_t\fP capability set, the
-IAB set, taken together, is incompatible with filesystem capabilities
+IAB tuple, taken together, is incompatible with filesystem capabilities
 created via tools like
 .BR setcap (8).
-That is, the Amb vector of the IAB set is rendered moot when an
+That is, the Amb vector of the IAB tuple is rendered moot when an
 executable with a file capability is executed.
 .PP
 Further, there are libcap
@@ -160,17 +157,17 @@ developed as the configuration syntax for the \fIpam_cap.so\fP
 Linux-PAM module in libcap-2.29. It was introduced to extend the
 \fIsimple\fP comma separated list of process Inheritable capabilities,
 that the module could besow on an authenticated process tree, to
-include enforced limits on the Bounding set and introduce support for
-the Amibient set of capability bits.
+include enforced limits on the Bounding vector and introduce support
+for the Amibient vector of capability bits.
 
-While the Inheritable and Bounding sets were anticipated by the
-POSIX.1e draft that introduced capabilities, the Ambient set is a
+While the Inheritable and Bounding vectors were anticipated by the
+POSIX.1e draft that introduced capabilities, the Ambient vector is a
 Linux invention, and incompatible with the POSIX.1e file capability
 model. As such, it was felt that trying to meld together all of the 5
 capability vectors into one text representation was not going to
 work. Instead the \fIpam_cap.so\fP config syntax was generalized into
 a whole set of libcap functions for bundling together all three
-naively inheritable capabilities: the IAB set. The support for this
+naively inheritable capabilities: the IAB tuple. The support for this
 debuted in libcap-2.33.
 .SH "REPORTING BUGS"
 Please report bugs via: