Base: Document new chroot abilities

Base/usr/share/man/man2/chroot.md

@@ -1,6 +1,6 @@
 ## Name
 
-chroot - change filesystem root
+chroot, chroot_with_mount_flags - change filesystem root
 
 ## Synopsis
 
@@ -8,12 +8,18 @@ chroot - change filesystem root
 #include <unistd.h>
 
 int chroot(const char* path);
+int chroot_with_mount_flags(const char* path, int mount_flags);
 ```
 
 ## Description
 
 `chroot()` changes the filesystem root of the current process to a new directory specified by `path`.
 
+`chroot_with_mount_flags()` additionally applies the given `mount_flags` to the new root directory
+of the current process as if it was a separate mount. All the same flags as for [`mount`(2)](mount.md)
+are accepted, except `MS_BIND` doesn't make sense for chroots. Additionally, the value -1 is accepted,
+and makes `chroot_with_mount_flags()` behave like regular `chroot()`.
+
 ## Errors
 
 * `EPERM`: The current process does not have superuser privileges.
@@ -24,3 +30,4 @@ All of the usual path resolution errors may also occur.
 ## See also
 
 * [`chroot`(8)](../man8/chroot.md)
+* [`mount`(2)](mount.md)

Base/usr/share/man/man8/chroot.md

@@ -5,7 +5,7 @@ chroot - run a shell with a different filesystem root
 ## Synopsis
 
 ```**sh
-# chroot
+# chroot <path> [program] [-o options]
 ```
 
 ## Description
@@ -13,7 +13,8 @@ chroot - run a shell with a different filesystem root
 This program uses the [`chroot`(2)](../man2/chroot.md) syscall to switch into a
 different filesystem root and spawn a shell inside it.
 
-It will not work unless there is a `/bin/Shell` available inside the new root.
+It runs the given *program* (by default, `/bin/Shell`) inside the new root.
+Mount options can be given in the same format as for [`mount`(8)](mount.md).
 
 ## Examples
 
@@ -26,3 +27,4 @@ It will not work unless there is a `/bin/Shell` available inside the new root.
 ## See also
 
 * [`chroot`(2)](../man2/chroot.md)
+* [`mount`(8)](mount.md)