noble (2) procctl.2freebsd.gz

Provided by: freebsd-manpages_12.2-1_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 *data);

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_ASLR_CTL        Controls the Address Space Layout Randomization (ASLR) in the program images created
                          by execve(2) in the specified process or its descendants that did not changed the
                          control nor modified it by other means.  The data parameter must point to the integer
                          variable holding one of the following values:

                          PROC_ASLR_FORCE_ENABLE   Request that ASLR is enabled after execution, even if it is
                                                   disabled system-wide.  The image flag and set-uid might
                                                   prevent ASLR enablement still.

                          PROC_ASLR_FORCE_DISABLE  Request that ASLR is disabled after execution.  Same notes as
                                                   for PROC_ASLR_FORCE_ENABLE apply.

                          PROC_ASLR_NOFORCE        Use system-wide configured policy for ASLR.

     PROC_ASLR_STATUS     Returns the current status of ASLR enablement for the target process.  The data
                          parameter must point to the integer variable, where one of the following values is
                          written:

                          PROC_ASLR_FORCE_ENABLE

                          PROC_ASLR_FORCE_DISABLE

                          PROC_ASLR_NOFORCE

                          If the currently executed image in the process itself has ASLR enabled, the
                          PROC_ASLR_ACTIVE flag is or-ed with the value listed above.

     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 data 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.

                          REAPER_PIDINFO_REAPER  The reported process is itself a reaper.  The descendants of
                                                 the subordinate reaper are not reported.

     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_enotcap
                                                    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_enotcap above, which gives independent global
                          control of signal delivery.

     PROC_PDEATHSIG_CTL   Request the delivery of a signal when the parent of the calling process exits.  idtype
                          must be P_PID and id must be the either caller's pid or zero, with no difference in
                          effect.  The value is cleared for child processes and when executing set-user-ID or
                          set-group-ID binaries.  arg must point to a value of type int indicating the signal
                          that should be delivered to the caller.  Use zero to cancel a previously requested
                          signal delivery.

     PROC_PDEATHSIG_STATUS
                          Query the current signal number that will be delivered when the parent of the calling
                          process exits.  idtype must be P_PID and id must be the either caller's pid or zero,
                          with no difference in effect.  arg must point to a memory location that can hold a
                          value of type int.  If signal delivery has not been requested, it will contain zero on
                          return.

     PROC_STACKGAP_CTL    Controls the stack gaps in the specified process.  A stack gap is the part of the
                          growth area for a MAP_STACK mapped region that is reserved and never filled by memory.
                          Instead, the process is guaranteed to receive a SIGSEGV signal on accessing pages in
                          the gap.  Gaps protect against stack overflow corrupting memory adjacent to the stack.

                          The data argument must point to an integer variable containing flags.  The following
                          flags are allowed:

                          PROC_STACKGAP_ENABLE        This flag is only accepted for consistency with
                                                      PROC_STACKGAP_STATUS.  If stack gaps are enabled, the flag
                                                      is ignored.  If disabled, the flag causes an EINVAL error
                                                      to be returned.  After gaps are disabled in a process,
                                                      they can only be re-enabled when an execve(2) is
                                                      performed.

                          PROC_STACKGAP_DISABLE       Disable stack gaps for the process.  For existing stacks,
                                                      the gap is no longer a reserved part of the growth area
                                                      and can be filled by memory on access.

                          PROC_STACKGAP_ENABLE_EXEC   Enable stack gaps for programs started after an execve(2)
                                                      by the specified process.

                          PROC_STACKGAP_DISABLE_EXEC  Inherit disabled stack gaps state after execve(2).  In
                                                      other words, if the currently executing program has stack
                                                      gaps disabled, they are kept disabled on exec.  If gaps
                                                      were enabled, they are kept enabled after exec.

                          The stack gap state is inherited from the parent on fork(2).

     PROC_STACKGAP_STATUS
                          Returns the current stack gap state for the specified process.  data must point to an
                          integer variable, which is used to return a bitmask consisting of the following flags:

                          PROC_STACKGAP_ENABLE        Stack gaps are enabled.

                          PROC_STACKGAP_DISABLE       Stack gaps are disabled.

                          PROC_STACKGAP_ENABLE_EXEC   Stack gaps are enabled in the process after execve(2).

                          PROC_STACKGAP_DISABLE_EXEC  Stack gaps are disabled in the process after execve(2).

x86 MACHINE-SPECIFIC REQUESTS

     PROC_KPTI_CTL     AMD64 only.  Controls the Kernel Page Table Isolation (KPTI) option for the children of
                       the specified process.  For the command to work, the vm.pmap.kpti tunable must be enabled
                       on boot.  It is not possible to change the KPTI setting for a running process, except at
                       the execve(2), where the address space is reinitialized.

                       The data parameter must point to an integer variable containing one of the following
                       commands:

                       PROC_KPTI_CTL_ENABLE_ON_EXEC   Enable KPTI after execve(2).

                       PROC_KPTI_CTL_DISABLE_ON_EXEC  Disable KPTI after execve(2).  Only root or a process
                                                      having the PRIV_IO privilege might use this option.

     PROC_KPTI_STATUS  Returns the current KPTI status for the specified process.  data must point to the
                       integer variable, which returns the following statuses:

                       PROC_KPTI_CTL_ENABLE_ON_EXEC

                       PROC_KPTI_CTL_DISABLE_ON_EXEC

                       The status is or-ed with the PROC_KPTI_STATUS_ACTIVE in case KPTI is active for the
                       current address space of the process.

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.

     [EINVAL]           The PROC_PDEATHSIG_CTL or PROC_PDEATHSIG_STATUS request referenced an unsupported id,
                        idtype or invalid signal number.

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.

     The PROC_PDEATHSIG_CTL facility is based on the prctl(PR_SET_PDEATHSIG, ...) feature of Linux, and first
     appeared in FreeBSD 11.2.

     The ASLR support was added to system for the checklists compliance in FreeBSD 13.0.