cap_copy_ext, cap_size, cap_copy_int - capability state external representation
translation
#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.
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.
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.
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),
capabilities(7)