NAME¶
cap_clear, cap_clear_flag, cap_get_flag, cap_set_flag, cap_compare - capability
data object manipulation
SYNOPSIS¶
#include <sys/capability.h>
int cap_clear(cap_t cap_p);
int cap_clear_flag(cap_t cap_p, cap_flag_t flag);
int cap_get_flag(cap_t cap_p, cap_value_t cap,
cap_flag_t flag, cap_flag_value_t *value_p);
int cap_set_flag(cap_t cap_p, cap_flag_t flag, int ncap,
const cap_value_t *caps, cap_flag_value_t value);
int cap_compare(cap_t cap_a, cap_t cap_b);
Link with -lcap.
DESCRIPTION¶
These functions work on a capability state held in working storage. A
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).
These functions work with the following data types:
- cap_value_t
- identifies a capability, such as CAP_CHOWN.
- 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 CAP_EFFECTIVE, CAP_INHERITABLE or
CAP_PERMITTED.
- 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 CAP_CLEAR
(0) or CAP_SET (1).
cap_clear() initializes the capability state in working storage
identified by
cap_p so that all capability flags are cleared.
cap_clear_flag() clears all of the capabilities of the specified
capability flag,
flag.
cap_get_flag() obtains the current value of the capability flag,
flag, of the capability,
cap, from the capability state
identified by
cap_p and places it in the location pointed to by
value_p.
cap_set_flag() sets the flag,
flag, of each capability in the
array
caps in the capability state identified by
cap_p to
value. The argument,
ncap, is used to specify the number of
capabilities in the array,
caps.
cap_compare() compares two full capability sets and, in the spirit of
memcmp(), returns zero if the two capability sets are identical. A
positive return value,
status, indicates there is a difference between
them. The returned value carries further information about which of three
sets,
cap_flag_t flag, differ. Specifically, the macro
CAP_DIFFERS (
status,
flag) evaluates to non-zero if the
returned status differs in its
flag components.
RETURN VALUE¶
cap_clear(),
cap_clear_flag(),
cap_get_flag()
cap_set_flag() and
cap_compare() return zero on success, and -1
on failure. Other return values for
cap_compare() are described above.
On failure,
errno is set to
EINVAL, indicating that one of the
arguments is invalid.
These functions are as per the withdrawn POSIX.1e draft specification.
cap_clear_flag() and
cap_compare() are Linux extensions.
SEE ALSO¶
libcap(3),
cap_copy_ext(3),
cap_from_text(3),
cap_get_file(3),
cap_get_proc(3),
cap_init(3),
capabilities(7)