Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 166 insertions, 0 deletions

diff --git a/man/man2/chroot.2 b/man/man2/chroot.2
new file mode 100644
index 0000000..359d213
--- /dev/null
+++ b/man/man2/chroot.2
@@ -0,0 +1,166 @@
+.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified by Michael Haardt <michael@moria.de>
+.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
+.\" Modified 1994-08-21 by Michael Chastain <mec@shell.portal.com>
+.\" Modified 1996-06-13 by aeb
+.\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 1997-08-21 by Joseph S. Myers <jsm28@cam.ac.uk>
+.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.TH chroot 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+chroot \- change root directory
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "int chroot(const char *" path );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR chroot ():
+.nf
+    Since glibc 2.2.2:
+        _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
+            || /* Since glibc 2.20: */ _DEFAULT_SOURCE
+            || /* glibc <= 2.19: */ _BSD_SOURCE
+    Before glibc 2.2.2:
+        none
+.fi
+.SH DESCRIPTION
+.BR chroot ()
+changes the root directory of the calling process to that specified in
+.IR path .
+This directory will be used for pathnames beginning with \fI/\fP.
+The root directory is inherited by all children of the calling process.
+.P
+Only a privileged process (Linux: one with the
+.B CAP_SYS_CHROOT
+capability in its user namespace) may call
+.BR chroot ().
+.P
+This call changes an ingredient in the pathname resolution process
+and does nothing else.
+In particular, it is not intended to be used
+for any kind of security purpose, neither to fully sandbox a process nor
+to restrict filesystem system calls.
+In the past,
+.BR chroot ()
+has been used by daemons to restrict themselves prior to passing paths
+supplied by untrusted users to system calls such as
+.BR open (2).
+However, if a folder is moved out of the chroot directory, an attacker
+can exploit that to get out of the chroot directory as well.
+The easiest way to do that is to
+.BR chdir (2)
+to the to-be-moved directory, wait for it to be moved out, then open a
+path like ../../../etc/passwd.
+.P
+.\" This is how the "slightly trickier variation" works:
+.\" https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt#L142
+A slightly
+trickier variation also works under some circumstances if
+.BR chdir (2)
+is not permitted.
+If a daemon allows a "chroot directory" to be specified,
+that usually means that if you want to prevent remote users from accessing
+files outside the chroot directory, you must ensure that folders are never
+moved out of it.
+.P
+This call does not change the current working directory,
+so that after the call \[aq]\fI.\fP\[aq] can
+be outside the tree rooted at \[aq]\fI/\fP\[aq].
+In particular, the superuser can escape from a "chroot jail"
+by doing:
+.P
+.in +4n
+.EX
+mkdir foo; chroot foo; cd ..
+.EE
+.in
+.P
+This call does not close open file descriptors, and such file
+descriptors may allow access to files outside the chroot tree.
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Depending on the filesystem, other errors can be returned.
+The more general errors are listed below:
+.TP
+.B EACCES
+Search permission is denied on a component of the path prefix.
+(See also
+.BR path_resolution (7).)
+.\" Also search permission is required on the final component,
+.\" maybe just to guarantee that it is a directory?
+.TP
+.B EFAULT
+.I path
+points outside your accessible address space.
+.TP
+.B EIO
+An I/O error occurred.
+.TP
+.B ELOOP
+Too many symbolic links were encountered in resolving
+.IR path .
+.TP
+.B ENAMETOOLONG
+.I path
+is too long.
+.TP
+.B ENOENT
+The file does not exist.
+.TP
+.B ENOMEM
+Insufficient kernel memory was available.
+.TP
+.B ENOTDIR
+A component of
+.I path
+is not a directory.
+.TP
+.B EPERM
+The caller has insufficient privilege.
+.SH STANDARDS
+None.
+.SH HISTORY
+SVr4, 4.4BSD, SUSv2 (marked LEGACY).
+This function is not part of POSIX.1-2001.
+.\" SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions.
+.\" X/OPEN does not document EIO, ENOMEM or EFAULT error conditions.
+.SH NOTES
+A child process created via
+.BR fork (2)
+inherits its parent's root directory.
+The root directory is left unchanged by
+.BR execve (2).
+.P
+The magic symbolic link,
+.IR /proc/ pid /root ,
+can be used to discover a process's root directory; see
+.BR proc (5)
+for details.
+.P
+FreeBSD has a stronger
+.BR jail ()
+system call.
+.SH SEE ALSO
+.BR chroot (1),
+.BR chdir (2),
+.BR pivot_root (2),
+.BR path_resolution (7),
+.BR switch_root (8)