Manual Pages  — PROCCTL

The control request to perform is specified by the cmd argument.

All status changing requests *_CTL require the caller to have the right to debug the target. All status query requests require the caller to have the right to observe the target.

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 the 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_PROTMAX_CTL	Controls implicit application of PROT_MAX protection equal to the prot argument of the mmap(2) syscall, in the target process. The data parameter must point to the integer variable holding one of the following values:

PROC_PROTMAX_FORCE_ENABLE	Enables implicit PROT_MAX application, even if it is disabled system-wide by the sysctl vm.imply_prot_max. The image flag might still prevent the enablement.
PROC_PROTMAX_FORCE_DISABLE
	Request that implicit application of PROT_MAX be disabled. Same notes as for PROC_PROTMAX_FORCE_ENABLE apply.
PROC_PROTMAX_NOFORCE	Use the system-wide configured policy for PROT_MAX.

PROC_PROTMAX_STATUS	Returns the current status of implicit PROT_MAX enablement for the target process. The data parameter must point to the integer variable, where one of the following values is written:
PROC_PROTMAX_FORCE_ENABLE PROC_PROTMAX_FORCE_DISABLE PROC_PROTMAX_NOFORCE

If the currently executed image in the process itself has implicit PROT_MAX application enabled, the PROC_PROTMAX_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.