'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH priv_str_to_set 3C "6 Jan 2004" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
priv_str_to_set, priv_set_to_str, priv_getbyname, priv_getbynum,
priv_getsetbyname, priv_getsetbynum, priv_gettext \- privilege name functions
.SH SYNOPSIS
.LP
.nf
#include <priv.h>

\fBpriv_set_t *\fR\fBpriv_str_to_set\fR(\fBconst char *\fR\fIbuf\fR, \fBconst char *\fR\fIsep\fR,
     \fBconst char **\fR\fIendptr\fR);
.fi

.LP
.nf
\fBchar *\fR\fBpriv_set_to_str\fR(\fBconst priv_set_t *\fR\fIset\fR, \fBchar\fR \fIsep\fR, \fBint\fR \fIflag\fR);
.fi

.LP
.nf
\fBint\fR \fBpriv_getbyname\fR(\fBconst char *\fR\fIprivname\fR);
.fi

.LP
.nf
\fBconst char *\fR\fBpriv_getbynum\fR(\fBint\fR \fIprivnum\fR);
.fi

.LP
.nf
\fBint\fR \fBpriv_getsetbyname\fR(\fBconst char *\fR\fIprivsetname\fR);
.fi

.LP
.nf
\fBconst char *\fR\fBpriv_getsetbynum\fR(\fBint\fR \fIprivname\fR);
.fi

.LP
.nf
\fBchar *\fR\fBpriv_gettext\fR(\fBconst char *\fR\fIprivname\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpriv_str_to_set()\fR function maps the privilege specification in
\fIbuf\fR to a privilege set. It returns a privilege set on success or
\fINULL\fR 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 \fIendptr\fR,
provided that \fIendptr\fR is not a null pointer. If an error occurs when
allocating memory, \fBerrno\fR is set and the object pointed to by \fIendptr\fR
is set to the null pointer, provided that \fIendptr\fR is not a null pointer.
.sp
.LP
The application is responsible for freeing the returned privilege set using
\fBpriv_freeset\fR(3C).
.sp
.LP
A privilege specification should contain one or more privilege names, separated
by characters in \fIsep\fR using the same algorithm as \fBstrtok\fR(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.
.sp
.LP
The \fBpriv_set_to_str()\fR function converts the privilege set to a sequence
of privileges separated by \fIsep\fR, returning the a pointer to the
dynamically allocated result. The application is responsible for freeing the
memory using \fBfree\fR(3C).
.sp
.LP
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 \fBpriv_str_to_set()\fR 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 \fIflag\fR argument
of \fBPRIV_STR_PORT\fR. When specifying a \fIflag\fR argument of
\fBPRIV_STR_LIT\fR, the result does not treat basic privileges differently and
the privileges present are all literally presented in the output. A flag
argument of \fBPRIV_STR_SHORT\fR attempts to arrive at the shortest output,
using the tokens "basic", "zone", "all", and negated privileges. This output is
most useful for trace output.
.sp
.LP
The \fBpriv_getbyname()\fR and \fBpriv_getsetbyname()\fR 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 \fBerrno\fR to \fBEINVAL\fR.
.sp
.LP
The \fBpriv_getbynum()\fR and \fBpriv_getsetbynum()\fR 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
\fINULL\fR on error, setting \fBerrno\fR to \fBEINVAL\fR.
.sp
.LP
The \fBpriv_gettext()\fR 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 {\fBLC_MESSAGES\fR}. The application is responsibe for
freeing the memory returned.
.sp
.LP
These functions pick up privileges allocated during the lifetime of the process
using \fBpriv_getbyname\fR(9F) by refreshing the internal data structures when
necessary.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBpriv_str_to_set()\fR and \fBpriv_set_to_str()\fR
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.
.sp
.LP
The \fBpriv_getbynum()\fR and \fBpriv_getsetbynum()\fR functions return
non-null pointers to constant memory that should not be modified or freed by
the application. Otherwise, \fINULL\fR is returned and \fBerrno\fR is set to
indicate the error.
.sp
.LP
Upon successful completion, \fBpriv_getbyname()\fR and
\fBpriv_getsetbyname()\fR return a non-negative integer. Otherwise, -1 is
returned and \fBerrno\fR is set to indicate the error.
.sp
.LP
Upon successful completion, \fBpriv_gettext()\fR returns a non-null value. It
returns \fINULL\fR if an error occurs or no descriptive text for the specified
privilege can be found.
.SH ERRORS
.sp
.LP
The \fBpriv_str_to_set()\fR and \fBpriv_set_to_str()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
.rt  
The physical limits of the system are exceeded by the memory allocation needed
to hold a privilege set.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
.rt  
There is not enough memory available to allocate sufficient memory to hold a
privilege set, but the application could try again later.
.RE

.sp
.LP
All of these functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
One or more of the arguments is invalid.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRList all the sets and privileges defined in the system.
.sp
.LP
The following example lists all the sets and privileges defined in the system.

.sp
.in +2
.nf
#include <priv.h>
#include <stdio.h>

/* list all the sets and privileges defined in the system */

const char *name;
int i;

printf("Each process has the following privilege sets:\en");
for (i = 0; (name = priv_getsetbynum(i++)) != NULL; )
        printf("\et%s\en", name);

printf("Each set can contain the following privileges:\en");
for (i = 0; (name = priv_getbynum(i++)) != NULL; )
        printf("\et%s\en", name);
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityEvolving
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBfree\fR(3C), \fBpriv_set\fR(3C), \fBattributes\fR(5), \fBprivileges\fR(5),
\fBpriv_getbyname\fR(9F)