| .TH PIVOT_ROOT 2 "Feb 23, 2000" "Linux" "System Calls" |
| .SH NAME |
| pivot_root \- change the root file system |
| .SH SYNOPSIS |
| .B #include <linux/unistd.h> |
| .sp |
| .B _syscall2(int,pivot_root,const char *,new_root,const char *,put_old) |
| .sp |
| .BI "int pivot_root(const char *" new_root ", const char *" put_old ); |
| .SH DESCRIPTION |
| \fBpivot_root\fP moves the root file system of the current process to the |
| directory \fIput_old\fP and makes \fInew_root\fP the new root file system |
| of the current process. |
| |
| The typical use of \fBpivot_root\fP is during system startup, when the |
| system mounts a temporary root file system (e.g. an \fBinitrd\fP), then |
| mounts the real root file system, and eventually turns the latter into |
| the current root of all relevant processes or threads. |
| |
| \fBpivot_root\fP may or may not change the current root and the current |
| working directory (cwd) of any processes or threads which use the old |
| root directory. The caller of \fBpivot_root\fP |
| must ensure that processes with root or cwd at the old root operate |
| correctly in either case. An easy way to ensure this is to change their |
| root and cwd to \fInew_root\fP before invoking \fBpivot_root\fP. |
| |
| The paragraph above is intentionally vague because the implementation |
| of \fBpivot_root\fP may change in the future. At the time of writing, |
| \fBpivot_root\fP changes root and cwd of each process or |
| thread to \fInew_root\fP if they point to the old root directory. This |
| is necessary in order to prevent kernel threads from keeping the old |
| root directory busy with their root and cwd, even if they never access |
| the file system in any way. In the future, there may be a mechanism for |
| kernel threads to explicitly relinquish any access to the file system, |
| such that this fairly intrusive mechanism can be removed from |
| \fBpivot_root\fP. |
| |
| Note that this also applies to the current process: \fBpivot_root\fP may |
| or may not affect its cwd. It is therefore recommended to call |
| \fBchdir("/")\fP immediately after \fBpivot_root\fP. |
| |
| The following restrictions apply to \fInew_root\fP and \fIput_old\fP: |
| .IP \- 3 |
| They must be directories. |
| .IP \- 3 |
| \fInew_root\fP and \fIput_old\fP must not be on the same file system as |
| the current root. |
| .IP \- 3 |
| \fIput_old\fP must be underneath \fInew_root\fP, i.e. adding a non-zero |
| number of \fB/..\fP to the string pointed to by \fIput_old\fP must yield |
| the same directory as \fInew_root\fP. |
| .IP \- 3 |
| No other file system may be mounted on \fIput_old\fP. |
| .PP |
| See also \fBpivot_root(8)\fP for additional usage examples. |
| |
| If the current root is not a mount point (e.g. after \fBchroot(2)\fP or |
| \fBpivot_root\fP, see also below), not the old root directory, but the |
| mount point of that file system is mounted on \fIput_old\fP. |
| .SH NOTES |
| \fInew_root\fP does not have to be a mount point. In this case, |
| \fB/proc/mounts\fP will show the mount point of the file system containing |
| \fInew_root\fP as root (\fB/\fP). |
| .SH "RETURN VALUE" |
| On success, zero is returned. On error, \-1 is returned, and |
| \fIerrno\fP is set appropriately. |
| .SH ERRORS |
| \fBpivot_root\fP may return (in \fIerrno\fP) any of the errors returned by |
| \fBstat(2)\fP. Additionally, it may return: |
| |
| .TP |
| .B EBUSY |
| \fInew_root\fP or \fIput_old\fP are on the current root file system, |
| or a file system is already mounted on \fIput_old\fP. |
| .TP |
| .B EINVAL |
| \fIput_old\fP is not underneath \fInew_root\fP. |
| .TP |
| .B ENOTDIR |
| \fInew_root\fP or \fIput_old\fP is not a directory. |
| .TP |
| .B EPERM |
| The current process does not have the administrator capability. |
| .SH BUGS |
| \fBpivot_root\fP should not have to change root and cwd of all other |
| processes in the system. |
| |
| Some of the more obscure uses of \fBpivot_root\fP may quickly lead to |
| insanity. |
| .SH HISTORY |
| \fBpivot_root\fP was introduced in Linux 2.3.41. |
| .SH "SEE ALSO" |
| .BR chdir(2), |
| .BR chroot(2), |
| .BR initrd(4), |
| .BR pivot_root(8), |
| .BR stat(2) |