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_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.
This page is part of the libcap (capabilities commands and library)
project. Information about the project can be found at
⟨https://git.kernel.org/pub/scm/libs/libcap/libcap.git/⟩. If you have
a bug report for this manual page, send it to email@example.com
(please put "libcap" in the Subject line). This page was obtained
from the project's upstream Git repository
2020-06-09. (At that time, the date of the most recent commit that
was found in the repository was 2020-06-04.) If you discover any
rendering problems in this HTML version of the page, or you believe
there is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to