Skip to content

dirfd: preliminary unix and windows implementations #139514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: master
Choose a base branch
from
Open

dirfd: preliminary unix and windows implementations #139514

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
bcd769d
dirfd: initial quick and dirty implementation for unix
Qelxiros Apr 8, 2025
05f87c5
add documentation, implementations for unsupported platforms
Qelxiros May 3, 2025
bdeb57e
add new Dir struct, rename/remove functions, constructors, and docume…
Qelxiros May 5, 2025
0a82f16
fix doctests, add real tests
Qelxiros May 5, 2025
228d994
add windows implementation
Qelxiros May 6, 2025
c58a2d8
add unix implementation for create_dir
Qelxiros May 6, 2025
c1c4fb1
add create_dir test
Qelxiros May 6, 2025
4890e60
fix windows functions, documentation
Qelxiros May 24, 2025
f4d6ffc
requested changes
Qelxiros Jun 10, 2025
02f9073
add unsupported implementations for missing platforms
Qelxiros Jun 11, 2025
9ae1e46
add pathbuf implementation to common
Qelxiros Jun 12, 2025
f07f7c5
requested changes
Qelxiros Jun 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
321 changes: 321 additions & 0 deletions library/std/src/fs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,33 @@ pub enum TryLockError {
WouldBlock,
}

/// An object providing access to a directory on the filesystem.
///
/// Files are automatically closed when they go out of scope. Errors detected
/// on closing are ignored by the implementation of `Drop`.
///
/// # Examples
///
/// Opens a directory and then a file inside it.
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::{fs::Dir, io::Read};
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new("foo")?;
/// let mut file = dir.open("bar.txt")?;
/// let mut s = String::new();
/// file.read_to_string(&mut s)?;
/// println!("{}", s);
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub struct Dir {
inner: fs_imp::Dir,
}

/// Metadata information about a file.
///
/// This structure is returned from the [`metadata`] or
Expand Down Expand Up @@ -1453,6 +1480,300 @@ impl Seek for Arc<File> {
}
}

impl Dir {
/// Attempts to open a directory at `path` in read-only mode.
///
/// See [`new_with`] for more options.
///
/// # Errors
///
/// This function will return an error if `path` does not point to an existing directory.
/// Other errors may also be returned according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::{fs::Dir, io::Read};
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new("foo")?;
/// let mut f = dir.open("bar.txt")?;
/// let mut data = vec![];
/// f.read_to_end(&mut data)?;
/// Ok(())
/// }
/// ```
///
/// [`new_with`]: Dir::new_with
#[unstable(feature = "dirfd", issue = "120426")]
pub fn new<P: AsRef<Path>>(path: P) -> io::Result<Self> {
fs_imp::Dir::new(path).map(|inner| Self { inner })
}

/// Attempts to open a directory at `path` with the options specified by `opts`.
///
/// # Errors
///
/// This function may return an error according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::fs::{Dir, OpenOptions};
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new_with("foo", OpenOptions::new().write(true))?;
/// let mut f = dir.remove_file("bar.txt")?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn new_with<P: AsRef<Path>>(path: P, opts: &OpenOptions) -> io::Result<Self> {
fs_imp::Dir::new_with(path, &opts.0).map(|inner| Self { inner })
}

/// Attempts to open a directory at `path` with the minimum permissions for traversal.
///
/// # Errors
///
/// This function may return an error according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::{fs::Dir, io::Read};
///
/// fn main() -> std::io::Result<()> {
/// let foo = Dir::new_for_traversal("foo")?;
/// let foobar = foo.open_dir("bar")?;
/// let mut s = String::new();
/// foobar.open("baz")?.read_to_string(&mut s)?;
/// println!("{s}");
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn new_for_traversal<P: AsRef<Path>>(path: P) -> io::Result<Self> {
fs_imp::Dir::new_for_traversal(path).map(|inner| Self { inner })
}

