cap_size

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



NAME
       cap_copy_ext,  cap_size, cap_copy_int - capability state external rep-
       resentation 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);

USAGE
       cc ... -lcap

DESCRIPTION
       These functions translate a capability state from an  internal  repre-
       sentation  into	an  external  one.  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 neces-
       sary  to convert the capability state from the undefined internal for-
       mat 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 painted 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.	 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	work-
       ing  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(3) is set to EINVAL, ENOMEM, or ERANGE.

CONFORMING TO
       These functions are specified by POSIX.1e.

SEE ALSO
       cap_clear(3),   cap_from_text(3),   cap_get_file(3),  cap_get_proc(3),
       cap_init(3)



				26th May 1997		      CAP_COPY_EXT(3)