.TH CAP_COPY_EXT 3 "2008-05-11" "" "Linux Programmer's Manual"
.SH NAME
cap_copy_ext, cap_size, cap_copy_int \- capability state
external representation translation
.SH SYNOPSIS
.B #include <sys/capability.h>
.sp
.BI "ssize_t cap_size(cap_t " cap_p );
.sp
.BI "ssize_t cap_copy_ext(void *" ext_p ", cap_t " cap_p ", ssize_t " size );
.sp
.BI "cap_t cap_copy_int(const void *" ext_p );
.sp
Link with \fI-lcap\fP.
.SH DESCRIPTION
These functions translate between internal and external
representations of a capability state.  The external representation is
an exportable, contiguous, persistent representation of a capability
state in user-managed space.  The internal representation is managed
by the capability functions in working storage.
.PP
.BR cap_size ()
returns the total length (in bytes) that the capability state in working
storage identified by
.I cap_p
would require when converted by
.BR cap_copy_ext ().
This function is used primarily to determine the amount of buffer space that
must be provided to the
.BR cap_copy_ext ()
function in order to hold the capability data record created from
.IR cap_p .
.PP
.BR cap_copy_ext ()
copies a capability state in working storage, identified by
.IR cap_p ,
from system managed space to user-managed space (pointed to by
.IR ext_p )
and returns the length of the resulting data record.  The size parameter
represents the maximum size, in bytes, of the resulting data record.  The
.BR cap_copy_ext ()
function will do any conversions necessary to convert the capability
state from the undefined internal format to an exportable, contiguous,
persistent data record.  It is the responsibility of the user to
allocate a buffer large enough to hold the copied data.  The buffer
length required to hold the copied data may be obtained by a call to
the
.BR cap_size ()
function.
.PP
.BR cap_copy_int ()
copies a capability state from a capability data record in user-managed
space to a new capability state in working storage, allocating any
memory necessary, and returning a pointer to the newly created capability
state.  The function initializes the capability state and then copies
the capability state from the record pointed to by
.I ext_p
into the capability state, converting, if necessary, the data from a
contiguous, persistent format to an undefined, internal format.  Once
copied into internal format, the object can be manipulated by the capability
state manipulation functions (see
.BR cap_clear (3)).
Note that the record pointed to by
.I ext_p
must have been obtained from a previous, successful call to
.BR cap_copy_ext ()
for this function to work successfully.  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.
.SH "RETURN VALUE"
.BR cap_size ()
returns the length required to hold a capability data record on success,
and -1 on failure.
.PP
.BR cap_copy_ext ()
returns the number of bytes placed in the user managed space pointed to by
.I ext_p 
on success, and -1 on failure.
.PP
.BR cap_copy_int ()
returns a pointer to the newly created capability state in working storage
on success, and NULL on failure.
.PP
On failure,
.BR errno
is set to
.BR EINVAL ,
.BR ENOMEM ,
or
.BR ERANGE .
.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_from_text (3),
.BR cap_get_file (3),
.BR cap_get_proc (3),
.BR cap_init (3),
.BR capabilities (7)