1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\"
  14 .Dd May 11, 2016
  15 .Dt PCRED 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pcred
  19 .Nd obtain process credentials
  20 .Sh SYNOPSIS
  21 .Lb libproc
  22 .In libproc.h
  23 .Ft int
  24 .Fo Pcred
  25 .Fa "struct ps_prochandle *P"
  26 .Fa "prcred_t *pcrp"
  27 .Fa "int ngroups"
  28 .Fc
  29 .Sh DESCRIPTION
  30 The
  31 .Fn Pcred
  32 function obtains the credentials of the process from the handle
  33 .Fa P .
  34 .Pp
  35 The credentials are read into the buffer pointed to by
  36 .Fa pcrp .
  37 The
  38 .Sy prcred_t
  39 type is defined in
  40 .Xr proc 4 .
  41 It contains information about the current effective, saved, and real
  42 user and group IDs.
  43 It also allows for supplemental groups to be obtained.
  44 The
  45 .Fn Pcred
  46 function will read a number of supplemental groups based on the value of
  47 .Fa ngroups .
  48 The
  49 .Sy prcred_t
  50 structure only contains the space for one supplemental group by default.
  51 Callers should ensure that the buffer pointed to by
  52 .Fa pcrp
  53 contains enough space to include all of the required supplemental
  54 groups that are desired.
  55 .Pp
  56 Not all process handles have credential information available to them.
  57 For example, the handles that come from
  58 .Xr Pgrab_file 3PROC
  59 have no processes associated with them and thus have no credentials
  60 associated with them.
  61 .Sh RETURN VALUES
  62 Upon successful completion, the
  63 .Fn Pcred
  64 function returns
  65 .Sy 0
  66 and updates the memory at
  67 .Fa pcrp
  68 with the credentials.
  69 Otherwise,
  70 .Sy -1
  71 is returned to indicate an error.
  72 .Sh INTERFACE STABILITY
  73 .Sy Uncommitted
  74 .Sh MT-LEVEL
  75 See
  76 .Sy LOCKING
  77 in
  78 .Xr libproc 3LIB .
  79 .Sh SEE ALSO
  80 .Xr libproc 3LIB ,
  81 .Xr Psetcred 3PROC ,
  82 .Xr proc 4