Provided by: libcap-dev_2.21-2_i386 bug

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)

                                  2008-05-11                       CAP_INIT(3)