usr/src/man/man3c/priv_addset.3c

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