CHROOT(2)

✨ chroot(2), fchroot(2) — change root directory ✨

okay bestie so this one's from the System Calls Manual, section 2, and the whole thing ships in the Standard C Library (libc, -lc). buckle up, we're moving the root of the filesystem today 💅

---

🌸 NAME 🌸

chroot, fchroot — change root directory

🎀 LIBRARY 🎀

Standard C Library (libc, -lc) — she's built in, no extra credit needed 💖

---

🦋 SYNOPSIS 🦋

#include <unistd.h>

int
chroot(const char *dirname);

int
fchroot(int fd);

---

✨ DESCRIPTION ✨

so dirname is the address of the pathname of a directory, and it's terminated by an ASCII NUL — classic string behaviour, no notes 🙈. The chroot() system call makes dirname become the root directory, like, the actual starting point for path searches of any pathname that begins with /. very main character energy for a directory ngl 👑

For a directory to become the root directory, a process must have execute (search) access on that directory. no search access, no root, periodt.

⚠️ also lowkey important: chroot() has no effect on the process's current directory. she does not touch it. do not @ me.

This call is restricted to the super-user — unless the security.bsd.unprivileged_chroot sysctl variable is set to 1 and the process has enabled the PROC_NO_NEW_PRIVS_CTL procctl(2). both. it's an and situation, bestie 🫶

Depending on how kern.chroot_allow_open_directories is set, open file descriptors that reference directories will make chroot() fail like this:

• If kern.chroot_allow_open_directories is set to zero, chroot() will always fail with EPERM if there are any directories open. any. at all. 💀
• If kern.chroot_allow_open_directories is set to one — and hey, that's the default — chroot() will fail with EPERM if there are any directories open and the process is already subject to the chroot() system call.
• Any other value for kern.chroot_allow_open_directories will bypass the check for open directories entirely, mimicking the historic insecure behavior of chroot() that's still present on other systems. iykyk, that's the sketchy one 🚩

The fchroot() system call is identical to chroot() except it takes a file descriptor instead of a path. same vibes, different argument ✨

---

💜 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. zero = slay, negative one = check errno, that's the whole deal 🎀

---

🔥 ERRORS 🔥

The chroot() and fchroot() system calls will fail and the root directory will be unchanged if:

• [EPERM] — the effective user ID is not the super-user and the security.bsd.unprivileged_chroot sysctl is 0. sorry bestie, no root for you 🙈
• [EPERM] — the effective user ID is not the super-user and the process has not enabled the PROC_NO_NEW_PRIVS_CTL procctl(2).
• [EPERM] — one or more file descriptors are open directories and the kern.chroot_allow_open_directories sysctl is not set to permit this.
• [EIO] — an I/O error occurred while reading from or writing to the file system. ow 😭
• [EINTEGRITY] — corrupted data was detected while reading from the file system.

The chroot() system call will fail and the root directory will be unchanged if:

• [ENOTDIR] — a component of the path name is not a directory.
• [ENAMETOOLONG] — a component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. that's a Lot of characters 💀
• [ENOENT] — the named directory does not exist. she's not there, girl.
• [EACCES] — search permission is denied for any component of the path name.
• [ELOOP] — too many symbolic links were encountered in translating the pathname. symlink spiral, we've all been there 🌀
• [EFAULT] — the dirname argument points outside the process's allocated address space.

The fchroot() system call will fail and the root directory will be unchanged if:

• [EACCES] — search permission is denied for the directory referenced by the file descriptor.
• [EBADF] — the argument fd is not a valid file descriptor.
• [ENOTDIR] — the file descriptor does not reference a directory.

---

🫶 SEE ALSO 🫶

chdir(2), jail(2)

like yeah go read those too, they're literally the neighbours 💖

---

👑 HISTORY 👑

The chroot() system call appeared in Version 7 AT&T UNIX — ancient. iconic. she's been here a minute 🕰️. It was marked as “legacy” in Version 2 of the Single UNIX Specification (“SUSv2”), and was removed in subsequent standards. rip bozo-ish behaviour, but she's still here 😌. The fchroot() system call first appeared in FreeBSD 15.0. fresh out the box ✨

---

💀 BUGS 💀

okay so this is a weird one: if the process is able to change its working directory to the target directory, but another access control check fails — like a check for open directories, or a MAC check — it is possible that this system call may return an error, with the working directory of the process left changed. so you get a fail and a side effect. rude. 🙈

---

🌈 SECURITY CONSIDERATIONS 🌈

The system has many hardcoded paths to files which it may load after the process starts. so like, it is generally recommended to drop privileges immediately after a successful chroot call, and to restrict write access to a limited subtree of the chroot root. for instance, set up the sandbox so the sandboxed user will have no write access to any well-known system directories. please. for me. 🥺

For complete isolation from the rest of the system, use jail(2) instead. that's the actual final form, no cap 👑

---

💅 that's the whole page bestie, go forth and chroot responsibly 💅

and this little beauty comes to you via Debian, dated April 27, 2026 — mwah, take care of her 🎀🦋💖