CAP_CLEAR(3)

NAME
cap_clear, cap_get_flag, cap_set_flag - 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);

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.

RETURN VALUE
cap_clear(), cap_clear_flag(), cap_get_flag() and cap_set_flag() return zero on success, and -1 on failure.

On failure, errno is set to EINVAL, indicating that one of the arguments is invalid.

CONFORMING TO
These functions are as per the withdrawn POSIX.1e draft specification. cap_clear_flag() is a Linux extension.

SEE ALSO
cap_copy_ext(3), cap_from_text(3), cap_get_file(3), cap_get_proc(3), cap_init(3), capabilities(7)