cap_from_text,  cap_to_text, _cap_names - capability state
       textual representation translation


SYNOPSIS

       #include <sys/capability.h>

       cap_t cap_from_text(const char *buf_p);

       char *cap_to_text(cap_t caps, ssize_t *length_p);

       extern char const *_cap_names[];


USAGE

       cc ... -lcap


DESCRIPTION

       These functions  translate  a  capability  state  from  an
       internal  representation into a textual one.  The internal
       representation is managed by the capability  functions  in
       working  storage.  The  textual representation is a struc­
       tured, human-readable, string suitable for display.

       cap_from_text allocates and initializes a capability state
       in  working  storage.  It  then  sets the contents of this
       newly-created capability state to the state represented by
       human-readable,  null  terminated character string pointed
       to by buf_p.  It returns a pointer to  the  newly  created
       capability  state.   The caller should free any releasable
       memory, when the capability state in working storage is no
       longer  required,  by  calling  cap_free  with cap_t as an
       argument.  The function returns  an  error  if  it  cannot
       parse  the  contents  of the string pointed to by buf_p or
       does not recognize any capability_name or  flag  character
       as  valid.  The function also returns an error if any flag
       is both set and cleared within a single clause.

       cap_to_text converts the capability state in working stor­
       age identified by cap_p into a null terminated human-read­
       able string.  This function allocates any memory necessary
       to  contain  the  string,  and  returns  a  pointer to the
       string.  If the pointer len_p is not  NULL,  the  function
       shall  also  return  the  full  length  of the string (not
       including the null terminator) in the location pointed  to
       by  len_p.  The capability state in working storage, iden­
       tified by cap_p, is completely represented in the  charac­
       ter string.  The caller should free any releasable memory,
       when the capability state in working storage is no  longer
       required, by calling cap_free with cap_p as an argument.

       _cap_names  is  an  array  of textual names for capability
       numbers.  Unnamed capabilities have a NULL  entry.   (This
       array is not defined by POSIX.1e.)

       A  textual  representation  of capability sets consists of
       one or more  whitespace-separated  clauses.   Each  clause
       specifies  some  operations  to  a capability set; the set
       starts out with all capabilities lowered, and the  meaning
       of the string is the state of the capability set after all
       the clauses have been applied in order.

       Each clause consists of a list of comma-separated capabil­
       ity names (or the word `all'), followed by an action-list.
       An action-list consists of a  sequence  of  operator  flag
       pairs.   Legal  operators  are:  `=', '+', and `-'.  Legal
       flags are: `e', `i', and `p'.  These flags are case-sensi­
       tive  and specify the Effective, Inheritable and Permitted
       sets respectively.

       In the capability name lists, all names are  case-insensi­
       tive.   The special name `all' specifies all capabilities;
       it is equivalent to a list naming every  capability  indi­
       vidually.

       Although not defined by POSIX, unnamed capabilities can be
       specified by number.

       The `=' operator indicates that  the  listed  capabilities
       are  first reset in all three capability sets.  The subse­
       quent flags (which are optional when associated with  this
       operator)  indicate  that  the listed capabilities for the
       corresponding set are to be raised.  For example:  "all=p"
       means  lower every capability in the Effective and Inheri­
       table sets but raise all of  the  Permitted  capabilities;
       or,  "cap_fowner=ep" means raise the Effective and Permit­
       ted  override-file-ownership  capability,  while  lowering
       this Inheritable capability.

       In  the case that the leading operator is `=', and no list
       of capabilities is provided, the action-list is assumed to
       refer  to  `all' capabilities.  For example, the following
       three clauses are equivalent to each other (and indicate a
       completely    empty    capability   set):   "all=";   "=";
       "cap_chown,<every-other-capability>=".

       The operators, `+' and `-' both require an  explicit  pre­
       ceding  capability  list and one or more explicit trailing
       flags.  The `+' operator will  raise  all  of  the  listed
       capabilities  in  the  flagged  capability  sets.  The `-'
       operator will lower all of the listed capabilities in  the
       flagged  capability sets.  For example: "all+p" will raise
       all of the Permitted capabilities;  "cap_fowner+p-i"  will
       raise  the  override-file-ownership capability in the Per­
       mitted capability set and lower this Inheritable  capabil­
       ity;  "cap_fowner+pe-i"  and  "cap_fowner=+pe" are equiva­
       lent.

       cap_from_text and cap_to_text return a non-NULL  value  on
       success, and NULL on failure.

       On failure, errno(3) is set to EINVAL, or ENOMEM.


CONFORMING TO

       cap_from_text  and  cap_to_text are specified by POSIX.1e.
       _cap_names is a Linux extension.


SEE ALSO

       cap_clear(3),      cap_copy_ext(3),       cap_get_file(3),
       cap_get_proc(3), cap_init(3)


Man(1) output converted with man2html