doc/cap_clear.3

.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)