/// Attempts to open a file in read-only mode relative to this directory.
///
/// # Errors
///
/// This function will return an error if `path` does not point to an existing file.
/// Other errors may also be returned according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::{fs::Dir, io::Read};
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new("foo")?;
/// let mut f = dir.open("bar.txt")?;
/// let mut data = vec![];
/// f.read_to_end(&mut data)?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
self.inner.open(path).map(|f| File { inner: f })
}

/// Attempts to open a file relative to this directory with the options specified by `opts`.
///
/// # Errors
///
/// This function may return an error according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::{fs::{Dir, OpenOptions}, io::Read};
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new("foo")?;
/// let mut f = dir.open_with("bar.txt", OpenOptions::new().read(true))?;
/// let mut data = vec![];
/// f.read_to_end(&mut data)?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn open_with<P: AsRef<Path>>(&self, path: P, opts: &OpenOptions) -> io::Result<File> {
self.inner.open_with(path, &opts.0).map(|f| File { inner: f })
}

/// Attempts to create a directory relative to this directory.
///
/// # Errors
///
/// This function will return an error if `path` points to an existing file or directory.
/// Other errors may also be returned according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::{fs::{Dir, OpenOptions}, io::Read};
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new("foo")?;
/// let mut f = dir.open_with("bar.txt", OpenOptions::new().read(true))?;
/// let mut data = vec![];
/// f.read_to_end(&mut data)?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
self.inner.create_dir(path)
}

/// Attempts to open a directory relative to this directory in read-only mode.
///
/// # Errors
///
/// This function will return an error if `path` does not point to an existing directory.
/// Other errors may also be returned according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::{fs::Dir, io::Read};
///
/// fn main() -> std::io::Result<()> {
/// let foo = Dir::new("foo")?;
/// let foobar = foo.open_dir("bar")?;
/// let mut s = String::new();
/// foobar.open("baz")?.read_to_string(&mut s)?;
/// println!("{s}");
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn open_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<Self> {
self.inner.open_dir(path).map(|inner| Self { inner })
}

/// Attempts to open a directory relative to this directory in read-only mode.
///
/// # Errors
///
/// This function will return an error according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::{fs::{Dir, OpenOptions}, io::Write};
///
/// fn main() -> std::io::Result<()> {
/// let foo = Dir::new("foo")?;
/// let foobar = foo.open_dir_with("bar", OpenOptions::new().write(true))?;
/// foobar.open("baz")?.write(b"baz")?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn open_dir_with<P: AsRef<Path>>(&self, path: P, opts: &OpenOptions) -> io::Result<Self> {
self.inner.open_dir_with(path, &opts.0).map(|inner| Self { inner })
}

/// Attempts to remove a file relative to this directory.
///
/// # Errors
///
/// This function will return an error if `path` does not point to an existing file.
/// Other errors may also be returned according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::fs::Dir;
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new("foo")?;
/// dir.remove_file("bar.txt")?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
self.inner.remove_file(path)
}

/// Attempts to remove a directory relative to this directory.
///
/// # Errors
///
/// This function will return an error if `path` does not point to an existing, non-empty directory.
/// Other errors may also be returned according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::fs::Dir;
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new("foo")?;
/// dir.remove_dir("baz")?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn remove_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
self.inner.remove_dir(path)
}

/// Attempts to rename a file or directory relative to this directory to a new name, replacing
/// the destination file if present.
///
/// # Errors
///
/// This function will return an error if `from` does not point to an existing file or directory.
/// Other errors may also be returned according to [`OpenOptions::open`].
///
/// # Examples
///
/// ```no_run
/// #![feature(dirfd)]
/// use std::fs::Dir;
///
/// fn main() -> std::io::Result<()> {
/// let dir = Dir::new("foo")?;
/// dir.rename("bar.txt", &dir, "quux.txt")?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "dirfd", issue = "120426")]
pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(
&self,
from: P,
to_dir: &Self,
to: Q,
) -> io::Result<()> {
self.inner.rename(from, &to_dir.inner, to)
}
}

#[unstable(feature = "dirfd", issue = "120426")]
impl fmt::Debug for Dir {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.inner.fmt(f)
}
}

impl OpenOptions {
/// Creates a blank new set of options ready for configuration.
///
Expand Down
Loading
Loading