Fix a number of typos in manual pages and user-visible messages.
[dragonfly.git] / lib / libc / sys / procctl.2
CommitLineData
6e2a912c
MD
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
fc3bc286 33.Dt PROCCTL 2
6e2a912c
MD
34.Os
35.Sh NAME
fc3bc286 36.Nm procctl
6e2a912c
MD
37.Nd control reaping of sub-processes
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
fc3bc286 41.In sys/procctl.h
6e2a912c 42.Ft int
fc3bc286
MD
43.Fo procctl
44.Fa "idtype_t idtype"
45.Fa "id_t id"
46.Fa "int cmd"
47.Fa "void *data"
6e2a912c
MD
48.Fc
49.Sh DESCRIPTION
50The
fc3bc286 51.Fn procctl
6e2a912c
MD
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
fc3bc286 67.In sys/procctl.h :
6e2a912c 68.Bl -tag -width indent
fc3bc286 69.It Dv PROC_REAP_ACQUIRE
6e2a912c
MD
70Become a reaper for all sub-processes forked after the call returns.
71The data argument is ignored and can be NULL.
fc3bc286 72.It Dv PROC_REAP_RELEASE
6e2a912c
MD
73Release reaping duties, reaping returns to normal operation.
74The data argument is ignored and can be NULL.
fc3bc286 75.It Dv PROC_REAP_STATUS
6e2a912c
MD
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
a0cfb174
SW
79the system call exists or not (assuming you catch
80.Er ENOSYS ) .
6e2a912c
MD
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.
1ef3b4ca 92This is guaranteed to ultimately irradicate everything that was directly
6e2a912c 93or indirectly started under the reaper.
6e2a912c
MD
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
fc3bc286 107.Fn procctl
6e2a912c
MD
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
fc3bc286 122.Fn procctl
6e2a912c
MD
123system call first appeared in
124.Dx 4.0 .
125.Sh AUTHORS
126.An -nosplit
127The
fc3bc286 128.Fn procctl
6e2a912c
MD
129system call was written by
130.An Matthew Dillon .