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.

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_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.

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

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.