Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for cap_to_text (redhat section 3)

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

NAME
       cap_from_text,  cap_to_text, _cap_names - capability state textual representation transla-
       tion

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  tex-
       tual  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  character  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 capabil-
       ity 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	individu-
       ally.

       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 capa-
       bility 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 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 preceding 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 capabili-
       ties 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)


All times are GMT -4. The time now is 07:12 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password