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