usr/src/man/man3proc/Pcred.3proc

   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 LIBRARY
  21 .Lb libproc
  22 .Sh SYNOPSIS
  23 .In libproc.h
  24 .Ft int
  25 .Fo Pcred
  26 .Fa "struct ps_prochandle *P"
  27 .Fa "prcred_t *pcrp"
  28 .Fa "int ngroups"
  29 .Fc
  30 .Sh DESCRIPTION
  31 The
  32 .Fn Pcred
  33 function obtains the credentials of the process from the handle
  34 .Fa P .
  35 .Pp
  36 The credentials are read into the buffer pointed to by
  37 .Fa pcrp .
  38 The
  39 .Sy prcred_t
  40 type is defined in
  41 .Xr proc 4 .
  42 It contains information about the current effective, saved, and real
  43 user and group IDs.
  44 It also allows for supplemental groups to be obtained.
  45 The
  46 .Fn Pcred
  47 function will read a number of supplemental groups based on the value of
  48 .Fa ngroups .
  49 The
  50 .Sy prcred_t
  51 structure only contains the space for one supplemental group by default.
  52 Callers should ensure that the buffer pointed to by
  53 .Fa pcrp
  54 contains enough space to include all of the required supplemental
  55 groups that are desired.
  56 .Pp
  57 Not all process handles have credential information available to them.
  58 For example, the handles that come from
  59 .Xr Pgrab_file 3PROC
  60 have no processes associated with them and thus have no credentials
  61 associated with them.
  62 .Sh RETURN VALUES
  63 Upon successful completion, the
  64 .Fn Pcred
  65 function returns
  66 .Sy 0
  67 and updates the memory at
  68 .Fa pcrp
  69 with the credentials.
  70 Otherwise,
  71 .Sy -1
  72 is returned to indicate an error.
  73 .Sh INTERFACE STABILITY
  74 .Sy Uncommitted
  75 .Sh MT-LEVEL
  76 See
  77 .Sy LOCKING
  78 in
  79 .Xr libproc 3LIB .
  80 .Sh SEE ALSO
  81 .Xr libproc 3LIB ,
  82 .Xr Psetcred 3PROC ,
  83 .Xr proc 4