Struct Dir 

pub struct Dir {
    inner: Dir,
}

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

Fields

inner: Dir

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

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.

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

Trait Implementations

impl AsFd for Dir

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

Available on Unix or HermitCore or target_os=trusty or WASI or target_os=motor only.

Borrows the file descriptor.

impl AsInner<Dir> for Dir

fn as_inner(&self) -> &Dir

impl AsRawFd for Dir

fn as_raw_fd(&self) -> RawFd

Available on Unix or HermitCore or target_os=trusty or WASI or target_os=motor 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 FromInner<Dir> for Dir

fn from_inner(f: Dir) -> Dir

impl FromRawFd for Dir

unsafe fn from_raw_fd(fd: RawFd) -> Self

Available on Unix or HermitCore or target_os=trusty or WASI or target_os=motor only.

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

impl IntoInner<Dir> for Dir

fn into_inner(self) -> Dir

impl IntoRawFd for Dir

fn into_raw_fd(self) -> RawFd

Available on Unix or HermitCore or target_os=trusty or WASI or target_os=motor only.

Consumes this object, returning the raw underlying file descriptor.