163 lines
3.4 KiB
Groff
163 lines
3.4 KiB
Groff
.\" @(#)chroot.2 1.1 94/10/31 SMI; from UCB 4.3
|
|
.TH CHROOT 2 "21 January 1990"
|
|
.SH NAME
|
|
chroot \- change root directory
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
int chroot(dirname)
|
|
char \(**dirname;
|
|
.LP
|
|
.ft B
|
|
int fchroot(fd)
|
|
int fd;
|
|
.ft R
|
|
.fi
|
|
.IX chroot() "" "\fLchroot()\fP \(em change root directory"
|
|
.IX change "root directory \(em \fLchroot()\fR"
|
|
.IX "root directory, change \(em \fLchroot()\fR"
|
|
.IX directory "change root \(em \fLchroot()\fR"
|
|
.SH DESCRIPTION
|
|
.LP
|
|
.B chroot(\|)
|
|
and
|
|
.B fchroot(\|)
|
|
cause a directory to become the root directory,
|
|
the starting point for path names beginning with
|
|
.RB ` / '.
|
|
The current working directory is unaffected by this call.
|
|
This root directory setting is inherited across
|
|
.BR execve (2V)
|
|
and by all children of this process created with
|
|
.B fork (2V)
|
|
calls.
|
|
.LP
|
|
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
|
|
.SM 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
|
|
.BR lofs (4S)).
|
|
.B 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
|
|
.I fd
|
|
be in all respects valid.
|
|
.LP
|
|
The
|
|
.I dirname
|
|
argument to
|
|
.B chroot(\|)
|
|
points to a path name of a directory. The
|
|
.I fd
|
|
argument to
|
|
.B fchroot(\|)
|
|
is the open file descriptor of the directory which is to become the
|
|
root.
|
|
.LP
|
|
The
|
|
.B .\|.
|
|
entry in the root directory is interpreted to mean the root directory
|
|
itself. Thus,
|
|
.B .\|.
|
|
cannot be used to access files outside the subtree rooted at the root
|
|
directory.
|
|
Instead,
|
|
.B fchroot(\|)
|
|
can be used to set the root back to a directory which was opened before
|
|
the root directory was changed.
|
|
.SH WARNINGS
|
|
.LP
|
|
The only use of
|
|
.B 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.
|
|
.SH RETURN VALUES
|
|
.LP
|
|
.B chroot(\|)
|
|
returns:
|
|
.TP
|
|
0
|
|
on success.
|
|
.TP
|
|
\-1
|
|
on failure and sets
|
|
.B errno
|
|
to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
.B chroot(\|)
|
|
will fail and the root directory will be unchanged if
|
|
one or more of the following are true:
|
|
.TP 20
|
|
.SM EACCES
|
|
Search permission is denied for a component of the path prefix of
|
|
.IR dirname .
|
|
.IP
|
|
Search permission is denied for the directory referred to by
|
|
.IR dirname .
|
|
.TP
|
|
.SM EBADF
|
|
The descriptor is not valid.
|
|
.TP
|
|
.SM EFAULT
|
|
.I dirname
|
|
points outside the process's allocated address space.
|
|
.TP
|
|
.SM EINVAL
|
|
.B fchroot(\|)
|
|
attempted to change to a directory which is not the system root and
|
|
external circumstances, such as auditing, do not allow this.
|
|
.TP
|
|
.SM EIO
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
.TP
|
|
.SM ELOOP
|
|
Too many symbolic links were encountered in translating
|
|
.IR dirname .
|
|
.TP
|
|
.SM ENAMETOOLONG
|
|
The length of the path argument exceeds
|
|
.SM {PATH_MAX}\s0.
|
|
.IP
|
|
A pathname component is longer than
|
|
.SM {NAME_MAX}
|
|
(see
|
|
.BR sysconf (2V))
|
|
while
|
|
.SM {_POSIX_NO_TRUNC}
|
|
is in effect
|
|
(see
|
|
.BR pathconf (2V)).
|
|
.TP
|
|
.SM ENOENT
|
|
The directory referred to by
|
|
.I dirname
|
|
does not exist.
|
|
.br
|
|
.ne 5
|
|
.TP
|
|
.SM ENOTDIR
|
|
A component of the path prefix of
|
|
.I dirname
|
|
is not a directory.
|
|
.IP
|
|
The file referred to by
|
|
.I dirname
|
|
is not a directory.
|
|
.TP
|
|
.SM EPERM
|
|
The effective user
|
|
.SM ID
|
|
is not super-user.
|
|
.SH "SEE ALSO"
|
|
.BR chdir (2V),
|
|
.BR execve (2V),
|
|
.BR fork (2V),
|
|
.BR lofs (4S)
|