A libcap.3 man page and fix up the cap_get_pid() docs.

Make it easier to find what functions are available in
the API.

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

9 files changed, 149 insertions, 15 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 4ea2986..eb4b6a8 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -7,11 +7,11 @@ include $(topdir)/Make.Rules
 
 MAN3S = cap_init.3 cap_free.3 cap_dup.3 \
 	cap_clear.3 cap_clear_flag.3 cap_get_flag.3 cap_set_flag.3 \
-	cap_compare.3 cap_get_proc.3 cap_set_proc.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_copy_ext.3 cap_size.3 cap_copy_int.3 \
 	cap_from_text.3 cap_to_text.3 cap_from_name.3 cap_to_name.3 \
-	capsetp.3 capgetp.3
+	capsetp.3 capgetp.3 libcap.3
 MAN8S = getcap.8 setcap.8
 
 MANS = $(MAN3S) $(MAN8S)
diff --git a/doc/cap_clear.3 b/doc/cap_clear.3
index 32258ac..3fb5178 100644
--- a/doc/cap_clear.3
+++ b/doc/cap_clear.3
@@ -124,6 +124,7 @@ and
 .BR cap_compare ()
 are Linux extensions.
 .SH "SEE ALSO"
+.BR libcap (3),
 .BR cap_copy_ext (3),
 .BR cap_from_text (3),
 .BR cap_get_file (3),
diff --git a/doc/cap_copy_ext.3 b/doc/cap_copy_ext.3
index 8ec4d08..61d9381 100644
--- a/doc/cap_copy_ext.3
+++ b/doc/cap_copy_ext.3
@@ -95,6 +95,7 @@ or
 .SH "CONFORMING TO"
 These functions are specified in the withdrawn POSIX.1e draft specification.
 .SH "SEE ALSO"
+.BR libcap (3),
 .BR cap_clear (3),
 .BR cap_from_text (3),
 .BR cap_get_file (3),
diff --git a/doc/cap_from_text.3 b/doc/cap_from_text.3
index 995ddc3..1128df8 100644
--- a/doc/cap_from_text.3
+++ b/doc/cap_from_text.3
@@ -223,6 +223,7 @@ main(int argc, char *argv[])
 }
 .fi
 .SH "SEE ALSO"
+.BR libcap (3),
 .BR cap_clear (3),
 .BR cap_compare (3),
 .BR cap_copy_ext (3),
diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
index 0ed1249..107b6d1 100644
--- a/doc/cap_get_file.3
+++ b/doc/cap_get_file.3
@@ -115,6 +115,7 @@ and
 will have the Effective flag enabled for each capability that has the
 Permitted or Inheritable flag enabled.
 .SH "SEE ALSO"
+.BR libcap (3),
 .BR cap_clear (3),
 .BR cap_copy_ext (3),
 .BR cap_from_text (3),
diff --git a/doc/cap_get_pid.3 b/doc/cap_get_pid.3
new file mode 100644
index 0000000..65ea3e4
--- /dev/null
+++ b/doc/cap_get_pid.3
@@ -0,0 +1 @@
+.so man3/cap_get_proc.3
diff --git a/doc/cap_get_proc.3 b/doc/cap_get_proc.3
index ee586a2..18564e5 100644
--- a/doc/cap_get_proc.3
+++ b/doc/cap_get_proc.3
@@ -8,11 +8,13 @@ processes
 .SH SYNOPSIS
 .B #include <sys/capability.h>
 .sp
-.B cap_t cap_get_proc(void);
+.B "cap_t cap_get_proc(void);"
 .sp
 .BI "int cap_set_proc(cap_t " cap_p );
 .sp
-.BI "cap_t capgetp(pid_t " pid ", cap_t " cap_d );
+.B #include <sys/types.h>
+.sp
+.BI "cap_t cap_get_pid(pid_t " pid );
 .sp
 Link with \fI-lcap\fP.
 .SH DESCRIPTION
@@ -40,8 +42,8 @@ is set for any capability not currently permitted for the calling process,
 the function will fail, and the capability state of the process will remain
 unchanged.
 .PP
-.BR capgetp ()
-fills an existing
+.BR cap_get_pid ()
+returns
 .IR cap_d ,
 see 
 .BR cap_init (3),
@@ -51,12 +53,14 @@ This information can also be obtained from the
 .I /proc/<pid>/status
 file.
 .SH "RETURN VALUE"
+The functions
 .BR cap_get_proc ()
-returns a non-NULL value on success, and NULL on failure.
+and
+.BR cap_get_pid ()
+return a non-NULL value on success, and NULL on failure.
 .PP
+The function
 .BR cap_set_proc ()
-and
-.BR capgetp ()
 return zero for success, and \-1 on failure.
 .PP
 On failure,
@@ -71,14 +75,24 @@ or
 and
 .BR cap_get_proc ()
 are specified in the withdrawn POSIX.1e draft specification.
-.BR capgetp ()
-and
-.BR capsetp ()
-(described below) are Linux extensions.
+.BR cap_get_pid ()
+is a Linux extension.
 .SH "NOTES"
-The library also supports the deprecated function:
+The library also supports the deprecated functions:
+.PP
+.BI "int capgetp(pid_t " pid ", cap_t " cap_d );
 .PP
