CAP_COPY_EXT(3) Linux Programmer's Manual CAP_COPY_EXT(3)
cap_copy_ext, cap_size, cap_copy_int - capability state external representation transla-
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.
These functions translate between internal and external representations of a capability
state. The external representation is an exportable, contiguous, persistent representa-
tion 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 stor-
age 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, con-
tiguous, persistent data record. It is the responsibility of the user to allocate a buf-
fer 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, persis-
tent 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.
cap_size() returns the length required to hold a capability data record on success, and -1
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.
These functions are specified in the withdrawn POSIX.1e draft specification.
libcap(3), cap_clear(3), cap_from_text(3), cap_get_file(3), cap_get_proc(3), cap_init(3),