chroot()

Arguments:

path

The name of the new root directory.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The chroot() function causes the path directory to become the root directory, the starting point for path searches for path names beginning with a forward slash (/). It also changes the current working directory to path.

If path starts with three forward slashes (///), the path is interpreted as system absolute instead of relative to the process's current root directory.

The .. entry in the root directory is interpreted to mean the root directory itself. Thus, you can't use .. to access files outside the subtree rooted at the root directory.

For more information, go to chroot (change root) in the QNX OS System Security Guide.

The CHROOT ability

The ability to use chroot is controlled by the CHROOT ability. A process that doesn't have CHROOT ability can't call chroot() to change the root path. CHROOT is a subranged ability that can include (or not include) two possible values:

• 0—a process that has the CHROOT ability with a subrange that includes 0 but not 1 can call chroot() only for paths that are within its current root directory. That is, it can call chroot() multiple times but only to locations that are progressively deeper in the path space.
• 1—if a process has the CHROOT ability with a subrange that includes 1, its use of normal paths (not system-absolute paths indicated by three or more forward slash (/) characters) follows the normal rules of a chrooted process. However, it can also access system-absolute paths with no restrictions. It can call chroot() with a system-absolute path to change its root directory to any path. Chrooting a process that has the CHROOT ability without a subrange, or with a subrange that includes 1, does not add any security.

For more information, go to Abilities in the QNX OS System Security Guide.

Returns:

0

Success.

-1

An error occurred; errno is set.

Errors:

EACCES

Search permission is denied for a component of path.

EINTR

A signal was caught during the chroot() function.

EIO

An I/O error occurred while reading from or writing to the filesystem.

ELOOP

Too many symbolic links were encountered in translating path.

ENAMETOOLONG

The length of the path string exceeds PATH_MAX.

ENOENT

The named directory doesn't exist or is a null pathname.

ENOTDIR

Any component of the path name isn't a directory.

EPERM

The process does not have the CHROOT ability with the required subrange.

Classification:

Legacy Unix