Man Pages

cap_copy_ext(3) - phpMan cap_copy_ext(3) - phpMan

Command: man perldoc info search(apropos)  


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 parame-
       ter 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  capabil-
       ity  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 manip-
       ulated  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 suc-
       cessfully.   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)