.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PCRED 3PROC
.Os
.Sh NAME
.Nm Pcred
.Nd obtain process credentials
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft int
.Fo Pcred
.Fa "struct ps_prochandle *P"
.Fa "prcred_t *pcrp"
.Fa "int ngroups"
.Fc
.Sh DESCRIPTION
The
.Fn Pcred
function obtains the credentials of the process from the handle
.Fa P .
.Pp
The credentials are read into the buffer pointed to by
.Fa pcrp .
The
.Sy prcred_t
type is defined in
.Xr proc 5 .
It contains information about the current effective, saved, and real
user and group IDs.
It also allows for supplemental groups to be obtained.
The
.Fn Pcred
function will read a number of supplemental groups based on the value of
.Fa ngroups .
The
.Sy prcred_t
structure only contains the space for one supplemental group by default.
Callers should ensure that the buffer pointed to by
.Fa pcrp
contains enough space to include all of the required supplemental
groups that are desired.
.Pp
Not all process handles have credential information available to them.
For example, the handles that come from
.Xr Pgrab_file 3PROC
have no processes associated with them and thus have no credentials
associated with them.
.Sh RETURN VALUES
Upon successful completion, the
.Fn Pcred
function returns
.Sy 0
and updates the memory at
.Fa pcrp
with the credentials.
Otherwise,
.Sy -1
is returned to indicate an error.
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr libproc 3LIB ,
.Xr Psetcred 3PROC ,
.Xr proc 5