PROCCTL(2)

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

LIBRARY
libc

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_REAP_KILL
    Request to deliver a signal to the descendants of the reaper. The data argument must point to a reaper_kill structure, which is used both for parameters and status return.

        struct reaper_kill {
        	uint32_t	flags;
        	int		signal;		/* signal to deliver */
        	uint32_t	killed;		/* number of processes signaled */
        	pid_t		pid_failed;	/* 1st process failed to signal */
        };

    The flags field controls how to deliver the signal: if the REAPER_KILL_CHILDREN flag is set, deliver the signal only to direct children of the reaper; otherwise, deliver to all the descendants of the reaper except the descendants of any sub-reapers. The signal field specifies the signal to be delivered.

    Upon return, the killed field identifies the number of processes signaled. If the pid_failed field is greater than 0, it is the pid of the first process for which the signal delivery failed, e.g., due to permissions.

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

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. The PROC_REAP_KILL request was added in DragonFly 6.5.

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