Provided by: libcap-dev_2.17-2ubuntu1_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)