man2/pivot_root.2

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