RIGHTS(4)

💅 RIGHTS(4) — Capability rights, bestie 💅

🌸 NAME 🌸

Capability rights — the Capsicum capability rights situation for file descriptors, and yes bestie this is the whole vibe.

---

✨ DESCRIPTION ✨

Okay so when a file descriptor gets created by a function like fhopen(2), kqueue(2), mq_open(2), open(2), pdfork(2), pipe(2), shm_open(2), socket(2) or socketpair(2), it starts out with all the capability rights. And for accept(2), accept4(2) or openat(2), it inherits capability rights from the “parent” file descriptor. Iconic inheritance behavior, honestly.

Those rights can be reduced — but never expanded, no cap — by using the cap_rights_limit(2), cap_fcntls_limit(2) and cap_ioctls_limit(2) system calls. Once the capability rights are reduced, operations on the file descriptor are limited to those permitted by rights. That’s the whole point, periodt.

The complete list of capability rights is below. The cap_rights_t type stores the list of capability rights. The cap_rights_init(3) family of functions should be used to manage the structure. Use the right tools for the job, babes.

🦋 RIGHTS 🦋

Heads up: rights are not simple bitmasks, and they cannot be bitwise-ORed together. Not me warning you again. See cap_rights_init(3) for the details.

The following rights are available:

• CAP_ACCEPT — Lets accept(2) and accept4(2) happen.
• CAP_ACL_CHECK — Lets acl_valid_fd_np(3) happen.
• CAP_ACL_DELETE — Lets acl_delete_fd_np(3) happen.
• CAP_ACL_GET — Lets acl_get_fd(3) and acl_get_fd_np(3) happen.
• CAP_ACL_SET — Lets acl_set_fd(3) and acl_set_fd_np(3) happen.
• CAP_BIND — When you’re not in capabilities mode, lets bind(2) and bindat(2) work with the special value AT_FDCWD in the fd parameter. Also note that sockets can become bound implicitly as a result of connect(2) or send(2), and socket options set with setsockopt(2) may also affect binding behavior. Sneaky little binding behavior, but okay.
• CAP_BINDAT — Lets bindat(2) happen. This right has to be present on the directory descriptor. This right includes the CAP_LOOKUP right.
• CAP_CHFLAGSAT — An alias to CAP_FCHFLAGS and CAP_LOOKUP.
• CAP_CONNECT — When you’re not in capabilities mode, lets connect(2) and connectat(2) work with the special value AT_FDCWD in the fd parameter. This right is also required for sendto(2) with a non-NULL destination address. Very “you need me for that too” energy.
• CAP_CONNECTAT — Lets connectat(2) happen. This right has to be present on the directory descriptor. This right includes the CAP_LOOKUP right.
• CAP_CREATE — Lets openat(2) use the O_CREAT flag.
• CAP_EVENT — Lets select(2), poll(2), and kevent(2) be used to monitor the file descriptor for events. Event-watching rights, slay.
• CAP_EXTATTR_DELETE — Lets extattr_delete_fd(2) happen.
• CAP_EXTATTR_GET — Lets extattr_get_fd(2) happen.
• CAP_EXTATTR_LIST — Lets extattr_list_fd(2) happen.
• CAP_EXTATTR_SET — Lets extattr_set_fd(2) happen.
• CAP_FCHDIR — Lets fchdir(2) happen.
• CAP_FCHFLAGS — Lets fchflags(2) and chflagsat(2) happen if the CAP_LOOKUP right is also present.
• CAP_FCHMOD — Lets fchmod(2) and fchmodat(2) happen if the CAP_LOOKUP right is also present.
• CAP_FCHMODAT — An alias to CAP_FCHMOD and CAP_LOOKUP.
• CAP_FCHOWN — Lets fchown(2) and fchownat(2) happen if the CAP_LOOKUP right is also present.
• CAP_FCHOWNAT — An alias to CAP_FCHOWN and CAP_LOOKUP.
• CAP_FCHROOT — Lets fchroot(2) happen.
• CAP_FCNTL — Lets fcntl(2) happen. Note that only the F_GETFL, F_SETFL, F_GETOWN and F_SETOWN commands require this capability right. Also note that the list of permitted commands can be further limited with the cap_fcntls_limit(2) system call.
• CAP_FEXECVE — Lets fexecve(2) and openat(2) use the O_EXEC flag; CAP_READ is also required. Teamwork makes the dream work.
• CAP_FLOCK — Lets flock(2), fcntl(2) (with F_GETLK, F_SETLK, F_SETLKW or F_SETLK_REMOTE flag) and openat(2) (with O_EXLOCK or O_SHLOCK flag) happen.
• CAP_FPATHCONF — Lets fpathconf(2) happen.
• CAP_FSCK — Lets UFS background-fsck operations happen on the descriptor.
• CAP_FSTAT — Lets fstat(2) and fstatat(2) happen if the CAP_LOOKUP right is also present.
• CAP_FSTATAT — An alias to CAP_FSTAT and CAP_LOOKUP.
• CAP_FSTATFS — Lets fstatfs(2) happen.
• CAP_FSYNC — Lets aio_fsync(2), fdatasync(2), fsync(2) and openat(2) with the O_DSYNC, O_FSYNC, or O_SYNC flag happen.
• CAP_FTRUNCATE — Lets ftruncate(2) and openat(2) with the O_TRUNC flag happen.
• CAP_FUTIMES — Lets futimens(2) and futimes(2) happen, and lets futimesat(2) and utimensat(2) happen if the CAP_LOOKUP right is also present.
• CAP_FUTIMESAT — An alias to CAP_FUTIMES and CAP_LOOKUP.
• CAP_GETPEERNAME — Lets getpeername(2) happen.
• CAP_GETSOCKNAME — Lets getsockname(2) happen.
• CAP_GETSOCKOPT — Lets getsockopt(2) happen.
• CAP_INOTIFY_ADD — Lets inotify_add_watch(2) and inotify_add_watch_at(2) happen.
• CAP_INOTIFY_RM — Lets inotify_rm_watch(2) happen.
• CAP_IOCTL — Lets ioctl(2) happen. Be aware that this system call has enormous scope, including potentially global scope for some objects. The list of permitted ioctl commands can be further limited with the cap_ioctls_limit(2) system call. Huge scope, handle with care, bestie.
• CAP_KQUEUE — An alias to CAP_KQUEUE_CHANGE and CAP_KQUEUE_EVENT.
• CAP_KQUEUE_CHANGE — Lets kevent(2) happen on a kqueue(2) descriptor that modifies the list of monitored events (the changelist argument is non-NULL).
• CAP_KQUEUE_EVENT — Lets kevent(2) happen on a kqueue(2) descriptor that monitors events (the eventlist argument is non-NULL). CAP_EVENT is also required on file descriptors that will be monitored using kevent(2). Yes, both. It’s giving teamwork.
• CAP_LINKAT_SOURCE — Lets linkat(2) happen on the source directory descriptor. This right includes the CAP_LOOKUP right.

