CAP_FROM_TEXT(3) Linux Programmer's Manual CAP_FROM_TEXT(3)
cap_from_text, cap_to_text, _cap_names - capability state textual representation transla-
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;
cc ... -lcap
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
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.)
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-
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.
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.
cap_from_text and cap_to_text are specified by POSIX.1e. _cap_names is a Linux extension.
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)