fs::dir: Add a reopen_dir() method

In some cases when working with an existing C/C++ codebase already
using `openat()` or other crates such as the `openat` crate, one
may have an existing file descriptor and want to create a `cap-std`
view of the same directory.

Add an API which reopens from a source FD.

Author: cgwalters

cap-std/src/fs/dir.rs

@@ -609,6 +609,20 @@ impl Dir {
         let _ = ambient_authority;
         fs::create_dir_all(path)
     }
+
+    /// Construct a new instance of `Self` from existing directory file descriptor.
+    ///
+    /// This can be useful when interacting with other libraries and or C/C++ code
+    /// which has invoked `openat(..., O_DIRECTORY)` external to this crate.
+    #[cfg(not(windows))]
+    pub fn reopen_dir(fd: BorrowedFd) -> io::Result<Self> {
+        use io_lifetimes::AsFilelike;
+        cap_primitives::fs::open_dir(
+            &fd.as_filelike_view::<std::fs::File>(),
+            std::path::Component::CurDir.as_ref(),
+        )
+        .map(Self::from_std_file)
+    }
 }
 
 #[cfg(not(windows))]

tests/fs_additional.rs

@@ -847,3 +847,13 @@ fn maybe_dir() {
     // Opening directories works on all platforms with `maybe_dir`.
     check!(tmpdir.open_with("dir", OpenOptions::new().read(true).maybe_dir(true)));
 }
+
+#[test]
+#[cfg(not(windows))]
+fn reopen_fd() {
+    use rustix::fd::AsFd;
+    let tmpdir = tmpdir();
+    check!(tmpdir.create_dir("subdir"));
+    let tmpdir2 = check!(cap_std::fs::Dir::reopen_dir(tmpdir.as_fd()));
+    assert!(tmpdir2.exists("subdir"));
+}