1 '\" te
   2 .\" Copyright (c) 2005, 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_ADDSET 3C "Sep 08, 2015"
   7 .SH NAME
   8 priv_addset, priv_allocset, priv_copyset, priv_delset, priv_emptyset,
   9 priv_basicset, priv_defaultset, priv_fillset, priv_freeset, priv_intersect,
  10 priv_inverse, priv_isemptyset, priv_isequalset, priv_isfullset, priv_ismember,
  11 priv_issubset, priv_union \-
  12 privilege set manipulation functions
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 #include <priv.h>
  17 
  18 \fBint\fR \fBpriv_addset\fR(\fBpriv_set_t *\fR\fIsp\fR, \fBconst char *\fR\fIpriv\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBpriv_set_t *\fR\fBpriv_allocset\fR(\fBvoid\fR);
  24 .fi
  25 
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBpriv_copyset\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBpriv_set_t *\fR\fIdst\fR);
  29 .fi
  30 
  31 .LP
  32 .nf
  33 \fBint\fR \fBpriv_delset\fR(\fBpriv_set_t *\fR\fIsp\fR, \fBconst char *\fR\fIpriv\fR);
  34 .fi
  35 
  36 .LP
  37 .nf
  38 \fBvoid\fR \fBpriv_emptyset\fR(\fBpriv_set_t *\fR\fIsp\fR);
  39 .fi
  40 
  41 .LP
  42 .nf
  43 \fBvoid\fR \fBpriv_basicset\fR(\fBpriv_set_t *\fR\fIsp\fR);
  44 .fi
  45 
  46 .LP
  47 .nf
  48 \fBvoid\fR \fBpriv_defaultset\fR(\fBpriv_set_t *\fR\fIsp\fR);
  49 .fi
  50 
  51 .LP
  52 .nf
  53 \fBvoid\fR \fBpriv_fillset\fR(\fBpriv_set_t *\fR\fIsp\fR);
  54 .fi
  55 
  56 .LP
  57 .nf
  58 \fBvoid\fR \fBpriv_freeset\fR(\fBpriv_set_t *\fR\fIsp\fR);
  59 .fi
  60 
  61 .LP
  62 .nf
  63 \fBvoid\fR \fBpriv_intersect\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBpriv_set_t *\fR\fIdst\fR);
  64 .fi
  65 
  66 .LP
  67 .nf
  68 \fBvoid\fR \fBpriv_inverse\fR(\fBpriv_set_t *\fR\fIsp\fR);
  69 .fi
  70 
  71 .LP
  72 .nf
  73 \fBboolean_t\fR \fBpriv_isemptyset\fR(\fBconst priv_set_t *\fR\fIsp\fR);
  74 .fi
  75 
  76 .LP
  77 .nf
  78 \fBboolean_t\fR \fBpriv_isequalset\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBconst priv_set_t *\fR\fIdst\fR);
  79 .fi
  80 
  81 .LP
  82 .nf
  83 \fBboolean_t\fR \fBpriv_isfullset\fR(\fBconst priv_set_t *\fR\fIsp\fR);
  84 .fi
  85 
  86 .LP
  87 .nf
  88 \fBboolean_t\fR \fBpriv_ismember\fR(\fBconst priv_set_t *\fR\fIsp\fR, \fBconst char *\fR\fIpriv\fR);
  89 .fi
  90 
  91 .LP
  92 .nf
  93 \fBboolean_t\fR \fBpriv_issubset\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBconst priv_set_t *\fR\fIdst\fR);
  94 .fi
  95 
  96 .LP
  97 .nf
  98 \fBvoid\fR \fBpriv_union\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBpriv_set_t *\fR\fIdst\fR);
  99 .fi
 100 
 101 .SH DESCRIPTION
 102 .LP
 103 The \fIsp\fR, \fIsrc\fR, and \fIdst\fR arguments point to privilege sets. The
 104 \fIpriv\fR argument points to a named privilege.
 105 .sp
 106 .LP
 107 The \fBpriv_addset()\fR function adds the named privilege \fIpriv\fR to
 108 \fIsp\fR.
 109 .sp
 110 .LP
 111 The \fBpriv_allocset()\fR function allocates sufficient memory to contain a
 112 privilege set. The value of the returned privilege set is indeterminate. The
 113 function returns \fINULL\fR and sets \fBerrno\fR when it fails to allocate
 114 memory.
 115 .sp
 116 .LP
 117 The \fBpriv_copyset()\fR function copies the set \fIsrc\fR to \fIdst\fR.
 118 .sp
 119 .LP
 120 The \fBpriv_delset()\fR function removes the named privilege \fIpriv\fR from
 121 \fIsp\fR.
 122 .sp
 123 .LP
 124 The \fBpriv_emptyset()\fR function clears all privileges from \fIsp\fR.
 125 .sp
 126 .LP
 127 The \fBpriv_basicset()\fR function copies the basic privilege set to \fIsp\fR.
 128 .sp
 129 .LP
 130 The \fBpriv_defaultset()\fR function copies the default privilege set to
 131 \fIsp\fR.
 132 .sp
 133 .LP
 134 The \fBpriv_fillset()\fR function asserts all privileges in \fIsp\fR, including
 135 the privileges not currently defined in the system.
 136 .sp
 137 .LP
 138 The \fBpriv_freeset()\fR function frees the storage allocated by
 139 \fBpriv_allocset()\fR.
 140 .sp
 141 .LP
 142 The \fBpriv_intersect()\fR function intersects \fIsrc\fR with \fIdst\fR and
 143 places the results in \fIdst\fR.
 144 .sp
 145 .LP
 146 The \fBpriv_inverse()\fR function inverts the privilege set given as argument
 147 in place.
 148 .sp
 149 .LP
 150 The \fBpriv_isemptyset()\fR function checks whether the argument is an empty
 151 set.
 152 .sp
 153 .LP
 154 The \fBpriv_isequalset()\fR function checks whether the privilege set \fIsrc\fR
 155 is equal to \fIdst\fR.
 156 .sp
 157 .LP
 158 The \fBpriv_isfullset()\fR function checks whether the argument is a full set.
 159 A full set is a set with all bits set, regardless of whether the privilege is
 160 currently defined in the system.
 161 .sp
 162 .LP
 163 The \fBpriv_ismember()\fR function checks whether the named privilege
 164 \fIpriv\fR is a member of \fIsp\fR.
 165 .sp
 166 .LP
 167 The \fBpriv_issubset()\fR function checks whether \fIsrc\fR is a subset of
 168 \fIdst\fR.
 169 .sp
 170 .LP
 171 The \fBpriv_union()\fR function takes the union of \fIsrc\fR and \fIdst\fR and
 172 places the result in \fIdst\fR.
 173 .SH RETURN VALUES
 174 .LP
 175 Upon successful completion, \fBpriv_allocset()\fR returns a pointer to an
 176 opaque data structure. It returns \fINULL\fR if memory allocation fails and
 177 sets \fBerrno\fR to indicate the error.
 178 .sp
 179 .LP
 180 Upon successful completion, \fBpriv_isemptyset()\fR, \fBpriv_isfullset()\fR,
 181 \fBpriv_isequalset()\fR, \fBpriv_issubset()\fR, and \fBpriv_ismember()\fR
 182 return \fBB_TRUE\fR. Otherwise, they return \fBB_FALSE\fR.
 183 .sp
 184 .LP
 185 Upon successful completion, \fBpriv_delset()\fR and \fBpriv_addset()\fR return
 186 0. Otherwise, they return -1 and set \fBerrno\fR to indicate the error.
 187 .SH ERRORS
 188 .LP
 189 The \fBpriv_allocset()\fR function will fail if:
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fBENOMEM\fR\fR
 194 .ad
 195 .RS 10n
 196 The physical limits of the system are exceeded by the memory allocation needed
 197 to hold a privilege set.
 198 .RE
 199 
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBEAGAIN\fR\fR
 204 .ad
 205 .RS 10n
 206 There is insufficient memory for allocation to hold a privilege set. The
 207 application can try again later.
 208 .RE
 209 
 210 .sp
 211 .LP
 212 The \fBpriv_delset()\fR and \fBpriv_addset()\fR functions will fail if:
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBEINVAL\fR\fR
 217 .ad
 218 .RS 10n
 219 The privilege argument is not a valid privilege name.
 220 .RE
 221 
 222 .SH ATTRIBUTES
 223 .LP
 224 See \fBattributes\fR(5) for descriptions of the following attributes:
 225 .sp
 226 
 227 .sp
 228 .TS
 229 box;
 230 c | c
 231 l | l .
 232 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 233 _
 234 Interface Stability     Evolving
 235 _
 236 MT-Level        MT-Safe
 237 .TE
 238 
 239 .SH SEE ALSO
 240 .LP
 241 \fBsetppriv\fR(2), \fBmalloc\fR(3C), \fBpriv_str_to_set\fR(3C),
 242 \fBattributes\fR(5), \fBprivileges\fR(5)
 243 .SH NOTES
 244 .LP
 245 The functions that compare sets operate on all bits of the set, regardless of
 246 whether the specific privileges are currently defined in the system.