PROCCTL(2)

💅 PROCCTL(2) 💅

so this is procctl from the System Calls Manual, and bestie, it is a whole vibe — it's how you get hands-on with processes. buckle up. 🎀

---

✨ NAME ✨

procctl — control processes 🫶

📚 LIBRARY 📚

Standard C Library (libc, -lc) — yeah, the classic. no extra lib needed, she's built in. 💖

🧚 SYNOPSIS 🧚

#include <sys/procctl.h>

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

🌸 DESCRIPTION 🌸

okay so the procctl() system call is your main character moment for controlling processes. the idtype and id arguments are how you pick which processes you're controlling. and here's the tea: if multiple processes match that identifier, procctl will do a "best effort" and try to control as many of the selected processes as it possibly can. an error only comes back if literally zero of the selected processes actually completed the request. ngl that's forgiving of her.

these are the identifier types she supports:

• P_PID — control the process with the process ID id. just the one. 💅
• P_PGID — control processes belonging to the process group with the ID id. the whole squad. 👑

the actual control request you're doing is picked by the cmd argument. here are the commands she supports:

🔥 PROC_ASLR_CTL 🔥

controls the Address Space Layout Randomization (ASLR) in the program images created by execve(2) in the specified process — or in its descendants, as long as they didn't change the control and didn't modify it by other means. so like, it's giving ✨generational✨ energy.

the data parameter must point to the integer variable holding one of these values:

• PROC_ASLR_FORCE_ENABLE — requesting that ASLR is enabled after execution, even if it's disabled system-wide. but heads up: the image flag and set-uid might still prevent ASLR enablement. so don't come for her if it doesn't work, ok? 😭
• PROC_ASLR_FORCE_DISABLE — requesting that ASLR is disabled after execution. same notes as for PROC_ASLR_FORCE_ENABLE apply. 💀
• PROC_ASLR_NOFORCE — just use the system-wide configured policy for ASLR. lowkey the chill option. 🦋

✨ 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 gets written:

• PROC_ASLR_FORCE_ENABLE
• PROC_ASLR_FORCE_DISABLE
• PROC_ASLR_NOFORCE

and the little detail iyk: 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 might get both, bestie. 💖

🛡️ PROC_SPROTECT 🛡️

sets the process protection state. this one is used to mark a process as protected from being killed if the system exhausts the available memory and swap — literally the bodyguard of processes, no cap. 💪

the data parameter must point to an integer containing an operation and zero or more optional flags. the operations she supports:

• PPROT_SET — mark the selected processes as protected. 🫶
• PPROT_CLEAR — clear the protected state of selected processes. 🙈

and these are the optional flags:

• PPROT_DESCEND — apply the requested operation to all child processes of each selected process, in addition to each selected process. the nepo babies get included. 👑
• PPROT_INHERIT — when used with PPROT_SET, mark all future child processes of each selected process as protected. and those future child processes will also mark all of their future child processes. it's generational protection, she's passing it down. 🧬

🌈 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 — get reparented to the reaper process. after system initialization, init(8) is the default reaper. so yeah, init was doing this the whole time. iconic behavior. 💅

🌸 PROC_REAP_RELEASE 🌸

releases the reaper state for the current process. the reaper of the current process then becomes the new reaper of the current process's descendants. passing the crown. 👑

🎀 PROC_REAP_STATUS 🎀

gives you info about the reaper of the specified process — or about the process itself when it is a reaper. the data argument must point to a procctl_reaper_status structure, which gets 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 these flags returned:

• REAPER_STATUS_OWNED — the specified process has acquired reaper status and has not released it. when this 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 literal final boss. 👑

now the fields, bestie, pay attention:

• the rs_children field returns the number of children of the reaper among the descendants. it's 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. so don't @ her about it. 😭
• 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. this 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 — the kernel will fill in no more than rp_count elements into it. no overflow, we behave. ✨

the struct procctl_reaper_pidinfo structure provides some info about one of the reaper's descendants. and okay, important caveat bestie: 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. so like, drama. 💀

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 lets the caller detect the end of the returned array. cute little sentinel, we stan. 🫶
  • 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. sorry bestie, they're not on the list. 🙈

🔥 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;
};

ok so rk_sig is literally just the signal you wanna send 💌 bestie, heads up: zero is NOT a valid signal number here, which is not how kill(2) does it, so don't get cute with it. And rk_flags is what actually steers the whole operation — you or together any of these lil guys:

• REAPER_KILL_CHILDREN — send the signal to the reaper's direct children only, nobody deeper. keep it in the family ✨
• REAPER_KILL_SUBTREE — send it only to descendants that were forked by the direct child whose pid you dropped in the rk_subtree field. like, one specific branch of the tree 🎀

And if you specify neither REAPER_KILL_CHILDREN nor REAPER_KILL_SUBTREE? then babes, it's everyone — all current descendants of the reaper get signalled. full send 🌈

If a signal actually landed on any process, the request returns zero. in that case rk_killed tells you how many processes got signalled 👑 and rk_fpid gets set to the pid of the first process where signal delivery failed — like, say, permission problems being rude 🙈 if there's no such process at all, rk_fpid is set to -1.

---

💅 PROC_TRACE_CTL 💅

Turn tracing on or off for the specified process(es), based on whatever integer you passed in. and bestie, "tracing" here is a big umbrella — it covers attaching to the process with ptrace(2) and ktrace(2), debugging sysctls, hwpmc(4), dtrace(1), and core dumping. so many vibes, one switch 🫶

