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 PGRAB 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pgrab
  19 .Nd grab and control a process
  20 .Sh LIBRARY
  21 .Lb libproc
  22 .Sh SYNOPSIS
  23 .In libproc.h
  24 .Ft "struct ps_prochandle *"
  25 .Fo Pgrab
  26 .Fa "pid_t pid"
  27 .Fa "int flags"
  28 .Fa "int *perr"
  29 .Fc
  30 .Sh DESCRIPTION
  31 The
  32 .Fn Pgrab
  33 function attempts to grab the process identified by
  34 .Fa pid
  35 and returns a handle to it that allows the process to be controlled,
  36 interrogated, and manipulated.
  37 This interface only works with processes that already exist.
  38 Use
  39 .Xr Pgrab_core 3PROC
  40 for core files and
  41 .Xr Pcreate 3PROC
  42 to create processes.
  43 .Pp
  44 A grabbed process undergoes the following changes unless
  45 .Fa flags
  46 is set to the contrary:
  47 .Bl -bullet -offset indent
  48 .It
  49 The process is stopped
  50 .It
  51 All other tracing flags are cleared
  52 .It
  53 The grab is exclusive.
  54 If any existing handles to this process exist or anyone else is using the
  55 underlying facilities of the /proc file system to control this process,
  56 it will fail.
  57 .It
  58 Unless the process is already stopped, the
  59 .Dv PR_RLC
  60 flag is set indicating the process should run-on-last-close.
  61 Allowing the process to resume running if its controlling process dies.
  62 .El
  63 .Pp
  64 Grabbing a process is a
  65 .Em destructive
  66 action.
  67 Stopping a process stops execution of all its threads.
  68 The impact of stopping a process depends on the purpose of that process.
  69 For example, if one stops a process that's primarily doing
  70 computation, then its computation is delayed the entire time that it
  71 is stopped.
  72 However, if instead this is an active TCP server, then the accept backlog may
  73 fill causing connection errors and potentially connection time out errors.
  74 .Pp
  75 Special care must be taken to ensure that a stopped process continues,
  76 even if the controlling process terminates.
  77 If the controlling process disables the
  78 .Dv PR_RLC
  79 flag or the process was already stopped, then the process remains
  80 stopped after the controlling process terminates.
  81 Exercise caution when changing this behavior.
  82 .Pp
  83 Many of these default behaviors can be controlled by passing values to
  84 the
  85 .Fa flags
  86 argument.
  87 Values for
  88 .Fa flags
  89 are constructed by a bitwise-inclusive-OR of flags from the following
  90 list:
  91 .Bl -tag -width Dv -offset indent
  92 .It Dv PGRAB_RETAIN
  93 Indicates that any existing tracing flags on
  94 .Fa pid
  95 should be retained.
  96 If this flag is not specified, they will be cleared as part of creating the
  97 .Sy libproc
  98 handle for this process.
  99 .Pp
 100 Normally extant tracing flags are cleared when a process is grabbed.
 101 .It Dv PGRAB_FORCE
 102 Indicates that the process should not be grabbed exclusively.
 103 Care should be taken with this option.
 104 If other consumers are manipulating the process, then this may result in
 105 surprising behavior as the process is being manipulated from multiple points of
 106 control at the same time.
 107 .Pp
 108 Normally an attempt will be made to grab the process exclusively and
 109 fail if it is already in use.
 110 .It Dv PGRAB_RDONLY
 111 Indicates that the process should be grabbed in a read-only fashion.
 112 This implies that both the
 113 .Dv PGRAB_RETAIN
 114 and
 115 .Dv PGRAB_NOSTOP
 116 flags should be set.
 117 If a process is opened read-only, then a caller can only read information about
 118 a process and cannot manipulate it, change its current state, or inject systems
 119 calls into it.
 120 .Pp
 121 Normally when a process is grabbed, it does so for both reading and writing.
 122 .It Dv PGRAB_NOSTOP
 123 Do not stop a process as it is grabbed.
 124 Note, any extant tracing flags on the process will still be cleared unless the
 125 .Dv PGRAB_RETAIN
 126 flag has been set.
 127 .Pp
 128 Normally a process is stopped as a result of grabbing the process.
 129 .El
 130 .Pp
 131 The
 132 .Fa perr
 133 argument must be a
 134 .Pf non- Dv NULL
 135 pointer which will store a more detailed error in the event that the
 136 .Fn Pgrab
 137 function fails.
 138 A human-readable form of the error can be obtained with
 139 .Xr Pgrab_error 3PROC .
 140 .Pp
 141 Once a caller is done with the library handle it should call
 142 .Xr Prelease 3PROC
 143 to release the grabbed process.
 144 Failure to properly release the handle may leave a process stopped and interfere
 145 with the ability of other software to obtain a handle.
 146 .Ss Permissions
 147 Unprivileged users may grab and control their own processes only if both
 148 the user and group IDs of the target process match those of the calling
 149 process.
 150 In addition, the caller must have a super set of the target's privileges.
 151 Processes with the
 152 .Sy PRIV_PROC_OWNER
 153 privilege may manipulate any process on the system, as long as it has an
 154 equal privilege set.
 155 For more details on the security and programming considerations, please see the
 156 section
 157 .Sy PROGRAMMING NOTES
 158 in
 159 .Xr proc 4 .
 160 .Sh RETURN VALUES
 161 Upon successful completion, the
 162 .Fn Pgrab
 163 function returns a control handle to the process.
 164 Otherwise,
 165 .Dv NULL
 166 is returned with
 167 .Fa perr
 168 containing the error code.
 169 .Sh ERRORS
 170 The
 171 .Fn Pgrab
 172 function will fail if:
 173 .Bl -tag -width Er
 174 .It Er G_BUSY
 175 The process
 176 .Fa pid
 177 is already being traced and the
 178 .Dv PGRAB_FORCE
 179 flag was not passed in
 180 .Fa flags .
 181 .It Er G_LP64
 182 The calling process is a 32-bit process and process
 183 .Fa pid
 184 is 64-bit.
 185 .It Er G_NOFD
 186 Too many files are open.
 187 This is logically equivalent to receiving
 188 .Er EMFILE .
 189 .It Er G_NOPROC
 190 The process referred to by
 191 .Fa pid
 192 does not exist.
 193 .It Er G_PERM
 194 The calling process has insufficient permissions or privileges to open
 195 the specified process.
 196 See
 197 .Sx Permissions
 198 for more information.
 199 .It Er G_SYS
 200 The process referred to by
 201 .Fa pid
 202 is a system process and cannot be grabbed.
 203 .It Er G_SELF
 204 The process referred to by
 205 .Fa pid
 206 is the process ID of the caller and the
 207 .Dv PGRAB_RDONLY
 208 was not passed.
 209 A process may only grab itself if it's read-only.
 210 .It Er G_STRANGE
 211 An unanticipated system error occurred while trying to grab the process
 212 file and create the handle.
 213 The value of
 214 .Sy errno
 215 indicates the system failure.
 216 .It Er G_ZOMB
 217 The process referred to by
 218 .Fa pid
 219 is a zombie and cannot be grabbed.
 220 .El
 221 .Sh INTERFACE STABILITY
 222 .Sy Uncommitted
 223 .Sh MT-LEVEL
 224 .Sy MT-Safe
 225 .Sh SEE ALSO
 226 .Xr errno 3C ,
 227 .Xr libproc 3LIB ,
 228 .Xr Pfree 3PROC ,
 229 .Xr Pgrab_core 3PROC ,
 230 .Xr Pgrab_error 3PROC ,
 231 .Xr Pgrab_file 3PROC ,
 232 .Xr Prelease 3PROC