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