cap_copy_ext

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



NAME
       cap_copy_ext, cap_size, cap_copy_int - capability state external
       representation translation

SYNOPSIS
       #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
       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
       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
       These functions are specified in the withdrawn POSIX.1e draft
       specification.

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



                                  2008-05-11                   CAP_COPY_EXT(3)