NAME

chroot − change root directory

SYNOPSIS

int chroot(dirname)
char ∗dirname;

int fchroot(fd)
int fd;

DESCRIPTION

chroot() and fchroot() cause a directory to become the root directory, the starting point for path names beginning with ‘/’.  The current working directory is unaffected by this call.  This root directory setting is inherited across execve(2V) and by all children of this process created with fork (2V) calls. 

In order for a directory to become the root directory a process must have execute (search) access to the directory and either the effective user ID of the process must be super-user or the target directory must be the system root or a loop-back mount of the system root (see lofs(4S)).  fchroot() is further restricted in that while it is always possible to change to the system root using this call, it is not guaranteed to succeed in any other case, even should fd be in all respects valid. 

The dirname argument to chroot() points to a path name of a directory.  The fd argument to fchroot() is the open file descriptor of the directory which is to become the root. 

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.  Instead, fchroot() can be used to set the root back to a directory which was opened before the root directory was changed. 

WARNINGS

The only use of fchroot() that is appropriate is to change back to the system root.  While it may succeed in some other cases, it is guaranteed to fail if auditing is enabled.  Super-user processes are not exempt from this limitation. 

RETURN VALUES

chroot() returns:

0 on success. 

−1 on failure and sets errno to indicate the error. 

ERRORS

chroot() will fail and the root directory will be unchanged if one or more of the following are true:

EACCES Search permission is denied for a component of the path prefix of dirname.

Search permission is denied for the directory referred to by dirname.

EBADF The descriptor is not valid. 

EFAULT dirname points outside the process’s allocated address space. 

EINVAL fchroot() attempted to change to a directory which is not the system root and external circumstances, such as auditing, do not allow this. 

EIO An I/O error occurred while reading from or writing to the file system. 

ELOOP Too many symbolic links were encountered in translating dirname.

ENAMETOOLONG The length of the path argument exceeds {PATH_MAX}. 

A pathname component is longer than {NAME_MAX} (see sysconf(2V)) while {_POSIX_NO_TRUNC} is in effect (see pathconf(2V)). 

ENOENT The directory referred to by dirname does not exist. 

ENOTDIR A component of the path prefix of dirname is not a directory. 

The file referred to by dirname is not a directory. 

EPERM The effective user ID is not super-user. 

SEE ALSO

chdir(2V), execve(2V), fork(2V), lofs(4S)

Sun Release 4.1  —  Last change: 21 January 1990