1chroot(2)                        System Calls                        chroot(2)
2
3
4

NAME

6       chroot, fchroot - change root directory
7

SYNOPSIS

9       #include <unistd.h>
10
11       int chroot(const char *path);
12
13
14       int fchroot(int fildes);
15
16

DESCRIPTION

18       The  chroot()  and  fchroot() functions cause a directory to become the
19       root directory, the starting point for path  searches  for  path  names
20       beginning with / (slash). The user's working directory is unaffected by
21       the chroot() and fchroot() functions.
22
23
24       The path argument points to a path name naming a directory. The  fildes
25       argument  to  fchroot()  is  the  open file descriptor of the directory
26       which is to become the root.
27
28
29       The privilege {PRIV_PROC_CHROOT} must be asserted in the effective  set
30       of  the process to change the root directory. While it is always possi‐
31       ble to change to the system root using the fchroot()  function,  it  is
32       not guaranteed to succeed in any other case, even if fildes is valid in
33       all respects.
34
35
36       The ".." entry in the root directory is interpreted to  mean  the  root
37       directory  itself.  Therefore, ".." cannot be used to access files out‐
38       side the subtree rooted at the root directory. Instead,  fchroot()  can
39       be  used  to  reset  the root to a directory that was opened before the
40       root directory was changed.
41

RETURN VALUES

43       Upon successful completion, 0 is returned. Otherwise, −1  is  returned,
44       the  root directory remains unchanged, and errno is set to indicate the
45       error.
46

ERRORS

48       The chroot() function will fail if:
49
50       EACCES          Search permission is denied for a component of the path
51                       prefix  of  dirname, or search permission is denied for
52                       the directory referred to by dirname.
53
54
55       EBADF           The descriptor is not valid.
56
57
58       EFAULT          The path argument points to an illegal address.
59
60
61       EINVAL          The fchroot() function attempted to change to a  direc‐
62                       tory  the  is  not the system root and external circum‐
63                       stances do not allow this.
64
65
66       EINTR           A  signal  was  caught  during  the  execution  of  the
67                       chroot() function.
68
69
70       EIO             An  I/O error occurred while reading from or writing to
71                       the file system.
72
73
74       ELOOP           Too many symbolic links were encountered in translating
75                       path.
76
77
78       ENAMETOOLONG    The  length  of  the path argument exceeds PATH_MAX, or
79                       the length of a path component exceeds  NAME_MAX  while
80                       _POSIX_NO_TRUNC is in effect.
81
82
83       ENOENT          The  named  directory does not exist or is a null path‐
84                       name.
85
86
87       ENOLINK         The path argument points to a remote  machine  and  the
88                       link to that machine is no longer active.
89
90
91       ENOTDIR         Any component of the path name is not a directory.
92
93
94       EPERM           The {PRIV_PROC_CHROOT} privilege is not asserted in the
95                       effective set of the calling process.
96
97

SEE ALSO

99       chroot(1M), chdir(2), privileges(5)
100

WARNINGS

102       The only use of fchroot() that is appropriate is to change back to  the
103       system root.
104
105
106
107SunOS 5.11                        20 Jan 2003                        chroot(2)