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 .Rv -std
  98 .Pp
  99 If a data structure is supplied, data may be read or written to it
 100 according to the op code.
 101 Only sufficient data to support the requested operation is read or
 102 written.
 103 .Sh ERRORS
 104 The
 105 .Fn procctl
 106 function will fail when one of the following occurs:
 107 .Bl -tag -width Er
 108 .It Bq Er EALREADY
 109 An attempt to acquire reaping is made but the current
 110 process has already acquired the feature.
 111 .It Bq Er ENOTCONN
 112 An attempt to release reaping is made but the current
 113 process has not currently acquired the feature.
 114 .It Bq Er EINVAL
 115 The operation is not supported.
 116 .El
 117 .\".Sh SEE ALSO
 118 .Sh HISTORY
 119 The
 120 .Fn procctl
 121 system call first appeared in
 122 .Dx 4.0 .
 123 .Sh AUTHORS
 124 .An -nosplit
 125 The
 126 .Fn procctl
 127 system call was written by
 128 .An Matthew Dillon .