Provided by: freebsd-manpages_11.1-3_all bug

NAME

     procctl — control processes

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <sys/procctl.h>

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

DESCRIPTION

     The procctl() system call provides for control over processes.  The idtype and id arguments
     specify the set of processes to control.  If multiple processes match the identifier,
     procctl will make a “best effort” to control as many of the selected processes as possible.
     An error is only returned if no selected processes successfully complete the request.  The
     following identifier types are supported:

     P_PID      Control the process with the process ID id.

     P_PGID     Control processes belonging to the process group with the ID id.

     The control request to perform is specified by the cmd argument.  The following commands are
     supported:

     PROC_SPROTECT           Set process protection state.  This is used to mark a process as
                             protected from being killed if the system exhausts the available
                             memory and swap.  The arg parameter must point to an integer
                             containing an operation and zero or more optional flags.  The
                             following operations are supported:

                             PPROT_SET       Mark the selected processes as protected.

                             PPROT_CLEAR     Clear the protected state of selected processes.

                             The following optional flags are supported:

                             PPROT_DESCEND     Apply the requested operation to all child
                                               processes of each selected process in addition to
                                               each selected process.

                             PPROT_INHERIT     When used with PPROT_SET, mark all future child
                                               processes of each selected process as protected.
                                               Future child processes will also mark all of their
                                               future child processes.

     PROC_REAP_ACQUIRE       Acquires the reaper status for the current process.  Reaper status
                             means that children orphaned by the reaper's descendants that were
                             forked after the acquisition of reaper status are reparented to the
                             reaper process.  After system initialization, init(8) is the default
                             reaper.

     PROC_REAP_RELEASE       Release the reaper state for the current process.  The reaper of the
                             current process becomes the new reaper of the current process's
                             descendants.

     PROC_REAP_STATUS        Provides information about the reaper of the specified process, or
                             the process itself when it is a reaper.  The data argument must
                             point to a procctl_reaper_status structure which is filled in by the
                             syscall on successful return.

                             struct procctl_reaper_status {
                                     u_int   rs_flags;
                                     u_int   rs_children;
                                     u_int   rs_descendants;
                                     pid_t   rs_reaper;
                                     pid_t   rs_pid;
                             };
                             The rs_flags may have the following flags returned:

                             REAPER_STATUS_OWNED        The specified process has acquired reaper
                                                        status and has not released it.  When the
                                                        flag is returned, the specified process
                                                        id, pid, identifies the reaper, otherwise
                                                        the rs_reaper field of the structure is
                                                        set to the pid of the reaper for the
                                                        specified process id.

                             REAPER_STATUS_REALINIT     The specified process is the root of the
                                                        reaper tree, i.e., init(8).

                             The rs_children field returns the number of children of the reaper
                             among the descendants.  It is possible to have a child whose reaper
                             is not the specified process, since the reaper for any existing
                             children is not reset on the PROC_REAP_ACQUIRE operation.  The
                             rs_descendants field returns the total number of descendants of the
                             reaper(s), not counting descendants of the reaper in the subtree.
                             The rs_reaper field returns the reaper pid.  The rs_pid returns the
                             pid of one reaper child if there are any descendants.

     PROC_REAP_GETPIDS       Queries the list of descendants of the reaper of the specified
                             process.  The request takes a pointer to a procctl_reaper_pids
                             structure in the data parameter.

                             struct procctl_reaper_pids {
                                     u_int   rp_count;
                                     struct procctl_reaper_pidinfo *rp_pids;
                             };
                             When called, the rp_pids field must point to an array of
                             procctl_reaper_pidinfo structures, to be filled in on return, and
                             the rp_count field must specify the size of the array, into which no
                             more than rp_count elements will be filled in by the kernel.

                             The struct procctl_reaper_pidinfo structure provides some
                             information about one of the reaper's descendants.  Note that for a
                             descendant that is not a child, it may be incorrectly identified
                             because of a race in which the original child process exited and the
                             exited process's pid was reused for an unrelated process.

                             struct procctl_reaper_pidinfo {
                                     pid_t   pi_pid;
                                     pid_t   pi_subtree;
                                     u_int   pi_flags;
                             };
                             The pi_pid field is the process id of the descendant.  The
                             pi_subtree field provides the pid of the child of the reaper, which
                             is the (grand-)parent of the process.  The pi_flags field returns
                             the following flags, further describing the descendant:

                             REAPER_PIDINFO_VALID     Set to indicate that the
                                                      procctl_reaper_pidinfo structure was filled
                                                      in by the kernel.  Zero-filling the rp_pids
                                                      array and testing the REAPER_PIDINFO_VALID
                                                      flag allows the caller to detect the end of
                                                      the returned array.

                             REAPER_PIDINFO_CHILD     The pi_pid field identifies the direct
                                                      child of the reaper.

     PROC_REAP_KILL          Request to deliver a signal to some subset of the descendants of the
                             reaper.  The data parameter must point to a procctl_reaper_kill
                             structure, which is used both for parameters and status return.

                             struct procctl_reaper_kill {
                                     int     rk_sig;
                                     u_int   rk_flags;
                                     pid_t   rk_subtree;
                                     u_int   rk_killed;
                                     pid_t   rk_fpid;
                             };
                             The rk_sig field specifies the signal to be delivered.  Zero is not
                             a valid signal number, unlike for kill(2).  The rk_flags field
                             further directs the operation.  It is or-ed from the following
                             flags:

                             REAPER_KILL_CHILDREN     Deliver the specified signal only to direct
                                                      children of the reaper.

                             REAPER_KILL_SUBTREE      Deliver the specified signal only to
                                                      descendants that were forked by the direct
                                                      child with pid specified in the rk_subtree
                                                      field.
                             If neither the REAPER_KILL_CHILDREN nor the REAPER_KILL_SUBTREE
                             flags are specified, all current descendants of the reaper are
                             signalled.

                             If a signal was delivered to any process, the return value from the
                             request is zero.  In this case, the rk_killed field identifies the
                             number of processes signalled.  The rk_fpid field is set to the pid
                             of the first process for which signal delivery failed, e.g., due to
                             permission problems.  If no such process exists, the rk_fpid field
                             is set to -1.

     PROC_TRACE_CTL          Enable or disable tracing of the specified process(es), according to
                             the value of the integer argument.  Tracing includes attachment to
                             the process using the ptrace(2) and ktrace(2), debugging sysctls,
                             hwpmc(4), dtrace(1), and core dumping.  Possible values for the data
                             argument are:

                             PROC_TRACE_CTL_ENABLE           Enable tracing, after it was
                                                             disabled by PROC_TRACE_CTL_DISABLE.
                                                             Only allowed for self.

                             PROC_TRACE_CTL_DISABLE          Disable tracing for the specified
                                                             process.  Tracing is re-enabled when
                                                             the process changes the executing
                                                             program with the execve(2) syscall.
                                                             A child inherits the trace settings
                                                             from the parent on fork(2).

                             PROC_TRACE_CTL_DISABLE_EXEC     Same as PROC_TRACE_CTL_DISABLE, but
                                                             the setting persists for the process
                                                             even after execve(2).

     PROC_TRACE_STATUS       Returns the current tracing status for the specified process in the
                             integer variable pointed to by data.  If tracing is disabled, data
                             is set to -1.  If tracing is enabled, but no debugger is attached by
                             the ptrace(2) syscall, data is set to 0.  If a debugger is attached,
                             data is set to the pid of the debugger process.

     PROC_TRAPCAP_CTL        Controls the capability mode sandbox actions for the specified
                             sandboxed processes, on a return from any syscall which gives either
                             a ENOTCAPABLE or ECAPMODE error.  If the control is enabled, such
                             errors from the syscalls cause delivery of the synchronous SIGTRAP
                             signal to the thread immediately before returning from the syscalls.

                             Possible values for the data argument are:

                             PROC_TRAPCAP_CTL_ENABLE      Enable the SIGTRAP signal delivery on
                                                          capability mode access violations.  The
                                                          enabled mode is inherited by the
                                                          children of the process, and is kept
                                                          after fexecve(2) calls.

                             PROC_TRAPCAP_CTL_DISABLE     Disable the signal delivery on
                                                          capability mode access violations.
                                                          Note that the global sysctl
                                                          kern.trap_enocap might still cause the
                                                          signal to be delivered.  See
                                                          capsicum(4).

                             On signal delivery, the si_errno member of the siginfo signal
                             handler parameter is set to the syscall error value, and the si_code
                             member is set to TRAP_CAP.

                             See capsicum(4) for more information about the capability mode.

     PROC_TRAPCAP_STATUS     Return the current status of signalling capability mode access
                             violations for the specified process.  The integer value pointed to
                             by the data argument is set to the PROC_TRAPCAP_CTL_ENABLE value if
                             the process control enables signal delivery, and to
                             PROC_TRAPCAP_CTL_DISABLE otherwise.

                             See the note about sysctl kern.trap_enocap above, which gives
                             independent global control of signal delivery.

