236 lines
7.2 KiB
Groff
236 lines
7.2 KiB
Groff
|
.\"
|
||
|
|
.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
|
||
|
|
.\"
|
||
|
|
.TH CAP_FROM_TEXT 3 "2008-05-10" "" "Linux Programmer's Manual"
|
||
|
|
.SH NAME
|
||
|
|
cap_from_text, cap_to_text, cap_to_name, cap_from_name \- capability
|
||
|
|
state textual representation translation
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
#include <sys/capability.h>
|
||
|
|
|
||
|
|
cap_t cap_from_text(const char* buf_p );
|
||
|
|
char *cap_to_text(cap_t caps, ssize_t * length_p);
|
||
|
|
int cap_from_name(const char* name , cap_value_t* cap_p);
|
||
|
|
char *cap_to_name(cap_value_t cap);
|
||
|
|
.fi
|
||
|
|
Link with \fI\-lcap\fP.
|
||
|
|
.SH DESCRIPTION
|
||
|
|
These functions translate a capability state between
|
||
|
|
an internal representation and 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.
|
||
|
|
.PP
|
||
|
|
.BR 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 a human-readable, nul-terminated character
|
||
|
|
string pointed to by
|
||
|
|
.IR buf_p .
|
||
|
|
It returns a pointer to the newly created capability state.
|
||
|
|
When the capability state in working storage is no longer required,
|
||
|
|
the caller should free any releasable memory
|
||
|
|
by calling
|
||
|
|
.BR cap_free ()
|
||
|
|
with
|
||
|
|
.I cap_t
|
||
|
|
as an argument. The function returns an error if it cannot parse the
|
||
|
|
contents of the string pointed to by
|
||
|
|
.I buf_p
|
||
|
|
or does not recognize any
|
||
|
|
.I 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.
|
||
|
|
.PP
|
||
|
|
.BR cap_to_text ()
|
||
|
|
converts the capability state in working storage identified by
|
||
|
|
.I cap_p
|
||
|
|
into a nul-terminated human-readable string. This function allocates
|
||
|
|
any memory necessary to contain the string, and returns a pointer to
|
||
|
|
the string. If the pointer
|
||
|
|
.I len_p
|
||
|
|
is not NULL,
|
||
|
|
the function shall also return the full length of the string (not including
|
||
|
|
the nul terminator) in the location pointed to by
|
||
|
|
.IR len_p .
|
||
|
|
The capability state in working storage, identified by
|
||
|
|
.IR cap_p ,
|
||
|
|
is completely represented in the character string.
|
||
|
|
When the capability state in working storage is no longer required,
|
||
|
|
the caller should free any releasable memory by calling
|
||
|
|
.BR cap_free ()
|
||
|
|
with the returned string pointer as an argument.
|
||
|
|
.PP
|
||
|
|
.BR cap_from_name ()
|
||
|
|
converts a text representation of a capability, such as "cap_chown",
|
||
|
|
to its numerical representation
|
||
|
|
.RB ( CAP_CHOWN=0 ),
|
||
|
|
writing the decoded value into
|
||
|
|
.IR *cap_p .
|
||
|
|
If
|
||
|
|
.I cap_p
|
||
|
|
is NULL
|
||
|
|
no result is written, but the return code of the function indicates
|
||
|
|
whether or not the specified capability can be represented by the
|
||
|
|
library.
|
||
|
|
.PP
|
||
|
|
.BR cap_to_name ()
|
||
|
|
converts a capability index value,
|
||
|
|
.IR cap ,
|
||
|
|
to a libcap-allocated textual string. This string should be
|
||
|
|
deallocated with
|
||
|
|
.BR cap_free ().
|
||
|
|
.SH "TEXTUAL REPRESENTATION"
|
||
|
|
A textual representation of capability sets consists of one or more
|
||
|
|
whitespace-separated
|
||
|
|
.IR clauses .
|
||
|
|
Each clause specifies some operations on 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.
|
||
|
|
.PP
|
||
|
|
Each clause consists of a list of comma-separated capability names
|
||
|
|
(or the word
|
||
|
|
.RB ` all '),
|
||
|
|
followed by an
|
||
|
|
.IR action-list .
|
||
|
|
An action-list consists of a sequence of
|
||
|
|
.I operator flag
|
||
|
|
pairs. Legal operators are:
|
||
|
|
.RB ` = "', '" + "', and `" \- "'."
|
||
|
|
Legal flags are:
|
||
|
|
.RB ` e "', `" i "', and `" p "'."
|
||
|
|
These flags are case-sensitive and specify the Effective, Inheritable
|
||
|
|
and Permitted sets respectively.
|
||
|
|
.PP
|
||
|
|
In the capability name lists, all names are case-insensitive. The
|
||
|
|
special name
|
||
|
|
.RB ` all '
|
||
|
|
specifies all capabilities; it is equivalent to a list naming every
|
||
|
|
capability individually.
|
||
|
|
.PP
|
||
|
|
Unnamed capabilities can also be specified by number. This feature
|
||
|
|
ensures that libcap can support capabilities that were not allocated
|
||
|
|
at the time libcap was compiled. However, generally upgrading libcap
|
||
|
|
will add names for recently allocated capabilities.
|
||
|
|
.PP
|
||
|
|
The
|
||
|
|
.RB ` = '
|
||
|
|
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 capability, while lowering this Inheritable
|
||
|
|
capability.
|
||
|
|
.PP
|
||
|
|
In the case that the leading operator is
|
||
|
|
.RB ` = ',
|
||
|
|
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>=".
|
||
|
|
.PP
|
||
|
|
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
|
||
|
|
capabilities in the flagged capability sets. For example:
|
||
|
|
"all+p" will raise all of the Permitted capabilities and
|
||
|
|
"cap_fowner\-i" will lower the override-file-ownership in the Inheritable set.
|
||
|
|
.PP
|
||
|
|
The action list can consist of multiple
|
||
|
|
.I operator flag
|
||
|
|
pairs; the actions are performed in left-to-right order.
|
||
|
|
Thus, for example,
|
||
|
|
"cap_fowner+p\-i"
|
||
|
|
is equivalent to "cap_fowner+p cap_fowner\-i".
|
||
|
|
As another example,
|
||
|
|
"cap_fowner+pe\-i" and "cap_fowner=+pe" are equivalent.
|
||
|
|
.SH "RETURN VALUE"
|
||
|
|
.BR cap_from_text (),
|
||
|
|
.BR cap_to_text ()
|
||
|
|
and
|
||
|
|
.BR cap_to_name ()
|
||
|
|
return a non-NULL value on success, and NULL on failure.
|
||
|
|
.BR cap_from_name ()
|
||
|
|
returns 0 for success, and \-1 on failure (unknown capability).
|
||
|
|
.PP
|
||
|
|
On failure,
|
||
|
|
.I errno
|
||
|
|
is set to
|
||
|
|
.BR EINVAL ,
|
||
|
|
or
|
||
|
|
.BR ENOMEM .
|
||
|
|
.SH "CONFORMING TO"
|
||
|
|
.BR cap_from_text ()
|
||
|
|
and
|
||
|
|
.BR cap_to_text ()
|
||
|
|
are specified by the withdrawn POSIX.1e draft specification.
|
||
|
|
.BR cap_from_name ()
|
||
|
|
and
|
||
|
|
.BR cap_to_name ()
|
||
|
|
are Linux extensions.
|
||
|
|
.SH EXAMPLE
|
||
|
|
The example program below demonstrates the use of
|
||
|
|
.BR cap_from_text ()
|
||
|
|
and
|
||
|
|
.BR cap_to_text ().
|
||
|
|
The following shell session shows some example runs:
|
||
|
|
.nf
|
||
|
|
|
||
|
|
$ ./a.out "cap_chown=p cap_chown+e"
|
||
|
|
caps_to_text() returned "cap_chown=ep"
|
||
|
|
$ ./a.out "all=pe cap_chown\-e cap_kill\-pe"
|
||
|
|
caps_to_text() returned "=ep cap_chown\-e cap_kill\-ep"
|
||
|
|
|
||
|
|
.fi
|
||
|
|
The source code of the program is as follows:
|
||
|
|
.nf
|
||
|
|
|
||
|
|
#include <stdlib.h>
|
||
|
|
#include <stdio.h>
|
||
|
|
#include <sys/capability.h>
|
||
|
|
|
||
|
|
#define handle_error(msg) \\
|
||
|
|
do { perror(msg); exit(EXIT_FAILURE); } while (0)
|
||
|
|
|
||
|
|
int
|
||
|
|
main(int argc, char *argv[])
|
||
|
|
{
|
||
|
|
cap_t caps;
|
||
|
|
char *txt_caps;
|
||
|
|
|
||
|
|
if (argc != 2) {
|
||
|
|
fprintf(stderr, "%s <textual\-cap\-set>\\n", argv[0]);
|
||
|
|
exit(EXIT_FAILURE);
|
||
|
|
}
|
||
|
|
|
||
|
|
caps = cap_from_text(argv[1]);
|
||
|
|
if (caps == NULL)
|
||
|
|
handle_error("cap_from_text");
|
||
|
|
|
||
|
|
txt_caps = cap_to_text(caps, NULL);
|
||
|
|
if (txt_caps == NULL)
|
||
|
|
handle_error("cap_to_text");
|
||
|
|
|
||
|
|
printf("caps_to_text() returned \\"%s\\"\\n", txt_caps);
|
||
|
|
|
||
|
|
if (cap_free(txt_caps) != 0 || cap_free(caps) != 0)
|
||
|
|
handle_error("cap_free");
|
||
|
|
|
||
|
|
exit(EXIT_SUCCESS);
|
||
|
|
}
|
||
|
|
.fi
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.BR libcap (3),
|
||
|
|
.BR cap_clear (3),
|
||
|
|
.BR cap_copy_ext (3),
|
||
|
|
.BR cap_get_file (3),
|
||
|
|
.BR cap_get_proc (3),
|
||
|
|
.BR cap_init (3),
|
||
|
|
.BR capabilities (7)
|