statx: Add an example of using this to determine mountpoint (#831)

- This use case is a specific reason to directly use the `statx`
  system call
- It's a bit of a subtle API because there's 4 different flags
  involved, and it's not necessarily obvious that the relevant
  bitmasks aren't (yet) exposed in rustix, so one needs to use
  libc/linux-raw-sys directly
- On the general principle of adding examples

Author: cgwalters

src/fs/statx.rs

@@ -21,6 +21,35 @@ use compat::statx as _statx;
 /// # References
 ///  - [Linux]
 ///
+/// # Examples
+///
+/// ```
+/// # use std::path::Path;
+/// # use std::io;
+/// # use rustix::fs::{AtFlags, StatxFlags};
+/// # use rustix::fd::BorrowedFd;
+/// /// Try to determine if the provided path is a mount root.  Will return `Ok(None)` if
+/// /// the kernel is not new enough to support statx() or [`libc::STATX_ATTR_MOUNT_ROOT`].
+/// fn is_mountpoint(root: BorrowedFd<'_>, path: &Path) -> io::Result<Option<bool>> {
+///     use rustix::fs::{AtFlags, StatxFlags};
+///
+///     let mountroot_flag = libc::STATX_ATTR_MOUNT_ROOT as u64;
+///     match rustix::fs::statx(
+///         root,
+///         path,
+///         AtFlags::NO_AUTOMOUNT | AtFlags::SYMLINK_NOFOLLOW,
+///         StatxFlags::empty(),
+///     ) {
+///         Ok(r) => {
+///             let present = (r.stx_attributes_mask & mountroot_flag) > 0;
+///             Ok(present.then(|| r.stx_attributes & mountroot_flag > 0))
+///         }
+///         Err(e) if e == rustix::io::Errno::NOSYS => Ok(None),
+///         Err(e) => Err(e.into()),
+///     }
+/// }
+/// ```
+///
 /// [Linux]: https://man7.org/linux/man-pages/man2/statx.2.html
 #[inline]
 pub fn statx<P: path::Arg, Fd: AsFd>(