DragonFly On-Line Manual Pages

PROCCTL(2)               DragonFly System Calls Manual              PROCCTL(2)

NAME
     procctl - control reaping of sub-processes and other functions

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/types.h>
     #include <sys/procctl.h>

     int
     procctl(idtype_t idtype, id_t id, int cmd, void *data);

DESCRIPTION
     The procctl() system call applies certain process-related control
     operations to the system.  The idtype argument may be P_PID or P_PGID,
     and the id argument is either a process id or a process group id, or 0
     indicating the current process or process group.

     Note that currently all functions only operate on the current process.

REAPER OPERATION
     The procctl() system call may be used by a process to take-over the
     reaping task from init for any forked sub-process, recursively (for all
     children thereafter) which would otherwise reparent to init.  This allows
     a chain of control to be maintained no matter what the sub-process does.

     Any process may become a reaper for its sub-processes.  The feature may
     also be used recursively, or independently, to create reaping domains or
     sub-domains.

     This call is typically used by service monitoring programs, jails, or
     chroots to ensure that the underlying services cannot get away from under
     the monitor.

CONTROL OPERATIONS
     The following operations are defined in <sys/procctl.h>:

     PROC_REAP_ACQUIRE
             Become a reaper for all sub-processes forked after the call
             returns.  The data argument is ignored and can be NULL.

     PROC_REAP_RELEASE
             Release reaping duties, reaping returns to normal operation.  The
             data argument is ignored and can be NULL.

     PROC_REAP_STATUS
             Request status.  The supplied data structure is loaded with the
             current reaper status.  The data argument may be NULL, which can
             be used to test whether the system call exists or not (assuming
             you catch ENOSYS).  See the include file for more information.

             Current status flags, indicating whether reaping is acquired.  If
             reaping is acquired additional data will be returned.

             When reaping is acquired, the first running pid under the reaper
             is also loaded into the data structure, or -1 if there are none
             running.  Callers wishing to destroy all processes under
             management can kill the process in question, waitpid it, and loop
             until no processes remain.  This is guaranteed to ultimately
             irradicate everything that was directly or indirectly started
             under the reaper.

     PROC_PDEATHSIG_CTL
             The argument is a pointer to an integer specifying the signal
             that should be delivered to the current process when its parent
             process exits.  A value of 0 cancels any previously set signal.

             Any previously set signal is automatically canceled in the child
             process of a fork() or when a suid or sgid program is exec'd.

             Only the current process pid or 0 may be specified.  Both have
             the same effect.

     PROC_PDEATHSIG_STATUS
             The argument is a pointer to an integer variable which will be
             filled in with the current pdeathsig signal, or 0 if the feature
             is not enabled.

             Only the current process pid or 0 may be specified.  Both have
             the same effect.

RETURN VALUES
     Upon successful completion, the value 0 is returned; otherwise the
     value -1 is returned and the global variable errno is set to indicate the
     error.

     If a data structure is supplied, data may be read or written to it
     according to the op code.  Only sufficient data to support the requested
     operation is read or written.

ERRORS
     The procctl() function will fail when one of the following occurs:

     [EALREADY]         An attempt to acquire reaping is made but the current
                        process has already acquired the feature.

     [ENOTCONN]         An attempt to release reaping is made but the current
                        process has not currently acquired the feature.

     [EINVAL]           The operation is not supported.

HISTORY
     The procctl() system call first appeared in DragonFly 4.0.

AUTHORS
     The procctl() system call was written by Matthew Dillon.

DragonFly 6.1-DEVELOPMENT      December 2, 2014      DragonFly 6.1-DEVELOPMENT