Warning: CAP_LINKAT_SOURCE makes it possible to link files in a directory for which file descriptors exist that have additional rights. For example, a file stored in a directory that does not allow CAP_READ may be linked in another directory that does allow CAP_READ, thereby granting read access to a file that is otherwise unreadable. That’s not a cute little loophole, that’s a real warning.

• CAP_LINKAT_TARGET — Lets linkat(2) happen on the target directory descriptor. This right includes the CAP_LOOKUP right.
• CAP_LISTEN — Lets listen(2) happen; not much use (generally) without CAP_BIND.
• CAP_LOOKUP — Lets the file descriptor be used as a starting directory for calls such as linkat(2), openat(2), and unlinkat(2).
• CAP_MAC_GET — Lets mac_get_fd(3) happen.
• CAP_MAC_SET — Lets mac_set_fd(3) happen.
• CAP_MKDIRAT — Lets mkdirat(2) happen. This right includes the CAP_LOOKUP right.
• CAP_MKFIFOAT — Lets mkfifoat(2) happen. This right includes the CAP_LOOKUP right.
• CAP_MKNODAT — Lets mknodat(2) happen. This right includes the CAP_LOOKUP right.
• CAP_MMAP — Lets mmap(2) happen with the PROT_NONE protection.
• CAP_MMAP_R — Lets mmap(2) happen with the PROT_READ protection. This right includes the CAP_READ and CAP_SEEK rights.
• CAP_MMAP_RW — An alias to CAP_MMAP_R and CAP_MMAP_W.
• CAP_MMAP_RWX — An alias to CAP_MMAP_R, CAP_MMAP_W and CAP_MMAP_X.
• CAP_MMAP_RX — An alias to CAP_MMAP_R and CAP_MMAP_X.
• CAP_MMAP_W — Lets mmap(2) happen with the PROT_WRITE protection. This right includes the CAP_WRITE and CAP_SEEK rights.
• CAP_MMAP_WX — An alias to CAP_MMAP_W and CAP_MMAP_X.
• CAP_MMAP_X — Lets mmap(2) happen with the PROT_EXEC protection. This right includes the CAP_SEEK right.
• CAP_PDGETPID — Lets pdgetpid(2) happen.
• CAP_PDKILL — Lets pdkill(2) happen.
• CAP_PDWAIT — Lets pdwait(2) happen.
• CAP_PEELOFF — Lets sctp_peeloff(2) happen.
• CAP_PREAD — An alias to CAP_READ and CAP_SEEK.
• CAP_PWRITE — An alias to CAP_SEEK and CAP_WRITE.
• CAP_READ — Lets aio_read(2) happen (CAP_SEEK is also required), lets openat(2) use the O_RDONLY flag, and lets read(2), readv(2), recv(2), recvfrom(2), recvmsg(2), pread(2) (CAP_SEEK is also required), preadv(2) (CAP_SEEK is also required), getdents(2), getdirentries(2), and related system calls happen. A whole little read squad.
• CAP_RECV — An alias to CAP_READ.
• CAP_RENAMEAT_SOURCE — Lets renameat(2) happen on the source directory descriptor. This right includes the CAP_LOOKUP right.

