Add cap_iab_{compare,get_pid} functions to libcap; --iab to getpcaps.

This brings libcap back to parity with the Go 'cap' package. We
provide a CAP_IAB_DIFFERS(result, vector) macro to evaluate the result
of cap_iab_compare().

Extend the getpcaps arguments to include --iab. This causes the utility
to explore the IAB tuple for the specified process. When used, this
outputs a text representation in a similar format to that of the
'captree' (Go) utility.

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

5 files changed, 29 insertions, 1 deletions

diff --git a/doc/Makefile b/doc/Makefile
index a34cee0..943dbfa 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -21,7 +21,8 @@ MAN3S = cap_init.3 cap_free.3 cap_dup.3 \
 	cap_launcher_set_chroot.3 cap_launcher_set_mode.3 \
 	cap_launcher_setgroups.3 cap_launcher_setuid.3 \
 	cap_launcher_set_iab.3 cap_new_launcher.3 \
-	cap_iab.3 cap_iab_init.3 cap_iab_get_proc.3 cap_iab_set_proc.3 \
+	cap_iab.3 cap_iab_init.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 \
 	psx_syscall.3 psx_syscall3.3 psx_syscall6.3 libpsx.3
diff --git a/doc/cap_iab.3 b/doc/cap_iab.3
index a453428..7e87a0f 100644
--- a/doc/cap_iab.3
+++ b/doc/cap_iab.3
@@ -7,6 +7,8 @@ cap_iab_t cap_iab_init(void);
 
 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);
@@ -16,6 +18,8 @@ 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);
 
@@ -75,6 +79,11 @@ returns a copy of the IAB value for the current process.  The returned
 cap_iab_t should be freed with
 .BR cap_free (3).
 .sp
+.BR cap_iab_get_pid ()
+returns a copy of the IAB value for the specified process.  The returned
+cap_iab_t should be freed with
+.BR cap_free (3).
+.sp
 .BR cap_iab_set_proc ()
 can be used to set the IAB value carried by the current process. Such
 a setting will fail if the process is insufficiently capable. The
@@ -107,6 +116,15 @@ for the \fIpam_cap.so\fP config file.
 can be used to determine the specific capability value of an IAB
 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 )
+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.
 .BR cap_iab_fill ()
diff --git a/doc/cap_iab_compare.3 b/doc/cap_iab_compare.3
new file mode 100644
index 0000000..3e730b1
--- /dev/null
+++ b/doc/cap_iab_compare.3
@@ -0,0 +1 @@
+.so man3/cap_iab.3
diff --git a/doc/cap_iab_get_pid.3 b/doc/cap_iab_get_pid.3
new file mode 100644
index 0000000..3e730b1
--- /dev/null
+++ b/doc/cap_iab_get_pid.3
@@ -0,0 +1 @@
+.so man3/cap_iab.3
diff --git a/doc/getpcaps.8 b/doc/getpcaps.8
index d519357..3926a8c 100644
--- a/doc/getpcaps.8
+++ b/doc/getpcaps.8
@@ -33,11 +33,18 @@ Displays output in a somewhat ugly legacy format.
 .B \-\-verbose
 Displays usage in a legacy-like format but not quite so ugly in modern
 default terminal fonts.
+.TP
+.B \-\-iab
+Displays IAB tuple capabilities from the process. The output format
+here is unique. Double quotes encase the regular process capabilities
+and square brackets encase the IAB tuple.
 .SH SEE ALSO
 .BR capsh (1),
 .BR capabilities (7),
 .BR getcap (8),
 .BR setcap (8)
+and
+.BR cap_iab (3).
 .SH AUTHOR
 This manual page was originally written by Robert Bihlmeyer
 <robbe@debian.org>, for the Debian GNU/Linux system (but may be used