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