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 repre-
       sentation 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 represen-
       tation  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 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,  allo-
       cating  any memory necessary, and returning a pointer to the newly cre-
       ated 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 working  stor-
       age  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)