usr/src/man/man3c/ucred.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 3C "Nov 6, 2014"
   7 .SH NAME
   8 ucred, 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 .LP
  98 These functions return or act on a user credential, \fBucred_t\fR. User
  99 credentials are returned by various functions and describe the credentials of a
 100 process. Information about the process can then be obtained by calling the
 101 access functions. Access functions can fail if the underlying mechanism did not
 102 return sufficient information.
 103 .sp
 104 .LP
 105 The \fBucred_get()\fR function returns the user credential of the specified
 106 \fIpid\fR or \fINULL\fR if none can be obtained. A \fIpid\fR value of
 107 \fBP_MYID\fR returns information about the calling process. The return value is
 108 dynamically allocated and must be freed using \fBucred_free()\fR.
 109 .sp
 110 .LP
 111 The \fBucred_geteuid()\fR, \fBucred_getruid()\fR, \fBucred_getsuid()\fR,
 112 \fBucred_getegid()\fR, \fBucred_getrgid()\fR, and \fBucred_getsgid()\fR
 113 functions return the effective UID, real UID, saved UID, effective GID, real
 114 GID, saved GID, respectively, or -1 if the user credential does not contain
 115 sufficient information.
 116 .sp
 117 .LP
 118 The \fBucred_getgroups()\fR function stores a pointer to the group list in the
 119 \fBgid_t *\fR pointed to by the second argument and returns the number of
 120 groups in the list. It returns -1 if the information is not available. The
 121 returned group list is valid until \fBucred_free()\fR is called on the user
 122 credential given as argument.
 123 .sp
 124 .LP
 125 The \fBucred_getpid()\fR function returns the process ID of the process or -1
 126 if the process ID is not available. The process ID returned in a user
 127 credential is only guaranteed to be correct in a very limited number of cases
 128 when returned by \fBdoor_ucred\fR(3C) and \fBucred_get()\fR. In all other
 129 cases, the process in question might have handed of the file descriptor, the
 130 process might have exited or executed another program, or the process ID might
 131 have been reused by a completely unrelated process after the original program
 132 exited.
 133 .sp
 134 .LP
 135 The \fBucred_getprojid()\fR function returns the project ID of the process or
 136 -1 if the project ID is not available.
 137 .sp
 138 .LP
 139 The \fBucred_getzoneid()\fR function returns the zone ID of the process or
 140 \(mi1 if the zone ID is not available.
 141 .sp
 142 .LP
 143 The \fBucred_getprivset()\fR function returns the specified privilege set
 144 specified as second argument, or \fINULL\fR if either the requested information
 145 is not available or the privilege set name is invalid. The returned privilege
 146 set is valid until \fBucred_free()\fR is called on the specified user
 147 credential.
 148 .sp
 149 .LP
 150 The \fBucred_getpflags()\fR function returns the value of the specified
 151 privilege flags from the \fBucred\fR structure, or (\fBuint_t\fR)-1 if none was
 152 present.
 153 .sp
 154 .LP
 155 The \fBucred_getlabel()\fR function returns the value of the label, or
 156 \fINULL\fR if the label is not available. The returned label is valid until
 157 \fBucred_free()\fR is called on the specified user credential. This function is
 158 available only if the system is configured with Trusted Extensions.
 159 .sp
 160 .LP
 161 The \fBucred_free()\fR function frees the memory allocated for the specified
 162 user credential.
 163 .sp
 164 .LP
 165 The \fBucred_size()\fR function returns \fBsizeof\fR(\fBucred_t\fR). This value
 166 is constant only until the next boot, at which time it could change. The
 167 \fBucred_size()\fR function can be used to determine the size of the buffer
 168 needed to receive a credential option with \fBSO_RECVUCRED\fR. See
 169 \fBsocket.h\fR(3HEAD).
 170 .SH RETURN VALUES
 171 .LP
 172 See DESCRIPTION.
 173 .SH ERRORS
 174 .LP
 175 The \fBucred_get()\fR function will fail if:
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBEAGAIN\fR\fR
 180 .ad
 181 .RS 10n
 182 There is not enough memory available to allocate sufficient memory to hold a
 183 user credential. The application can try again later.
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBEACCES\fR\fR
 190 .ad
 191 .RS 10n
 192 The caller does not have sufficient privileges to examine the target process.
 193 .RE
 194
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBEMFILE\fR\fR
 199 .ad
 200 .br
 201 .na
 202 \fB\fBENFILE\fR\fR
 203 .ad
 204 .RS 10n
 205 The calling process cannot open any more files.
 206 .RE
 207
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fBENOMEM\fR\fR
 212 .ad
 213 .RS 10n
 214 The physical limits of the system are exceeded by the memory allocation needed
 215 to hold a user credential.
 216 .RE
 217
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fBESRCH\fR\fR
 222 .ad
 223 .RS 10n
 224 The target process does not exist.
 225 .RE
 226
 227 .sp
 228 .LP
 229 The \fBucred_getprivset()\fR function will fail if:
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBEINVAL\fR\fR
 234 .ad
 235 .RS 10n
 236 The privilege set argument is invalid.
 237 .RE
 238
 239 .sp
 240 .LP
 241 The \fBucred_getlabel()\fR function will fail if:
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBEINVAL\fR\fR
 246 .ad
 247 .RS 10n
 248 The label is not present.
 249 .RE
 250
 251 .sp
 252 .LP
 253 The \fBucred_geteuid()\fR, \fBucred_getruid()\fR, \fBucred_getsuid()\fR,
 254 \fBucred_getegid()\fR, \fBucred_getrgid()\fR, \fBucred_getsgid()\fR,
 255 \fBucred_getgroups()\fR, \fBucred_getpflags()\fR, \fBucred_getprivset()\fR,
 256 \fBucred_getprojid()\fR, \fBucred_getpid()\fR, and \fBucred_getlabel()\fR
 257 functions will fail if:
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fBEINVAL\fR\fR
 262 .ad
 263 .RS 10n
 264 The requested user credential attribute is not available in the specified user
 265 credential.
 266 .RE
 267
 268 .SH ATTRIBUTES
 269 .LP
 270 See \fBattributes\fR(5) for descriptions of the following attributes:
 271 .sp
 272
 273 .sp
 274 .TS
 275 box;
 276 c | c
 277 l | l .
 278 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 279 _
 280 Interface Stability     Committed
 281 _
 282 MT-Level        MT-Safe
 283 .TE
 284
 285 .SH SEE ALSO
 286 .LP
 287 \fBgetpflags\fR(2), \fBgetppriv\fR(2), \fBdoor_ucred\fR(3C),
 288 \fBgetpeerucred\fR(3C), \fBpriv_set\fR(3C), \fBsocket.h\fR(3HEAD),
 289 \fBattributes\fR(5), \fBlabels\fR(5), \fBprivileges\fR(5)