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 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 allows a process to take-over the reaping task from init for 54any forked sub-process, recursively (for all children thereafter) which 55would otherwise reparent to init. 56This allows a chain of control to be maintained no matter what the 57sub-process does. 58.Pp 59Any process may become a reaper for its sub-processes. 60The feature may also be used recursively, or independently, to 61create reaping domains or sub-domains. 62.Pp 63This call is typically used by service monitoring programs, jails, or 64chroots to ensure that the underlying services cannot get away from under 65the monitor. 66.Sh CONTROL OPERATIONS 67The following operations are defined in 68.In sys/procctl.h : 69.Bl -tag -width indent 70.It Dv PROC_REAP_ACQUIRE 71Become a reaper for all sub-processes forked after the call returns. 72The data argument is ignored and can be NULL. 73.It Dv PROC_REAP_RELEASE 74Release reaping duties, reaping returns to normal operation. 75The data argument is ignored and can be NULL. 76.It Dv PROC_REAP_STATUS 77Request status. 78The supplied data structure is loaded with the current reaper status. 79The data argument may be NULL, which can be used to test whether 80the system call exists or not (assuming you catch 81.Er ENOSYS ) . 82See the include file for more information. 83.Pp 84Current status flags, indicating whether reaping is acquired. 85If reaping is acquired additional data will be returned. 86.Pp 87When reaping is acquired, the first running pid under the reaper 88is also loaded into the data structure, or -1 if there are none 89running. 90Callers wishing to destroy all processes under management can 91kill the process in question, waitpid it, and loop until no processes 92remain. 93This is guaranteed to ultimately irradicate everything that was directly 94or indirectly started under the reaper. 95.El 96.Sh RETURN VALUES 970 is returned upon successful completion. 98Otherwise -1 is returned and 99.Va errno 100is set to indicate the error. 101.Pp 102If a data structure is supplied, data may be read or written to it 103according to the op code. 104Only sufficient data to support the requested operation is read or 105written. 106.Sh ERRORS 107The 108.Fn procctl 109function will fail when one of the following occurs: 110.Bl -tag -width Er 111.It Bq Er EALREADY 112An attempt to acquire reaping is made but the current 113process has already acquired the feature. 114.It Bq Er ENOTCONN 115An attempt to release reaping is made but the current 116process has not currently acquired the feature. 117.It Bq Er EINVAL 118The operation is not supported. 119.El 120.Sh SEE ALSO 121.Sh HISTORY 122The 123.Fn procctl 124system call first appeared in 125.Dx 4.0 . 126.Sh AUTHORS 127.An -nosplit 128The 129.Fn procctl 130system call was written by 131.An Matthew Dillon . 132