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

   1 '\" te
   2 .\"  Copyright (c) 2003, 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 DDI_CRED 9F "Aug 6, 2003"
   7 .SH NAME
   8 ddi_cred, crgetuid, crgetruid, crgetsuid, crgetgid, crgetrgid, crgetsgid,
   9 crgetzoneid, crgetgroups, crgetngroups \- access and change parts of the cred_t
  10 structure
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/cred.h>
  15
  16
  17
  18 \fBuid_t\fR \fBcrgetuid\fR(\fBconst cred_t *\fR\fIcr\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBuid_t\fR \fBcrgetruid\fR(\fBconst cred_t *\fR\fIcr\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBuid_t\fR \fBcrgetsuid\fR(\fBconst cred_t *\fR\fIcr\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBgid_t\fR \fBcrgetgid\fR(\fBconst cred_t *\fR\fIcr\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBgid_t\fR \fBcrgetrgid\fR(\fBconst cred_t *\fR\fIcr\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBgid_t\fR \fBcrgetsgid\fR(\fBconst cred_t *\fR\fIcr\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBzoneid_t\fR \fBcrgetzoneid\fR(\fBconst cred_t *\fR\fIcr\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBconst gid_t *\fR\fBcrgetgroups\fR(\fBconst cred_t *\fR\fIcr\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBint\fR \fBcrgetngroups\fR(\fBconst cred_t *\fR\fIcr\fR);
  59 .fi
  60
  61 .LP
  62 .nf
  63 \fBint\fR \fBcrsetresuid\fR(\fBcred_t *\fR\fIcr\fR, \fBuid_t\fR \fIruid\fR, \fBuid_t\fR \fIeuid\fR, \fBuid_t\fR \fIsuid\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBint\fR \fBcrsetresgid\fR(\fBcred_t *\fR\fIcr\fR, \fBgid_t\fR \fIrgid\fR, \fBgid_t\fR \fIegid\fR, \fBgid_t\fR \fIsgid\fR);
  69 .fi
  70
  71 .LP
  72 .nf
  73 \fBint\fR \fBcrsetugid\fR(\fBcred_t *\fR\fIcr\fR, \fBuid_t\fR \fIuid\fR, \fBgid_t\fR \fIgid\fR);
  74 .fi
  75
  76 .LP
  77 .nf
  78 \fBint\fR \fBcrsetgroups\fR(\fBcred_t *\fR\fIcr\fR, \fBint\fR \fIngroups\fR, \fBgid_t\fR \fIgids\fR);
  79 .fi
  80
  81 .SH INTERFACE LEVEL
  82 .sp
  83 .LP
  84 Solaris DDI specific (Solaris DDI).
  85 .SH PARAMETERS
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fIcr\fR\fR
  90 .ad
  91 .RS 25n
  92 pointer to the user credential structure
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fIuid\fR, \fIruid\fR, \fIeuid\fR, \fIsuid\fR\fR
  99 .ad
 100 .RS 25n
 101 new user id, real, effective and saved user id
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fIgid\fR, \fIrgid\fR, \fIegid\fR, \fIsgid\fR\fR
 108 .ad
 109 .RS 25n
 110 new group id, real, effective and saved group id
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fIngroups\fR\fR
 117 .ad
 118 .RS 25n
 119 number of groups in the group array
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fIgids\fR\fR
 126 .ad
 127 .RS 25n
 128 pointer to array of new groups
 129 .RE
 130
 131 .SH DESCRIPTION
 132 .sp
 133 .LP
 134 The user credential is a shared, read-only, ref-counted data structure. Its
 135 actual size and layout are subject to change. The functions described in this
 136 page allow the programmer to retrieve fields from the structure and to
 137 initialize newly allocated credential structures.
 138 .sp
 139 .LP
 140 \fBcrgetuid()\fR, \fBcrgetruid()\fR, and \fBcrgetsuid()\fR return,
 141 respectively, the effective, real, and saved user id from the user credential
 142 pointed to by \fIcr\fR.
 143 .sp
 144 .LP
 145 \fBcrgetgid()\fR, \fBcrgetrgid()\fR, and \fBcrgetsgid()\fR return,
 146 respectively, the effective, real, and saved group id from the user credential
 147 pointed to by \fIcr\fR.
 148 .sp
 149 .LP
 150 \fBcrgetzoneid()\fR returns the zone id from the user credential pointed to by
 151 \fIcr\fR.
 152 .sp
 153 .LP
 154 \fBcrgetgroups()\fR returns the group list of the user credential pointed to by
 155 \fIcr\fR.
 156 .sp
 157 .LP
 158 \fBcrgetngroups()\fR returns the number of groups in the user credential
 159 pointed to by \fIcr\fR.
 160 .sp
 161 .LP
 162 \fBcrsetresuid()\fR sets the real, effective and saved user id. All but one can
 163 be specified as -1, which causes the original value not to change.
 164 .sp
 165 .LP
 166 \fBcrsetresgid()\fR sets the real, effective and saved group id. All but one
 167 can be specified as -1, which causes the original value not to change.
 168 .sp
 169 .LP
 170 \fBcrsetugid()\fR initializes the real, effective and saved user id \fBall\fR
 171 to \fIuid\fR. It initializes the real, effective, and saved group id \fBall\fR
 172 to \fIgid\fR.
 173 .sp
 174 .LP
 175 \fBcrsetgroups()\fR sets the number of groups in the user credential to
 176 \fIngroups\fR and copies the groups from \fIgids\fR to the user credential. If
 177 \fIngroups\fR is 0, \fIgids\fR need not point to valid storage.
 178 .sp
 179 .LP
 180 It is an error to call this any of the \fBcrset*()\fR functions on a user
 181 credential structure that was newly allocated.
 182 .SH RETURN VALUES
 183 .sp
 184 .LP
 185 The \fBcrget*()\fR functions return the requested information.
 186 .sp
 187 .LP
 188 The \fBcrset*id()\fR functions return 0 on success and -1 if any of the
 189 specified ids are invalid. The functions might cause a system panic if called
 190 on a user credential structure that is referenced by other parts of the system.
 191 .SH CONTEXT
 192 .sp
 193 .LP
 194 These functions can be called from user and kernel contexts.
 195 .SH ATTRIBUTES
 196 .sp
 197 .LP
 198 See \fBattributes\fR(5) for a description of the following attributes:
 199 .sp
 200
 201 .sp
 202 .TS
 203 box;
 204 c | c
 205 l | l .
 206 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 207 _
 208 Architecture    All
 209 _
 210 Interface Stability     Committed
 211 .TE
 212
 213 .SH SEE ALSO
 214 .sp
 215 .LP
 216 \fBattributes\fR(5), \fBprivileges\fR(5), \fBdrv_priv\fR(9F)
 217 .sp
 218 .LP
 219 \fIWriting Device Drivers\fR