CRED(9)

NAME
cred, crcopy, crcvt crdup, crfree, crget, crhold, - operations on user credentials

SYNOPSIS
#include <sys/param.h>
#include <sys/ucred.h>
struct ucred *
crcopy(struct ucred *cr);
void
crcvt(struct ucred *cr, const struct uucred *ucr);
struct ucred *
crdup(struct ucred *cr);
void
crfree(struct ucred *cr);
struct ucred *
crget(void);
void
crhold(struct ucred *cr);

DESCRIPTION
A process must have the appropriate user credentials for the kernel to perform an operation on its behalf. The user credentials are stored along with the process in the following structure:

    struct ucred {
            u_int32_t       cr_ref;                 /* reference count */
            uid_t           cr_uid;                 /* effective user id */
            gid_t           cr_gid;                 /* effective group id */
            u_int32_t       cr_ngroups;             /* number of groups */
            gid_t           cr_groups[NGROUPS];     /* groups */
    };

User credentials are controlled by the group(5) and passwd(5) files and manipulated using the setregid(2), setgid(2), setegid(2), setgroups(2), and getgroups(2) system calls.

References to user credentials are maintained from many different data structures, including processes, file descriptors and vnodes. The ucred member cr_ref reflects the number of references to the credentials.

FUNCTIONS
The following functions operate on user credentials:

crcopy(cr)
    Allocate a new credentials structure and copy the contents from credentials cr to the new one. The old credentials cr are freed. The reference count on the returned credentials is guaranteed to be one.

crcvt(cr, ucr)
    Convert from userland credentials ucr to kernel credentials cr.

crdup(cr)
    Allocate a new credentials structure and copy the contents from credentials cr to the new one. The old credentials cr remain unchanged. The reference count on the returned credentials is guaranteed to be one.

crfree(cr)
    Decrement the reference count on credentials cr. If the reference count drops to zero, then the credentials are freed.

crget(void)
    Allocate and return zeroed credentials.

crhold(cr)
    Increment the reference count on credentials cr.

SEE ALSO
suser(9)

BUGS
User credentials are sometimes allocated using MALLOC(9) and sometimes using the pool(9) facility. This cannot be right.