ABCDEFGHIJKLMNOPQRSTUVWXYZ

cap_to_text

CAP_FROM_TEXT(3)           Linux Programmer's Manual          CAP_FROM_TEXT(3)



NAME
       cap_from_text,  cap_to_text, _cap_names - capability state textual rep-
       resentation 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 represen-
       tation  into  a textual one.  The internal representation is managed by
       the capability functions in working storage. The textual representation
       is a structured, 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 char-
       acter string pointed to by buf_p.  It returns a pointer  to  the  newly
       created  capability  state.  The caller should free any releasable mem-
       ory, 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 storage identified
       by cap_p into a null terminated human-readable 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, identified by cap_p, is completely represented in
       the character 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.)

TEXTUAL REPRESENTATION
       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 capability 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-
       sensitive and specify the Effective,  Inheritable  and  Permitted  sets
       respectively.

       In the capability name lists, all names are case-insensitive.  The spe-
       cial name `all' specifies all capabilities; it is equivalent to a  list
       naming every capability individually.

       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 subsequent flags (which are optional
       when associated with this operator) indicate that the listed  capabili-
       ties  for the corresponding set are to be raised.  For example: "all=p"
       means lower every capability in the Effective and Inheritable sets  but
       raise  all  of  the  Permitted  capabilities; or, "cap_fowner=ep" means
       raise the Effective and Permitted  override-file-ownership  capability,
       while lowering this Inheritable capability.

       In  the case that the leading operator is `=', and no list of capabili-
       ties is provided, the action-list is assumed to refer to `all' capabil-
       ities.  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 preceding capabil-
       ity 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  Permitted capability set and lower
       this Inheritable capability; "cap_fowner+pe-i" and "cap_fowner=+pe" are
       equivalent.

RETURN VALUE
       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)



                                 26th May 1997                CAP_FROM_TEXT(3)