-.BI "cap_t capsetp(pid_t " pid ", cap_t " cap_d );
+.BI "int capsetp(pid_t " pid ", cap_t " cap_d );
+.PP
+.BR capgetp ()
+attempts to obtain the capabilities of some other process; storing the
+capabilities in a pre-allocated
+.IR cap_d . See
+.BR cap_init ()
+for information on allocating an empty capability set. This function,
+.BR capgetp (),
+is deprecated, you should use
+.BR cap_get_pid ().
 .PP
 .BR capsetp ()
 attempts to set the capabilities of some other process(es),
@@ -142,6 +156,7 @@ effective capabilities for the caller:
         /* handle error */;
 .fi
 .SH "SEE ALSO"
+.BR libcap (3),
 .BR cap_clear (3),
 .BR cap_copy_ext (3),
 .BR cap_from_text (3),
diff --git a/doc/cap_init.3 b/doc/cap_init.3
index 212c2e9..f198f63 100644
--- a/doc/cap_init.3
+++ b/doc/cap_init.3
@@ -77,6 +77,7 @@ or
 .SH "CONFORMING TO"
 These functions are specified in the withdrawn POSIX.1e draft specification.
 .SH "SEE ALSO"
+.BR libcap (3),
 .BR cap_clear (3),
 .BR cap_copy_ext (3),
 .BR cap_from_text (3),
diff --git a/doc/libcap.3 b/doc/libcap.3
new file mode 100644
index 0000000..827ce60
--- /dev/null
+++ b/doc/libcap.3
@@ -0,0 +1,113 @@
+.TH LIBCAP 3 "2008-07-29" "" "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
+.SH SYNOPSIS
+.nf
+.B #include <sys/capability.h>
+.sp
+.BI "int cap_clear(cap_t " cap_p );
+.sp
+.BI "int cap_clear_flag(cap_t " cap_p ", cap_flag_t " flag ");"
+.sp
+.BI "int cap_compare(cap_t " cap_a ", cap_t " cap_b ");"
+.sp
+.BI "ssize_t cap_copy_ext(void *" ext_p ", cap_t " cap_p ", ssize_t " size );
+.sp
+.BI "cap_t cap_copy_int(const void *" ext_p );
+.sp
+.BI "int cap_free(void *" obj_d );
+.sp
+.BI "int cap_from_name(const char *" name ", cap_value_t *" cap_p );
+.sp
+.BI "cap_t cap_from_text(const char *" buf_p );
+.sp
+.BI "cap_t cap_get_fd(int " fd );
+.sp
+.BI "cap_t cap_get_file(const char *" path_p );
+.sp
+.BI "int cap_get_flag(cap_t " cap_p ", cap_value_t " cap ,
+.BI "                 cap_flag_t " flag ", cap_flag_value_t *" value_p ");"
+.sp
+.B #include <sys/types.h>
+.BI "cap_t cap_get_pid(pid_t " pid );
+.sp
+.B "cap_t cap_get_proc(void);"
+.sp
+.BI "int cap_set_fd(int " fd ", cap_t " caps );
+.sp
+.BI "int cap_set_file(const char *" path_p ", cap_t " cap_p );
+.sp
+.sp
+.BI "int cap_set_flag(cap_t " cap_p ", cap_flag_t " flag ", int " ncap ,
+.BI "                 const cap_value_t *" caps ", cap_flag_value_t " value ");"
+.BI "int cap_set_proc(cap_t " cap_p );
+.sp
+.BI "ssize_t cap_size(cap_t " cap_p );
+.sp
+.BI "char *cap_to_name(cap_value_t " cap );
+.sp
+.BI "char *cap_to_text(cap_t " caps ", ssize_t *" length_p );
+.sp
+.BI "cap_t cap_get_pid(pid_t " pid );
+.sp
+.BI "cap_t cap_dup(cap_t " cap_p );
+.sp
+Link with \fI-lcap\fP.
+.fi
+.SH DESCRIPTION
+These functions work on a capability state held in working storage.
+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).
+.PP
+These functions work with the following data types:
+.TP 18
+.I cap_value_t
+identifies a capability, such as
+.BR CAP_CHOWN .
+.TP
+.I cap_flag_t
+identifies one of the three flags associated with a capability
+(i.e., it identifies one of the three capability sets).
+Valid values for this type are
+.BR CAP_EFFECTIVE ,
+.B CAP_INHERITABLE
+or
+.BR CAP_PERMITTED .
+.TP
+.I cap_flag_value_t
+identifies the setting of a particular capability flag
+(i.e, the value of a capability in a set).
+Valid values for this type are
+.BR CAP_CLEAR (0)
+or
+.BR CAP_SET (1).
+.SH "RETURN VALUE"
+The return value is generally specific to the individual function called.
+On failure,
+.I errno
+is set appropriately.
+.SH "CONFORMING TO"
+These functions are as per the withdrawn POSIX.1e draft specification.
+The following functions are Linux extensions:
+.BR cap_clear_flag (),
+.BR cap_compare (),
+.BR cap_from_name (),
+.BR cap_to_name (),
+and
+.BR cap_compare ().
+.SH "SEE ALSO"
+.BR cap_clear (3),
+.BR cap_copy_ext (3),
+.BR cap_from_text (3),
+.BR cap_get_file (3),
+.BR cap_get_proc (3),
+.BR cap_init (3),
+.BR capabilities (7),
+.BR getpid (2)