CAP_INIT(3) Linux Programmer's Manual CAP_INIT(3)NAME
cap_init, cap_free, cap_dup - capability data object storage management
SYNOPSIS
#include <sys/capability.h>
cap_t cap_init(void);
int cap_free(void *obj_d);
cap_t cap_dup(cap_t cap_p);
Link with -lcap.
DESCRIPTION
The capabilities associated with a file or process are never edited
directly. Instead, working storage is allocated to contain a represen‐
tation of the capability state. Capabilities are edited and manipu‐
lated only within this working storage area. Once editing of the capa‐
bility state is complete, the updated capability state is used to
replace the capability state associated with the file or process.
cap_init() creates a capability state in working storage and returns a
pointer to the capability state. The initial value of all flags are
cleared. The caller should free any releasable memory, when the capa‐
bility state in working storage is no longer required, by calling
cap_free() with the cap_t as an argument.
cap_free() liberates any releasable memory that has been allocated to
the capability state identified by obj_d. The obj_d argument may iden‐
tify either a cap_t entity, or a char * entity allocated by the
cap_to_text() function.
cap_dup() returns a duplicate capability state in working storage given
by the source object cap_p, allocating any memory necessary, and
returning a pointer to the newly created capability state. Once dupli‐
cated, no operation on either capability state affects the other in any
way. When the duplicated capability state in working storage is no
longer required, the caller should free any releasable memory by call‐
ing cap_free() with the cap_t as an argument.
RETURN VALUEcap_init() and cap_dup() return a non-NULL value on success, and NULL
on failure.
cap_free() returns zero on success, and -1 on failure.
On failure, errno is set to EINVAL or ENOMEM.
CONFORMING TO
These functions are specified in the withdrawn POSIX.1e draft specifi‐
cation.
SEE ALSOlibcap(3), cap_clear(3), cap_copy_ext(3), cap_from_text(3),
cap_get_file(3), cap_get_proc(3), capabilities(7)
2008-05-11 CAP_INIT(3)