'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" Portions Copyright 2021 OmniOS Community Edition (OmniOSce) Association.
.\"
.Dd March 18, 2021
.Dt CHROOT 8
.Os
.Sh NAME
.Nm chroot
.Nd change root directory for a command
.Sh SYNOPSIS
.Nm
.Ar newroot
.Ar command
.Sh DESCRIPTION
The
.Nm
utility causes
.Ar command
to be executed relative to
.Ar newroot .
The meaning of any initial slash
.Pq /
in the path names is changed to
.Ar newroot
for
.Ar command
and any of its child processes.
Upon execution, the initial working directory is
.Ar newroot .
.Pp
Notice that redirecting the output of
.Ar command
to a file, such as in:
.Pp
.D1 Nm chroot Ar newroot Ar command Sy > Pa xyz
.Pp
will create the file
.Pa xyz
relative to the original root of
.Ar command ,
not the new one.
.Pp
The new root path name is always relative to the current root.
Even if a
.Nm
is currently in effect, the
.Ar newroot
argument is relative to the current root of the running process.
.Pp
This command can be run only by the super-user.
.Sh EXIT STATUS
The exit status of
.Nm
is the exit status of
.Ar command .
.Sh OPERANDS
The following operands are supported:
.Bl -tag -width Ar
.It Ar newroot
The new root directory.
.It Ar command
The command to be executed relative to
.Ar newroot .
.El
.Sh EXAMPLES
.Sy Example 1
Using the
.Nm
Utility
.Pp
The
.Nm
utility provides an easy way to extract
.Sy tar
files
.Pq see Xr tar 1
written with absolute filenames to a different location.
It is necessary to copy the shared libraries used by
.Sy tar
.Pq see Xr ldd 1
to the
.Ar newroot
filesystem.
.Bd -literal -offset indent
example# mkdir -p /tmp/lib /tmp/usr/lib
example# cd /lib && cp ld.so.1 \e
         libavl.so.1 libc.so.1 libcmdutils.so.1 libcustr.so.1 \e
         libm.so.2 libmd.so.1 libmp.so.2 libnsl.so.1 \e
         libnvpair.so.1 libsec.so.1 libsecdb.so.1 libtsol.so.2 \e
         libuutil.so.1 /tmp/lib/
example# cp /usr/lib/libidmap.so.1 /tmp/usr/lib/
example# cp /usr/bin/tar /tmp
example# dd if=/dev/rmt/0 | chroot /tmp tar xvf -
.Ed
.Sh SEE ALSO
.Xr cd 1 ,
.Xr ldd 1 ,
.Xr tar 1 ,
.Xr chroot 2 ,
.Xr ttyname 3C ,
.Xr attributes 7
.Sh NOTES
Exercise extreme caution when referencing device files in the new root file
system.
.Pp
References by routines such as
.Xr ttyname 3C
to
.Dv stdin ,
.Dv stdout ,
and
.Dv stderr
will find that the device associated with the file descriptor is unknown after
.Nm
is run.