cap_dup

CAP_INIT(3)		  Linux Programmer’s Manual		  CAP_INIT(3)



NAME
       cap_init,  cap_free,  cap_dup - capability data object storage manage-
       ment

SYNOPSIS
       #include <sys/capability.h>

       cap_t cap_init(void);

       int cap_free(void *obj_d);

       cap_t cap_dup(cap_t cap_p);

USAGE
       cc ... -lcap

DESCRIPTION
       The capabilities associated with a file or process  are	never  edited
       directly.   Instead,  working storage is allocated to contain a repre-
       sentation of the capability state.  Capabilities are edited and manip-
       ulated  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 return 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
       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.

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(3) is set to EINVAL, or ENOMEM.

CONFORMING TO
       These functions are specified by POSIX.1e.

SEE ALSO
       cap_clear(3),   cap_copy_ext(3),	  cap_from_text(3),  cap_get_file(3),
       cap_get_proc(3)



				26th May 1997			  CAP_INIT(3)