diff options
Diffstat (limited to 'doc/cap_from_text.3')
-rw-r--r-- | doc/cap_from_text.3 | 233 |
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) |