share/man/man3c/priv_str_to_set.3c

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PRIV_STR_TO_SET 3C "Jan 6, 2004"
   7 .SH NAME
   8 priv_str_to_set, priv_set_to_str, priv_getbyname, priv_getbynum,
   9 priv_getsetbyname, priv_getsetbynum, priv_gettext \- privilege name functions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <priv.h>
  14
  15 \fBpriv_set_t *\fR\fBpriv_str_to_set\fR(\fBconst char *\fR\fIbuf\fR, \fBconst char *\fR\fIsep\fR,
  16      \fBconst char **\fR\fIendptr\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBchar *\fR\fBpriv_set_to_str\fR(\fBconst priv_set_t *\fR\fIset\fR, \fBchar\fR \fIsep\fR, \fBint\fR \fIflag\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBpriv_getbyname\fR(\fBconst char *\fR\fIprivname\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBconst char *\fR\fBpriv_getbynum\fR(\fBint\fR \fIprivnum\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBpriv_getsetbyname\fR(\fBconst char *\fR\fIprivsetname\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBconst char *\fR\fBpriv_getsetbynum\fR(\fBint\fR \fIprivname\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBchar *\fR\fBpriv_gettext\fR(\fBconst char *\fR\fIprivname\fR);
  47 .fi
  48
  49 .SH DESCRIPTION
  50 .sp
  51 .LP
  52 The \fBpriv_str_to_set()\fR function maps the privilege specification in
  53 \fIbuf\fR to a privilege set. It returns a privilege set on success or
  54 \fINULL\fR on failure. If an error occurs when parsing the string, a pointer to
  55 the remainder of the string is stored in the object pointed to by \fIendptr\fR,
  56 provided that \fIendptr\fR is not a null pointer. If an error occurs when
  57 allocating memory, \fBerrno\fR is set and the object pointed to by \fIendptr\fR
  58 is set to the null pointer, provided that \fIendptr\fR is not a null pointer.
  59 .sp
  60 .LP
  61 The application is responsible for freeing the returned privilege set using
  62 \fBpriv_freeset\fR(3C).
  63 .sp
  64 .LP
  65 A privilege specification should contain one or more privilege names, separated
  66 by characters in \fIsep\fR using the same algorithm as \fBstrtok\fR(3C).
  67 Privileges can optionally be preceded by a dash (-) or an exclamation mark (!),
  68 in which case they are excluded from the resulting set. The special strings
  69 "none" for the empty set, "all" for the set of all privileges, "zone" for the
  70 set of all privileges available within the caller's zone, and "basic" for the
  71 set of basic privileges are also recognized. Set specifications are interpreted
  72 from left to right.
  73 .sp
  74 .LP
  75 The \fBpriv_set_to_str()\fR function converts the privilege set to a sequence
  76 of privileges separated by \fIsep\fR, returning the a pointer to the
  77 dynamically allocated result. The application is responsible for freeing the
  78 memory using \fBfree\fR(3C).
  79 .sp
  80 .LP
  81 To maintain future compatibility, the "basic" set of privileges is included as
  82 "basic,!missing_basic_priv1,...". When further currently unprivileged
  83 operations migrate to the basic privilege set, the conversion back of the
  84 result with \fBpriv_str_to_set()\fR includes the additional basic privileges,
  85 guaranteeing that the resulting privilege set carries the same privileges. This
  86 behavior is the default and is equivalent to specifying a \fIflag\fR argument
  87 of \fBPRIV_STR_PORT\fR. When specifying a \fIflag\fR argument of
  88 \fBPRIV_STR_LIT\fR, the result does not treat basic privileges differently and
  89 the privileges present are all literally presented in the output. A flag
  90 argument of \fBPRIV_STR_SHORT\fR attempts to arrive at the shortest output,
  91 using the tokens "basic", "zone", "all", and negated privileges. This output is
  92 most useful for trace output.
  93 .sp
  94 .LP
  95 The \fBpriv_getbyname()\fR and \fBpriv_getsetbyname()\fR functions map
  96 privilege names and privilege set names to numbers. The numbers returned are
  97 valid for the current kernel instance only and could change at the next boot.
  98 Only the privilege names should be committed to persistent storage. The numbers
  99 should not be committed to persistent storage. Both functions return -1 on
 100 error, setting \fBerrno\fR to \fBEINVAL\fR.
 101 .sp
 102 .LP
 103 The \fBpriv_getbynum()\fR and \fBpriv_getsetbynum()\fR functions map privileges
 104 numbers to names. The strings returned point to shared storage that should not
 105 be modified and is valid for the lifetime of the process. Both functions return
 106 \fINULL\fR on error, setting \fBerrno\fR to \fBEINVAL\fR.
 107 .sp
 108 .LP
 109 The \fBpriv_gettext()\fR function returns a pointer to a string consisting of
 110 one or more newline-separated lines of text describing the privilege. The text
 111 is localized using {\fBLC_MESSAGES\fR}. The application is responsibe for
 112 freeing the memory returned.
 113 .sp
 114 .LP
 115 These functions pick up privileges allocated during the lifetime of the process
 116 using \fBpriv_getbyname\fR(9F) by refreshing the internal data structures when
 117 necessary.
 118 .SH RETURN VALUES
 119 .sp
 120 .LP
 121 Upon successful completion, \fBpriv_str_to_set()\fR and \fBpriv_set_to_str()\fR
 122 return a non-null pointer to allocated memory that should be freed by the
 123 application using the appropriate functions when it is no longer referenced.
 124 .sp
 125 .LP
 126 The \fBpriv_getbynum()\fR and \fBpriv_getsetbynum()\fR functions return
 127 non-null pointers to constant memory that should not be modified or freed by
 128 the application. Otherwise, \fINULL\fR is returned and \fBerrno\fR is set to
 129 indicate the error.
 130 .sp
 131 .LP
 132 Upon successful completion, \fBpriv_getbyname()\fR and
 133 \fBpriv_getsetbyname()\fR return a non-negative integer. Otherwise, -1 is
 134 returned and \fBerrno\fR is set to indicate the error.
 135 .sp
 136 .LP
 137 Upon successful completion, \fBpriv_gettext()\fR returns a non-null value. It
 138 returns \fINULL\fR if an error occurs or no descriptive text for the specified
 139 privilege can be found.
 140 .SH ERRORS
 141 .sp
 142 .LP
 143 The \fBpriv_str_to_set()\fR and \fBpriv_set_to_str()\fR functions will fail if:
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBENOMEM\fR\fR
 148 .ad
 149 .RS 10n
 150 The physical limits of the system are exceeded by the memory allocation needed
 151 to hold a privilege set.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBEAGAIN\fR\fR
 158 .ad
 159 .RS 10n
 160 There is not enough memory available to allocate sufficient memory to hold a
 161 privilege set, but the application could try again later.
 162 .RE
 163
 164 .sp
 165 .LP
 166 All of these functions will fail if:
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBEINVAL\fR\fR
 171 .ad
 172 .RS 10n
 173 One or more of the arguments is invalid.
 174 .RE
 175
 176 .SH EXAMPLES
 177 .LP
 178 \fBExample 1 \fRList all the sets and privileges defined in the system.
 179 .sp
 180 .LP
 181 The following example lists all the sets and privileges defined in the system.
 182
 183 .sp
 184 .in +2
 185 .nf
 186 #include <priv.h>
 187 #include <stdio.h>
 188
 189 /* list all the sets and privileges defined in the system */
 190
 191 const char *name;
 192 int i;
 193
 194 printf("Each process has the following privilege sets:\en");
 195 for (i = 0; (name = priv_getsetbynum(i++)) != NULL; )
 196         printf("\et%s\en", name);
 197
 198 printf("Each set can contain the following privileges:\en");
 199 for (i = 0; (name = priv_getbynum(i++)) != NULL; )
 200         printf("\et%s\en", name);
 201 .fi
 202 .in -2
 203
 204 .SH ATTRIBUTES
 205 .sp
 206 .LP
 207 See \fBattributes\fR(5) for descriptions of the following attributes:
 208 .sp
 209
 210 .sp
 211 .TS
 212 box;
 213 c | c
 214 l | l .
 215 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 216 _
 217 Interface Stability     Evolving
 218 _
 219 MT-Level        MT-Safe
 220 .TE
 221
 222 .SH SEE ALSO
 223 .sp
 224 .LP
 225 \fBfree\fR(3C), \fBpriv_set\fR(3C), \fBattributes\fR(5), \fBprivileges\fR(5),
 226 \fBpriv_getbyname\fR(9F)