Warning: CAP_RENAMEAT_SOURCE makes it possible to move files to a directory for which file descriptors exist that have additional rights. For example, a file stored in a directory that does not allow CAP_READ may be moved to another directory that does allow CAP_READ, thereby granting read access to a file that is otherwise unreadable. Again: real warning, not just drama.

• CAP_RENAMEAT_TARGET — Lets renameat(2) happen on the target directory descriptor. This right includes the CAP_LOOKUP right.
• CAP_SEEK — Lets operations that seek on the file descriptor happen, such as lseek(2), but it’s also required for I/O system calls that can read or write at any position in the file, such as pread(2) and pwrite(2).
• CAP_SEM_GETVALUE — Lets sem_getvalue(3) happen.
• CAP_SEM_POST — Lets sem_post(3) happen.
• CAP_SEM_WAIT — Lets sem_wait(3) and sem_trywait(3) happen.
• CAP_SEND — An alias to CAP_WRITE.
• CAP_SETSOCKOPT — Lets setsockopt(2) happen; this controls various aspects of socket behavior and may affect binding, connecting, and other behaviors with global scope.
• CAP_SHUTDOWN — Lets explicit shutdown(2) happen; closing the socket will also generally shut down any connections on it.
• CAP_SYMLINKAT — the green light for symlinkat(2) 🔗✨ and ngl it comes bundled with the CAP_LOOKUP right, so you get lookups too. package deal, bestie 🎀
• CAP_TTYHOOK — lets you configure TTY hooks on that file descriptor, like snp(4) 👀 which is very much a "with great power" situation, so use it responsibly 💅
• CAP_UNLINKAT — permission slip for unlinkat(2) and renameat(2) 🗑️ but here's the nuance: you only need this right for renameat(2) on the destination directory descriptor if the destination object already exists and is gonna get removed by the rename. tiny detail, huge difference, iykyk. aaaand it includes the CAP_LOOKUP right too 🫶
• CAP_WRITE — the big one, the main character 👑 this lets through aio_write(2), openat(2) with the O_WRONLY and O_APPEND flags set, send(2), sendmsg(2), sendto(2), write(2), writev(2), pwrite(2), pwritev(2) and all their related system calls 🔥 but bestie, the fine print is fine:
  • for sendto(2) with a non-NULL connection address, you also need CAP_CONNECT 📡
  • for openat(2) with the O_WRONLY flag but without the O_APPEND or O_TRUNC flag, you also need CAP_SEEK 🎯
  • for aio_write(2), pwrite(2) and pwritev(2), CAP_SEEK is also required 🌀

---

✨ SEE ALSO ✨

okay so this is the friend group 💖 like, the whole extended roster, no cap:

accept(2), accept4(2), aio_fsync(2), aio_read(2), aio_write(2), bind(2), bindat(2), cap_enter(2), cap_fcntls_limit(2), cap_ioctls_limit(2), cap_rights_limit(2), chflagsat(2), connect(2), connectat(2), extattr_delete_fd(2), extattr_get_fd(2), extattr_list_fd(2), extattr_set_fd(2), fchflags(2), fchmod(2), fchmodat(2), fchown(2), fchownat(2), fcntl(2), fexecve(2), fhopen(2), flock(2), fpathconf(2), fstat(2), fstatat(2), fstatfs(2), fsync(2), ftruncate(2), futimes(2), getdents(2), getdirentries(2), getpeername(2), getsockname(2), getsockopt(2), ioctl(2), kevent(2), kqueue(2), linkat(2), listen(2), mmap(2), mq_open(2), open(2), openat(2),

pdfork(2), pdgetpid(2), pdkill(2), pdwait4(2), pipe(2), poll(2), pread(2), preadv(2), pwrite(2), pwritev(2), read(2), readv(2), recv(2), recvfrom(2), recvmsg(2), renameat(2), sctp_peeloff(2), select(2), send(2), sendmsg(2), sendto(2), setsockopt(2), shm_open(2), shutdown(2), socket(2), socketpair(2), symlinkat(2), unlinkat(2), write(2), writev(2),

acl_delete_fd_np(3), acl_get_fd(3), acl_get_fd_np(3), acl_set_fd(3), acl_set_fd_np(3), acl_valid_fd_np(3), mac_get_fd(3), mac_set_fd(3), sem_getvalue(3), sem_post(3), sem_trywait(3), sem_wait(3), capsicum(4), snp(4)

like, that's the whole group chat, go say hi 🦋

---

🌸 HISTORY 🌸

so basically, support for capabilities and capabilities mode was developed as part of the TrustedBSD Project 🧚 a little origin story, we love to see it ✨

---

💜 AUTHORS 💜

this manual page was created by Pawel Jakub Dawidek <pawel@dawidek.net> 🫶 under sponsorship from the FreeBSD Foundation, based on the cap_new(2) manual page by Robert Watson <rwatson@FreeBSD.org> — collaborative queen behavior, honestly 👑

---

and that's a wrap on rights(4), bestie!! 🎀 this lil beauty comes to you from Debian, dated May 22, 2025 — go forth and gate those file descriptors responsibly, mwah 💋💅✨