Your possible values for the data argument:

• PROC_TRACE_CTL_ENABLE — turns tracing back on, after it got disabled by PROC_TRACE_CTL_DISABLE. only allowed for self, no doing this for other people's processes ✋
• PROC_TRACE_CTL_DISABLE — disables tracing for the specified process. lowkey important: tracing gets re-enabled when the process changes the executing program with the execve(2) syscall. and 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). stubborn. iconic. 💀

🔍 PROC_TRACE_STATUS 🔍

Hands you the current tracing status of the specified process in the integer variable that data points to. here's the decoder ring:

• tracing disabled → data is set to -1
• tracing enabled but no debugger attached via the ptrace(2) syscall → data is set to 0
• 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 — specifically on a return from any syscall that gives either an ENOTCAPABLE or ECAPMODE error. if the control is enabled, those errors cause delivery of the synchronous SIGTRAP signal to the thread immediately before returning from the syscalls. caught in 4k 📸

Your possible values for the data argument:

• PROC_TRAPCAP_CTL_ENABLE — enable the SIGTRAP signal delivery on capability mode access violations. this 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. ⚠️ but note: the global sysctl kern.trap_enotcap might still cause the signal to be delivered anyway. 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 info about capability mode, iykyk.

📊 PROC_TRAPCAP_STATUS 📊

Returns the current status of signalling capability mode access violations for the specified process. the integer value pointed to by the data argument gets set to PROC_TRAPCAP_CTL_ENABLE if the process control enables signal delivery, and to PROC_TRAPCAP_CTL_DISABLE otherwise.

And fr, see the note about the sysctl kern.trap_enotcap up above — that thing gives independent global control of signal delivery, so it's not just you calling the shots here 💅

👻 PROC_PDEATHSIG_CTL 👻

Requests the delivery of a signal when the parent of the calling process exits 😭 abandonment arc. idtype must be P_PID, and id must be either the caller's pid or zero — with no difference in effect, so don't stress about which one. The value is cleared for child processes and when executing set-user-ID or set-group-ID binaries (yes, security said no). 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 🕵️

Queries 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 the caller's pid or zero, again 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. ok so what even is a stack gap? it's the part of the growth area for a MAP_STACK mapped region that's reserved and never filled by memory. instead, the process is guaranteed to receive a SIGSEGV signal on accessing pages in the gap 💥 and why do we care? because gaps protect against stack overflow corrupting memory adjacent to the stack. little bodyguard, no cap 🛡️

The data argument must point to an integer variable containing flags. these are the allowed ones:

• PROC_STACKGAP_ENABLE — this flag is only accepted for consistency with PROC_STACKGAP_STATUS. if stack gaps are already enabled, the flag is ignored. if they're disabled, the flag causes an EINVAL error to be returned 😤 and heads up: 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 — ok so this one makes the process inherit the "stack gaps disabled" state after execve(2). Translation: if the program running right now has stack gaps turned off, they stay off through the exec. And if gaps were on? They stay on after exec. No surprise flips, bestie. 💅

The stack gap state is inherited from the parent on fork(2). Like, it's a family thing, it runs in the genes. 🧬

---

🌸 PROC_STACKGAP_STATUS 🌸

This one hands you back the current stack gap state for whatever process you're pointing at. data has to point to an integer variable, and that variable gets used to return a bitmask made out of these flags:

• PROC_STACKGAP_ENABLE — stack gaps are enabled, we love that for them.
• 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 💻

Heads up bestie: this whole section is the x86-only corner of the party.

🛡️ PROC_KPTI_CTL

AMD64 only. This controls the Kernel Page Table Isolation (KPTI) option for the children of the process you specified. For the command to actually work, the vm.pmap.kpti tunable has to be enabled on boot. And nope, you cannot change the KPTI setting for a process that's already running — the only moment you get to touch it is at execve(2), where the address space gets reinitialized. That's the one window. 🪟

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 holding the PRIV_IO privilege, might use this option. So like, check your privileges before you vibe-check this one.

📊 PROC_KPTI_STATUS

Returns the current KPTI status for the process you're asking about. data must point to the integer variable, and it returns one of these statuses:

• PROC_KPTI_CTL_ENABLE_ON_EXEC
• PROC_KPTI_CTL_DISABLE_ON_EXEC

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

---

📝 NOTES

Okay so real talk, no cap: disabling tracing on a process should not be considered a security feature. It's bypassable — by the kernel, by privileged processes, and through other system mechanisms too. So please don't use it to reliably protect cryptographic keying material or any other confidential data. It's giving decorative, not defensive. 🚫🔐

---

↩️ RETURN VALUES

If something goes wrong, a value of -1 is returned and errno is set to indicate the error. That's it, that's the whole return story. 😭

---

💀 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.
• [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.
• [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. (sir, not you.)
• [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)

Go read those next, they're the rest of the friend group. 🫶

---

📜 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. And the ASLR support was added to system for the checklists compliance in FreeBSD 13.0. Glow up after glow up. 👑

---

And that's the whole page bestie!! 🎀 This version came from the Debian package, dated June 13, 2020, and it's the man page for PROCCTL(2). tysm for reading the entire thing, you're literally the main character of this terminal. mwah 💖💅✨