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