1 PGRAB(3PROC) Process Control Library Functions PGRAB(3PROC) 2 3 NAME 4 Pgrab - grab and control a process 5 6 LIBRARY 7 Process Control Library (libproc, -lproc) 8 9 SYNOPSIS 10 #include <libproc.h> 11 12 struct ps_prochandle * 13 Pgrab(pid_t pid, int flags, int *perr); 14 15 DESCRIPTION 16 The Pgrab() function attempts to grab the process identified by pid and 17 returns a handle to it that allows the process to be controlled, 18 interrogated, and manipulated. This interface only works with processes 19 that already exist. Use Pgrab_core(3PROC) for core files and 20 Pcreate(3PROC) to create processes. 21 22 A grabbed process undergoes the following changes unless flags is set to 23 the contrary: 24 25 o The process is stopped 26 27 o All other tracing flags are cleared 28 29 o The grab is exclusive. If any existing handles to this process 30 exist or anyone else is using the underlying facilities of the 31 /proc file system to control this process, it will fail. 32 33 o Unless the process is already stopped, the PR_RLC flag is set 34 indicating the process should run-on-last-close. Allowing the 35 process to resume running if its controlling process dies. 36 37 Grabbing a process is a destructive action. Stopping a process stops 38 execution of all its threads. The impact of stopping a process depends 39 on the purpose of that process. For example, if one stops a process 40 that's primarily doing computation, then its computation is delayed the 41 entire time that it is stopped. However, if instead this is an active 42 TCP server, then the accept backlog may fill causing connection errors 43 and potentially connection time out errors. 44 45 Special care must be taken to ensure that a stopped process continues, 46 even if the controlling process terminates. If the controlling process 47 disables the PR_RLC flag or the process was already stopped, then the 48 process remains stopped after the controlling process terminates. 49 Exercise caution when changing this behavior. 50 51 Many of these default behaviors can be controlled by passing values to 52 the flags argument. Values for flags are constructed by a bitwise- 53 inclusive-OR of flags from the following list: 54 55 PGRAB_RETAIN Indicates that any existing tracing flags on pid 56 should be retained. If this flag is not specified, 57 they will be cleared as part of creating the libproc 58 handle for this process. 59 60 Normally extant tracing flags are cleared when a 61 process is grabbed. 62 63 PGRAB_FORCE Indicates that the process should not be grabbed 64 exclusively. Care should be taken with this option. 65 If other consumers are manipulating the process, then 66 this may result in surprising behavior as the process 67 is being manipulated from multiple points of control 68 at the same time. 69 70 Normally an attempt will be made to grab the process 71 exclusively and fail if it is already in use. 72 73 PGRAB_RDONLY Indicates that the process should be grabbed in a 74 read-only fashion. This implies that both the 75 PGRAB_RETAIN and PGRAB_NOSTOP flags should be set. 76 If a process is opened read-only, then a caller can 77 only read information about a process and cannot 78 manipulate it, change its current state, or inject 79 systems calls into it. 80 81 Normally when a process is grabbed, it does so for 82 both reading and writing. 83 84 PGRAB_NOSTOP Do not stop a process as it is grabbed. Note, any 85 extant tracing flags on the process will still be 86 cleared unless the PGRAB_RETAIN flag has been set. 87 88 Normally a process is stopped as a result of grabbing 89 the process. 90 91 The perr argument must be a non-NULL pointer which will store a more 92 detailed error in the event that the Pgrab() function fails. A human- 93 readable form of the error can be obtained with Pgrab_error(3PROC). 94 95 Once a caller is done with the library handle it should call 96 Prelease(3PROC) to release the grabbed process. Failure to properly 97 release the handle may leave a process stopped and interfere with the 98 ability of other software to obtain a handle. 99 100 Permissions 101 Unprivileged users may grab and control their own processes only if both 102 the user and group IDs of the target process match those of the calling 103 process. In addition, the caller must have a super set of the target's 104 privileges. Processes with the PRIV_PROC_OWNER privilege may manipulate 105 any process on the system, as long as it has an equal privilege set. For 106 more details on the security and programming considerations, please see 107 the section PROGRAMMING NOTES in proc(4). 108 109 RETURN VALUES 110 Upon successful completion, the Pgrab() function returns a control handle 111 to the process. Otherwise, NULL is returned with perr containing the 112 error code. 113 114 ERRORS 115 The Pgrab() function will fail if: 116 117 G_BUSY The process pid is already being traced and the 118 PGRAB_FORCE flag was not passed in flags. 119 120 G_LP64 The calling process is a 32-bit process and process 121 pid is 64-bit. 122 123 G_NOFD Too many files are open. This is logically equivalent 124 to receiving EMFILE. 125 126 G_NOPROC The process referred to by pid does not exist. 127 128 G_PERM The calling process has insufficient permissions or 129 privileges to open the specified process. See 130 Permissions for more information. 131 132 G_SYS The process referred to by pid is a system process and 133 cannot be grabbed. 134 135 G_SELF The process referred to by pid is the process ID of 136 the caller and the PGRAB_RDONLY was not passed. A 137 process may only grab itself if it's read-only. 138 139 G_STRANGE An unanticipated system error occurred while trying to 140 grab the process file and create the handle. The 141 value of errno indicates the system failure. 142 143 G_ZOMB The process referred to by pid is a zombie and cannot 144 be grabbed. 145 146 INTERFACE STABILITY 147 Uncommitted 148 149 MT-LEVEL 150 MT-Safe 151 152 SEE ALSO 153 errno(3C), libproc(3LIB), Pfree(3PROC), Pgrab_core(3PROC), 154 Pgrab_error(3PROC), Pgrab_file(3PROC), Prelease(3PROC) 155 156 illumos May 11, 2016 illumos