Tweaking the psx and cap package documentation further.psx/v0.2.42-rc2cap/v0.2.42-rc2

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

4 files changed, 51 insertions, 34 deletions

diff --git a/cap/cap.go b/cap/cap.go
index e00affe..ed087e1 100644
--- a/cap/cap.go
+++ b/cap/cap.go
@@ -41,7 +41,7 @@
 // POSIX semantics system calls that manipulate thread state
 // uniformly over the whole Go (and CGo linked) process runtime.
 //
-// Note, if the Go runtime syscall interface contains the linux
+// Note, if the Go runtime syscall interface contains the Linux
 // variant syscall.AllThreadsSyscall() API (it is not in go1.15rc1
 // for example, but see https://github.com/golang/go/issues/1435 for
 // current status) then this present package can use that to invoke
@@ -51,7 +51,7 @@
 //
 //   CGO_ENABLED=0 go build -tags allthreadssyscall ...
 //
-// ------------------------------------------------------------------
+//
 // Copyright (c) 2019,20 Andrew G. Morgan <morgan@kernel.org>
 //
 // The cap and psx packages are licensed with a (you choose) BSD
diff --git a/cap/names.go b/cap/names.go
index d466719..ff60017 100644
--- a/cap/names.go
+++ b/cap/names.go
@@ -3,22 +3,23 @@ package cap
 /* ** DO NOT EDIT THIS FILE. IT WAS AUTO-GENERATED BY LIBCAP'S GO BUILDER (mknames.go) ** */
 
 // NamedCount holds the number of capability values with official
-// names at the time this libcap version, this package is part of, was
-// released.  The "../libcap/cap" package is fully able to manipulate
-// higher numbered capability values by numerical value. However, if
-// you find cap.NamedCount < cap.MaxBits(), it is probably time to
-// upgrade this package on your system.
+// names known at the time this libcap/cap version, was released. The
+// "../libcap/cap" package is fully able to manipulate higher numbered
+// capability values by numerical value. However, if you find
+// cap.NamedCount < cap.MaxBits(), it is probably time to upgrade this
+// package on your system.
 //
 // FWIW the userspace tool '/sbin/capsh' also contains a runtime check
-// for the condition that libcap is behind the kernel like this.
+// for the condition that libcap is behind the running kernel in this
+// way.
 const NamedCount = 40
 
-// CHOWN etc., are the named capability values of the Linux kernel. The
-// canonical source for each name is the "uapi/linux/capabilities.h"
-// file, a snapshot (from kernel.org) is hard-coded into this package.
-// Some values may not be available (yet) where the kernel is older.
-// The actual number of capabities supported by the running kernel can
-// be obtained using the cap.MaxBits() function.
+// CHOWN etc., are the named capability values of the Linux
+// kernel. The canonical source for each name is the
+// "uapi/linux/capabilities.h" file.  Some values may not be available
+// (yet) where the kernel is older.  The actual number of capabities
+// supported by the running kernel can be obtained using the
+// cap.MaxBits() function.
 const (
 	// CHOWN allows a process to arbitrarily change the user and
 	// group ownership of a file.
diff --git a/go/mknames.go b/go/mknames.go
index 754d2f8..ff07218 100644
--- a/go/mknames.go
+++ b/go/mknames.go
@@ -53,22 +53,23 @@ func main() {
 /* ** DO NOT EDIT THIS FILE. IT WAS AUTO-GENERATED BY LIBCAP'S GO BUILDER (mknames.go) ** */
 
 // NamedCount holds the number of capability values with official
-// names at the time this libcap version, this package is part of, was
-// released.  The "../libcap/cap" package is fully able to manipulate
-// higher numbered capability values by numerical value. However, if
-// you find cap.NamedCount < cap.MaxBits(), it is probably time to
-// upgrade this package on your system.
+// names known at the time this libcap/cap version, was released. The
+// "../libcap/cap" package is fully able to manipulate higher numbered
+// capability values by numerical value. However, if you find
+// cap.NamedCount < cap.MaxBits(), it is probably time to upgrade this
+// package on your system.
 //
 // FWIW the userspace tool '/sbin/capsh' also contains a runtime check
-// for the condition that libcap is behind the kernel like this.
+// for the condition that libcap is behind the running kernel in this
+// way.
 const NamedCount = `, len(list), `
 
-// CHOWN etc., are the named capability values of the Linux kernel. The
-// canonical source for each name is the "uapi/linux/capabilities.h"
-// file, a snapshot (from kernel.org) is hard-coded into this package.
-// Some values may not be available (yet) where the kernel is older.
-// The actual number of capabities supported by the running kernel can
-// be obtained using the cap.MaxBits() function.
+// CHOWN etc., are the named capability values of the Linux
+// kernel. The canonical source for each name is the
+// "uapi/linux/capabilities.h" file.  Some values may not be available
+// (yet) where the kernel is older.  The actual number of capabities
+// supported by the running kernel can be obtained using the
+// cap.MaxBits() function.
 const (
 `)
 	bits := make(map[string]string)
diff --git a/psx/psx.go b/psx/psx.go
index 7075362..7eaad55 100644
--- a/psx/psx.go
+++ b/psx/psx.go
@@ -9,19 +9,34 @@
 // The package works via CGo wrappers for system call functions that
 // call the C [lib]psx functions of these names. This ensures that the
 // system calls execute simultaneously on all the pthreads of the Go
-// (and CGo) combined runtime. Since Go's runtime freely migrates code
-// execution between pthreads, support of this type is required for
-// any successful attempt to fully drop or modify user privilege of a
-// Go program under Linux. More info on how privilege works can be
-// found here:
+// (and CGo) combined runtime.
+//
+// The psx support works in the following way: the pthread that is
+// first asked to execute the syscall does so, and determines if it
+// succeeds or fails. If it fails, it returns immediately without
+// attempting the syscall on other pthreads. If the initial attempt
+// succeeds, however, then the runtime is stopped in order for the
+// same system call to be performed on all the remaining pthreads of
+// the runtime. Once all pthreads have completed the syscall, the
+// return codes are those obtained by the first pthread's invocation
+// of the syscall.
+//
+// Note, there is no need to use this variant of syscall where the
+// syscalls only read state from the kernel. However, since Go's
+// runtime freely migrates code execution between pthreads, support of
+// this type is required for any successful attempt to fully drop or
+// modify the privilege of a running Go program under Linux.
+//
+// More info on how Linux privilege works can be found here:
 //
 //    https://sites.google.com/site/fullycapable
 //
-// Correct compilation of this package may require an extra step:
+// WARNING: Correct compilation of this package may require an extra
+// step:
 //
 // If your Go compiler is older than go1.15, a workaround may be
 // required to be able to link this package. In order to do what it
-// needs to, this package employs some unusual linking flags. You will
+// needs to this package employs some unusual linking flags. You will
 // need to do this for any Go toolchain that that does not include
 // this patch:
 //
@@ -35,7 +50,7 @@
 //
 //    export CGO_LDFLAGS_ALLOW="-Wl,-?-wrap[=,][^-.@][^,]*"
 //
-// ------------------------------------------------------------------
+//
 // Copyright (c) 2019,20 Andrew G. Morgan <morgan@kernel.org>
 //
 // The psx package is licensed with a (you choose) BSD 3-clause or