Man

Command Section
PROCCTL(2)                FreeBSD System Calls Manual               PROCCTL(2)

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.

FreeBSD 11.1-RELEASE-p4       September 27, 2016       FreeBSD 11.1-RELEASE-p4
Command Section