1 files changed, 133 insertions, 0 deletions
diff --git a/doc/cap_clear.3 b/doc/cap_clear.3
new file mode 100644
index 0000000..48f5cc0
--- /dev/null
+++ b/doc/cap_clear.3
@@ -0,0 +1,133 @@
+.TH CAP_CLEAR 3 "2008-05-11" "" "Linux Programmer's Manual"
+.SH NAME
+cap_clear, cap_clear_flag, cap_get_flag, cap_set_flag, cap_compare \- 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_get_flag(cap_t " cap_p ", cap_value_t " cap ,
+.BI "                 cap_flag_t " flag ", cap_flag_value_t *" value_p ");"
+.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 ");"
+.sp
+.BI "int cap_compare(cap_t " cap_a ", cap_t " cap_b ");"
+.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
+.B CAP_CLEAR
+(0) or
+.B CAP_SET
+(1).
+.PP
+.BR cap_clear ()
+initializes the capability state in working storage identified by
+.I cap_p
+so that all capability flags are cleared.
+.PP
+.BR cap_clear_flag ()
+clears all of the capabilities of the specified capability flag,
+.IR flag .
+.PP
+.BR cap_get_flag ()
+obtains the current value of the capability flag,
+.IR flag ,
+of the capability,
+.IR cap ,
+from the capability state identified by
+.I cap_p
+and places it in the location pointed to by
+.IR value_p .
+.PP
+.BR cap_set_flag ()
+sets the flag,
+.IR flag ,
+of each capability in the array
+.I caps
+in the capability state identified by
+.I cap_p
+to
+.IR value .
+The argument,
+.IR ncap ,
+is used to specify the number of capabilities in the array,
+.IR caps .
+.PP
+.BR cap_compare ()
+compares two full capability sets and, in the spirit of
+.BR memcmp (),
+returns zero if the two capability sets are identical. A positive
+return value,
+.BR status ,
+indicates there is a difference between them. The
+returned value carries further information about which of three sets,
+.I cap_flag_t
+.BR flag ,
+differ. Specifically, the macro
+.B CAP_DIFFERS
+.RI ( status ", " flag )
+evaluates to non-zero if the returned status differs in its
+.I flag
+components.
+.SH "RETURN VALUE"
+.BR cap_clear (),
+.BR cap_clear_flag (),
+.BR cap_get_flag ()
+.BR cap_set_flag ()
+and
+.BR cap_compare ()
+return zero on success, and \-1 on failure. Other return values for
+.BR cap_compare ()
+are described above.
+.PP
+On failure,
+.I errno
+is set to 
+.BR EINVAL ,
+indicating that one of the arguments is invalid.
+.SH "CONFORMING TO"
+These functions are as per the withdrawn POSIX.1e draft specification.
+.BR cap_clear_flag ()
+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),
+.BR cap_get_proc (3),
+.BR cap_init (3),
+.BR capabilities (7)