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