1.\" $NetBSD: chroot.2,v 1.23 2010/05/31 12:16:20 njoly Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)chroot.2 8.1 (Berkeley) 6/4/93 31.\" 32.Dd April 18, 2001 33.Dt CHROOT 2 34.Os 35.Sh NAME 36.Nm chroot 37.Nd change root directory 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In unistd.h 42.Ft int 43.Fn chroot "const char *dirname" 44.Ft int 45.Fn fchroot "int fd" 46.Sh DESCRIPTION 47.Fa dirname 48is the address of the pathname of a directory, terminated by an ASCII NUL. 49.Fn chroot 50causes 51.Fa dirname 52to become the root directory, 53that is, the starting point for path searches of pathnames 54beginning with 55.Ql / . 56.Pp 57In order for a directory to become the root directory 58a process must have execute (search) access for that directory. 59.Pp 60If the current working directory is not at or under the new root 61directory, it is silently set to the new root directory. 62It should be noted that, on most other systems, 63.Fn chroot 64has no effect on the process's current directory. 65.Pp 66This call is restricted to the super-user. 67.Pp 68The 69.Fn fchroot 70function performs the same operation on an open directory file 71known by the file descriptor 72.Fa fd . 73.Sh RETURN VALUES 74Upon successful completion, a value of 0 is returned. 75Otherwise, a value of \-1 is returned and 76.Va errno 77is set to indicate an error. 78.Sh ERRORS 79.Fn chroot 80will fail and the root directory will be unchanged if: 81.Bl -tag -width Er 82.It Bq Er ENOTDIR 83A component of the path name is not a directory. 84.It Bq Er ENAMETOOLONG 85A component of a pathname exceeded 86.Brq Dv NAME_MAX 87characters, or an entire path name exceeded 88.Brq Dv PATH_MAX 89characters. 90.It Bq Er ENOENT 91The named directory does not exist. 92.It Bq Er EACCES 93Search permission is denied for any component of the path name. 94.It Bq Er ELOOP 95Too many symbolic links were encountered in translating the pathname. 96.It Bq Er EFAULT 97.Fa dirname 98points outside the process's allocated address space. 99.It Bq Er EIO 100An I/O error occurred while reading from or writing to the file system. 101.It Bq Er EPERM 102The effective user ID of the calling process is not the super-user. 103.El 104.Pp 105.Fn fchroot 106will fail and the root directory will be unchanged if: 107.Bl -tag -width Er 108.It Bq Er EACCES 109Search permission is denied for the directory referenced 110by the file descriptor. 111.It Bq Er EBADF 112The argument 113.Fa fd 114is not a valid file descriptor. 115.It Bq Er EIO 116An I/O error occurred while reading from or writing to the file system. 117.It Bq Er ENOTDIR 118The argument 119.Fa fd 120does not reference a directory. 121.It Bq Er EPERM 122The effective user ID of the calling process is not the super-user. 123.El 124.Sh SEE ALSO 125.Xr chdir 2 126.Sh STANDARDS 127The 128.Fn chroot 129function conforms to 130.St -xsh5 , 131with the restriction that the calling process' working directory must be at 132or under the new root directory. 133Otherwise, the working directory is silently set to the new root directory; 134this is an extension to the standard. 135.Pp 136.Fn chroot 137was declared a legacy interface, and subsequently removed in 138.St -p1003.1-2001 . 139.Sh HISTORY 140The 141.Fn chroot 142function call appeared in 143.Bx 4.2 . 144Working directory handling was changed in 145.Nx 1.4 146to prevent one way a process could use a second 147.Fn chroot 148call to a different directory to "escape" from the restricted subtree. 149The 150.Fn fchroot 151function appeared in 152.Nx 1.4 . 153