1.\" Copyright (c) 2013 Advanced Computing Technologies LLC 2.\" Written by: John H. Baldwin <[email protected]> 3.\" All rights reserved. 4.\" 5.\" Copyright (c) 2014 The FreeBSD Foundation 6.\" Portions of this documentation were written by Konstantin Belousov 7.\" under sponsorship from the FreeBSD Foundation. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd December 16, 2014 33.Dt PROCCTL 2 34.Os 35.Sh NAME 36.Nm procctl 37.Nd control processes 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/procctl.h 42.Ft int 43.Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *arg" 44.Sh DESCRIPTION 45The 46.Fn procctl 47system call provides for control over processes. 48The 49.Fa idtype 50and 51.Fa id 52arguments specify the set of processes to control. 53If multiple processes match the identifier, 54.Nm 55will make a 56.Dq best effort 57to control as many of the selected processes as possible. 58An error is only returned if no selected processes successfully complete 59the request. 60The following identifier types are supported: 61.Bl -tag -width "Dv P_PGID" 62.It Dv P_PID 63Control the process with the process ID 64.Fa id . 65.It Dv P_PGID 66Control processes belonging to the process group with the ID 67.Fa id . 68.El 69.Pp 70The control request to perform is specified by the 71.Fa cmd 72argument. 73The following commands are supported: 74.Bl -tag -width "Dv PROC_REAP_GETPIDS" 75.It Dv PROC_SPROTECT 76Set process protection state. 77This is used to mark a process as protected from being killed if the system 78exhausts available memory and swap. 79The 80.Fa arg 81parameter must point to an integer containing an operation and zero or more 82optional flags. 83The following operations are supported: 84.Bl -tag -width "Dv PPROT_CLEAR" 85.It Dv PPROT_SET 86Mark the selected processes as protected. 87.It Dv PPROT_CLEAR 88Clear the protected state of selected processes. 89.El 90.Pp 91The following optional flags are supported: 92.Bl -tag -width "Dv PPROT_DESCE" 93.It Dv PPROT_DESCEND 94Apply the requested operation to all child processes of each selected process 95in addition to each selected process. 96.It Dv PPROT_INHERIT 97When used with 98.Dv PPROT_SET , 99mark all future child processes of each selected process as protected. 100Future child processes will also mark all of their future child processes. 101.El 102.It Dv PROC_REAP_ACQUIRE 103Acquires the reaper status for the current process. 104The status means that children orphaned by the reaper's descendants 105that were forked after the acquisition of the status are reparented to the 106reaper. 107After the system initialization, 108.Xr init 8 109is the default reaper. 110.It Dv PROC_REAP_RELEASE 111Releases the reaper state for the current process. 112The reaper of the current process becomes the new reaper of the 113current process's descendants. 114.It Dv PROC_REAP_STATUS 115Provides the information about the reaper of the specified process, 116or the process itself when it is a reaper. 117The 118.Fa data 119argument must point to a 120.Vt procctl_reaper_status 121structure which is filled in by the syscall on successful return. 122.Bd -literal 123struct procctl_reaper_status { 124 u_int rs_flags; 125 u_int rs_children; 126 u_int rs_descendants; 127 pid_t rs_reaper; 128 pid_t rs_pid; 129}; 130.Ed 131The 132.Fa rs_flags 133may have the following flags returned: 134.Bl -tag -width "Dv REAPER_STATUS_REALINIT" 135.It Dv REAPER_STATUS_OWNED 136The specified process has acquired the reaper status and has not 137released it. 138When the flag is returned, the specified process 139.Fa id , 140pid, identifies the reaper, otherwise the 141.Fa rs_reaper 142field of the structure is set to the pid of the reaper 143for the specified process id. 144.It Dv REAPER_STATUS_REALINIT 145The specified process is the root of the reaper tree, i.e. 146.Xr init 8 . 147.El 148.Pp 149The 150.Fa rs_children 151field returns the number of children of the reaper. 152The 153.Fa rs_descendants 154field returns the total number of descendants of the reaper(s), 155not counting descendants of the reaper in the subtree. 156The 157.Fa rs_reaper 158field returns the reaper pid. 159The 160.Fa rs_pid 161returns the pid of one reaper child if there are any descendants. 162.It Dv PROC_REAP_GETPIDS 163Queries the list of descendants of the reaper of the specified process. 164The request takes a pointer to a 165.Vt procctl_reaper_pids 166structure in the 167.Fa data 168parameter. 169.Bd -literal 170struct procctl_reaper_pids { 171 u_int rp_count; 172 struct procctl_reaper_pidinfo *rp_pids; 173}; 174.Ed 175When called, the 176.Fa rp_pids 177field must point to an array of 178.Vt procctl_reaper_pidinfo 179structures, to be filled in on return, 180and the 181.Fa rp_count 182field must specify the size of the array, 183into which no more than 184.Fa rp_count 185elements will be filled in by the kernel. 186.Pp 187The 188.Vt "struct procctl_reaper_pidinfo" 189structure provides some information about one of the reaper's descendants. 190Note that for a descendant that is not a child, it may be incorrectly 191identified because of a race in which the original child process exited 192and the exited process's pid was reused for an unrelated process. 193.Bd -literal 194struct procctl_reaper_pidinfo { 195 pid_t pi_pid; 196 pid_t pi_subtree; 197 u_int pi_flags; 198}; 199.Ed 200The 201.Fa pi_pid 202field is the process id of the descendant. 203The 204.Fa pi_subtree 205field provides the pid of the child of the reaper, which is the (grand-)parent 206of the process. 207The 208.Fa pi_flags 209field returns the following flags, further describing the descendant: 210.Bl -tag -width "Dv REAPER_PIDINFO_VALID" 211.It Dv REAPER_PIDINFO_VALID 212Set to indicate that the 213.Vt procctl_reaper_pidinfo 214structure was filled in by the kernel. 215Zero-filling the 216.Fa rp_pids 217array and testing the 218.Dv REAPER_PIDINFO_VALID 219flag allows the caller to detect the end 220of the returned array. 221.It Dv REAPER_PIDINFO_CHILD 222The 223.Fa pi_pid 224field identifies the direct child of the reaper. 225.El 226.It Dv PROC_REAP_KILL 227Request to deliver a signal to some subset of the descendants of the reaper. 228The 229.Fa data 230parameter must point to a 231.Vt procctl_reaper_kill 232structure, which is used both for parameters and status return. 233.Bd -literal 234struct procctl_reaper_kill { 235 int rk_sig; 236 u_int rk_flags; 237 pid_t rk_subtree; 238 u_int rk_killed; 239 pid_t rk_fpid; 240}; 241.Ed 242The 243.Fa rk_sig 244field specifies the signal to be delivered. 245Zero is not a valid signal number, unlike 246.Xr kill 2 . 247The 248.Fa rk_flags 249field further directs the operation. 250It is or-ed from the following flags: 251.Bl -tag -width "Dv REAPER_KILL_CHILDREN" 252.It Dv REAPER_KILL_CHILDREN 253Deliver the specified signal only to direct children of the reaper. 254.It Dv REAPER_KILL_SUBTREE 255Deliver the specified signal only to descendants that were forked by 256the direct child with pid specified in the 257.Fa rk_subtree 258field. 259.El 260If neither the 261.Dv REAPER_KILL_CHILDREN 262nor the 263.Dv REAPER_KILL_SUBTREE 264flags are specified, all current descendants of the reaper are signalled. 265.Pp 266If a signal was delivered to any process, the return value from the request 267is zero. 268In this case, the 269.Fa rk_killed 270field identifies the number of processes signalled. 271The 272.Fa rk_fpid 273field is set to the pid of the first process for which signal 274delivery failed, e.g. due to the permission problems. 275If no such process exist, the 276.Fa rk_fpid 277field is set to -1. 278.El 279.Sh RETURN VALUES 280If an error occurs, a value of -1 is returned and 281.Va errno 282is set to indicate the error. 283.Sh ERRORS 284The 285.Fn procctl 286system call 287will fail if: 288.Bl -tag -width Er 289.It Bq Er EFAULT 290The 291.Fa arg 292parameter points outside the process's allocated address space. 293.It Bq Er EINVAL 294The 295.Fa cmd 296argument specifies an unsupported command. 297.Pp 298The 299.Fa idtype 300argument specifies an unsupported identifier type. 301.It Bq Er EPERM 302The calling process does not have permission to perform the requested 303operation on any of the selected processes. 304.It Bq Er ESRCH 305No processes matched the requested 306.Fa idtype 307and 308.Fa id . 309.It Bq Er EINVAL 310An invalid operation or flag was passed in 311.Fa arg 312for a 313.Dv PROC_SPROTECT 314command. 315.It Bq Er EPERM 316The 317.Fa idtype 318argument is not equal to 319.Dv P_PID , 320or 321.Fa id 322is not equal to the pid of the calling process, for 323.Dv PROC_REAP_ACQUIRE 324or 325.Dv PROC_REAP_RELEASE 326requests. 327.It Bq Er EINVAL 328Invalid or undefined flags were passed to a 329.Dv PROC_REAP_KILL 330request. 331.It Bq Er EINVAL 332An invalid or zero signal number was requested for a 333.Dv PROC_REAP_KILL 334request. 335.It Bq Er EINVAL 336The 337.Dv PROC_REAP_RELEASE 338request was issued by the 339.Xr init 8 340process. 341.It Bq Er EBUSY 342The 343.Dv PROC_REAP_ACQUIRE 344request was issued by a process that had already acquired reaper status 345and has not yet released it. 346.El 347.Sh SEE ALSO 348.Xr kill 2 , 349.Xr ptrace 2 , 350.Xr wait 2 , 351.Xr init 8 352.Sh HISTORY 353The 354.Fn procctl 355function appeared in 356.Fx 10.0 . 357The reaper facility is based on a similar feature of Linux and 358DragonflyBSD, and first appeared in 359.Fx 10.2 . 360