Struct Dir 

pub struct Dir { /* private fields */ }

🔬This is a nightly-only experimental API. (dirfd #120426)

An object providing access to a directory on the filesystem.

Directories are automatically closed when they go out of scope. Errors detected on closing are ignored by the implementation of Drop.

Platform-specific behavior

On supported systems (including Windows and some UNIX-based OSes), this function acquires a handle/file descriptor for the directory. This allows functions like Dir::open_file to avoid TOCTOU errors when the directory itself is being moved.

On other systems, it stores an absolute path (see canonicalize()). In the latter case, no TOCTOU guarantees are made.

Examples

Opens a directory and then a file inside it.

#![feature(dirfd)]
use std::{fs::Dir, io};

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let mut file = dir.open_file("bar.txt")?;
    let contents = io::read_to_string(file)?;
    assert_eq!(contents, "Hello, world!");
    Ok(())
}

Implementations

impl Dir

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to open a directory at path in read-only mode.

This function opens a directory. To open a file instead, see File::open.

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

#![feature(dirfd)]
use std::{fs::Dir, io};

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let mut f = dir.open_file("bar.txt")?;
    let contents = io::read_to_string(f)?;
    assert_eq!(contents, "Hello, world!");
    Ok(())
}

pub fn open_with<P: AsRef<Path>>(path: P, opts: &OpenOptions) -> Result<Self>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to open a directory at path according to opts.

This function opens a directory. To open a file instead, see File::open.

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

#![feature(dirfd)]
use std::{fs::{Dir, OpenOptions}, io};

fn main() -> std::io::Result<()> {
    let dir = Dir::open_with("foo", &OpenOptions::new().read(true))?;
    let mut f = dir.open_file("bar.txt")?;
    let contents = io::read_to_string(f)?;
    assert_eq!(contents, "Hello, world!");
    Ok(())
}

pub fn open_for_traversal<P: AsRef<Path>>(path: P) -> Result<Self>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to open a directory at path with the minimum permissions for traversal.

The permissions requested by this function are guaranteed to be sufficient to open a child file or folder, but not necessarily to list all children.

Errors

This function may return an error according to OpenOptions::open.

Examples

#![feature(dirfd)]
use std::{fs::Dir, io};

fn main() -> std::io::Result<()> {
    let foo = Dir::open_for_traversal("foo")?;
    let foobar = foo.open_dir("bar")?;
    let mut foobarbaz = foobar.open_file("baz")?;
    let contents = io::read_to_string(foobarbaz)?;
    assert_eq!(contents, "Hello, world!");
    Ok(())
}

pub fn self_metadata(&self) -> Result<Metadata>

🔬This is a nightly-only experimental API. (dirfd #120426)

Queries metadata about the underlying directory.

This is equivalent to dir.metadata(".") but can be more efficient.

Examples

#![feature(dirfd)]
use std::fs::Dir;

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let metadata = dir.self_metadata()?;
    Ok(())
}

pub fn open_file<P: AsRef<Path>>(&self, path: P) -> Result<File>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to open a file in read-only mode relative to this directory.

This function interprets path relative to the directory provided by self. To open a file relative to the current working directory, or at an absolute path, see File::open.

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

#![feature(dirfd)]
use std::{fs::Dir, io};

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let mut f = dir.open_file("bar.txt")?;
    let contents = io::read_to_string(f)?;
    assert_eq!(contents, "Hello, world!");
    Ok(())
}

pub fn open_file_with<P: AsRef<Path>>( &self, path: P, opts: &OpenOptions, ) -> Result<File>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to open a file according to opts relative to this directory.

This function interprets path relative to the directory provided by self. To open a file relative to the current working directory, or at an absolute path, see File::open.

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

#![feature(dirfd)]
use std::{fs::{Dir, OpenOptions}, io::{self, Write}};

fn main() -> io::Result<()> {
    let dir = Dir::open("foo")?;
    let mut opts = OpenOptions::new();
    opts.read(true).write(true);
    let mut f = dir.open_file_with("bar.txt", &opts)?;
    f.write_all(b"Hello, world!")?;
    let contents = io::read_to_string(f)?;
    assert_eq!(contents, "Hello, world!");
    Ok(())
}

pub fn remove_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to remove a file relative to this directory.

This function interprets path relative to the directory provided by self. To remove a file relative to the current working directory, or at an absolute path, see fs::remove_file.

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

#![feature(dirfd)]
use std::fs::Dir;

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    dir.remove_file("bar.txt")?;
    Ok(())
}

pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>( &self, from: P, to_dir: &Self, to: Q, ) -> Result<()>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to rename a file or directory relative to this directory to a new name, replacing the destination file if present.

This function interprets from relative to the directory provided by self and to relative to the directory provided by to_dir. To rename a file relative to the current working directory, or at an absolute path, see fs::rename.

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

#![feature(dirfd)]
use std::fs::Dir;

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    dir.rename("bar.txt", &dir, "quux.txt")?;
    Ok(())
}

pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to create a directory relative to this directory.

This function interprets path relative to the directory provided by self. To create a directory relative to the current working directory, or at an absolute path, see fs::create_dir.

pub fn open_dir<P: AsRef<Path>>(&self, path: P) -> Result<Self>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to open a directory in read-only mode relative to this directory.

This function interprets path relative to the directory provided by self. To open a directory relative to the current working directory, or at an absolute path, see Dir::open.

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

#![feature(dirfd)]
use std::{fs::Dir};

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let foobar = dir.open_dir("bar")?;
    Ok(())
}

pub fn open_dir_with<P: AsRef<Path>>( &self, path: P, opts: &OpenOptions, ) -> Result<Self>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to open a directory relative to this directory according to opts.

This function interprets path relative to the directory provided by self. To open a directory relative to the current working directory, or at an absolute path, see Dir::open.

Errors

This function will return errors according to OpenOptions::open.

Examples

#![feature(dirfd)]
use std::fs::{Dir, OpenOptions};

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let foobar_w = dir.open_dir_with("bar", &OpenOptions::new().write(true))?;
    Ok(())
}

pub fn remove_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>

🔬This is a nightly-only experimental API. (dirfd #120426)

Attempts to remove a directory relative to this directory.

This function interprets path relative to the directory provided by self. To remove a directory relative to the current working directory, or at an absolute path, see fs::remove_dir.

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

#![feature(dirfd)]
use std::{fs::Dir};

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    dir.remove_dir("bar")?;
    Ok(())
}

pub fn try_clone(&self) -> Result<Self>

🔬This is a nightly-only experimental API. (dirfd #120426)

Creates a new Dir instance that shares the same underlying directory handle as the existing Dir instance.

Examples

Creates two handles for a directory named foo:

#![feature(dirfd)]
use std::fs::Dir;

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let dir_copy = dir.try_clone()?;
    Ok(())
}

pub fn metadata<P: AsRef<Path>>(&self, path: P) -> Result<Metadata>

🔬This is a nightly-only experimental API. (dirfd #120426)

Queries the file system to get information about a file, directory, etc. relative to this directory.

This function will traverse symbolic links to query information about the destination file. To query metadata about the path itself without following symbolic links, use symlink_metadata.

Examples

#![feature(dirfd)]
use std::fs::Dir;

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let metadata = dir.metadata("subdir/file.txt")?;
    Ok(())
}

pub fn symlink_metadata<P: AsRef<Path>>(&self, path: P) -> Result<Metadata>

🔬This is a nightly-only experimental API. (dirfd #120426)

Queries the file system to get information about a file, directory, etc. relative to this directory.

This function will return the Metadata of the exact path without traversing symbolic links to a resolved destination file. Using this function on a path that is a file or directory (not a symbolic link) will behave the same as metadata.

Examples

#![feature(dirfd)]
use std::fs::Dir;

fn main() -> std::io::Result<()> {
    let dir = Dir::open("foo")?;
    let metadata = dir.symlink_metadata("subdir/file.txt")?;
    Ok(())
}

Trait Implementations

impl AsFd for Dir

fn as_fd(&self) -> BorrowedFd<'_>

Available on Hermit or Motor OS or Trusty or Unix or WASI only.

Borrows the file descriptor.

impl AsRawFd for Dir

fn as_raw_fd(&self) -> RawFd

Available on Hermit or Motor OS or Trusty or Unix or WASI only.

Extracts the raw file descriptor.

impl Debug for Dir

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Dir> for OwnedFd

fn from(value: Dir) -> Self

Converts to this type from the input type.

impl From<OwnedFd> for Dir

fn from(value: OwnedFd) -> Self

Converts to this type from the input type.

impl FromRawFd for Dir

unsafe fn from_raw_fd(fd: RawFd) -> Self

Available on Hermit or Motor OS or Trusty or Unix or WASI only.

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for Dir

fn into_raw_fd(self) -> RawFd

Available on Hermit or Motor OS or Trusty or Unix or WASI only.

Consumes this object, returning the raw underlying file descriptor.