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