Reviewed man pages, adding overlooked references.

This started out as addressing this bug:

   https://bugzilla.kernel.org/show_bug.cgi?id=216585

But I then made crosslink.sh to figure out what I had missed, and
fixed those bits too.

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

11 files changed, 150 insertions, 29 deletions

diff --git a/doc/Makefile b/doc/Makefile
index c7d50e0..c096a9f 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -11,6 +11,7 @@ MAN3S = cap_init.3 cap_free.3 cap_dup.3 \
 	cap_fill.3 cap_fill_flag.3 cap_max_bits.3 \
 	cap_compare.3 cap_get_proc.3 cap_get_pid.3 cap_set_proc.3 \
 	cap_get_file.3 cap_get_fd.3 cap_set_file.3 cap_set_fd.3 \
+	cap_set_nsowner.3 cap_get_nsowner.3 \
 	cap_copy_ext.3 cap_size.3 cap_copy_int.3 cap_mode.3 \
 	cap_from_text.3 cap_to_text.3 cap_from_name.3 cap_to_name.3 \
 	capsetp.3 capgetp.3 libcap.3 \
@@ -25,7 +26,8 @@ MAN3S = cap_init.3 cap_free.3 cap_dup.3 \
 	cap_iab.3 cap_iab_init.3 cap_iab_dup.3 cap_iab_compare.3 \
 	cap_iab_get_proc.3 cap_iab_get_pid.3 cap_iab_set_proc.3 \
 	cap_iab_to_text.3 cap_iab_from_text.3 cap_iab_get_vector.3 \
-	cap_iab_set_vector.3 cap_iab_fill.3 \
+	cap_iab_set_vector.3 cap_iab_fill.3 cap_proc_root.3 \
+	cap_prctl.3 cap_prctlw.3 \
 	psx_syscall.3 psx_syscall3.3 psx_syscall6.3 psx_set_sensitivity.3 \
 	libpsx.3
 MAN8S = getcap.8 setcap.8 getpcaps.8 captree.8
diff --git a/doc/cap_clear.3 b/doc/cap_clear.3
index 19a736a..b8dbc30 100644
--- a/doc/cap_clear.3
+++ b/doc/cap_clear.3
@@ -1,6 +1,6 @@
-.TH CAP_CLEAR 3 "2021-10-01" "" "Linux Programmer's Manual"
+.TH CAP_CLEAR 3 "2022-10-16" "" "Linux Programmer's Manual"
 .SH NAME
-cap_clear, cap_clear_flag, cap_get_flag, cap_set_flag, cap_fill_flag, cap_fill, cap_compare \- capability data object manipulation
+cap_clear, cap_clear_flag, cap_get_flag, cap_set_flag, cap_fill_flag, cap_fill, cap_compare, cap_max_bits \- capability data object manipulation
 .SH SYNOPSIS
 .nf
 #include <sys/capability.h>
diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
index 4c812fe..985236c 100644
--- a/doc/cap_get_file.3
+++ b/doc/cap_get_file.3
@@ -1,10 +1,10 @@
 .\"
 .\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
 .\"
-.TH CAP_GET_FILE 3 "2021-03-06" "" "Linux Programmer's Manual"
+.TH CAP_GET_FILE 3 "2022-10-16" "" "Linux Programmer's Manual"
 .SH NAME
-cap_get_file, cap_set_file, cap_get_fd, cap_set_fd \- capability
-manipulation on files
+cap_get_file, cap_set_file, cap_get_fd, cap_set_fd, cap_get_nsowner, \
+cap_set_nsowner \- capability manipulation on files
 .SH SYNOPSIS
 .nf
 #include <sys/capability.h>
