cap_copy_ext, cap_size, cap_copy_int - capability state external repre-
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);
cc ... -lcap
These functions translate a capability state from an internal represen-
tation into an external one. 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 neces-
sary 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, allo-
cating any memory necessary, and returning a pointer to the newly cre-
ated 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 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. 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 stor-
age is no longer required, by calling cap_free with the cap_t as an
On failure, errno(3) is set to EINVAL, ENOMEM, or ERANGE.
These functions are specified by POSIX.1e.
cap_clear(3), cap_from_text(3), cap_get_file(3), cap_get_proc(3),
26th May 1997 cap_copy_ext(3)