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);
USAGE
cc ... -lcap
DESCRIPTION
These functions translate a capability state from an
internal representation into an external one. The exter
nal representation is an exportable, contiguous, persis
tent 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 func
tion 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 repre
sents 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 unde
fined internal format to an exportable, contiguous, per
sistent 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 painted
to by ext_p into the capability state, converting, if nec
essary, the data from a contiguous, persistent format to
format, the object can be manipulated by the capability
state manipulation functions. Note that the record
pointed to by ext_p must have been obtained from a previ
ous, 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 capa
bility state in working storage on success, and NULL on
failure.
On failure, errno(3) is set to EINVAL, ENOMEM, or ERANGE.
CONFORMING TO
These functions are specified by POSIX.1e.
SEE ALSO
cap_clear(3), cap_from_text(3), cap_get_file(3),
cap_get_proc(3), cap_init(3)
Man(1) output converted with
man2html