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

   1 '\" te
   2 .\" Copyright (c) 2008, 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 UCRED_GET 3C "Apr 4, 2008"
   7 .SH NAME
   8 ucred_get, ucred_free, ucred_geteuid, ucred_getruid, ucred_getsuid,
   9 ucred_getegid, ucred_getrgid, ucred_getsgid, ucred_getgroups, ucred_getprivset,
  10 ucred_getpid, ucred_getprojid, ucred_getzoneid, ucred_getpflags,
  11 ucred_getlabel, ucred_size \- user credential functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 #include <ucred.h>
  16
  17 \fBucred_t *\fR\fBucred_get\fR(\fBpid_t\fR \fIpid\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBvoid\fR \fBucred_free\fR(\fBucred_t *\fR\fIuc\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBuid_t\fR \fBucred_geteuid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBuid_t\fR \fBucred_getruid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBuid_t\fR \fBucred_getsuid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBgid_t\fR \fBucred_getegid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  43 .fi
  44
  45 .LP
  46 .nf
  47 \fBgid_t\fR \fBucred_getrgid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  48 .fi
  49
  50 .LP
  51 .nf
  52 \fBgid_t\fR \fBucred_getsgid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  53 .fi
  54
  55 .LP
  56 .nf
  57 \fBint\fR \fBucred_getgroups\fR(\fBconst ucred_t *\fR\fIuc\fR, \fBconst gid_t **\fR\fIgroups\fR);
  58 .fi
  59
  60 .LP
  61 .nf
  62 \fBconst priv_set_t *\fR\fBucred_getprivset\fR(\fBconst ucred_t *\fR\fIuc\fR,
  63      \fBpriv_ptype_t\fR \fIset\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBpid_t\fR \fBucred_getpid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  69 .fi
  70
  71 .LP
  72 .nf
  73 \fBprojid_t\fR \fBucred_getprojid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  74 .fi
  75
  76 .LP
  77 .nf
  78 \fBzoneid_t\fR \fBucred_getzoneid\fR(\fBconst ucred_t *\fR\fIuc\fR);
  79 .fi
  80
  81 .LP
  82 .nf
  83 \fBuint_t\fR \fBucred_getpflags\fR(\fBconst ucred_t *\fR\fIuc\fR, \fBuint_t\fR \fIflags\fR);
  84 .fi
  85
  86 .LP
  87 .nf
  88 \fBm_label_t *\fR\fBucred_getlabel\fR(\fBconst ucred_t *\fR\fIuc\fR);
  89 .fi
  90
  91 .LP
  92 .nf
  93 \fBsize_t\fR \fBucred_size\fR(\fBvoid\fR);
  94 .fi
  95
  96 .SH DESCRIPTION
  97 .sp
  98 .LP
  99 These functions return or act on a user credential, \fBucred_t\fR. User
 100 credentials are returned by various functions and describe the credentials of a
 101 process. Information about the process can then be obtained by calling the
 102 access functions. Access functions can fail if the underlying mechanism did not
 103 return sufficient information.
 104 .sp
 105 .LP
 106 The \fBucred_get()\fR function returns the user credential of the specified
 107 \fIpid\fR or \fINULL\fR if none can be obtained. A \fIpid\fR value of
 108 \fBP_MYID\fR returns information about the calling process. The return value is
 109 dynamically allocated and must be freed using \fBucred_free()\fR.
 110 .sp
 111 .LP
 112 The \fBucred_geteuid()\fR, \fBucred_getruid()\fR, \fBucred_getsuid()\fR,
 113 \fBucred_getegid()\fR, \fBucred_getrgid()\fR, and \fBucred_getsgid()\fR
 114 functions return the effective UID, real UID, saved UID, effective GID, real
 115 GID, saved GID, respectively, or -1 if the user credential does not contain
 116 sufficient information.
 117 .sp
 118 .LP
 119 The \fBucred_getgroups()\fR function stores a pointer to the group list in the
 120 \fBgid_t *\fR pointed to by the second argument and returns the number of
 121 groups in the list. It returns -1 if the information is not available. The
 122 returned group list is valid until \fBucred_free()\fR is called on the user
 123 credential given as argument.
 124 .sp
 125 .LP
 126 The \fBucred_getpid()\fR function returns the process ID of the process or -1
 127 if the process ID is not available. The process ID returned in a user
 128 credential is only guaranteed to be correct in a very limited number of cases
 129 when returned by \fBdoor_ucred\fR(3C) and \fBucred_get()\fR. In all other
 130 cases, the process in question might have handed of the file descriptor, the
 131 process might have exited or executed another program, or the process ID might
 132 have been reused by a completely unrelated process after the original program
 133 exited.
 134 .sp
 135 .LP
 136 The \fBucred_getprojid()\fR function returns the project ID of the process or
 137 -1 if the project ID is not available.
 138 .sp
 139 .LP
 140 The \fBucred_getzoneid()\fR function returns the zone ID of the process or
 141 \(mi1 if the zone ID is not available.
 142 .sp
 143 .LP
 144 The \fBucred_getprivset()\fR function returns the specified privilege set
 145 specified as second argument, or \fINULL\fR if either the requested information
 146 is not available or the privilege set name is invalid. The returned privilege
 147 set is valid until \fBucred_free()\fR is called on the specified user
 148 credential.
 149 .sp
 150 .LP
 151 The \fBucred_getpflags()\fR function returns the value of the specified
 152 privilege flags from the \fBucred\fR structure, or (\fBuint_t\fR)-1 if none was
 153 present.
 154 .sp
 155 .LP
 156 The \fBucred_getlabel()\fR function returns the value of the label, or
 157 \fINULL\fR if the label is not available. The returned label is valid until
 158 \fBucred_free()\fR is called on the specified user credential. This function is
 159 available only if the system is configured with Trusted Extensions.
 160 .sp
 161 .LP
 162 The \fBucred_free()\fR function frees the memory allocated for the specified
 163 user credential.
 164 .sp
 165 .LP
 166 The \fBucred_size()\fR function returns \fBsizeof\fR(\fBucred_t\fR). This value
 167 is constant only until the next boot, at which time it could change. The
 168 \fBucred_size()\fR function can be used to determine the size of the buffer
 169 needed to receive a credential option with \fBSO_RECVUCRED\fR. See
 170 \fBsocket.h\fR(3HEAD).
 171 .SH RETURN VALUES
 172 .sp
 173 .LP
 174 See DESCRIPTION.
 175 .SH ERRORS
 176 .sp
 177 .LP
 178 The \fBucred_get()\fR function will fail if:
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBEAGAIN\fR\fR
 183 .ad
 184 .RS 10n
 185 There is not enough memory available to allocate sufficient memory to hold a
 186 user credential. The application can try again later.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBEACCES\fR\fR
 193 .ad
 194 .RS 10n
 195 The caller does not have sufficient privileges to examine the target process.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fBEMFILE\fR\fR
 202 .ad
 203 .br
 204 .na
 205 \fB\fBENFILE\fR\fR
 206 .ad
 207 .RS 10n
 208 The calling process cannot open any more files.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBENOMEM\fR\fR
 215 .ad
 216 .RS 10n
 217 The physical limits of the system are exceeded by the memory allocation needed
 218 to hold a user credential.
 219 .RE
 220
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBESRCH\fR\fR
 225 .ad
 226 .RS 10n
 227 The target process does not exist.
 228 .RE
 229
 230 .sp
 231 .LP
 232 The \fBucred_getprivset()\fR function will fail if:
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBEINVAL\fR\fR
 237 .ad
 238 .RS 10n
 239 The privilege set argument is invalid.
 240 .RE
 241
 242 .sp
 243 .LP
 244 The \fBucred_getlabel()\fR function will fail if:
 245 .sp
 246 .ne 2
 247 .na
 248 \fB\fBEINVAL\fR\fR
 249 .ad
 250 .RS 10n
 251 The label is not present.
 252 .RE
 253
 254 .sp
 255 .LP
 256 The \fBucred_geteuid()\fR, \fBucred_getruid()\fR, \fBucred_getsuid()\fR,
 257 \fBucred_getegid()\fR, \fBucred_getrgid()\fR, \fBucred_getsgid()\fR,
 258 \fBucred_getgroups()\fR, \fBucred_getpflags()\fR, \fBucred_getprivset()\fR,
 259 \fBucred_getprojid()\fR, \fBucred_getpid()\fR, and \fBucred_getlabel()\fR
 260 functions will fail if:
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fBEINVAL\fR\fR
 265 .ad
 266 .RS 10n
 267 The requested user credential attribute is not available in the specified user
 268 credential.
 269 .RE
 270
 271 .SH ATTRIBUTES
 272 .sp
 273 .LP
 274 See \fBattributes\fR(5) for descriptions of the following attributes:
 275 .sp
 276
 277 .sp
 278 .TS
 279 box;
 280 c | c
 281 l | l .
 282 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 283 _
 284 Interface Stability     Committed
 285 _
 286 MT-Level        MT-Safe
 287 .TE
 288
 289 .SH SEE ALSO
 290 .sp
 291 .LP
 292 \fBgetpflags\fR(2), \fBgetppriv\fR(2), \fBdoor_ucred\fR(3C),
 293 \fBgetpeerucred\fR(3C), \fBpriv_set\fR(3C), \fBsocket.h\fR(3HEAD),
 294 \fBattributes\fR(5), \fBlabels\fR(5), \fBprivileges\fR(5)