Be more systematic about POSIX.1e value group names

cap.Set's have Flag component Values
cap.IAB's have Vector component Values

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

6 files changed, 94 insertions, 78 deletions

diff --git a/cap/convenience.go b/cap/convenience.go
index c40b63d..e832981 100644
--- a/cap/convenience.go
+++ b/cap/convenience.go
@@ -57,7 +57,7 @@ func (sc *syscaller) setSecbits(s Secbits) error {
 
 // Set attempts to force the process Secbits to a value. This function
 // will raise cap.SETPCAP in order to achieve this operation, and will
-// completely lower the Effective  vector of the process returning.
+// completely lower the Effective Flag of the process upon returning.
 func (s Secbits) Set() error {
 	state, sc := scwStateSC()
 	defer scwSetState(launchBlocked, state, -1)
@@ -234,11 +234,11 @@ func (sc *syscaller) setUID(uid int) error {
 // all other variants of UID (EUID etc) to the specified value without
 // dropping the privilege of the current process. This function will
 // raise cap.SETUID in order to achieve this operation, and will
-// completely lower the Effective vector of the process before
+// completely lower the Effective Flag of the process before
 // returning. Unlike the traditional method of dropping privilege when
-// changing from [E]UID=0 to some other UID, this function only
-// performs a change of UID cap.SETUID is available, and the action
-// does not alter the Permitted Flag of the process' Set.
+// changing from [E]UID=0 to some other UID, this function only can
+// perform any change of UID if cap.SETUID is available, and this
+// operation will not alter the Permitted Flag of the process' Set.
 func SetUID(uid int) error {
 	state, sc := scwStateSC()
 	defer scwSetState(launchBlocked, state, -1)
diff --git a/cap/file.go b/cap/file.go
index 70dae92..a309bd0 100644
--- a/cap/file.go
+++ b/cap/file.go
@@ -229,20 +229,22 @@ func (c *Set) packFileCap() ([]byte, error) {
 // (*os.File).Fd(). This function can also be used to delete a file's
 // capabilities, by calling with c = nil.
 //
-// Note, Linux does not store the full Effective Value Flag in the
-// metadata for the file. Only a single Effective bit is stored in
-// this metadata. This single bit is non-zero if the Effective vector
-// has any overlapping bits with the Permitted or Inheritable vector
-// of c. This may appear suboptimal, but the reasoning behind it is
-// sound. Namely, the purpose of the Effective bit it to support
-// capabability unaware binaries that will only work if they magically
-// launch with the needed bits already raised (this bit is sometimes
-// referred to simply as the 'legacy' bit). Without *full* support for
-// capability manipulation, as it is provided in this "../libcap/cap"
-// package, this was the only way for Go programs to make use of
+// Note, Linux does not store the full Effective Flag in the metadata
+// for the file. Only a single Effective bit is stored in this
+// metadata. This single bit is non-zero if the Effective Flag has any
+// overlapping bits with the Permitted or Inheritable Flags of c. This
+// may appear suboptimal, but the reasoning behind it is sound.
+// Namely, the purpose of the Effective bit it to support capabability
+// unaware binaries that will only work if they magically launch with
+// the needed Values already raised (this bit is sometimes referred to
+// simply as the 'legacy' bit).
+//
+// Historical note: without *full* support for runtime capability
+// manipulation, as it is provided in this "../libcap/cap" package,
+// this was previously the only way for Go programs to make use of
 // file capabilities.
 //
-// The preferred way a binary will actually manipulate its
+// The preferred way that a binary will actually manipulate its
 // file-acquired capabilities is to carefully and deliberately use
 // this package (or libcap, assisted by libpsx, for threaded C/C++
 // family code).
@@ -272,7 +274,7 @@ func (c *Set) SetFd(file *os.File) error {
 // capabilities, by calling with c = nil.
 //
 // Note, see the comment for SetFd() for some non-obvious behavior of
-// Linux for the Effective Value vector on the modified file.
+// Linux for the Effective Flag on the modified file.
 func (c *Set) SetFile(path string) error {
 	fi, err := os.Stat(path)
 	if err != nil {
diff --git a/cap/flags.go b/cap/flags.go
index d46634d..310ac5d 100644
--- a/cap/flags.go
+++ b/cap/flags.go
@@ -2,8 +2,8 @@ package cap
 
 import "errors"
 
-// GetFlag determines if the requested bit is enabled in the Flag
-// vector of the capability Set.
+// GetFlag determines if the requested Value is enabled in the
+// specified Flag of the capability Set.
 func (c *Set) GetFlag(vec Flag, val Value) (bool, error) {
 	if c == nil || len(c.flat) == 0 {
 		// Checked this first, because otherwise we are sure
@@ -96,10 +96,10 @@ func (c *Set) Fill(to, from Flag) error {
 // ErrBadValue indicates a bad capability value was specified.
 var ErrBadValue = errors.New("bad capability value")
 
-// bitOf converts from a Value into the offset and mask for a
-// specific Value bit in the compressed (kernel ABI) representation of
-// a capability vector. If the requested bit is unsupported, an error
-// is returned.
+// bitOf converts from a Value into the offset and mask for a specific
+// Value bit in the compressed (kernel ABI) representation of a
+// capabilities. If the requested bit is unsupported, an error is
+// returned.
 func bitOf(vec Flag, val Value) (uint, uint32, error) {
 	if vec > Inheritable || val > Value(words*32) {
 		return 0, 0, ErrBadValue
@@ -126,7 +126,7 @@ func allMask(index uint) (mask uint32) {
 }
 
 // forceFlag sets 'all' capability values (supported by the kernel) of
-// a flag vector to enable.
+// a specified Flag to enable.
 func (c *Set) forceFlag(vec Flag, enable bool) error {
 	if c == nil || len(c.flat) == 0 || vec > Inheritable {
 		return ErrBadSet
@@ -143,8 +143,7 @@ func (c *Set) forceFlag(vec Flag, enable bool) error {
 	return nil
 }
 
-// ClearFlag clears a specific vector of Values associated with the
-// specified Flag.
+// ClearFlag clears all the Values associated with the specified Flag.
 func (c *Set) ClearFlag(vec Flag) error {
 	return c.forceFlag(vec, false)
 }
diff --git a/cap/names.go b/cap/names.go
index 8ee96d1..356da9e 100644
--- a/cap/names.go
+++ b/cap/names.go
@@ -70,24 +70,29 @@ const (
 	SETUID
 
 	// SETPCAP allows a process to freely manipulate its inheritable
-	// capabilities.  Linux supports the POSIX.1e Inheritable
-	// set, as well as Bounding and Ambient Linux extension
-	// vectors. This capability permits dropping bits from the
-	// Bounding vector. It also permits the process to raise
-	// Ambient vector bits that are both raised in the
-	// Permitted and Inheritable sets of the process. This
-	// capability cannot be used to raise Permitted bits, or
-	// Effective bits beyond those already present in the
-	// process' permitted set.
+	// capabilities.
 	//
-	// [Historical note: prior to the advent of file
-	// capabilities (2008), this capability was suppressed by
-	// default, as its unsuppressed behavior was not
-	// auditable: it could asynchronously grant its own
-	// Permitted capabilities to and remove capabilities from
-	// other processes arbitrarily. The former leads to
-	// undefined behavior, and the latter is better served by
-	// the kill system call.]
+	// Linux supports the POSIX.1e Inheritable set, the POXIX.1e (X
+	// vector) known in Linux as the Bounding vector, as well as
+	// the Linux extension Ambient vector.
+	//
+	// This capability permits dropping bits from the Bounding
+	// vector (ie. raising B bits in the libcap IAB
+	// representation). It also permits the process to raise
+	// Ambient vector bits that are both raised in the Permitted
+	// and Inheritable sets of the process. This capability cannot
+	// be used to raise Permitted bits, Effective bits beyond those
+	// already present in the process' permitted set, or
+	// Inheritable bits beyond those present in the Bounding
+	// vector.
+	//
+	// [Historical note: prior to the advent of file capabilities
+	// (2008), this capability was suppressed by default, as its
+	// unsuppressed behavior was not auditable: it could
+	// asynchronously grant its own Permitted capabilities to and
+	// remove capabilities from other processes arbitrarily. The
+	// former leads to undefined behavior, and the latter is better
+	// served by the kill system call.]
 	SETPCAP
 
 	// LINUX_IMMUTABLE allows a process to modify the S_IMMUTABLE and
diff --git a/doc/values/8.txt b/doc/values/8.txt
index d7654f0..de0b47c 100644
--- a/doc/values/8.txt
+++ b/doc/values/8.txt
@@ -1,19 +1,24 @@
 Allows a process to freely manipulate its inheritable
-capabilities.  Linux supports the POSIX.1e Inheritable
-set, as well as Bounding and Ambient Linux extension
-vectors. This capability permits dropping bits from the
-Bounding vector. It also permits the process to raise
-Ambient vector bits that are both raised in the
-Permitted and Inheritable sets of the process. This
-capability cannot be used to raise Permitted bits, or
-Effective bits beyond those already present in the
-process' permitted set.
+capabilities.
 
-[Historical note: prior to the advent of file
-capabilities (2008), this capability was suppressed by
-default, as its unsuppressed behavior was not
-auditable: it could asynchronously grant its own
-Permitted capabilities to and remove capabilities from
-other processes arbitrarily. The former leads to
-undefined behavior, and the latter is better served by
-the kill system call.]
+Linux supports the POSIX.1e Inheritable set, the POXIX.1e (X
+vector) known in Linux as the Bounding vector, as well as
+the Linux extension Ambient vector.
+
+This capability permits dropping bits from the Bounding
+vector (ie. raising B bits in the libcap IAB
+representation). It also permits the process to raise
+Ambient vector bits that are both raised in the Permitted
+and Inheritable sets of the process. This capability cannot
+be used to raise Permitted bits, Effective bits beyond those
+already present in the process' permitted set, or
+Inheritable bits beyond those present in the Bounding
+vector.
+
+[Historical note: prior to the advent of file capabilities
+(2008), this capability was suppressed by default, as its
+unsuppressed behavior was not auditable: it could
+asynchronously grant its own Permitted capabilities to and
+remove capabilities from other processes arbitrarily. The
+former leads to undefined behavior, and the latter is better
+served by the kill system call.]
diff --git a/progs/capshdoc.h b/progs/capshdoc.h
index c182144..2ac6ecb 100644
--- a/progs/capshdoc.h
+++ b/progs/capshdoc.h
@@ -64,24 +64,29 @@ static const char *explanation7[] = {  /* cap_setuid = 7 */
 };
 static const char *explanation8[] = {  /* cap_setpcap = 8 */
     "Allows a process to freely manipulate its inheritable",
-    "capabilities.  Linux supports the POSIX.1e Inheritable",
-    "set, as well as Bounding and Ambient Linux extension",
-    "vectors. This capability permits dropping bits from the",
-    "Bounding vector. It also permits the process to raise",
-    "Ambient vector bits that are both raised in the",
-    "Permitted and Inheritable sets of the process. This",
-    "capability cannot be used to raise Permitted bits, or",
-    "Effective bits beyond those already present in the",
-    "process' permitted set.",
+    "capabilities.",
     "",
-    "[Historical note: prior to the advent of file",
-    "capabilities (2008), this capability was suppressed by",
-    "default, as its unsuppressed behavior was not",
-    "auditable: it could asynchronously grant its own",
-    "Permitted capabilities to and remove capabilities from",
-    "other processes arbitrarily. The former leads to",
-    "undefined behavior, and the latter is better served by",
-    "the kill system call.]",
+    "Linux supports the POSIX.1e Inheritable set, the POXIX.1e (X",
+    "vector) known in Linux as the Bounding vector, as well as",
+    "the Linux extension Ambient vector.",
+    "",
+    "This capability permits dropping bits from the Bounding",
+    "vector (ie. raising B bits in the libcap IAB",
+    "representation). It also permits the process to raise",
+    "Ambient vector bits that are both raised in the Permitted",
+    "and Inheritable sets of the process. This capability cannot",
+    "be used to raise Permitted bits, Effective bits beyond those",
+    "already present in the process' permitted set, or",
+    "Inheritable bits beyond those present in the Bounding",
+    "vector.",
+    "",
+    "[Historical note: prior to the advent of file capabilities",
+    "(2008), this capability was suppressed by default, as its",
+    "unsuppressed behavior was not auditable: it could",
+    "asynchronously grant its own Permitted capabilities to and",
+    "remove capabilities from other processes arbitrarily. The",
+    "former leads to undefined behavior, and the latter is better",
+    "served by the kill system call.]",
     NULL
 };
 static const char *explanation9[] = {  /* cap_linux_immutable = 9 */