.\"

.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>

.\"

.TH CAP_INIT 3 "2008-05-11" "" "Linux Programmer's Manual"

.SH NAME

cap_init, cap_free, cap_dup \- capability data object storage management

.SH SYNOPSIS

.B #include <sys/capability.h>

.sp

.B cap_t cap_init(void);

.sp

.BI "int cap_free(void *" obj_d );

.sp

.BI "cap_t cap_dup(cap_t " cap_p );

.sp

Link with \fI-lcap\fP.

.SH 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.

.PP

.BR 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

.BR cap_free ()

with the 

.I cap_t

as an argument.

.PP

.BR cap_free ()

liberates any releasable memory that has been allocated to the

capability state identified by

.IR obj_d .

The

.I obj_d

argument may identify either a

.I cap_t

entity, or a

.I char *

entity allocated by the

.BR cap_to_text ()

function.

.PP

.BR cap_dup ()

returns a duplicate capability state in working storage given by the

source object

.IR 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

.BR cap_free ()

with the 

.I cap_t

as an argument.

.SH "RETURN VALUE"

.BR cap_init ()

and

.BR cap_dup ()

return a non-NULL value on success, and NULL on failure.

.PP

.BR cap_free ()

returns zero on success, and \-1 on failure.

.PP

On failure,

.I errno

is set to

.BR EINVAL

or

.BR ENOMEM .

.SH "CONFORMING TO"

These functions are specified in the withdrawn POSIX.1e draft specification.

.SH "SEE ALSO"

.BR libcap (3),

.BR cap_clear (3),

.BR cap_copy_ext (3),

.BR cap_from_text (3),

.BR cap_get_file (3),

.BR cap_get_proc (3),

.BR capabilities (7)