Linux::Prctl(3pm)

🌸 NAME 🌸

Linux::Prctl — a Perl extension for controlling process characteristics 💅

(you clocked it from the header, bestie: this is the Linux::Prctl(3pm) page out of the User Contributed Perl Documentation, and it is long, so buckle up 🎀)

✨ SYNOPSIS ✨

use Linux::Prctl;

💖 DESCRIPTION 💖

okay so. the linux prctl function is the thing that lets you control specific characteristics of a process' behaviour — like, very specific. very niche. very powerful. 🫶

the catch? actually using it is messy as hell, purely because of limitations in C and in linux itself 😭. this module exists so you don't have to deal with that mess — it hands you a nice, non-messy interface instead. and heads up, most of the text in this documentation is based on text from the linux manpages prctl(2) and capabilities(7), so if it sounds like a manpage, that's why 💀

and it's not just prctl! besides that, this library also wraps libcap so you get complete capability handling too. iconique. 👑

🎀 EXPORTS 🎀

there are exactly 2 export tags: :constants and :functions. and yes, they export exactly what you think they export. no cap. ✨

set_dumpable(flag)

sets the state of the flag that decides whether core dumps get produced for this process when it gets delivered a signal whose default behavior is to produce a core dump. (normally this flag is on for a process by default, but it gets cleared when a set-user-ID or set-group-ID program is executed, and also by various system calls that manipulate process UIDs and GIDs.)

get_dumpable()

returns the state of the dumpable flag. that's it, that's the whole job 🌸

set_endian(endiannes)

sets the endian-ness of the calling process. valid values are ENDIAN_BIG, ENDIAN_LITTLE and ENDIAN_PPC_LITTLE (that last one is PowerPC pseudo little endian, iykyk).

this function only works on PowerPC systems. don't come for me if you're on x86 🙈

get_endian()

returns the endian-ness of the calling process — go peek at set_endian if you need the deets.

set_fpemu(flag)

sets the floating-point emulation control flag. pass FPEMU_NOPRINT to silently emulate fp operations accesses, or pass FPEMU_SIGFPE to not emulate fp operations and send SIGFPE instead.

this function only works on ia64 systems. 💀

get_fpemu()

gets the floating-point emulation control flag. see set_fpemu.

set_fpexc(mode)

sets the floating-point exception mode. here's the menu, bestie:

• FP_EXC_SW_ENABLE — use FPEXC for FP exception
• FP_EXC_DIV — floating-point divide by zero
• FP_EXC_OVF — floating-point overflow
• FP_EXC_UND — floating-point underflow
• FP_EXC_RES — floating-point inexact result
• FP_EXC_INV — floating-point invalid operation
• FP_EXC_DISABLED — FP exceptions disabled
• FP_EXC_NONRECOV — async non-recoverable exception mode
• FP_EXC_ASYNC — async recoverable exception mode
• FP_EXC_PRECISE — precise exception mode

modes can be combined with the | operator, so go wild 🎀

this function only works on PowerPC systems.

get_fpexc()

returns the floating-point exception mode as a bitmap of enabled modes. see set_fpexc.

set_keepcaps(flag)

sets the state of the thread's "keep capabilities" flag. and what does that flag decide, you ask? it determines whether the thread's effective and permitted capability sets get cleared when a change is made to the thread's user IDs such that the thread's real UID, effective UID, and saved set-user-ID all become non-zero when at least one of them previously had the value 0. (by default, these credential sets are cleared.)

heads up: this value will be reset to False on subsequent calls to execve. 😭

get_keepcaps()

returns the current state of the calling thread's "keep capabilities" flag.

set_mce_kill(policy)

sets the machine check memory corruption kill policy for the current thread. the policy can be:

• early kill (MCE_KILL_EARLY)
• late kill (MCE_KILL_LATE)
• or the system-wide default (MCE_KILL_DEFAULT)

early kill means the task receives a SIGBUS signal as soon as hardware memory corruption is detected inside its address space. in late kill mode, the process is only killed when it accesses a corrupted page. the policy is inherited by children. use the system-wide default. the system-wide default is defined by /proc/sys/vm/memory_failure_early_kill.

this function is only available for kernel 2.6.32 and newer.

get_mce_kill()

