CAP_IOCTLS_LIMIT(2)

💅 CAP_IOCTLS_LIMIT(2) — the System Calls Manual one, bestie

okay so. you're in the System Calls Manual section of the CAP_IOCTLS_LIMIT(2) page and we're about to talk about cap_ioctls_limit and cap_ioctls_get, which are literally the bouncers for your ioctl commands. no cap. 🎀

---

✨ NAME ✨

cap_ioctls_limit, cap_ioctls_get — manage allowed ioctl commands

📚 LIBRARY 📚

Standard C Library (libc, -lc) 🫶

🦋 SYNOPSIS 🦋

#include <sys/capsicum.h>

int
cap_ioctls_limit(int fd, const unsigned long *cmds, size_t ncmds);

ssize_t
cap_ioctls_get(int fd, unsigned long *cmds, size_t maxcmds);

🌸 DESCRIPTION 🌸

so here's the tea. if a file descriptor has been granted the CAP_IOCTL capability right, you can selectively reduce the list of allowed ioctl(2) commands with the cap_ioctls_limit() system call. and when I say reduce, I mean reduce — you can never expand it back. that's the whole point, bestie, it's a one-way door. 🚪

• the cmds argument? that's an array of ioctl(2) commands.
• the ncmds argument? that's how many elements are chillin' in that array.
• there can be up to 256 elements in the array, periodt.
• and including an element that has been previously revoked will generate an error. do not try it. 🙈

after a successful call, only those commands listed in the array may be used. that's it, that's the list, that's the vibe check. ✨

---

now, the flip side: the list of allowed ioctl commands for a given file descriptor can be obtained with the cap_ioctls_get() system call. 👑

• cmds points at memory that can hold up to maxcmds values.
• the function populates the provided buffer with up to maxcmds elements, but always returns the total number of ioctl commands allowed for the given file descriptor. the way it gives you the full count even when it can't fit them all?? iconic.
• wanna just get the total number of ioctl commands for the given file descriptor? easy. pass NULL as the cmds argument and 0 as the maxcmds argument. 💅
• and if all ioctl commands are allowed (meaning the CAP_IOCTL capability right is assigned to the file descriptor and the cap_ioctls_limit() system call was never called for this file descriptor), then cap_ioctls_get() will return CAP_IOCTLS_ALL and will not modify the buffer pointed to by the cmds argument. hands off the buffer, she said. 🫶

🔥 RETURN VALUES 🔥

cap_ioctls_limit() returns the value 0 if successful — slay. otherwise the value -1 is returned and the global variable errno is set to indicate the error. 😭

cap_ioctls_get(), if successful, returns the total number of allowed ioctl commands, or the value CAP_IOCTLS_ALL if all ioctls commands are allowed. on failure the value -1 is returned and the global variable errno is set to indicate the error. it's giving success or chaos, nothing in between.

💀 ERRORS 💀

cap_ioctls_limit() succeeds unless:

• [EBADF] — the fd argument is not a valid descriptor.
• [EFAULT] — the cmds argument points at an invalid address.
• [EINVAL] — the ncmds argument is greater than 256.
• [ENOTCAPABLE] — cmds would expand the list of allowed ioctl(2) commands. (rude of you to even try, honestly.)

cap_ioctls_get() succeeds unless:

• [EBADF] — the fd argument is not a valid descriptor.
• [EFAULT] — the cmds argument points at invalid address.

👀 SEE ALSO 👀

cap_fcntls_limit(2), cap_rights_limit(2), ioctl(2)

📜 HISTORY 📜

The cap_ioctls_get() and cap_ioctls_limit() system calls first appeared in FreeBSD 8.3. support for capabilities and capabilities mode was developed as part of the TrustedBSD Project. history really said "let there be sandboxing." 🌈

👑 AUTHORS 👑

This function was created by Pawel Jakub Dawidek <pawel@dawidek.net> under sponsorship of the FreeBSD Foundation. we love a sponsored icon. 💖

---

and that's the whole page, bestie!! this one's from the Debian build of the page, dated May 5, 2020, and yes it lives under the name CAP_IOCTLS_LIMIT(2). go forth and limit those ioctls responsibly 🎀✨🦋