NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CONFORMING TO | SEE ALSO | COLOPHON

CAP_COPY_EXT(3)           Linux Programmer's Manual          CAP_COPY_EXT(3)

NAME         top

       cap_copy_ext, cap_size, cap_copy_int - capability state external rep‐
       resentation translation

SYNOPSIS         top

       #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.

DESCRIPTION         top

       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.

RETURN VALUE         top

       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.

CONFORMING TO         top

       These functions are specified in the withdrawn POSIX.1e draft
       specification.

SEE ALSO         top

       libcap(3), cap_clear(3), cap_from_text(3), cap_get_file(3),
       cap_get_proc(3), cap_init(3), capabilities(7)

COLOPHON         top

       This page is part of the libcap (capabilities commands and library)
       project.  Information about the project can be found at 
       ⟨https://git.kernel.org/cgit/linux/kernel/git/morgan/libcap.git/⟩.  If
       you have a bug report for this manual page, send it to
       morgan@kernel.org (please put "libcap" in the Subject line).  This
       page was obtained from the project's upstream Git repository 
       ⟨git://git.kernel.org/pub/scm/linux/kernel/git/morgan/libcap.git⟩ on
       2016-08-07.  If you discover any rendering problems in this HTML ver‐
       sion 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 man‐
       ual page), send a mail to man-pages@man7.org

                                 2008-05-11                  CAP_COPY_EXT(3)