Description

The priv_str_to_set() function maps the privilege specification in buf to a privilege
set. It returns a privilege set on success or NULL on failure.
If an error occurs when parsing the string, a pointer to the
remainder of the string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer. If an error occurs
when allocating memory, errno is set and the object pointed to by
endptr is set to the null pointer, provided that endptr is not a
null pointer.

The application is responsible for freeing the returned privilege set using priv_freeset(3C).

A privilege specification should contain one or more privilege names, separated by
characters in sep using the same algorithm as strtok(3C). Privileges can optionally be
preceded by a dash (-) or an exclamation mark (!), in which
case they are excluded from the resulting set. The special strings “none”
for the empty set, “all” for the set of all privileges, “zone”
for the set of all privileges available within the caller's zone, and “basic”
for the set of basic privileges are also recognized. Set specifications are
interpreted from left to right.

The priv_set_to_str() function converts the privilege set to a sequence of privileges
separated by sep, returning the a pointer to the dynamically allocated result.
The application is responsible for freeing the memory using free(3C).

To maintain future compatibility, the “basic” set of privileges is included as
“basic,!missing_basic_priv1,...”. When further currently unprivileged operations migrate to the basic privilege set,
the conversion back of the result with priv_str_to_set() includes the additional basic privileges,
guaranteeing that the resulting privilege set carries the same privileges. This behavior
is the default and is equivalent to specifying a flag argument of
PRIV_STR_PORT. When specifying a flag argument of PRIV_STR_LIT, the result does not treat
basic privileges differently and the privileges present are all literally presented in
the output. A flag argument of PRIV_STR_SHORT attempts to arrive at the
shortest output, using the tokens “basic”, “zone”, “all”, and negated privileges. This output
is most useful for trace output.

The priv_getbyname() and priv_getsetbyname() functions map privilege names and privilege set names
to numbers. The numbers returned are valid for the current kernel instance
only and could change at the next boot. Only the privilege names
should be committed to persistent storage. The numbers should not be committed to
persistent storage. Both functions return -1 on error, setting errno to EINVAL.

The priv_getbynum() and priv_getsetbynum() functions map privileges numbers to names. The strings
returned point to shared storage that should not be modified and is
valid for the lifetime of the process. Both functions return NULL on error,
setting errno to EINVAL.

The priv_gettext() function returns a pointer to a string consisting of one
or more newline-separated lines of text describing the privilege. The text is
localized using {LC_MESSAGES}. The application is responsibe for freeing the memory returned.

These functions pick up privileges allocated during the lifetime of the process
using priv_getbyname(9F) by refreshing the internal data structures when necessary.

Return Values

Upon successful completion, priv_str_to_set() and priv_set_to_str() return a non-null pointer to allocated
memory that should be freed by the application using the appropriate functions
when it is no longer referenced.

The priv_getbynum() and priv_getsetbynum() functions return non-null pointers to constant memory that
should not be modified or freed by the application. Otherwise, NULL is
returned and errno is set to indicate the error.

Upon successful completion, priv_getbyname() and priv_getsetbyname() return a non-negative integer. Otherwise, -1
is returned and errno is set to indicate the error.

Upon successful completion, priv_gettext() returns a non-null value. It returns NULL if
an error occurs or no descriptive text for the specified privilege can
be found.

Errors

The priv_str_to_set() and priv_set_to_str() functions will fail if:

ENOMEM

The physical limits of the system are exceeded by the memory allocation needed to hold a privilege set.

EAGAIN

There is not enough memory available to allocate sufficient memory to hold a privilege set, but the application could try again later.

All of these functions will fail if:

EINVAL

One or more of the arguments is invalid.

Examples

Example 1 List all the sets and privileges defined in the system.

The following example lists all the sets and privileges defined in the
system.