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