returns the current per-process machine check kill policy.

this function is only available for kernel 2.6.32 and newer.

set_name(name)

sets the process name for the calling process — the name can be up to 16 bytes long. this name is what shows up in the output of ps and top. the initial value is the name of the executable, which for perl applications will likely be perl. and as of perl 5.14, assigning to $0 also sets the process name. 🦋

get_name()

returns the (first 16 bytes of the) name for the calling process.

set_pdeathsig(signal)

sets the parent process death signal of the calling process (either a valid signal value from the :mod:signal module, or 0 to clear it). this is the signal that the calling process will get when its parent dies. this value is cleared for the child of a fork. 💀

get_pdeathsig()

returns the current value of the parent process death signal. see set_pdeathsig.

set_ptracer(pid)

sets the top of the process tree that's allowed to use PTRACE on the calling process, assuming the other requirements are met (matching uid, wasn't setuid, etc). use pid 0 to disallow all processes. for more details, see /etc/sysctl.d/10-ptrace.conf.

this function is only available for kernel 3.4 and newer, or Ubuntu 10.10 and newer.

get_ptracer(pid)

returns the top of the process tree that's allowed to use PTRACE on the calling process. see set_ptracer.

this function is only available for kernel 3.4 and newer, or Ubuntu 10.10 and newer.

set_seccomp(mode)

sets the secure computing mode for the calling thread. in the current implementation, mode must be True. once the secure computing mode has been set to True, the only system calls the thread is permitted to make are read, write, _exit, and sigreturn. any other system call results in the delivery of a SIGKILL signal. 🔥

secure computing mode is useful for number-crunching applications that may need to execute untrusted byte code, perhaps obtained by reading from a pipe or socket.

this operation is only available if the kernel is configured with CONFIG_SECCOMP enabled.

get_seccomp()

returns the secure computing mode of the calling thread. not very useful for the current implementation, but it may be useful for other possible future modes:

• if the caller is not in secure computing mode, this operation returns False
• if the caller is in secure computing mode, then the prctl call will cause a SIGKILL signal to be sent to the process 💀

this operation is only available if the kernel is configured with CONFIG_SECCOMP enabled.

set_timerslack()

controls the default "rounding" in nanoseconds that's used by select, poll and friends.

the default value of the slack is 50 microseconds; this is significantly less than the kernel's average timing error but still allows the kernel to group timers somewhat to preserve power behavior. 🌈

this function is only available for kernel 2.6.28 and newer.

get_timerslack(value)

returns the current timing slack, see get_timing_slack.

this function is only available for kernel 2.6.28 and newer.

set_timing(flag)

sets whether to use (normal, traditional) statistical process timing or accurate timestamp based process timing, by passing TIMING_STATISTICAL or PR_TIMING_TIMESTAMP.

heads up: TIMING_TIMESTAMP is not currently implemented 🙈

get_timing()

returns which process timing method is currently in use.

set_tsc(flag)

sets the state of the flag determining whether the timestamp counter can be read by the process. pass TSC_ENABLE to allow it to be read, or TSC_SIGSEGV to generate a SIGSEGV when the process tries to read the timestamp counter. 💅

this function only works on x86 systems.

get_tsc()

returns the state of the flag determining whether the timestamp counter can be read, see set_tsc.

set_unalign(flag)

sets the unaligned access control flag. pass UNALIGN_NOPRINT to silently fix up unaligned user accesses, or UNALIGN_SIGBUS to generate SIGBUS on unaligned user access.

this function only works on ia64, parisc, PowerPC and Alpha systems.

get_unalign

returns the unaligned access control bits, see set_unalign.

set_securebits(bitmap)

sets the "securebits" flags of the calling thread.

it is not recommended to use this function directly — use the %Linux::Prctl::securebits hash instead. 🫶

get_securebits()

gets the "securebits" flags of the calling thread.

as with set_securebits, it is not recommended to use this function directly — use the %Linux::Prctl::securebits hash instead.

capbset_read(capability)

returns whether the specified capability is in the calling thread's capability bounding set. the capability bounding set dictates whether the process can receive the capability through a file's permitted capability set on a subsequent call to execve.

it is not recommended to use this function directly — use the %Linux::Prctl::cap_* hashes instead.

