Struct Dir 

pub struct Dir { /* private fields */ }

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

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>(path: P) -> Result<Dir, Error>

where P: AsRef<Path>,

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

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 metadata(&self) -> Result<Metadata, Error>

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

Queries metadata about the underlying directory.

Examples

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

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

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

where P: AsRef<Path>,

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

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>( &self, path: P, opts: &OpenOptions, ) -> Result<File, Error>

where P: AsRef<Path>,

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

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>(&self, path: P) -> Result<(), Error>

where P: AsRef<Path>,

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

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, Q>(&self, from: P, to_dir: &Dir, to: Q) -> Result<(), Error>

where P: AsRef<Path>, Q: AsRef<Path>,

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

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(())
}

Trait Implementations

impl AsFd for Dir

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

Borrows the file descriptor.

impl AsRawFd for Dir

fn as_raw_fd(&self) -> i32

Extracts the raw file descriptor.

impl Debug for Dir

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

Formats the value using the given formatter.

impl From<OwnedFd> for Dir

fn from(value: OwnedFd) -> Dir

Converts to this type from the input type.

impl FromRawFd for Dir

unsafe fn from_raw_fd(fd: i32) -> Dir

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

impl IntoRawFd for Dir

fn into_raw_fd(self) -> i32

Consumes this object, returning the raw underlying file descriptor.