--- name: "procctl" section: "2" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/procctl" --- # procctl(2) control processes ## NAME **procctl** – control processes ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** *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)](/execve/2.md) 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)](/elfctl/1.md) “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)](/elfctl/1.md) 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)](/log/9.md) 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)](/sysctl/3.md) 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)](/mmap/2.md) 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)](/mprotect/2.md). 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)](/elfctl/1.md) “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)](/wait/2.md). 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)](/fork/2.md). 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)](/init/8.md) 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)](/init/8.md). 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)](/kill/2.md). 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)](/ptrace/2.md), [ktrace(2)](/ktrace/2.md), debugging sysctls, [hwpmc(4)](/hwpmc/4.md), or [dtrace(1)](/dtrace/1.md) 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)](/execve/2.md) system call. A child inherits the trace settings from the parent on [fork(2)](/fork/2.md). - PROC\_TRACE\_CTL\_DISABLE\_EXEC Same as PROC\_TRACE\_CTL\_DISABLE, but the setting persists for the process even after [execve(2)](/execve/2.md). - 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)](/ptrace/2.md) 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)](/fexecve/2.md) 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)](/capsicum/4.md). 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)](/capsicum/4.md) 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)](/execve/2.md) 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)](/execve/2.md) in the specified process. - PROC\_STACKGAP\_DISABLE\_EXEC Inherit disabled stack gaps state after [execve(2)](/execve/2.md). 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)](/fork/2.md). - 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)](/execve/2.md). - PROC\_STACKGAP\_DISABLE\_EXEC Stack gaps are disabled in the process after [execve(2)](/execve/2.md). Note that the [elfctl(1)](/elfctl/1.md) “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)](/execve/2.md). 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)](/execve/2.md) 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)](/execve/2.md), 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)](/execve/2.md). 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)](/elfctl/1.md) “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)](/execve/2.md) 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)](/execve/2.md), 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)](/execve/2.md). 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)](/execve/2.md). - PROC\_KPTI\_CTL\_DISABLE\_ON\_EXEC Disable KPTI after [execve(2)](/execve/2.md). 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)](/init/8.md) 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)](/execve/2.md) 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)](/dtrace/1.md), [elfctl(1)](/elfctl/1.md), [proccontrol(1)](/proccontrol/1.md), [protect(1)](/protect/1.md), [cap\_enter(2)](/cap_enter/2.md), [kill(2)](/kill/2.md), [ktrace(2)](/ktrace/2.md), [mmap(2)](/mmap/2.md), [mprotect(2)](/mprotect/2.md), [ptrace(2)](/ptrace/2.md), [wait(2)](/wait/2.md), [capsicum(4)](/capsicum/4.md), [hwpmc(4)](/hwpmc/4.md), [init(8)](/init/8.md) ## 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.