Struct rustix::fs::RawDir

pub struct RawDir<'buf, Fd: AsFd> { /* private fields */ }

A directory iterator implemented with getdents.

Note: This implementation does not handle growing the buffer. If this functionality is necessary, you’ll need to drop the current iterator, resize the buffer, and then re-create the iterator. The iterator is guaranteed to continue where it left off provided the file descriptor isn’t changed. See the example in RawDir::new.

Implementations

impl<'buf, Fd: AsFd> RawDir<'buf, Fd>

pub fn new(fd: Fd, buf: &'buf mut [MaybeUninit<u8>]) -> Self

Create a new iterator from the given file descriptor and buffer.

Note: the buffer size may be trimmed to accommodate alignment requirements.

Examples

Simple but non-portable

These examples are non-portable, because file systems may not have a maximum file name length. If you can make assumptions that bound this length, then these examples may suffice.

Using the heap:

let fd = openat(
    CWD,
    cstr!("."),
    OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC,
    Mode::empty(),
)
.unwrap();

let mut buf = Vec::with_capacity(8192);
let mut iter = RawDir::new(fd, buf.spare_capacity_mut());
while let Some(entry) = iter.next() {
    let entry = entry.unwrap();
    dbg!(&entry);
}

Using the stack:

let fd = openat(
    CWD,
    cstr!("."),
    OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC,
    Mode::empty(),
)
.unwrap();

let mut buf = [MaybeUninit::uninit(); 2048];
let mut iter = RawDir::new(fd, &mut buf);
while let Some(entry) = iter.next() {
    let entry = entry.unwrap();
    dbg!(&entry);
}

Portable

Heap allocated growing buffer for supporting directory entries with arbitrarily large file names:

# // The `notrust` above can be removed when we can depend on Rust 1.65.
# use std::mem::MaybeUninit;
# use rustix::fs::{CWD, Mode, OFlags, openat, RawDir};
# use rustix::io::Errno;
# use rustix::cstr;

let fd = openat(
    CWD,
    cstr!("."),
    OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC,
    Mode::empty(),
)
.unwrap();

let mut buf = Vec::with_capacity(8192);
'read: loop {
    'resize: {
        let mut iter = RawDir::new(&fd, buf.spare_capacity_mut());
        while let Some(entry) = iter.next() {
            let entry = match entry {
                Err(Errno::INVAL) => break 'resize,
                r => r.unwrap(),
            };
            dbg!(&entry);
        }
        break 'read;
    }

    let new_capacity = buf.capacity() * 2;
    buf.reserve(new_capacity);
}

impl<'buf, Fd: AsFd> RawDir<'buf, Fd>

pub fn next(&mut self) -> Option<Result<RawDirEntry<'_>>>

Identical to Iterator::next except that Iterator::Item borrows from self.

Note: this interface will be broken to implement a stdlib iterator API with GAT support once one becomes available.

pub fn is_buffer_empty(&self) -> bool

Returns true if the internal buffer is empty and will be refilled when calling next.