]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2000 by Werner Almesberger |
2297bf0e | 2 | .\" |
b55e2bb3 | 3 | .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
fea681da | 4 | .\" May be distributed under GPL |
b55e2bb3 | 5 | .\" %%%LICENSE_END |
fea681da MK |
6 | .\" |
7 | .\" Written 2000-02-23 by Werner Almesberger | |
c11b1abf | 8 | .\" Modified 2004-06-17 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 9 | .\" |
4b8c67d9 | 10 | .TH PIVOT_ROOT 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 11 | .SH NAME |
9ee4a2b6 | 12 | pivot_root \- change the root filesystem |
fea681da | 13 | .SH SYNOPSIS |
fea681da | 14 | .BI "int pivot_root(const char *" new_root ", const char *" put_old ); |
dbfe9c70 | 15 | .PP |
45c99e3e MK |
16 | .IR Note : |
17 | There is no glibc wrapper for this system call; see NOTES. | |
fea681da | 18 | .SH DESCRIPTION |
60a90ecd | 19 | .BR pivot_root () |
9ee4a2b6 MK |
20 | moves the root filesystem of the calling process to the |
21 | directory \fIput_old\fP and makes \fInew_root\fP the new root filesystem | |
edd1fa35 | 22 | of the calling process. |
fea681da MK |
23 | .\" |
24 | .\" The | |
25 | .\" .B CAP_SYS_ADMIN | |
26 | .\" capability is required. | |
efeece04 | 27 | .PP |
60a90ecd MK |
28 | The typical use of |
29 | .BR pivot_root () | |
30 | is during system startup, when the | |
9ee4a2b6 MK |
31 | system mounts a temporary root filesystem (e.g., an \fBinitrd\fP), then |
32 | mounts the real root filesystem, and eventually turns the latter into | |
fea681da | 33 | the current root of all relevant processes or threads. |
efeece04 | 34 | .PP |
60a90ecd MK |
35 | .BR pivot_root () |
36 | may or may not change the current root and the current | |
edd1fa35 | 37 | working directory of any processes or threads which use the old |
c13182ef | 38 | root directory. |
60a90ecd MK |
39 | The caller of |
40 | .BR pivot_root () | |
edd1fa35 MK |
41 | must ensure that processes with root or current working directory |
42 | at the old root operate correctly in either case. | |
c13182ef | 43 | An easy way to ensure this is to change their |
edd1fa35 | 44 | root and current working directory to \fInew_root\fP before invoking |
60a90ecd | 45 | .BR pivot_root (). |
efeece04 | 46 | .PP |
c33144e6 | 47 | The paragraph above is intentionally vague because the implementation of |
60a90ecd MK |
48 | .BR pivot_root () |
49 | may change in the future. | |
c13182ef | 50 | At the time of writing, |
60a90ecd | 51 | .BR pivot_root () |
edd1fa35 | 52 | changes root and current working directory of each process or |
c13182ef | 53 | thread to \fInew_root\fP if they point to the old root directory. |
c33144e6 | 54 | This is necessary in order to prevent kernel threads from keeping the old |
edd1fa35 MK |
55 | root directory busy with their root and current working directory, |
56 | even if they never access | |
9ee4a2b6 | 57 | the filesystem in any way. |
c13182ef | 58 | In the future, there may be a mechanism for |
9ee4a2b6 | 59 | kernel threads to explicitly relinquish any access to the filesystem, |
fea681da | 60 | such that this fairly intrusive mechanism can be removed from |
60a90ecd | 61 | .BR pivot_root (). |
efeece04 | 62 | .PP |
edd1fa35 | 63 | Note that this also applies to the calling process: |
60a90ecd | 64 | .BR pivot_root () |
c33144e6 | 65 | may or may not affect its current working directory. |
c13182ef | 66 | It is therefore recommended to call |
60a90ecd MK |
67 | \fBchdir("/")\fP immediately after |
68 | .BR pivot_root (). | |
efeece04 | 69 | .PP |
fea681da MK |
70 | The following restrictions apply to \fInew_root\fP and \fIput_old\fP: |
71 | .IP \- 3 | |
72 | They must be directories. | |
73 | .IP \- 3 | |
9ee4a2b6 | 74 | \fInew_root\fP and \fIput_old\fP must not be on the same filesystem as |
fea681da MK |
75 | the current root. |
76 | .IP \- 3 | |
c7094399 | 77 | \fIput_old\fP must be underneath \fInew_root\fP, that is, adding a nonzero |
8478ee02 | 78 | number of \fI/..\fP to the string pointed to by \fIput_old\fP must yield |
fea681da MK |
79 | the same directory as \fInew_root\fP. |
80 | .IP \- 3 | |
9ee4a2b6 | 81 | No other filesystem may be mounted on \fIput_old\fP. |
fea681da | 82 | .PP |
988db661 | 83 | See also |
60a90ecd MK |
84 | .BR pivot_root (8) |
85 | for additional usage examples. | |
efeece04 | 86 | .PP |
75b94dc3 | 87 | If the current root is not a mount point (e.g., after |
60a90ecd MK |
88 | .BR chroot (2) |
89 | or | |
90 | .BR pivot_root (), | |
91 | see also below), not the old root directory, but the | |
9ee4a2b6 | 92 | mount point of that filesystem is mounted on \fIput_old\fP. |
efeece04 | 93 | .PP |
c13182ef MK |
94 | \fInew_root\fP does not have to be a mount point. |
95 | In this case, | |
9ee4a2b6 | 96 | \fI/proc/mounts\fP will show the mount point of the filesystem containing |
8478ee02 | 97 | \fInew_root\fP as root (\fI/\fP). |
47297adb | 98 | .SH RETURN VALUE |
c13182ef MK |
99 | On success, zero is returned. |
100 | On error, \-1 is returned, and | |
fea681da MK |
101 | \fIerrno\fP is set appropriately. |
102 | .SH ERRORS | |
60a90ecd MK |
103 | .BR pivot_root () |
104 | may return (in \fIerrno\fP) any of the errors returned by | |
105 | .BR stat (2). | |
c13182ef | 106 | Additionally, it may return: |
fea681da MK |
107 | .TP |
108 | .B EBUSY | |
9ee4a2b6 MK |
109 | \fInew_root\fP or \fIput_old\fP are on the current root filesystem, |
110 | or a filesystem is already mounted on \fIput_old\fP. | |
fea681da MK |
111 | .TP |
112 | .B EINVAL | |
113 | \fIput_old\fP is not underneath \fInew_root\fP. | |
114 | .TP | |
dc9b6c92 JS |
115 | .B EINVAL |
116 | The current root is on the rootfs (initial ramfs) filesystem. | |
117 | .TP | |
fea681da MK |
118 | .B ENOTDIR |
119 | \fInew_root\fP or \fIput_old\fP is not a directory. | |
120 | .TP | |
121 | .B EPERM | |
edd1fa35 | 122 | The calling process does not have the |
fea681da MK |
123 | .B CAP_SYS_ADMIN |
124 | capability. | |
a1d5f77c MK |
125 | .SH VERSIONS |
126 | .BR pivot_root () | |
127 | was introduced in Linux 2.3.41. | |
47297adb | 128 | .SH CONFORMING TO |
a1d5f77c | 129 | .BR pivot_root () |
8382f16d | 130 | is Linux-specific and hence is not portable. |
f5b03186 MK |
131 | .SH NOTES |
132 | Glibc does not provide a wrapper for this system call; call it using | |
133 | .BR syscall (2). | |
82320f42 EK |
134 | .PP |
135 | The rootfs (initial ramfs) cannot be | |
136 | .BR pivot_root ()ed. | |
52fc743c MK |
137 | The recommended method of changing the root filesystem in this case is |
138 | to delete everything in rootfs, overmount rootfs with the new root, attach | |
82320f42 EK |
139 | .IR stdin / stdout / stderr |
140 | to the new | |
141 | .IR /dev/console , | |
52fc743c MK |
142 | and exec the new |
143 | .BR init (1). | |
144 | Helper programs for this process exist; see | |
82320f42 | 145 | .BR switch_root (8). |
fea681da | 146 | .SH BUGS |
60a90ecd | 147 | .BR pivot_root () |
edd1fa35 | 148 | should not have to change root and current working directory of all other |
fea681da | 149 | processes in the system. |
efeece04 | 150 | .PP |
60a90ecd MK |
151 | Some of the more obscure uses of |
152 | .BR pivot_root () | |
153 | may quickly lead to | |
fea681da | 154 | insanity. |
47297adb | 155 | .SH SEE ALSO |
fea681da MK |
156 | .BR chdir (2), |
157 | .BR chroot (2), | |
158 | .BR stat (2), | |
159 | .BR initrd (4), | |
b2bced6d MK |
160 | .BR pivot_root (8), |
161 | .BR switch_root (8) |