Add Dir::new function, constructing a Dir from an owned fd. (#950)

Add `Dir::new` function, which takes ownership of an `OwnedFd`. This
incurs undefined behavior from the libc `readdir` function if there
are any copies of the file descriptor live somewhere, so this function
is `unsafe`.

Author: sunfishcode

src/backend/libc/fs/dir.rs

@@ -2,7 +2,7 @@
 use super::types::FileType;
 use crate::backend::c;
 use crate::backend::conv::owned_fd;
-use crate::fd::{AsFd, BorrowedFd};
+use crate::fd::{AsFd, BorrowedFd, OwnedFd};
 use crate::ffi::{CStr, CString};
 use crate::fs::{fcntl_getfl, openat, Mode, OFlags};
 #[cfg(not(target_os = "vita"))]
@@ -48,8 +48,34 @@ pub struct Dir {
 }
 
 impl Dir {
-    /// Construct a `Dir` that reads entries from the given directory
-    /// file descriptor.
+    /// Take ownership of `fd` and construct a `Dir` that reads entries from
+    /// the given directory file descriptor.
+    #[inline]
+    pub fn new<Fd: Into<OwnedFd>>(fd: Fd) -> io::Result<Self> {
+        Self::_new(fd.into())
+    }
+
+    #[inline]
+    fn _new(fd: OwnedFd) -> io::Result<Self> {
+        let raw = owned_fd(fd);
+        unsafe {
+            let libc_dir = c::fdopendir(raw);
+
+            if let Some(libc_dir) = NonNull::new(libc_dir) {
+                Ok(Self {
+                    libc_dir,
+                    any_errors: false,
+                })
+            } else {
+                let err = io::Errno::last_os_error();
+                let _ = c::close(raw);
+                Err(err)
+            }
+        }
+    }
+
+    /// Borrow `fd` and construct a `Dir` that reads entries from the given
+    /// directory file descriptor.
     #[inline]
     pub fn read_from<Fd: AsFd>(fd: Fd) -> io::Result<Self> {
         Self::_read_from(fd.as_fd())

src/backend/linux_raw/fs/dir.rs

@@ -32,8 +32,26 @@ pub struct Dir {
 }
 
 impl Dir {
-    /// Construct a `Dir` that reads entries from the given directory
-    /// file descriptor.
+    /// Take ownership of `fd` and construct a `Dir` that reads entries from
+    /// the given directory file descriptor.
+    #[inline]
+    pub fn new<Fd: Into<OwnedFd>>(fd: Fd) -> io::Result<Self> {
+        Self::_new(fd.into())
+    }
+
+    #[inline]
+    fn _new(fd: OwnedFd) -> io::Result<Self> {
+        Ok(Self {
+            fd,
+            any_errors: false,
+            rewind: false,
+            buf: Vec::new(),
+            pos: 0,
+        })
+    }
+
+    /// Borrow `fd` and construct a `Dir` that reads entries from the given
+    /// directory file descriptor.
     #[inline]
     pub fn read_from<Fd: AsFd>(fd: Fd) -> io::Result<Self> {
         Self::_read_from(fd.as_fd())

tests/fs/dir.rs

@@ -1,5 +1,5 @@
 #[test]
-fn test_dir() {
+fn test_dir_read_from() {
     let t = rustix::fs::openat(
         rustix::fs::CWD,
         rustix::cstr!("."),
@@ -62,6 +62,70 @@ fn test_dir() {
     assert!(saw_cargo_toml);
 }
 
+#[test]
+fn test_dir_new() {
+    let t = rustix::fs::openat(
+        rustix::fs::CWD,
+        rustix::cstr!("."),
+        rustix::fs::OFlags::RDONLY | rustix::fs::OFlags::CLOEXEC,
+        rustix::fs::Mode::empty(),
+    )
+    .unwrap();
+
+    let _file = rustix::fs::openat(
+        &t,
+        rustix::cstr!("Cargo.toml"),
+        rustix::fs::OFlags::RDONLY | rustix::fs::OFlags::CLOEXEC,
+        rustix::fs::Mode::empty(),
+    )
+    .unwrap();
+
+    let mut dir = rustix::fs::Dir::new(t).unwrap();
+
+    // Read the directory entries. We use `while let Some(entry)` so that we
+    // don't consume the `Dir` so that we can run more tests on it.
+    let mut saw_dot = false;
+    let mut saw_dotdot = false;
+    let mut saw_cargo_toml = false;
+    while let Some(entry) = dir.read() {
+        let entry = entry.unwrap();
+        if entry.file_name() == rustix::cstr!(".") {
+            saw_dot = true;
+        } else if entry.file_name() == rustix::cstr!("..") {
+            saw_dotdot = true;
+        } else if entry.file_name() == rustix::cstr!("Cargo.toml") {
+            saw_cargo_toml = true;
+        }
+    }
+    assert!(saw_dot);
+    assert!(saw_dotdot);
+    assert!(saw_cargo_toml);
+
+    // Rewind the directory so we can iterate over the entries again.
+    dir.rewind();
+
+    // For what comes next, we don't need `mut` anymore.
+    let dir = dir;
+
+    // Read the directory entries, again. This time we use `for entry in dir`.
+    let mut saw_dot = false;
+    let mut saw_dotdot = false;
+    let mut saw_cargo_toml = false;
+    for entry in dir {
+        let entry = entry.unwrap();
+        if entry.file_name() == rustix::cstr!(".") {
+            saw_dot = true;
+        } else if entry.file_name() == rustix::cstr!("..") {
+            saw_dotdot = true;
+        } else if entry.file_name() == rustix::cstr!("Cargo.toml") {
+            saw_cargo_toml = true;
+        }
+    }
+    assert!(saw_dot);
+    assert!(saw_dotdot);
+    assert!(saw_cargo_toml);
+}
+
 // Test that `Dir` silently stops iterating if the directory has been removed.
 //
 // Except on FreeBSD and macOS, where apparently `readdir` just keeps reading.