1 files changed, 133 insertions, 0 deletions
diff --git a/usr/src/man/man8/chroot.8 b/usr/src/man/man8/chroot.8
new file mode 100644
index 0000000000..2e5c21b78b
--- /dev/null
+++ b/usr/src/man/man8/chroot.8
@@ -0,0 +1,133 @@
+'\" 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.