git: 95f8c3e1ed0c - main - chroot.2: Update errors and unprivileged use

The branch main has been updated by emaste:

URL: https://cgit.FreeBSD.org/src/commit/?id=95f8c3e1ed0c3075411444381a5a4baef4ed8fda

commit 95f8c3e1ed0c3075411444381a5a4baef4ed8fda
Author:     Ed Maste <emaste@FreeBSD.org>
AuthorDate: 2025-08-02 17:17:40 +0000
Commit:     Ed Maste <emaste@FreeBSD.org>
CommitDate: 2025-08-02 18:43:36 +0000

    chroot.2: Update errors and unprivileged use
    
    Include errors common to chroot and fchroot in a single list, followed
    by errors unique to each.
    
    Unprivileged chroot is permitted if the security.bsd.unprivileged_chroot
    sysctl is set to 1.  Make note of this and update the EPERM description.
    
    Reported by:    kevans
    Reviewed by:    kevans, kib
    Sponsored by:   The FreeBSD Foundation
    Differential Revision: https://reviews.freebsd.org/D51703
---
 lib/libsys/chroot.2 | 49 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 33 insertions(+), 16 deletions(-)

diff --git a/lib/libsys/chroot.2 b/lib/libsys/chroot.2
index 4c06e3673e03..3347df5cceee 100644
--- a/lib/libsys/chroot.2
+++ b/lib/libsys/chroot.2
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd July 15, 2024
+.Dd August 2, 2025
 .Dt CHROOT 2
 .Os
 .Sh NAME
@@ -61,7 +61,12 @@ It should be noted that
 .Fn chroot
 has no effect on the process's current directory.
 .Pp
-This call is restricted to the super-user.
+This call is restricted to the super-user, unless the
+.Ql security.bsd.unprivileged_chroot
+sysctl variable is set to 1
+and the process has enabled the
+.Dv PROC_NO_NEW_PRIVS_CTL
+.Xr procctl 2 .
 .Pp
 Depending on the setting of the
 .Ql kern.chroot_allow_open_directories
@@ -106,14 +111,37 @@ except it takes a file descriptor instead of path.
 .Sh ERRORS
 The
 .Fn chroot
+and
+.Fn fchroot
+system calls
+will fail and the root directory will be unchanged if:
+.Bl -tag -width Er
+.It Bq Er EPERM
+The effective user ID is not the super-user and the
+.Ql security.bsd.unprivileged_chroot
+sysctl is 0.
+.It Bq Er EPERM
+The effective user ID is not the super-user and the
+process has not enabled the
+.Dv PROC_NO_NEW_PRIVS_CTL
+.Xr procctl 2 .
+.It Bq Er EPERM
+One or more filedescriptors are open directories and the
+.Ql kern.chroot_allow_open_directories
+sysctl is not set to permit this.
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to the file system.
+.It Bq Er EINTEGRITY
+Corrupted data was detected while reading from the file system.
+.El
+.Pp
+The
+.Fn chroot
 system call
 will fail and the root directory will be unchanged if:
 .Bl -tag -width Er
 .It Bq Er ENOTDIR
 A component of the path name is not a directory.
-.It Bq Er EPERM
-The effective user ID is not the super-user, or one or more
-filedescriptors are open directories.
 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded 255 characters,
 or an entire path name exceeded 1023 characters.
@@ -128,10 +156,6 @@ The
 .Fa dirname
 argument
 points outside the process's allocated address space.
-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.
-.It Bq Er EINTEGRITY
-Corrupted data was detected while reading from the file system.
 .El
 .Pp
 The
@@ -146,15 +170,8 @@ file descriptor.
 The argument
 .Fa fd
 is not a valid file descriptor.
-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.
-.It Bq Er EINTEGRITY
-Corrupted data was detected while reading from the file system.
 .It Bq Er ENOTDIR
 The file descriptor does not reference a directory.
-.It Bq Er EPERM
-The effective user ID is not the super-user, or one or more
-filedescriptors are open directories.
 .El
 .Sh SEE ALSO
 .Xr chdir 2 ,