3 .\" The DragonFly Project. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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
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.
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
37 .Nd control reaping of sub-processes
52 system call allows a process to take-over the reaping task from init for
53 any forked sub-process, recursively (for all children thereafter) which
54 would otherwise reparent to init.
55 This allows a chain of control to be maintained no matter what the
58 Any process may become a reaper for its sub-processes.
59 The feature may also be used recursively, or independently, to
60 create reaping domains or sub-domains.
62 This call is typically used by service monitoring programs, jails, or
63 chroots to ensure that the underlying services cannot get away from under
65 .Sh CONTROL OPERATIONS
66 The following operations are defined in
68 .Bl -tag -width indent
69 .It Dv PROC_REAP_ACQUIRE
70 Become a reaper for all sub-processes forked after the call returns.
71 The data argument is ignored and can be NULL.
72 .It Dv PROC_REAP_RELEASE
73 Release reaping duties, reaping returns to normal operation.
74 The data argument is ignored and can be NULL.
75 .It Dv PROC_REAP_STATUS
77 The supplied data structure is loaded with the current reaper status.
78 The data argument may be NULL, which can be used to test whether
79 the system call exists or not (assuming you catch ENOSYS).
80 See the include file for more information.
82 Current status flags, indicating whether reaping is acquired.
83 If reaping is acquired additional data will be returned.
85 When reaping is acquired, the first running pid under the reaper
86 is also loaded into the data structure, or -1 if there are none
88 Callers wishing to destroy all processes under management can
89 kill the process in question, waitpid it, and loop until no processes
91 This is guarenteed to ultimately irradicate everything that was directly
92 or indirectly started under the reaper.
96 0 is returned upon successful completion.
97 Otherwise -1 is returned and
99 is set to indicate the error.
101 If a data structure is supplied, data may be read or written to it
102 according to the op code.
103 Only sufficient data to support the requested operation is read or
108 function will fail when one of the following occurs:
111 An attempt to acquire reaping is made but the current
112 process has already acquired the feature.
114 An attempt to release reaping is made but the current
115 process has not currently acquired the feature.
117 The operation is not supported.
123 system call first appeared in
129 system call was written by