1.\" Copyright (c) 2013 Advanced Computing Technologies LLC 2.\" Written by: John H. Baldwin <[email protected]> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd September 19, 2013 29.Dt PROCCTL 2 30.Os 31.Sh NAME 32.Nm procctl 33.Nd control processes 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/procctl.h 38.Ft int 39.Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *arg" 40.Sh DESCRIPTION 41The 42.Fn procctl 43system call provides for control over processes. 44The 45.Fa idtype 46and 47.Fa id 48arguments specify the set of processes to control. 49If multiple processes match the identifier, 50.Nm 51will make a 52.Dq best effort 53to control as many of the selected processes as possible. 54An error is only returned if no selected processes successfully complete 55the request. 56The following identifier types are supported: 57.Bl -tag -width "Dv P_PGID" 58.It Dv P_PID 59Control the process with the process ID 60.Fa id . 61.It Dv P_PGID 62Control processes belonging to the process group with the ID 63.Fa id . 64.El 65.Pp 66The control request to perform is specified by the 67.Fa cmd 68argument. 69The following commands are supported: 70.Bl -tag -width "Dv PROC_SPROTECT" 71.It Dv PROC_SPROTECT 72Set process protection state. 73This is used to mark a process as protected from being killed if the system 74exhausts available memory and swap. 75The 76.Fa arg 77parameter must point to an integer containing an operation and zero or more 78optional flags. 79The following operations are supported: 80.Bl -tag -width "Dv PPROT_CLEAR" 81.It Dv PPROT_SET 82Mark the selected processes as protected. 83.It Dv PPROT_CLEAR 84Clear the protected state of selected processes. 85.El 86.Pp 87The following optional flags are supported: 88.Bl -tag -width "Dv PPROT_DESCE" 89.It Dv PPROT_DESCEND 90Apply the requested operation to all child processes of each selected process 91in addition to each selected process. 92.It Dv PPROT_INHERIT 93When used with 94.Dv PPROT_SET , 95mark all future child processes of each selected process as protected. 96Future child processes will also mark all of their future child processes. 97.El 98.El 99.Sh RETURN VALUES 100If an error occurs, a value of -1 is returned and 101.Va errno 102is set to indicate the error. 103.Sh ERRORS 104The 105.Fn procctl 106system call 107will fail if: 108.Bl -tag -width Er 109.It Bq Er EFAULT 110The 111.Fa arg 112points outside the process's allocated address space. 113.It Bq Er EINVAL 114The 115.Fa cmd 116argument specifies an unsupported command. 117.Pp 118The 119.Fa idtype 120argument specifies an unsupported identifier type. 121.It Bq Er EPERM 122The calling process does not have permission to perform the requested 123operation on any of the selected processes. 124.It Bq Er ESRCH 125No processes matched the requested 126.Fa idtype 127and 128.Fa id . 129.It Bq Er EINVAL 130An invalid operation or flag was passed in 131.Fa arg 132for a 133.Dv PROC_SPROTECT 134command. 135.El 136.Sh SEE ALSO 137.Xr ptrace 2 138.Sh HISTORY 139The 140.Fn procctl 141function appeared in 142.Fx 10.0 . 143