1.\" 2.\" Copyright (c) 2014 3.\" The DragonFly Project. 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.\" 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 3. Neither the name of The DragonFly Project nor the names of its 16.\" contributors may be used to endorse or promote products derived 17.\" from this software without specific, prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd December 2, 2014 33.Dt PROCCTL 2 34.Os 35.Sh NAME 36.Nm procctl 37.Nd control reaping of sub-processes and other functions 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/types.h 42.In sys/procctl.h 43.Ft int 44.Fo procctl 45.Fa "idtype_t idtype" 46.Fa "id_t id" 47.Fa "int cmd" 48.Fa "void *data" 49.Fc 50.Sh DESCRIPTION 51The 52.Fn procctl 53system call applies certain process-related control operations to the system. 54The 55.Fa idtype 56argument may be 57.Dv P_PID 58or 59.Dv P_PGID , 60and the 61.Fa id 62argument is either a process id or a process group id, or 0 indicating 63the current process or process group. 64.Pp 65Note that currently all functions only operate on the current process. 66.Sh REAPER OPERATION 67The 68.Fn procctl 69system call may be used by a process to take-over the reaping task from init 70for any forked sub-process, recursively (for all children thereafter) which 71would otherwise reparent to init. 72This allows a chain of control to be maintained no matter what the 73sub-process does. 74.Pp 75Any process may become a reaper for its sub-processes. 76The feature may also be used recursively, or independently, to 77create reaping domains or sub-domains. 78.Pp 79This call is typically used by service monitoring programs, jails, or 80chroots to ensure that the underlying services cannot get away from under 81the monitor. 82.Sh CONTROL OPERATIONS 83The following operations are defined in 84.In sys/procctl.h : 85.Bl -tag -width indent 86.It Dv PROC_REAP_ACQUIRE 87Become a reaper for all sub-processes forked after the call returns. 88The data argument is ignored and can be NULL. 89.It Dv PROC_REAP_RELEASE 90Release reaping duties, reaping returns to normal operation. 91The data argument is ignored and can be NULL. 92.It Dv PROC_REAP_STATUS 93Request status. 94The supplied data structure is loaded with the current reaper status. 95The data argument may be NULL, which can be used to test whether 96the system call exists or not (assuming you catch 97.Er ENOSYS ) . 98See the include file for more information. 99.Pp 100Current status flags, indicating whether reaping is acquired. 101If reaping is acquired additional data will be returned. 102.Pp 103When reaping is acquired, the first running pid under the reaper 104is also loaded into the data structure, or -1 if there are none 105running. 106Callers wishing to destroy all processes under management can 107kill the process in question, waitpid it, and loop until no processes 108remain. 109This is guaranteed to ultimately irradicate everything that was directly 110or indirectly started under the reaper. 111.It Dv PROC_PDEATHSIG_CTL 112The argument is a pointer to an integer specifying the signal that should 113be delivered to the current process when its parent process exits. 114A value of 0 cancels any previously set signal. 115.Pp 116Any previously set signal is automatically canceled in the child process of 117a fork() or when a suid or sgid program is exec'd. 118.Pp 119Only the current process pid or 0 may be specified. Both have the same effect. 120.It Dv PROC_PDEATHSIG_STATUS 121The argument is a pointer to an integer variable which will be filled in 122with the current pdeathsig signal, or 0 if the feature is not enabled. 123.Pp 124Only the current process pid or 0 may be specified. Both have the same effect. 125.El 126.Sh RETURN VALUES 127.Rv -std 128.Pp 129If a data structure is supplied, data may be read or written to it 130according to the op code. 131Only sufficient data to support the requested operation is read or 132written. 133.Sh ERRORS 134The 135.Fn procctl 136function will fail when one of the following occurs: 137.Bl -tag -width Er 138.It Bq Er EALREADY 139An attempt to acquire reaping is made but the current 140process has already acquired the feature. 141.It Bq Er ENOTCONN 142An attempt to release reaping is made but the current 143process has not currently acquired the feature. 144.It Bq Er EINVAL 145The operation is not supported. 146.El 147.\".Sh SEE ALSO 148.Sh HISTORY 149The 150.Fn procctl 151system call first appeared in 152.Dx 4.0 . 153.Sh AUTHORS 154.An -nosplit 155The 156.Fn procctl 157system call was written by 158.An Matthew Dillon . 159