summaryrefslogtreecommitdiff
path: root/doc/cap_from_text.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/cap_from_text.3')
-rw-r--r--doc/cap_from_text.3233
1 files changed, 233 insertions, 0 deletions
diff --git a/doc/cap_from_text.3 b/doc/cap_from_text.3
new file mode 100644
index 0000000..ccf7d95
--- /dev/null
+++ b/doc/cap_from_text.3
@@ -0,0 +1,233 @@
+.\"
+.\" 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
+.B #include <sys/capability.h>
+.sp
+.BI "cap_t cap_from_text(const char *" buf_p );
+.sp
+.BI "char *cap_to_text(cap_t " caps ", ssize_t *" length_p );
+.sp
+.BI "int cap_from_name(const char *" name ", cap_value_t *" cap_p );
+.sp
+.BI "char *cap_to_name(cap_value_t " cap );
+.sp
+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; "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.
+.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 a some example runs:
+.in +4n
+.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
+.in
+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_compare (3),
+.BR cap_copy_ext (3),
+.BR cap_get_file (3),
+.BR cap_get_proc (3),
+.BR cap_init (3),
+.BR capabilities (7)