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