std::fs

Struct Dir

pub struct Dir { /* private fields */ }

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

Expand description

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§

Source §

impl Dir

Source

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.

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

Source

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.

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