chroot Subroutine

Purpose

Changes the effective root directory.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

Description

The chroot subroutine causes the directory named by the Path parameter to become the effective root directory. If the Path parameter refers to a symbolic link, the chroot subroutine sets the effective root directory to the directory pointed to by the symbolic link. If Network File System (NFS) is installed on your system, this path can cross into another node.

The effective root directory is the starting point when searching for a file's path name that begins with / (slash). The current directory is not affected by the chroot subroutine.

The calling process must have root user authority in order to change the effective root directory. The calling process must also have search access to the new effective root directory.

The .. (double period) entry in the effective root directory is interpreted to mean the effective root directory itself. Thus, this directory cannot be used to access files outside the subtree rooted at the effective root directory.

Parameters

Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The chroot subroutine fails and the effective root directory remains unchanged if one or more of the following are true:

The chroot subroutine can be unsuccessful for other reasons. See Appendix A. Base Operating System Error Codes for Services that Require Path-Name Resolution for a list of additional errors.

If NFS is installed on the system, the chroot subroutine can also fail if the following is true: