RCTL_ADD_RULE(2)

💖 RCTL_ADD_RULE(2) 💖

ok so bestie, welcome to the System Calls Manual — this is the page for the rctl family of syscalls, aka the resource limits database crew. buckle up 🎀

---

✨ NAME ✨

rctl_add_rule, rctl_get_limits, rctl_get_racct, rctl_get_rules, rctl_remove_rule — manipulate and query the resource limits database 💅

---

📚 LIBRARY 📚

Standard C Library (libc, -lc) — the classic, the icon, the moment 👑

---

🌸 SYNOPSIS 🌸

#include <sys/rctl.h>

int
rctl_add_rule(const char *inbufp, size_t inbuflen, char *outbufp,
    size_t outbuflen);

int
rctl_get_limits(const char *inbufp, size_t inbuflen, char *outbufp,
    size_t outbuflen);

int
rctl_get_racct(const char *inbufp, size_t inbuflen, char *outbufp,
    size_t outbuflen);

int
rctl_get_rules(const char *inbufp, size_t inbuflen, char *outbufp,
    size_t outbuflen);

int
rctl_remove_rule(const char *inbufp, size_t inbuflen, char *outbufp,
    size_t outbuflen);

---

🦋 DESCRIPTION 🦋

so these system calls are the ones you use to manipulate and query the resource limits database. for literally all of them, inbuflen is the length of the buffer that inbufp points at, and outbuflen is the length of the buffer that outbufp points at. simple as that, no cap 💜

• rctl_add_rule() — adds the rule pointed to by inbufp to the resource limits database. the outbufp and outbuflen args are just... sitting there, unused, not invited to the party 🙈. rule format is the one described in rctl(8), except for the little exceptions we spill in the “RULES AND FILTERS” section below.
• rctl_get_limits() — returns in outbufp a comma-separated list of rules that apply to the process matching the filter you put in inbufp. and this includes rules where the subject is the process itself, plus rules with a different subject (like user or loginclass) that still apply to that process. it's giving "everyone who has a say in your life" energy ngl 🫶
• rctl_get_racct() — returns resource usage info for a given subject. you specify that subject by passing a filter in inbufp. filter syntax is as described in rctl(8), with the exceptions noted in “RULES AND FILTERS”. what comes back in outbufp is a comma-separated list of resources and how much of each the specified subject has used. each resource and amount is formatted as "resource=amount" — exactly like that, = and everything ✨
• rctl_get_rules() — returns in outbufp a comma-separated list of rules from the resource limits database that match the filter passed in inbufp. filter syntax again = as described in rctl(8), exceptions in “RULES AND FILTERS”. and ooh, fun fact: you can pass a filter of :: to get ALL the rules back. main character behavior honestly 👑
• rctl_remove_rule() — removes all rules matching the filter passed in inbufp from the resource limits database. filter syntax = rctl(8), exceptions in “RULES AND FILTERS”. outbufp and outbuflen? unused, ignored, not relevant, bye 💀

---

🎀 RULES AND FILTERS 🎀

ok this section is lowkey important so pay attention bestie. it explains how the rule and filter format from rctl(8) is different from the format you pass straight to the system calls themselves. the rctl tool is out here doing extra favors for you that the syscalls simply do not do. so when you're using the system call:

• The subject must be fully specified. for example, abbreviating ‘user’ to ‘u’ is not acceptable. spell it out, no shortcuts 💅
• User and group IDs must be numeric. for example, ‘root’ must be expressed as ‘0’. the syscall does not know who root is, it knows 0 🔢
• Units are not permitted on resource amounts. for example, a quantity of 1024 bytes must be expressed as ‘1024’ and not ‘1k’. no cute little suffixes allowed, sorry 🥲

---

⭐ RETURN VALUES ⭐

when everything goes right, the value 0 is returned 😌✨. otherwise the value -1 comes back and the global variable errno gets set to tell you what went wrong. it's giving "we need to talk" energy 😭

---

💀 ERRORS 💀

the rctl system calls may fail if:

• [ENOSYS] — RACCT/RCTL support is not present in the kernel, or the kern.racct.enable sysctl is 0. the feature literally isn't home rn 🙈
• [EINVAL] — the rule or filter passed in inbufp is invalid. something you typed is not it, bestie 😬
• [EPERM] — user has insufficient privileges to carry out the requested operation. you do not have the clearance for this one, gatekept fr 🔒
• [E2BIG] — inbufp or outbufp are too large. too much. overwhelming. overstimulated 💀
• [ESRCH] — no process matched the provided rule or filter. nobody came to the function 😭
• [ENAMETOOLONG] — the loginclass or jail name specified is too long. it's a lot of letters and the kernel said no 🫠
• [ERANGE] — the rule amount is outside of the allowable range, or outbufp is too small. either the number is out of pocket or your buffer is tiny 🥲
• [EOPNOTSUPP] — the requested operation is not supported for the given rule or filter. it's just not the vibe for that particular combo ✋
• [EFAULT] — inbufp or outbufp refer to invalid addresses. those pointers are pointing into the void 🌌

---

🌈 SEE ALSO 🌈

• rctl(8) — go read it, it's the whole other half of this story 💖

---

📜 HISTORY 📜

The rctl family of system calls appeared in FreeBSD 9.0. a classic, an icon, a legend, periodt 💅

---

🫶 AUTHORS 🫶

The rctl system calls were developed by Edward Tomasz Napierala <trasz@FreeBSD.org> under sponsorship from the FreeBSD Foundation. This manual page was written by Eric Badger <badger@FreeBSD.org>. absolute legends, both of them, no notes 👑✨

---

and that's the whole page bestie! go forth and limit your resources responsibly 🎀💖

this little love letter came to you from the Debian edition, dated September 14, 2016 — RCTL_ADD_RULE(2), signing off 🦋🌸