usr/src/man/man9f/priv_policy.9f

   1 '\" te
   2 .\"  Copyright (c) 2009, 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. 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
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PRIV_POLICY 9F "Apr 3, 2009"
   7 .SH NAME
   8 priv_policy, priv_policy_only, priv_policy_choice \- check, report, and audit
   9 privileges
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/policy.h>
  14
  15 \fBint\fR \fBpriv_policy\fR(\fBconst cred_t  *\fR\fIcr\fR, \fBint\fR \fIpriv\fR, \fBint\fR \fIerr\fR,
  16      \fBboolean_t\fR \fIflag\fR, \fBconst char  *\fR\fImsg\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBboolean_t\fR \fBpriv_policy_only\fR(\fBconst cred_t  *\fR\fIcr\fR, \fBint\fR \fIpriv\fR,
  22      \fBboolean_t\fR \fIflag\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBboolean_t\fR \fBpriv_policy_choice\fR(\fBconst cred_t  *\fR\fIcr\fR, \fBint\fR \fIpriv\fR,
  28      \fBboolean_t\fR \fIflag\fR);
  29 .fi
  30
  31 .SH INTERFACE LEVEL
  32 .sp
  33 .LP
  34 Solaris DDI specific (Solaris DDI).
  35 .SH PARAMETERS
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIcr\fR\fR
  40 .ad
  41 .RS 8n
  42 The credential to be checked.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIpriv\fR\fR
  49 .ad
  50 .RS 8n
  51 The integer value of the privilege to test.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIflag\fR\fR
  58 .ad
  59 .RS 8n
  60 All zone privileges flag. Set to \fBB_FALSE\fR for most tests or \fBB_TRUE\fR
  61 if the operation requires the caller to have all available privileges in the
  62 zone.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIerr\fR\fR
  69 .ad
  70 .RS 8n
  71 The error code to return.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fImsg\fR\fR
  78 .ad
  79 .RS 8n
  80 String that is added to the privilege debugging message if one is generated.
  81 NULL if no additional information is needed. Because the function name is
  82 included in the output, NULL is usually the best value to pass as a parameter.
  83 .RE
  84
  85 .SH DESCRIPTION
  86 .sp
  87 .LP
  88 These functions aid in privilege checking and privilege debugging.
  89 .sp
  90 .LP
  91 The \fBpriv_policy()\fR, \fBpriv_policy_only()\fR, and
  92 \fBpriv_policy_choice()\fR functions all check whether \fIpriv\fR is asserted
  93 in the effective set of the credential. The special value \fBPRIV_ALL\fR tests
  94 for all privileges.
  95 .sp
  96 .LP
  97 The \fBpriv_policy()\fR function updates the ASU accounting flag and records
  98 the privilege used on success in the audit trail if the required privilege was
  99 not a basic privilege.
 100 .sp
 101 .LP
 102 The \fBpriv_policy_only()\fR function checks whether a privilege is asserted
 103 and has no side effects.
 104 .sp
 105 .LP
 106 The \fBpriv_policy_choice()\fR function behaves like \fBpriv_policy_only()\fR
 107 but records the successfully used non-basic privileges in the audit trail.
 108 .SH RETURN VALUES
 109 .sp
 110 .LP
 111 On success, \fBpriv_policy()\fR return 0. On failure it returns its parameter
 112 \fIerr\fR.
 113 .sp
 114 .LP
 115 On success, \fBpriv_policy_choice()\fR and \fBpriv_policy_only()\fR return 1,
 116 on failure both return 0.
 117 .SH ERRORS
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBEINVAL\fR\fR
 122 .ad
 123 .RS 16n
 124 This might be caused by any of the following:
 125 .RS +4
 126 .TP
 127 .ie t \(bu
 128 .el o
 129 The \fIflags\fR parameter is invalid.
 130 .RE
 131 .RS +4
 132 .TP
 133 .ie t \(bu
 134 .el o
 135 The specified privilege does not exist.
 136 .RE
 137 .RS +4
 138 .TP
 139 .ie t \(bu
 140 .el o
 141 The \fIpriv\fR parameter contains invalid characters.
 142 .RE
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBENOMEM\fR\fR
 149 .ad
 150 .RS 16n
 151 There is no room to allocate another privilege.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBENAMETOOLONG\fR\fR
 158 .ad
 159 .RS 16n
 160 An attempt was made to allocate a privilege that was longer than
 161 \fB{PRIVNAME_MAX}\fR characters.
 162 .RE
 163
 164 .SH CONTEXT
 165 .sp
 166 .LP
 167 This functions can be called from user, interrupt, or kernel context.
 168 .SH ATTRIBUTES
 169 .sp
 170 .LP
 171 See \fBattributes\fR(5) for a description of the following attributes:
 172 .sp
 173
 174 .sp
 175 .TS
 176 box;
 177 c | c
 178 l | l .
 179 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 180 _
 181 Interface Stability     Committed
 182 .TE
 183
 184 .SH SEE ALSO
 185 .sp
 186 .LP
 187 \fBacct\fR(3HEAD), \fBattributes\fR(5), \fBprivileges\fR(5)
 188 .sp
 189 .LP
 190 \fIWriting Device Drivers\fR