chroot(2)

chroot -- change root directory

Synopsis

   #include <unistd.h>
   
   int chroot(const char path);

Description

chroot changes the root directory of the calling process. path points to a pathname naming a directory. chroot causes the named directory to become the root directory, the starting point for path searches for pathnames beginning with /. The user's working directory is unaffected by the chroot system call.

The calling process must have the appropriate privilege (P_FILESYS) to change the root directory.

The .. entry in the root directory is interpreted to mean the root directory itself. Thus, .. cannot be used to access files outside the subtree rooted at the root directory.

Return values

On success, chroot returns 0. On failure, chroot returns -1, sets errno to identify the error, and the root directory remains unchanged.

In the following conditions, chroot fails and sets errno to:

EACCES: Search permission is denied on a component of the pathname.
ELOOP: Too many symbolic links were encountered in translating path.
ENAMETOOLONG: The length of the path argument exceeds {PATH_MAX}, or the length of a path component exceeds {NAME_MAX} while _POSIX_NO_TRUNC is in effect.
EFAULT: path points outside the allocated address space of the process.
EINTR: A signal was caught during the chroot system call.
EMULTIHOP: Components of path require hopping to multiple remote machines and file system type does not allow it.
ENOLINK: path points to a remote machine and the link to that machine is no longer active.
ENOTDIR: Any component of the pathname is not a directory.
ENOENT: The named directory does not exist or is a null pathname.
EPERM: The calling process does not have the appropriate privilege (P_FILESYS) for changing the root directory.

References

chdir(2)

Notices

Considerations for threads programming

Both current working directory and current root directory are process attributes and are shared by all related threads. A change by one thread will be shared by all siblings.