CAP_COPY_EXT
Section: Linux Programmer's Manual (3)
Updated: 2008-05-11
Index
Return to Main Contents
NAME
cap_copy_ext, cap_size, cap_copy_int - capability state
external representation translation
SYNOPSIS
#include <sys/capability.h>
ssize_t cap_size(cap_t cap_p);
ssize_t cap_copy_ext(void *ext_p, cap_t cap_p, ssize_t size);
cap_t cap_copy_int(const void *ext_p);
Link with -lcap.
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.
cap_size()
returns the total length (in bytes) that the capability state in working
storage identified by
cap_p
would require when converted by
cap_copy_ext().
This function is used primarily to determine the amount of buffer space that
must be provided to the
cap_copy_ext()
function in order to hold the capability data record created from
cap_p.
cap_copy_ext()
copies a capability state in working storage, identified by
cap_p,
from system managed space to user-managed space (pointed to by
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
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
cap_size()
function.
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
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
cap_clear(3)).
Note that the record pointed to by
ext_p
must have been obtained from a previous, successful call to
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
cap_free()
with the
cap_t
as an argument.
RETURN VALUE
cap_size()
returns the length required to hold a capability data record on success,
and -1 on failure.
cap_copy_ext()
returns the number of bytes placed in the user managed space pointed to by
ext_p
on success, and -1 on failure.
cap_copy_int()
returns a pointer to the newly created capability state in working storage
on success, and NULL on failure.
On failure,
errno
is set to
EINVAL,
ENOMEM,
or
ERANGE.
CONFORMING TO
These functions are specified in the withdrawn POSIX.1e draft specification.
SEE ALSO
libcap(3),
cap_clear(3),
cap_from_text(3),
cap_get_file(3),
cap_get_proc(3),
cap_init(3),
capabilities(7)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUE
-
- CONFORMING TO
-
- SEE ALSO
-
|
|
- Running on 
-
:
: 