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);


USAGE

       cc ... -lcap


DESCRIPTION

       These  functions  translate  a  capability  state  from an
       internal representation into an external one.  The  exter­
       nal  representation  is an exportable, contiguous, persis­
       tent 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  func­
       tion  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 repre­
       sents 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  unde­
       fined  internal  format to an exportable, contiguous, per­
       sistent 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 nec­
       essary, the data from a contiguous, persistent  format  to

       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  previ­
       ous,  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  capa­
       bility  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)


Man(1) output converted with man2html