te
Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
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. 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 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
ucred, ucred_get, ucred_free, ucred_geteuid, ucred_getruid, ucred_getsuid, ucred_getegid, ucred_getrgid, ucred_getsgid, ucred_getgroups, ucred_getprivset, ucred_getpid, ucred_getprojid, ucred_getzoneid, ucred_getpflags, ucred_getlabel, ucred_size - user credential functions

#include <ucred.h>

ucred_t *ucred_get(pid_t pid);

void ucred_free(ucred_t *uc);

uid_t ucred_geteuid(const ucred_t *uc);

uid_t ucred_getruid(const ucred_t *uc);

uid_t ucred_getsuid(const ucred_t *uc);

gid_t ucred_getegid(const ucred_t *uc);

gid_t ucred_getrgid(const ucred_t *uc);

gid_t ucred_getsgid(const ucred_t *uc);

int ucred_getgroups(const ucred_t *uc, const gid_t **groups);

const priv_set_t *ucred_getprivset(const ucred_t *uc,
 priv_ptype_t set);

pid_t ucred_getpid(const ucred_t *uc);

projid_t ucred_getprojid(const ucred_t *uc);

zoneid_t ucred_getzoneid(const ucred_t *uc);

uint_t ucred_getpflags(const ucred_t *uc, uint_t flags);

m_label_t *ucred_getlabel(const ucred_t *uc);

size_t ucred_size(void);

These functions return or act on a user credential, ucred_t. User credentials are returned by various functions and describe the credentials of a process. Information about the process can then be obtained by calling the access functions. Access functions can fail if the underlying mechanism did not return sufficient information.

The ucred_get() function returns the user credential of the specified pid or NULL if none can be obtained. A pid value of P_MYID returns information about the calling process. The return value is dynamically allocated and must be freed using ucred_free().

The ucred_geteuid(), ucred_getruid(), ucred_getsuid(), ucred_getegid(), ucred_getrgid(), and ucred_getsgid() functions return the effective UID, real UID, saved UID, effective GID, real GID, saved GID, respectively, or -1 if the user credential does not contain sufficient information.

The ucred_getgroups() function stores a pointer to the group list in the gid_t * pointed to by the second argument and returns the number of groups in the list. It returns -1 if the information is not available. The returned group list is valid until ucred_free() is called on the user credential given as argument.

The ucred_getpid() function returns the process ID of the process or -1 if the process ID is not available. The process ID returned in a user credential is only guaranteed to be correct in a very limited number of cases when returned by door_ucred(3C) and ucred_get(). In all other cases, the process in question might have handed of the file descriptor, the process might have exited or executed another program, or the process ID might have been reused by a completely unrelated process after the original program exited.

The ucred_getprojid() function returns the project ID of the process or -1 if the project ID is not available.

The ucred_getzoneid() function returns the zone ID of the process or -1 if the zone ID is not available.

The ucred_getprivset() function returns the specified privilege set specified as second argument, or NULL if either the requested information is not available or the privilege set name is invalid. The returned privilege set is valid until ucred_free() is called on the specified user credential.

The ucred_getpflags() function returns the value of the specified privilege flags from the ucred structure, or (uint_t)-1 if none was present.

The ucred_getlabel() function returns the value of the label, or NULL if the label is not available. The returned label is valid until ucred_free() is called on the specified user credential. This function is available only if the system is configured with Trusted Extensions.

The ucred_free() function frees the memory allocated for the specified user credential.

The ucred_size() function returns sizeof(ucred_t). This value is constant only until the next boot, at which time it could change. The ucred_size() function can be used to determine the size of the buffer needed to receive a credential option with SO_RECVUCRED. See socket.h(3HEAD).

See DESCRIPTION.

The ucred_get() function will fail if: EAGAIN

EACCES EMFILE

ENFILE

ENOMEM ESRCH

The ucred_getprivset() function will fail if: EINVAL

The ucred_getlabel() function will fail if: EINVAL

The ucred_geteuid(), ucred_getruid(), ucred_getsuid(), ucred_getegid(), ucred_getrgid(), ucred_getsgid(), ucred_getgroups(), ucred_getpflags(), ucred_getprivset(), ucred_getprojid(), ucred_getpid(), and ucred_getlabel() functions will fail if: EINVAL

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

MT-Level MT-Safe

getpflags (2), getppriv (2), door_ucred (3C), getpeerucred (3C), priv_set (3C), socket.h (3HEAD), attributes (7), labels (7), privileges (7)