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 manipulated 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 capability 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
       identify 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 duplicated, 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
       calling cap_free() with the cap_t as an argument.

RETURN VALUE

       cap_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 specification.

SEE ALSO

       libcap(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)