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