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(2) and by all children of this process created with fork(2) 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. 

WARNING

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 VALUE

Upon successful completion, a value of 0 is returned.  Otherwise, a value of −1 is returned and errno is set to indicate an error. 

ERRORS

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

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

ENOTDIR The file referred to by dirname is not a directory. 

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

ENAMETOOLONG The length of a component of dirname exceeds 255 characters, or the length of dirname exceeds 1023 characters. 

ENOENT The directory referred to by dirname does not exist. 

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

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

ELOOP Too many symbolic links were encountered in translating dirname.

EPERM The effective user ID is not super-user. 

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

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

EBADF The descriptor is not valid. 

SEE ALSO

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

Sun Release 4.0  —  Last change: 20 November 1987