Struct nix::dir::Dir

pub struct Dir(/* private fields */);

An open directory.

This is a lower-level interface than std::fs::ReadDir. Notable differences:

• can be opened from a file descriptor (as returned by openat, perhaps before knowing if the path represents a file or directory).
• implements AsFd, so it can be passed to fstat, openat, etc. The file descriptor continues to be owned by the Dir, so callers must not keep a RawFd after the Dir is dropped.
• can be iterated through multiple times without closing and reopening the file descriptor. Each iteration rewinds when finished.
• returns entries for . (current directory) and .. (parent directory).
• returns entries’ names as a CStr (no allocation or conversion beyond whatever libc does).

Examples

Traverse the current directory, and print entries’ names:

use nix::dir::Dir;
use nix::fcntl::OFlag;
use nix::sys::stat::Mode;

let mut cwd = Dir::open(".", OFlag::O_RDONLY | OFlag::O_CLOEXEC, Mode::empty()).unwrap();
for res_entry in cwd.iter() {
    let entry = res_entry.unwrap();
    println!("File name: {}", entry.file_name().to_str().unwrap());
}

Implementations

impl Dir

pub fn open<P: ?Sized + NixPath>( path: &P, oflag: OFlag, mode: Mode, ) -> Result<Self>

Opens the given path as with fcntl::open.

pub fn openat<Fd: AsFd, P: ?Sized + NixPath>( dirfd: Fd, path: &P, oflag: OFlag, mode: Mode, ) -> Result<Self>

Opens the given path as with fcntl::openat.

pub unsafe fn from<F: IntoRawFd>(fd: F) -> Result<Self>

👎Deprecated since 0.30.0: Deprecate this since it is not I/O-safe, use from_fd instead.

Converts from a descriptor-based object, closing the descriptor on success or failure.

Safety

It is only safe if fd is an owned file descriptor.

pub fn from_fd(fd: OwnedFd) -> Result<Self>

Converts from a file descriptor, closing it on failure.

Examples

ENOTDIR would be returned if fd does not refer to a directory:

use std::os::fd::OwnedFd;
use nix::dir::Dir;

let temp_file = tempfile::tempfile().unwrap();
let temp_file_fd: OwnedFd = temp_file.into();
let never = Dir::from_fd(temp_file_fd).unwrap();

pub fn iter(&mut self) -> Iter<'_>

Returns an iterator of Result<Entry> which rewinds when finished.

Trait Implementations

impl AsFd for Dir

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

Borrows the file descriptor.

impl AsRawFd for Dir

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Dir

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

Formats the value using the given formatter.

impl Drop for Dir

fn drop(&mut self)

Executes the destructor for this type.

impl Hash for Dir

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoIterator for Dir

fn into_iter(self) -> Self::IntoIter

Creates a owning iterator, that is, one that takes ownership of the Dir. The Dir cannot be used after calling this. This can be useful when you have a function that both creates a Dir instance and returns an Iterator.

Example:

use nix::{dir::Dir, fcntl::OFlag, sys::stat::Mode};
use std::{iter::Iterator, string::String};

fn ls_upper(dirname: &str) -> impl Iterator<Item=String> {
    let d = Dir::open(dirname, OFlag::O_DIRECTORY, Mode::S_IXUSR).unwrap();
    d.into_iter().map(|x| x.unwrap().file_name().as_ref().to_string_lossy().to_ascii_uppercase())
}

type Item = Result<Entry, Errno>

The type of the elements being iterated over.

type IntoIter = OwningIter

Which kind of iterator are we turning this into?

impl PartialEq for Dir

fn eq(&self, other: &Dir) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Dir

impl Send for Dir

impl StructuralPartialEq for Dir