Standard C Library Functions privstrtoset(3C)
NAME
privstrtoset, privsettostr, privgetbyname,
privgetbynum, privgetsetbyname, privgetsetbynum,
privgettext - privilege name functions
SYNOPSIS
#include
privsett *privstrtoset(const char *buf, const char *sep,
const char **endptr);
char *privsettostr(const privsett *set, char sep, int flag);
int privgetbyname(const char *privname);
const char *privgetbynum(int privnum);
int privgetsetbyname(const char *privsetname);
const char *privgetsetbynum(int privname);
char *privgettext(const char *privname);
DESCRIPTION
The privstrtoset() function maps the privilege specifica-
tion in buf to a privilege set. It returns a privilege set
on success or NUL on failure. If an error occurs when pars-
ing 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 allo-
cating 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 privfreeset(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
SunOS 5.11 Last change: 6 Jan 2004 1
Standard C Library Functions privstrtoset(3C)
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 privsettostr() 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,!missingbasicpriv1,...".
When further currently unprivileged operations migrate to
the basic privilege set, the conversion back of the result
with privstrtoset() 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
PRIVSTRPORT. When specifying a flag argument of
PRIVSTRLIT, the result does not treat basic privileges
differently and the privileges present are all literally
presented in the output. A flag argument of PRIVSTRSHORT
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 privgetbyname() and privgetsetbyname() 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 func-
tions return -1 on error, setting errno to EINVAL.
The privgetbynum() and privgetsetbynum() 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 NUL on
error, setting errno to EINVAL.
The privgettext() 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
{LCMESAGES}. The application is responsibe for freeing the
memory returned.
SunOS 5.11 Last change: 6 Jan 2004 2
Standard C Library Functions privstrtoset(3C)
These functions pick up privileges allocated during the
lifetime of the process using privgetbyname(9F) by refresh-
ing the internal data structures when necessary.
RETURN VALUES
Upon successful completion, privstrtoset() and
privsettostr() 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 privgetbynum() and privgetsetbynum() functions return
non-null pointers to constant memory that should not be
modified or freed by the application. Otherwise, NUL is
returned and errno is set to indicate the error.
Upon successful completion, privgetbyname() and
privgetsetbyname() return a non-negative integer. Other-
wise, -1 is returned and errno is set to indicate the error.
Upon successful completion, privgettext() returns a non-
null value. It returns NUL if an error occurs or no
descriptive text for the specified privilege can be found.
ERORS
The privstrtoset() and privsettostr() 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.
SunOS 5.11 Last change: 6 Jan 2004 3
Standard C Library Functions privstrtoset(3C)
The following example lists all the sets and privileges
defined in the system.
#include
#include
/* list all the sets and privileges defined in the system */
const char *name;
int i;
printf("Each process has the following privilege sets:\n");
for (i = 0; (name = privgetsetbynum(i])) != NUL; )
printf("\t%s\n", name);
printf("Each set can contain the following privileges:\n");
for (i = 0; (name = privgetbynum(i])) != NUL; )
printf("\t%s\n", name);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level MT-Safe
SEE ALSO
free(3C), privset(3C), attributes(5), privileges(5),
privgetbyname(9F)
SunOS 5.11 Last change: 6 Jan 2004 4
|