NOTES

     Disabling tracing on a process should not be considered a security feature, as it is
     bypassable both by the kernel and privileged processes, and via other system mechanisms.  As
     such, it should not be utilized to reliably protect cryptographic keying material or other
     confidential data.

RETURN VALUES

     If an error occurs, a value of -1 is returned and errno is set to indicate the error.

ERRORS

     The procctl() system call will fail if:

     [EFAULT]           The arg parameter points outside the process's allocated address space.

     [EINVAL]           The cmd argument specifies an unsupported command.

                        The idtype argument specifies an unsupported identifier type.

     [EPERM]            The calling process does not have permission to perform the requested
                        operation on any of the selected processes.

     [ESRCH]            No processes matched the requested idtype and id.

     [EINVAL]           An invalid operation or flag was passed in arg for a PROC_SPROTECT
                        command.

     [EPERM]            The idtype argument is not equal to P_PID, or id is not equal to the pid
                        of the calling process, for PROC_REAP_ACQUIRE or PROC_REAP_RELEASE
                        requests.

     [EINVAL]           Invalid or undefined flags were passed to a PROC_REAP_KILL request.

     [EINVAL]           An invalid or zero signal number was requested for a PROC_REAP_KILL
                        request.

     [EINVAL]           The PROC_REAP_RELEASE request was issued by the init(8) process.

     [EBUSY]            The PROC_REAP_ACQUIRE request was issued by a process that had already
                        acquired reaper status and has not yet released it.

     [EBUSY]            The PROC_TRACE_CTL request was issued for a process already being traced.

     [EPERM]            The PROC_TRACE_CTL request to re-enable tracing of the process
                        (PROC_TRACE_CTL_ENABLE), or to disable persistence of
                        PROC_TRACE_CTL_DISABLE on execve(2) was issued for a non-current process.

     [EINVAL]           The value of the integer data parameter for the PROC_TRACE_CTL or
                        PROC_TRAPCAP_CTL request is invalid.

SEE ALSO

     dtrace(1), cap_enter(2,) kill(2), ktrace(2), ptrace(2), wait(2), capsicum(4), hwpmc(4),
     init(8)

HISTORY

     The procctl() function appeared in FreeBSD 10.0.  The reaper facility is based on a similar
     feature of Linux and DragonflyBSD, and first appeared in FreeBSD 10.2.