diff --git a/doc/cap_get_nsowner.3 b/doc/cap_get_nsowner.3
new file mode 100644
index 0000000..3970c34
--- /dev/null
+++ b/doc/cap_get_nsowner.3
@@ -0,0 +1 @@
+.so man3/cap_get_file.3
diff --git a/doc/cap_iab.3 b/doc/cap_iab.3
index b8bab84..3e6282d 100644
--- a/doc/cap_iab.3
+++ b/doc/cap_iab.3
@@ -1,38 +1,28 @@
-.TH CAP_IAB 3 "2021-11-17" "" "Linux Programmer's Manual"
+.TH CAP_IAB 3 "2022-10-16" "" "Linux Programmer's Manual"
 .SH NAME
 cap_iab_init, cap_iab_dup, cap_iab_get_proc, cap_iab_get_pid, \
 cap_iab_set_proc, cap_iab_to_text, cap_iab_from_text, \
 cap_iab_get_vector, cap_iab_compare, cap_iab_set_vector, \
-cap_iab_fill \- inheritable IAB tuple support functions
+cap_iab_fill, cap_proc_root \- inheritable IAB tuple support functions
 .SH SYNOPSIS
 .nf
 #include <sys/capability.h>
 
 cap_iab_t cap_iab_init(void);
-
 cap_iab_t cap_iab_dup(cap_iab_t iab);
-
 cap_iab_t cap_iab_get_proc(void);
-
 cap_iab_t cap_iab_get_pid(pid_t pid);
-
 int cap_iab_set_proc(cap_iab_t iab);
-
 char *cap_iab_to_text(cap_iab_t iab);
-
 cap_iab_t cap_iab_from_text(const char *text);
-
 cap_flag_value_t cap_iab_get_vector(cap_iab_t iab, cap_iab_vector_t vec,
     cap_value_t val);
-
 int cap_iab_compare(cap_iab_t a, cap_iab_t b);
-
 int cap_iab_set_vector(cap_iab_t iab, cap_iab_vector_t vec, cap_value_t val,
     cap_flag_value_t enable);
-
 int cap_iab_fill(cap_iab_t iab, cap_iab_vector_t vec,
     cap_t set, cap_flag_t flag);
-
+char *cap_proc_root(const char *root);
 .fi
 .sp
 Link with \fI\-lcap\fP.
@@ -93,6 +83,11 @@ cap_iab_t should be freed with
 returns a copy of the IAB value for the specified process.  The returned
 cap_iab_t should be freed with
 .BR cap_free (3).
+This function defaults to searching
+.BR /proc/ <PID> /status
+for the IAB information, but that location can be overridden using the
+.BR cap_proc_root ()
+function.
 .sp
 .BR cap_iab_set_proc ()
 can be used to set the IAB value carried by the current process. Such
@@ -142,6 +137,19 @@ 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.
+.sp
+.BR cap_proc_root ()
+can be used to determine the current location queried by
+.BR cap_iab_get_pid ().
+Returned values should be released with
+.BR cap_free (3).
+If the argument to
+.BR cap_proc_root ()
+is not \fBNULL\fP, a copy of it will become the replacement for
+.BR /proc .
+Note, this function is \fInot\fP thread safe with respect to
+concurrent calls to
+.BR cap_iab_get_pid ().
 .SH "ERRORS"
 The functions returning \fIcap_iab_t\fP values or allocated memory in
 the form of a string return NULL on error.