capbset_drop(capability)

if the calling thread has the CAP_SETPCAP capability, then it drops the specified capability from the calling thread's capability bounding set. any children of the calling thread will inherit the newly reduced bounding set. 👑

as with capbset_read, it is not recommended to use this function directly — use the %Linux::Prctl::cap_* hashes instead.

---

👑 Capabilities and the capability bounding set 👑

okay so for the purpose of performing permission checks, traditional Unix implementations split processes into two categories, bestie:

• privileged processes — whose effective user ID is 0, aka superuser or root
• unprivileged processes — whose effective UID is non-zero

privileged processes bypass all kernel permission checks. unprivileged processes are subject to full permission checking based on the process's credentials (usually: effective UID, effective GID, and supplementary group list).

starting with kernel 2.2, linux divides the privileges traditionally associated with superuser into distinct units, known as capabilities, which can be independently enabled and disabled. capabilities are a per-thread attribute. ✨

each thread has three capability sets containing zero or more of the capabilities described below 🌸

Permitted (the %Linux::Prctl::cap_permitted hash):

this is a limiting superset for the effective capabilities that the thread may assume. it's also a limiting superset for the capabilities that may be added to the inheritable set by a thread that does not have the setpcap capability in its effective set.

if a thread drops a capability from its permitted set, it can never re-acquire that capability (unless it execves either a set-user-ID-root program, or a program whose associated file capabilities grant that capability). so like. be sure. 💀

Inheritabe (the %Linux::Prctl::cap_inheritable hash):

(yes it's spelled that way in here, we don't ask questions 🙈)

this is a set of capabilities preserved across an execve. it provides a mechanism for a process to assign capabilities to the permitted set of the new program during an execve. 🦋

Effective (the %Linux::Prctl::cap_effective hash):

Okay so real talk bestie, this is the capability <em>hash</em> situation and it's a lot, but we're gonna get through it together 💖

This is the set of capabilities the kernel uses to do permission checks for the thread. That's it, that's the whole vibe of it.

A child created via fork inherits copies of its parent's capability sets. And there's a whole discussion below about what happens to capabilities during execve — keep scrolling, we get there. 🫶

The $Linux::Prctl::capbset hash represents the current capability bounding sets of the process. The capability bounding set dictates whether the process can receive the capability through a file's permitted capability set on a subsequent call to execve. Every item in this hash is true by default, unless a parent process already removed them from the bounding set. (Rude of the parent, but okay.)

These four hashes have a number of keys. For the capability bounding set and the effective capabilities, these can only be set to False — doing that drops them from the corresponding set. That's the move, periodt.

All the details about capabilities and capability bounding sets live in the capabilities(7) manpage, and ngl most of the text below is based on that one.

These are the keys of the hashes, bestie, get comfy:

• audit_control — Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. 👑
• audit_write — Write records to kernel auditing log.
• chown — Make arbitrary changes to file UIDs and GIDs (see chown(2)).
• dac_override — Bypass file read, write, and execute permission checks. (DAC is an abbreviation of "discretionary access control".)
• dac_read_search — Bypass file read permission checks and directory read and execute permission checks.
• fowner — Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file (e.g., chmod, utime), excluding those operations covered by dac_override and dac_read_search.
  • Set extended file attributes (see chattr(1)) on arbitrary files.
  • Set Access Control Lists (ACLs) on arbitrary files.
  • Ignore directory sticky bit on file deletion.
  • Specify O_NOATIME for arbitrary files in open and fcntl.
