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  representation  of  the  capability  state.   Capabilities  are  edited  and
       manipulated only within this working storage area.  Once editing of the capability 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)

                                                   2021-03-06                                        CAP_INIT(3)