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  repre-
       sentation  into a textual one.  The internal representation is managed
       by the capability functions in working storage. The textual  represen-
       tation 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
       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 charac-
       ter 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 identi-
       fied 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 com-
       pletely 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
       special 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
       capabilities 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	capa-
       bility, 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’	capa-
       bilities.   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)