• fsetid — Don't clear set-user-ID and set-group-ID permission bits when a file is modified; set the set-group-ID bit for a file whose GID does not match the file system or any of the supplementary GIDs of the calling process.
• ipc_lock — Lock memory (mlock, mlockall, mmap, shmctl).
• ipc_owner — Bypass permission checks for operations on System V IPC objects.
• kill — Bypass permission checks for sending signals (see kill(2)). This includes use of the ioctl KDSIGACCEPT operation.
• lease — Establish leases on arbitrary files (see fcntl(2)).
• linux_immutable — Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags (see chattr(1)).
• mac_admin — Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM).
• mac_override — Allow MAC configuration or state changes. Implemented for the Smack LSM.
• mknod — Create special files using mknod.
• net_admin — Perform various network-related operations (e.g., setting privileged socket options, enabling multicasting, interface configuration, modifying routing tables).
• net_bind_service — Bind a socket to Internet domain privileged ports (port numbers less than 1024).
• net_broadcast — (Unused) Make socket broadcasts, and listen to multicasts. (Unused, bestie. It's giving retired icon.)
• net_raw — Use RAW and PACKET sockets.
• setgid — Make arbitrary manipulations of process GIDs and supplementary GID list; forge GID when passing socket credentials via Unix domain sockets.
• setfcap — Set file capabilities.
• setpcap — If file capabilities are not supported: grant or remove any capability in the caller's permitted capability set to or from any other process. (This property of setpcap is not available when the kernel is configured to support file capabilities, since setpcap has entirely different semantics for such kernels.)
  • If file capabilities are supported: add any capability from the calling thread's bounding set to its inheritable set; drop capabilities from the bounding set (via capbset_drop); make changes to the securebits flags.
• setuid — Make arbitrary manipulations of process UIDs (setuid, setreuid, setresuid, setfsuid); make forged UID when passing socket credentials via Unix domain sockets.
• syslog — Allow configuring the kernel's syslog (printk behaviour). Before linux 2.6.38 the sys_admin capability was needed for this.
  • This is only available in linux 2.6.38 and newer.
• sys_admin — Perform a range of system administration operations including: quotactl, mount, umount, swapon, swapoff, sethostname, and setdomainname.
  • Perform IPC_SET and IPC_RMID operations on arbitrary System V IPC objects.
  • Perform operations on trusted and security Extended Attributes (see attr(5)).
  • Use lookup_dcookie.
  • Use ioprio_set to assign the IOPRIO_CLASS_RT scheduling class.
  • Forge UID when passing socket credentials.
  • Exceed /proc/sys/fs/file-max, the system-wide limit on the number of open files, in system calls that open files (e.g., accept, execve, open, pipe).
  • Employ CLONE_NEWNS flag with clone and unshare.
  • Perform KEYCTL_CHOWN and KEYCTL_SETPERM keyctl operations.
• sys_boot — Use reboot and kexec_load.
• sys_chroot — Use chroot.
• sys_module — Load and unload kernel modules (see init_module(2) and delete_module(2)).
• sys_nice — Raise process nice value (nice, setpriority) and change the nice value for arbitrary processes.
  • Set real-time scheduling policies for calling process, and set scheduling policies and priorities for arbitrary processes (sched_setscheduler, sched_setparam).
  • Set CPU affinity for arbitrary processes (sched_setaffinity).
  • Set I/O scheduling class and priority for arbitrary processes (ioprio_set).
  • Apply migrate_pages to arbitrary processes and allow processes to be migrated to arbitrary nodes.
  • Apply move_pages to arbitrary processes.
  • Use the MPOL_MF_MOVE_ALL flag with mbind and move_pages.
• sys_pacct — Use acct.
• sys_ptrace — Trace arbitrary processes using ptrace.
• sys_rawio — Perform I/O port operations (iopl and ioperm); access /proc/kcore.
• sys_resource — Use reserved space on ext2 file systems.
  • Make ioctl calls controlling ext3 journaling.
  • Override disk quota limits.
  • Increase resource limits (see setrlimit(2)).
  • Override RLIMIT_NPROC resource limit.
  • Raise msg_qbytes limit for a System V message queue above the limit in /proc/sys/kernel/msgmnb (see msgop(2) and msgctl(2)).
• sys_time — Set system clock (settimeofday, stime, adjtimex); set real-time (hardware) clock.
• sys_tty_config — Use vhangup.
• wake_alarm — Allow triggering something that will wake the system.
  • This is only available in linux 3.0 and newer.

---

The four capabilities hashes also have two additional methods, because dropping a million capabilities one at a time is not the vibe:

• drop(cap [, ...]) — Drop all capabilities given as arguments from the set.
• limit(cap [, ...]) — Drop all but the given capabilities from the set.

These functions accept both names of capabilities as given above and the CAP_ constants as defined in capabilities.h. Those constants are available as CAP_SYS_ADMIN et cetera. ✨

🦋 Capabilities and execve 🦋

During an execve(2), the kernel calculates the new capabilities of the process using the following algorithm:

* P'(permitted) = (P(inheritable) & F(inheritable)) | (F(permitted) & cap_bset)
* P'(effective) = F(effective) ? P'(permitted) : 0
* P'(inheritable) = P(inheritable) [i.e., unchanged]

Where:

• P denotes the value of a thread capability set before the execve
• P' denotes the value of a capability set after the execve
• F denotes a file capability set
• cap_bset is the value of the capability bounding set

The downside of this is that you need to set file capabilities if you want to make applications capabilities-friendly via wrappers. For instance, to allow an http daemon to listen on port 80 without it needing root privileges, you could do the following:

%Linux::Prctl.cap_inheritable{net_bind_service} = 1;
$< = 1000;
exec "/usr/sbin/httpd";

This only works if /usr/sbin/httpd has CAP_NET_BIND_SOCK in its inheritable and effective sets. You can do this with the setcap(8) tool shipped with libcap.

$ sudo setcap cap_net_bind_service=ie /usr/sbin/httpd
$ getcap /usr/sbin/httpd
/usr/sbin/httpd = cap_net_bind_service+ei

Note that it only sets the capability in the inheritable set, so this capability is only granted if the program calling execve has it in its inheritable set too. The effective set of file capabilities does not exist in linux, it is a single bit that specifies whether capabilities in the permitted set are automatically raised in the effective set upon execve. 🎀

🌸 Establishing a capabilities-only environment with securebits 🌸

With a kernel in which file capabilities are enabled, Linux implements a set of per-thread securebits flags that can be used to disable special handling of capabilities for UID 0 (root). The securebits flags are inherited by child processes. During an execve, all of the flags are preserved, except keep_caps which is always cleared.

These capabilities are available via get_securebits, but are easier accessed via the $Linux::prctl::securebits hash. This hash has keys that tell you whether specific securebits are set, or unset. (Lowkey so handy.)

The following keys are available:

• keep_caps — Setting this flag allows a thread that has one or more 0 UIDs to retain its capabilities when it switches all of its UIDs to a non-zero value. If this flag is not set, then such a UID switch causes the thread to lose all capabilities. This flag is always cleared on an execve.
• no_setuid_fixup — Setting this flag stops the kernel from adjusting capability sets when the threads's effective and file system UIDs are switched between zero and non-zero values. (See the subsection Effect of User ID Changes on Capabilities in capabilities(7).)
• noroot — If this bit is set, then the kernel does not grant capabilities when a set-user-ID-root program is executed, or when a process with an effective or real UID of 0 calls execve. (See the subsection Capabilities and execution of programs by root in capabilities(7).)
• keep_caps_locked — Like keep_caps, but irreversible. 💀
• no_setuid_fixup_locked — Like no_setuid_fixup, but irreversible. 💀
• noroot_locked — Like noroot, but irreversible. 💀

💀 TODO 💀

• None of the capability stuff is actually implemented at the moment. (bestie. bestie no. it's not real yet. 😭)

🌈 SEE ALSO 🌈

Manpages: capabilities(7) and prctl(2)

Github source: <http://github.com/seveas/Linux-Prctl>

👑 AUTHOR 👑

Dennis Kaarsemaker, <dennis@kaarsemaker.net>

👑 COPYRIGHT AND LICENSE 👑

okay bestie, legal era. not the funnest part but we gotta give credit where credit is due, periodt.

Copyright (C) 2011 by Dennis Kaarsemaker — yeah, that's the icon who made this whole thing happen. respect. 🫶

and now the actual license tea, verbatim vibes:

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

so basically: it's free, you can share it, you can remix it, you can pass it around the group chat 💅 — as long as you play by the GPL's rules, which are laid out by the Free Software Foundation. and you get to pick: version 3 of the License, or honestly any later version if that's more your vibe. your choice, bestie, no cap.

---

and that's the whole page!! 🌸 you just read the entire Linux::Prctl(3pm) manpage and honestly? iconic behavior. go write some syscalls, you absolute legend. 💖

✨ lil sign-off ✨ this page is Linux::Prctl(3pm), shipped with perl v5.40.1, dated 2025-04-13. slay, bye 🦋