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 *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. id zero is a
shortcut for the calling process 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.
All status changing requests (*_CTL) require the caller to have the right
to debug the target. All status query requests (*_STATUS) require the
caller to have the right to observe the target.
The following commands are supported:
PROC_ASLR_CTL
Controls Address Space Layout Randomization (ASLR) in program
images created by execve(2) in the specified process or its
descendants that do not either change the control or modify it by
other means. The data parameter must point to an 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.
PROC_ASLR_FORCE_DISABLE
Request that ASLR is disabled after execution, even if it
is enabled system-wide.
PROC_ASLR_NOFORCE
Use the system-wide configured policy for ASLR.
Note that the elfctl(1) "noaslr" flag takes precedence over this
control. Executing a binary with this flag set will never use
ASLR. Similarly, executing a set-user-ID or set-group-ID binary
ignores this control and only honors the elfctl(1) flag and
system-wide policy.
PROC_ASLR_STATUS
Returns the current status of ASLR enablement for the target
process. The data parameter must point to an 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_LOGSIGEXIT_CTL
Controls the logging of exits due to signals that would normally
cause a core dump. The arg parameter must point to an integer
variable holding one of the following values:
PROC_LOGSIGEXIT_CTL_FORCE_ENABLE
Enables logging of exits due to signals that would
normally cause a core dump. Logging is done via log(9)
with a log level of LOG_INFO.
PROC_LOGSIGEXIT_CTL_FORCE_DISABLE
Disables the logging of exits due to signals that would
normally cause a core dump.
PROC_LOGSIGEXIT_CTL_NOFORCE
The logging behavior is delegated to the sysctl(3) MIB
variable kern.logsigexit.
PROC_LOGSIGEXIT_STATUS
Returns the current status of logging for the target process.
The arg parameter must point to an integer variable, where one of
the following values is written:
PROC_LOGSIGEXIT_CTL_FORCE_ENABLE
PROC_LOGSIGEXIT_CTL_FORCE_DISABLE
PROC_LOGSIGEXIT_CTL_NOFORCE
PROC_PROTMAX_CTL
Controls the maximum protection used for mmap(2) requests in the
target process that do not specify an explicit maximum protection
in the prot argument via PROT_MAX. The maximum protection limits
the permissions a mapping can be assigned by mprotect(2). If an
explicit maximum protection is not provided, the maximum
protection for a new mapping is set to either PROT_READ |
PROT_WRITE | PROT_EXEC (RWX) or the protection specified in prot.
Mappings created with prot set to PROT_NONE always use RWX
maximum protection.
The data parameter must point to an integer variable holding one
of the following values:
PROC_PROTMAX_FORCE_ENABLE
Use the permissions in prot as the implicit maximum
protection, even if RWX permissions are requested by the
sysctl vm.imply_prot_max.
PROC_PROTMAX_FORCE_DISABLE
Use RWX as the implicit maximum protection, even if
constrained permissions are requested by the sysctl
vm.imply_prot_max.
PROC_PROTMAX_NOFORCE
Use the system-wide configured policy for the implicit
PROT_MAX control.
Note that the elfctl(1) "noprotmax" flag takes precedence over
this control. Executing a binary with this flag set will always
use RWX as the implicit maximum protection.
PROC_PROTMAX_STATUS
Returns the current status of the implicit PROT_MAX control for
the target process. The data parameter must point to an 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 the
implicit PROT_MAX control 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 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
Enable orphaned process reaping for future children of the
current process.
If a parent process exits before one or more of its children
processes, the remaining children processes are orphaned. When
an orphaned process exits, it is reparented to a reaper process
that is responsible for harvesting the terminated process via
wait(2). When this control is enabled, the current process
becomes the reaper process for future children and their
descendants. Existing child processes continue to use the reaper
assigned when the child was created via fork(2). If a reaper
process exits, all of the processes for whom it was the reaper
are reassigned to the reaper process's reaper.
After system initialization, init(8) is the default reaper.
PROC_REAP_RELEASE
Disable orphaned process reaping for the current process.
Any processes for whom the current process was the reaper are
reassigned to the current process's reaper.
PROC_REAP_STATUS
Provides a consistent snapshot of information about the reaper of
the specified process, or the process itself if it is a reaper.
The data argument must point to a procctl_reaper_status structure
which is filled in by the system call 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 is a reaper. When this flag is
returned, the specified process id, pid, identifies a
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 processes that can be
reaped by the reaper that are also children of the reaper. It is
possible to have a child whose reaper is not the specified
process, since the reaper for existing children is not changed by
PROC_REAP_ACQUIRE. The rs_descendants field returns the total
number of processes that can be reaped by the reaper. The
rs_reaper field returns the reaper's pid. The rs_pid returns the
pid of one reaper child if there are any processes that can be
reapead; otherwise, it is set to -1.
PROC_REAP_GETPIDS
Queries the list of processes that can be reaped by 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 rp_count
procctl_reaper_pidinfo structures. The kernel will populate
these structures with information about the reaper's descendants.
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 direct child of the
reaper which is the (grand-)parent of the descendant 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 a direct child of the reaper.
REAPER_PIDINFO_REAPER
The reported process is itself a reaper. The descendants
of the subordinate reaper are not reported.
REAPER_PIDINFO_ZOMBIE
The reported process is in the zombie state, ready to be
reaped.
REAPER_PIDINFO_STOPPED
The reported process is stopped by a SIGSTOP/SIGTSTP
signal.
REAPER_PIDINFO_EXITING
The reported process is in the process of exiting (but
not yet a zombie).
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
inspecting the process via ptrace(2), ktrace(2), debugging
sysctls, hwpmc(4), or dtrace(1) as well as dumping core.
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) system call. 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) system call, 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 system call which fails
with either an ENOTCAPABLE or ECAPMODE error. If this control is
enabled and a system call fails with one of these errors, a
synchronous SIGTRAP signal is delivered to the thread immediately
before returning from the system call.
Possible values for the data argument are:
PROC_TRAPCAP_CTL_ENABLE
Enable 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 SIGTRAP 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 system call error value, and the
si_code member is set to TRAP_CAP. The system call number is
stored in the si_syscall field of the siginfo signal handler
parameter. The other system call parameters can be read from the
ucontext_t but the system call number is typically stored in the
register that also contains the return value and so is
unavailable in the signal handler.
See capsicum(4) for more information about capability mode.
PROC_TRAPCAP_STATUS
Return the current status of raising SIGTRAP for capability mode
access violations by the specified process. The integer value
pointed to by the data argument is set to the
PROC_TRAPCAP_CTL_ENABLE value if SIGTRAP delivery is enabled, 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. data 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. data 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 stack gaps in the specified process. A stack gap is one
or more virtual memory pages at the end of the growth area for a
MAP_STACK mapping that is reserved and never backed by memory.
Instead, the process is guaranteed to receive a synchronous
SIGSEGV signal for each access to pages in the gap. The number
of pages reserved for each stack is set by the sysctl
security.bsd.stack_guard_page.
Gaps protect against stack overflows by preventing them from
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 stack gaps are disabled, the request
fails with EINVAL. 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 reserved and can be filled by memory
on access.
PROC_STACKGAP_ENABLE_EXEC
Enable stack gaps for the new address space constructed
by any future execve(2) in 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).
Note that the elfctl(1) "nostackgap" flag takes precedence over
this setting for individual process address spaces. Executing a
binary with this flag set will never use stack gaps in the
address space constructed by execve(2). However, the controls
value can still be inherited by child processes, and executing a
binary without this flag set will revert to the behavior
specified by the control.
PROC_NO_NEW_PRIVS_CTL
Allows one to ignore the set-user-ID and set-group-ID bits on the
program images activated by execve(2) in the specified process
and its future descendants. The data parameter must point to an
integer variable holding the following value:
PROC_NO_NEW_PRIVS_ENABLE
Request set-user-ID and set-group-ID bits to be ignored.
It is not possible to disable this control once it has been
enabled.
PROC_NO_NEW_PRIVS_STATUS
Returns the current status of set-ID bits enablement for the
target process. The data parameter must point to an integer
variable, where one of the following values is written:
PROC_NO_NEW_PRIVS_ENABLE
PROC_NO_NEW_PRIVS_DISABLE
PROC_WXMAP_CTL
Controls the creation of mappings with both write and execute
permissions in a process's address space. The data parameter
must point to an integer variable holding one of the following
values:
PROC_WX_MAPPINGS_PERMIT
Enable creation of mappings that have both write and
execute permissions in the specified process' current and
future address spaces.
PROC_WX_MAPPINGS_DISALLOW_EXEC
In a new address space created by a future call to
execve(2), disallow creation of mappings that have both
write and execute permissions.
If both flags are set, PROC_WX_MAPPINGS_DISALLOW_EXEC takes
precedence during execve(2). If neither flag is set, mappings
with write and execute permissions are only permitted if the
kern.elf{32/64}.allow_wx sysctl is non-zero or the elfctl(1)
"wxneeded" flag is set in the ELF control note.
Once creation of writeable and executable mappings is enabled for
a process, it is impossible (and pointless) to disable it. The
only way to ensure the absence of such mappings after they were
enabled in a given process is to set the
PROC_WX_MAPPINGS_DISALLOW_EXEC flag and execve(2) an image.
PROC_WXMAP_STATUS
Returns the current status of the controls over creation of
mappings with both write and execute permissions for the
specified process. The data parameter must point to an integer
variable, where one of the following values is written:
PROC_WX_MAPPINGS_PERMIT
Creation of simultaneously writable and executable
mappings are permitted; otherwise, the process cannot
create such mappings.
PROC_WX_MAPPINGS_DISALLOW_EXEC
After execve(2), the new address space will not permit
creation of simultaneously writable and executable
mappings.
Additionally, if the address space of the process does not permit
creation of simultaneously writable and executable mappings and
it is guaranteed that no such mapping was created since address
space creation, the PROC_WXORX_ENFORCE flag is set in the
returned value.
x86 MACHINE-SPECIFIC REQUESTS
PROC_KPTI_CTL
AMD64 only. Controls the Kernel Page Table Isolation (KPTI)
option for the children of the specified process. This control
is only meaningful if KPTI has been enabled globally by the
vm.pmap.kpti tunable. It is not possible to change the KPTI
setting for a running process, only for new address spaces
constructed by a future execve(2).
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 can use this option.
PROC_KPTI_STATUS
Returns the current KPTI status for the specified process. data
must point to an integer variable, where one of the following
values is written:
PROC_KPTI_CTL_ENABLE_ON_EXEC
PROC_KPTI_CTL_DISABLE_ON_EXEC
The status is or-ed with PROC_KPTI_STATUS_ACTIVE if 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.
Note that processes can trivially bypass the 'no simultaneously writable
and executable mappings' policy by first marking some mapping as
writeable, writing code to it, then removing write and adding execute
permission. This may be legitimately required by some programs such as
JIT compilers.
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 data 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.
[ESRCH] No descendant processes can be found matching criteria
specified in the PROC_REAP_KILL request.
[EINVAL] An invalid operation or flag was passed in data 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] A PROC_REAP_RELEASE request was issued by the init(8)
process.
[EBUSY] A PROC_REAP_ACQUIRE request was issued by a process
that is already a reaper process.
[EBUSY] A PROC_TRACE_CTL request was issued for a process
being traced.
[EPERM] A 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)
specified a target process other than the calling
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), elfctl(1), proccontrol(1), protect(1), cap_enter(2), kill(2),
ktrace(2), mmap(2), mprotect(2), ptrace(2), wait(2), capsicum(4),
hwpmc(4), init(8)
HISTORY
The procctl() function appeared in FreeBSD 9.3.
The reaper facility is based on a similar feature in Linux and
DragonflyBSD, and first appeared in FreeBSD 10.2.
The PROC_PDEATHSIG_CTL facility is based on the `prctl(PR_SET_PDEATHSIG,
...)' feature in Linux, and first appeared in FreeBSD 11.2.
ASLR support was added for checklist compliance in FreeBSD 13.0.
FreeBSD 15.1-STABLE-HBSD April 21, 2025 PROCCTL(2)