diff --git a/doc/cap_prctl.3 b/doc/cap_prctl.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/cap_prctl.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/cap_prctlw.3 b/doc/cap_prctlw.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/cap_prctlw.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/cap_proc_root.3 b/doc/cap_proc_root.3
new file mode 100644
index 0000000..3e730b1
--- /dev/null
+++ b/doc/cap_proc_root.3
@@ -0,0 +1 @@
+.so man3/cap_iab.3
diff --git a/doc/cap_set_nsowner.3 b/doc/cap_set_nsowner.3
new file mode 100644
index 0000000..3970c34
--- /dev/null
+++ b/doc/cap_set_nsowner.3
@@ -0,0 +1 @@
+.so man3/cap_get_file.3
diff --git a/doc/crosslink.sh b/doc/crosslink.sh
new file mode 100755
index 0000000..d701522
--- /dev/null
+++ b/doc/crosslink.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+#
+# So many cross links to maintain. Here is a script that I've used to
+# validate things at least conform to some structure:
+#
+for x in *.? ; do
+    y=$(grep -F '.so m' ${x} | awk '{print $2}' | sed -e 's/man..//')
+    if [ -z "${y}" ]; then
+	continue
+    fi
+    echo
+    echo "###########"
+    echo "${x} => ${y}"
+    grep -F "${x%.*}" "${y}"
+done
diff --git a/doc/libcap.3 b/doc/libcap.3
index c1ae4ba..a91cf7e 100644
--- a/doc/libcap.3
+++ b/doc/libcap.3
@@ -1,15 +1,21 @@
-.TH LIBCAP 3 "2021-03-06" "" "Linux Programmer's Manual"
+.TH LIBCAP 3 "2022-10-16" "" "Linux Programmer's Manual"
 .SH NAME
 cap_clear, cap_clear_flag, cap_compare, cap_copy_ext, cap_copy_int, \
-cap_free, cap_from_name, cap_from_text, cap_get_fd, cap_get_file, \
-cap_get_flag, cap_get_pid, cap_get_proc, cap_set_fd, cap_set_file, \
-cap_set_flag, cap_set_proc, cap_size, cap_to_name, cap_to_text, \
-cap_get_pid, cap_dup \- capability data object manipulation
+cap_drop_bound, cap_dup, cap_fill, cap_fill_flag, cap_free, cap_from_name, \
+cap_from_text, cap_get_ambient, cap_get_bound, cap_get_fd, \
+cap_get_file, cap_get_flag, cap_get_mode, cap_get_nsowner, cap_get_pid, \
+cap_get_pid, cap_get_proc, cap_get_secbits, cap_init, cap_max_bits, \
+cap_prctl, cap_prctlw, cap_proc_root, cap_reset_ambient, \
+cap_set_ambient, cap_set_fd, cap_set_file, cap_set_flag, cap_setgroups, \
+cap_set_mode, cap_set_nsowner, cap_set_proc, cap_set_secbits, \
+cap_setuid, cap_size, cap_to_name, cap_to_text \- capability data object manipulation
 .SH SYNOPSIS
 .nf
 #include <sys/capability.h>
 
 int cap_clear(cap_t cap_p);
+int cap_fill(cap_t cap_p, cap_flag_t to, cap_flag_t from);
+int cap_fill_flag(cap_t cap_p, cap_flag_t to, const cap_t ref, cap_flag_t from);
 int cap_clear_flag(cap_t cap_p, cap_flag_t flag);
 int cap_compare(cap_t cap_a, cap_t cap_b);
 ssize_t cap_copy_ext(void *ext_p, cap_t cap_p, ssize_t size);
@@ -36,18 +42,42 @@ ssize_t cap_size(cap_t cap_p);
 char *cap_to_name(cap_value_t cap);
 char *cap_to_text(cap_t caps, ssize_t *length_p);
 cap_t cap_get_pid(pid_t pid);
+cap_t cap_init();
 cap_t cap_dup(cap_t cap_p);
+
+char *cap_proc_root(const char *root);
+int cap_get_nsowner(cap_t cap_p);
+int cap_set_nsowner(cap_t cap_p, uid_t rootuid);
+int cap_get_bound(cap_value_t cap);
+int cap_drop_bound(cap_value_t cap);
+int cap_get_ambient(cap_value_t cap);
+int cap_set_ambient(cap_value_t cap, cap_flag_value_t value);
+int cap_reset_ambient(void);
+int cap_set_mode(cap_mode_t flavor);
+cap_mode_t cap_get_mode(void);
+const char *cap_mode_name(cap_mode_t flavor);
+unsigned cap_get_secbits();
+int cap_set_secbits(unsigned bits);
+int cap_prctl(long int pr_cmd, long int arg1, long int arg2, long int arg3,
+              long int arg4, long int arg5);
+int cap_prctlw(long int pr_cmd, long int arg1, long int arg2, long int arg3,
+               long int arg4, long int arg5);
+int cap_setuid(uid_t uid);
+int cap_setgroups(gid_t gid, size_t ngroups, const gid_t groups[]);
 .fi
 .sp
 Link with \fI\-lcap\fP.
 .fi
 .SH DESCRIPTION
