pivot_root() — Change root mount

Standards

Standards / Extensions C or C++ Dependencies
z/OS® UNIX both  

Format

#define _XPLATFORM_SOURCE
#include <unistd.h>

int pivot_root(const char *new_root, const char *put_old);

General description

pivot_root() changes the root mount in the mount namespace of the calling process. It moves the root mount to the directory put_old and makes new_root the new root mount. The caller must be an authorized program or must run for a user with appropriate privileges.

pivot_root() changes the root directory and the current working directory of each process or thread in the same mount namespace to new_root if they point to the old root directory. pivot_root() does not change the caller's current working directory (unless it is on the old root directory), and thus it must be followed by a chdir("/") call.

Restriction:
  • new_root and put_old must be directories.
  • new_root and put_old must not be on the same mount as the current root.
  • put_old must be at or underneath new_root; that is, adding some nonnegative number of "/.." prefixes to the path name that is pointed to by put_old must yield the same directory as new_root.
  • new_root must be a path to a mount point but can't be "/". A path that is not a mount point can be converted into one by bind mounting the path onto itself.
  • The current root directory must be a mount point.

Returned value

If successful, pivot_root() returns 0.

If unsuccessful, pivot_root() returns -1 and sets errno to one of the following values:
Error Code
Description
EBUSY
new_root or put_old is on the current root mount.
EINVAL
  • new_root is not a mount point.
  • put_old is not at or underneath new_root.
  • The current root directory is not a mount point.
ENOTDIR
new_root or put_old is not a directory.
EPERM
The calling process has no authority.

Related information