PROCCTL(2)

✨ NAME ✨

okay so bestie, welcome to procctl(2) — from the System Calls Manual, no less 👑 — and it literally does what it says on the tin: it controls processes. 💅

🎀 LIBRARY 🎀

Standard C Library (libc, -lc) — yes, the classic, the icon, the one and only 🫶

🦋 SYNOPSIS 🦋

#include <sys/procctl.h>

int
procctl(idtype_t idtype, id_t id, int cmd, void *data);

🌸 DESCRIPTION 🌸

The procctl() system call is your little remote control for processes, bestie. The idtype and id arguments pick the set of processes you want to control. And if multiple processes match the identifier? procctl makes 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. That's the whole vibe check 💀

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. yes, zero means “me, myself, and I” 💅
• 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. no cap, permissions matter ✨

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. slay, randomize everything 🌈
• PROC_ASLR_FORCE_DISABLE — request that ASLR is disabled after execution, even if it is enabled system-wide. okay predictable queen 💀
• 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. so you get the status plus the little “active” sticker ✨

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. iconic behavior, honestly 🫶

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. cute little flag, very demure ✨

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. protect the besties 🫶
• 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. it's giving generational protection 💅

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. mother of all reapers, honestly 🌈

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 original, the blueprint 👑

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. (yes, “reapead” is exactly what the page says, bestie — we don't fix the queen's spelling 💀)

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. 😭 yes, PID reuse said “new phone who dis” — keep that in mind.

and here’s the struct that goes with all that pidinfo goodness, bestie:

struct procctl_reaper_pidinfo {
        pid_t   pi_pid;
        pid_t   pi_subtree;
        u_int   pi_flags;
};

The pi_pid field is literally the process id of the descendant. The pi_subtree field gives you the pid of the direct child of the reaper that is the (grand-)parent of the descendant process. And the pi_flags field returns these flags, which describe the descendant even more:

• REAPER_PIDINFO_VALID — set to show 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 lets the caller detect the end of the returned array. iykyk 💅
• 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. no cap.
• 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 🔥

This is the 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. iconic.

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 here, 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. slay.

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. periodt.
• 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. lowkey useful.

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 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 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. iconic behavior tbh.

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

Bestie, this one lets you ignore the set-user-ID and set-group-ID bits on any program image activated by execve(2) — for the process you point at, and for all its future descendants, forever. The data parameter has to point to an integer variable holding this value:

• PROC_NO_NEW_PRIVS_ENABLE — literally just "yes please, ignore those set-user-ID and set-group-ID bits."

Heads up: once you enable this, you cannot turn it back off. Like, ever. It's not possible to disable this control once it's been enabled. 💀

🌈 PROC_NO_NEW_PRIVS_STATUS

Just tells you where things stand re: set-ID bit enablement for the target process. The data parameter must point to an integer variable, and one of these gets written into it:

• PROC_NO_NEW_PRIVS_ENABLE
• PROC_NO_NEW_PRIVS_DISABLE

🔥 PROC_WXMAP_CTL

This is the vibe check for mappings that are both writable and executable in a process's address space (yes, the spicy W+X combo 🌶️). The data parameter must point to an integer variable holding one of these:

• PROC_WX_MAPPINGS_PERMIT — enable creation of mappings that have both write and execute permissions in the specified process' current and future address spaces. Go off, I guess.
• 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. Very demure, very mindful.

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 if the elfctl(1) “wxneeded” flag is set in the ELF control note. iykyk.

Once creation of writeable and executable mappings is enabled for a process, it is impossible (and like, also 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. That's the whole entire plan, no cap.

💅 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 these gets 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.

Bonus lore ✨: if the address space of the process doesn't permit creation of simultaneously writable and executable mappings, and it's guaranteed that no such mapping was created since address space creation, then the PROC_WXORX_ENFORCE flag is set in the returned value. Iconic behaviour, honestly.

---

🦋 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. You cannot change the KPTI setting for a running process — only for new address spaces constructed by a future execve(2). Main character energy only applies to new address spaces, sorry.

The data parameter must point to an integer variable containing one of these 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 these gets 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. Chef's kiss. 🫶

---

🌸 NOTES

Disabling tracing on a process should not be considered a security feature, bestie — it's bypassable both by the kernel and by privileged processes, and also via other system mechanisms. So like, don't use it to reliably protect cryptographic keying material or other confidential data. Please. I'm begging. 😭

Also 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. And honestly? This may be legitimately required by some programs such as JIT compilers. So it's giving "policy, not prison." 💀

---

⭐ RETURN VALUES

If an error occurs, a value of -1 is returned and errno is set to indicate the error. That's it, that's the whole rule.

---

💜 ERRORS

The procctl() system call will fail if:

• [EFAULT] — The data parameter points outside the process's allocated address space. Rude.
• [EINVAL] — The cmd argument specifies an unsupported command.
• [EINVAL] — 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) — go read them, they're all lowkey essential. 📚

---

✨ HISTORY

The procctl() function appeared in FreeBSD 9.3. Baby era. 🍼

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. (Checklist compliance. Felt that. 🙈)

---

Okay bestie, that's the whole page — every flag, every error, every era of FreeBSD history. You're basically a procctl() scholar now, fr fr. 💖

This lil beauty comes to you from Debian, dated April 21, 2025, and it's the PROCCTL(2) page. Go forth and process-control responsibly. 👑✨