RCTL_ADD_RULE(2)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 RCTL_ADD_RULE(2) — the resource-limits girlies 🎀

okay so bestie, buckle up, this is the System Calls Manual page for the whole rctl family and it lives in section 2 (system calls, not commands, iykyk) ✨

🌸 NAME

rctl_add_rule, rctl_get_limits, rctl_get_racct, rctl_get_rules, rctl_remove_rule — literally the whole squad that manipulates and queries the resource limits database 💖

🦋 LIBRARY

Standard C Library (libc, -lc) 🫶

⭐ 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 ✨

okay so these system calls are your main characters for manipulating and querying the resource limits database 👑 for all of them, inbuflen is the length of the buffer that inbufp points to, and outbuflen is the length of the buffer that outbufp points to. no cap, that's the whole buffer deal 💅

  • rctl_add_rule() — adds the rule that inbufp points to into the resource limits database 🎀 the outbufp and outbuflen arguments are unused (they're just... there, vibing 🙈). rule format is exactly as described in rctl(8), except for the exceptions noted down in the “RULES AND FILTERS” section below, so don't skip it bestie.
  • rctl_get_limits() — hands you back, in outbufp, a comma-separated list of rules that apply to the process matching the filter you specified in inbufp 🌈 and yes, this includes rules whose subject is the process itself and rules with a different subject (like user or loginclass) that still apply to that process. it's giving "everyone who has beef with you, listed" 💀
  • rctl_get_racct() — returns resource usage info for a given subject 🍓 you specify that subject by passing a filter in inbufp, and the filter syntax is as described in rctl(8) except for those exceptions in “RULES AND FILTERS”. you get back, in outbufp, 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" ⭐
  • 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) with the exceptions in “RULES AND FILTERS”. and here's the iconic trick: pass a filter of :: to return all the rules 👑
  • rctl_remove_rule() — removes every rule matching the filter passed in inbufp from the resource limits database 🧚 filter syntax as described in rctl(8), exceptions in “RULES AND FILTERS”, and outbufp and outbuflen are unused. girl, it's a delete, what did you expect in the output buffer 😭

🌈 RULES AND FILTERS

this section is the whole "here's what's different" moment, because the rule and filter format described in rctl(8) is not identical to the format you pass into the system calls themselves. the rctl tool gives you several conveniences that the system calls simply do not 💅 so when you're using the system call:

  • the subject must be fully specified. for example, abbreviating ‘user’ to ‘u’ is not acceptable 🙅‍♀️
  • user and group IDs must be numeric. for example, ‘root’ must be expressed as ‘0’ 🫶
  • units are not permitted on resource amounts. for example, a quantity of 1024 bytes must be expressed as ‘1024’ and not ‘1k’ 💀

🎀 RETURN VALUES

upon successful completion, the value 0 is returned 🥳 otherwise the value -1 is returned and the global variable errno is set to indicate the error. classic.

💀 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. it's giving "feature not found, go home" 😭
  • [EINVAL] — the rule or filter passed in inbufp is invalid.
  • [EPERM] — user has insufficient privileges to carry out the requested operation. no keys to the kingdom for you 🙈
  • [E2BIG] — inbufp or outbufp are too large.
  • [ESRCH] — no process matched the provided rule or filter.
  • [ENAMETOOLONG] — the loginclass or jail name specified is too long. bestie that name is a whole paragraph 💀
  • [ERANGE] — the rule amount is outside of the allowable range, or outbufp is too small.
  • [EOPNOTSUPP] — the requested operation is not supported for the given rule or filter.
  • [EFAULT] — inbufp or outbufp refer to invalid addresses.

🔥 SEE ALSO

rctl(8) — go read it, it's the vibe source for all the rule formats up there ⭐

💜 HISTORY

the rctl family of system calls appeared in FreeBSD 9.0. vintage, but make it iconic.

🧚 AUTHORS

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

okay that's the whole page, no cap, every flag and every errno accounted for 💖

and that's a wrap bestie!! this page is from Debian, dated September 14, 2016, and it's the RCTL_ADD_RULE(2) page — slay, go set some resource limits, periodt ✨💅🎀

📦 where this page comes from