MAN page from Trustix libcap-devel-1.10-2tr.i586.rpm

CAP_FROM_TEXT

Section: Linux Programmer's Manual (3)
Updated: 26th May 1997
Index

NAME

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 representationinto a textual one. The internal representation is managed by the capabilityfunctions in working storage. The textual representation is a structured,human-readable, string suitable for display.

cap_from_textallocates and initializes a capability state in working storage. It thensets the contents of this newly-created capability state to the staterepresented by human-readable, null terminated character string pointed to bybuf_p.It returns a pointer to the newly created capability state. Thecaller should free any releasable memory, when the capability state in workingstorage is no longer required, by callingcap_freewithcap_tas an argument. The function returns an error if it cannot parse thecontents of the string pointed to bybuf_por does not recognize anycapability_nameor flag character as valid. The function also returns an error if any flagis both set and cleared within a single clause.

cap_to_textconverts the capability state in working storage identified bycap_pinto a null terminated human-readable string. This function allocates anymemory necessary to contain the string, and returns a pointer to the string. Ifthe pointerlen_pis notNULL,the function shall also return the full length of the string (not includingthe null terminator) in the location pointed to bylen_p.The capability state in working storage, identified bycap_p,is completely represented in the character string. The caller shouldfree any releasable memory, when the capability state in workingstorage is no longer required, by callingcap_freewithcap_pas an argument.

_cap_namesis an array of textual names for capability numbers. Unnamed capabilitieshave a NULL entry. (This array is not defined by POSIX.1e.)

TEXTUAL REPRESENTATION

A textual representation of capability sets consists of one or morewhitespace-separatedclauses.Each clause specifies some operations to a capability set; the setstarts out with all capabilities lowered, and the meaning of thestring is the state of the capability set after all the clauses havebeen applied in order.

Each clause consists of a list of comma-separated capability names(or the word`all'),followed by anaction-list.An action-list consists of a sequence ofoperator flagpairs. Legal operators are:`=', '+', and `-'.Legal flags are:`e', `i', and `p'.These flags are case-sensitive and specify the Effective, Inheritableand Permitted sets respectively.

In the capability name lists, all names are case-insensitive. Thespecial name`all'specifies all capabilities; it is equivalent to a list naming everycapability individually.

Although not defined by POSIX, unnamed capabilities can be specifiedby number.

The`='operator indicates that the listed capabilities are first reset inall three capability sets. The subsequent flags (which are optionalwhen associated with this operator) indicate that the listedcapabilities for the corresponding set are to be raised. For example:"all=p" means lower every capability in the Effective and Inheritablesets but raise all of the Permitted capabilities;or, "cap_fowner=ep" means raise the Effective and Permittedoverride-file-ownership capability, while lowering this Inheritablecapability.

In the case that the leading operator is`=',and no list of capabilities is provided, the action-list is assumed torefer to `all' capabilities. For example, the following threeclauses are equivalent to each other (and indicate a completely emptycapability set): "all="; "="; "cap_chown,<every-other-capability>=".

The operators, `+' and `-' both require an explicit precedingcapability list and one or more explicit trailing flags. The `+'operator will raise all of the listed capabilities in the flaggedcapability sets. The `-' operator will lower all of the listedcapabilities 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 Permittedcapability set and lower this Inheritable capability;"cap_fowner+pe-i" and "cap_fowner=+pe" are equivalent.

RETURN VALUE

cap_from_textandcap_to_textreturn a non-NULL value on success, and NULL on failure.

On failure,errno(3)is set to EINVAL,or ENOMEM.

CONFORMING TO

cap_from_textandcap_to_textare specified by POSIX.1e._cap_namesis a Linux extension.

This document was created byman2html,using the manual pages.