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