-These functions work on a capability state held in working storage.
+These primary functions work on a capability state held in working
+storage and attempt to complete the POSIX.1e (draft) user space API
+for Capability based privilege.
+.PP
 A
 .I cap_t
 holds information about the capabilities in each of the three sets,
-Permitted, Inheritable, and Effective.
-Each capability in a set may be clear (disabled, 0) or set (enabled, 1).
+Permitted, Inheritable, and Effective.  Each capability in a set may
+be clear (disabled, 0) or set (enabled, 1).
 .PP
 These functions work with the following data types:
 .TP 18
@@ -80,10 +110,65 @@ is set appropriately.
 These functions are as per the withdrawn POSIX.1e draft specification.
 The following functions are Linux extensions:
 .BR cap_clear_flag (),
+.BR cap_drop_bound (),
+.BR cap_fill (),
+.BR cap_fill_flag (),
 .BR cap_from_name (),
-.BR cap_to_name (),
+.BR cap_get_ambient (),
+.BR cap_get_bound (),
+.BR cap_get_mode (),
+.BR cap_get_nsowner (),
+.BR cap_get_secbits (),
+.BR cap_mode_name (),
+.BR cap_proc_root (),
+.BR cap_prctl (),
+.BR cap_prctlw (),
+.BR cap_reset_ambient (),
+.BR cap_setgroups (),
+.BR cap_setuid (),
+.BR cap_set_ambient (),
+.BR cap_set_mode (),
+.BR cap_set_nsowner (),
+.BR cap_set_secbits (),
+.BR cap_to_name ()
 and
 .BR cap_compare ().
+.PP
+A Linux, \fIIAB\fP, extension of Inheritable, Bounding and Ambient
+tuple capability vectors are also supported by \fBlibcap\fP. Those
+functions are described in a companion man page:
+.BR cap_iab (3).
+Further, for managing the complexity of launching a sub-process,
+\fBlibcap\fP supports the abstraction:
+.BR cap_launch (3).
+.PP
+In addition to the \fBcap_\fP prefixed \fBlibcap\fP API, the library
+also provides prototypes for the Linux system calls that provide the
+native API for process capabilities. These prototypes are:
+.sp
+.nf
+int capget(cap_user_header_t header, cap_user_data_t data);
+int capset(cap_user_header_t header, const cap_user_data_t data);
+.fi
+.sp
+Further, \fBlibcap\fP provides a set-up function,
+.sp
+.nf
+void cap_set_syscall(
+        long int (*new_syscall)(long int, long int, long int, long int),
+        long int (*new_syscall6)(long int,
+                                 long int, long int, long int,
+                                 long int, long int, long int));
+.fi
+.sp
+which can be used to redirect its use of the
+.BR capset ()
+and other system calls that write kernel managed state. This is
+especially useful when supporting POSIX semantics for security
+state. When a program is linked against
+.BR libpsx (3)
+as described in that man page, this function is used to connect
+\fBlibcap\fP to POSIX semantics system calls.
 .SH "REPORTING BUGS"
 The
 .B libcap
@@ -99,9 +184,15 @@ https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757
 .BR cap_from_text (3),
 .BR cap_get_file (3),
 .BR cap_get_proc (3),
+.BR cap_iab (3),
 .BR cap_init (3),
+.BR cap_launch (3),
 .BR capabilities (7),
 .BR getpid (2),
-.BR capsh (1)
+.BR capsh (1),
+.BR captree (8),
+.BR getcap (8),
+.BR getpcaps (8),
+.BR setcap (8)
 and
 .BR libpsx (3).