dirwalk 1.1.1

Platform-optimized recursive directory walker with metadata
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

//! Platform-specific directory scanning backends.
//!
//! Each backend takes a directory path and returns `Vec<Entry>` with metadata
//! populated during enumeration. Dispatch is compile-time via `#[cfg(target_os)]`.
//!
//! | Platform | API | Notes |
//! |----------|-----|-------|
//! | Windows | `FindFirstFileW`/`FindNextFileW` | Metadata free in `WIN32_FIND_DATAW`. `\\?\` long paths. [`StorageHint::Network`] enables `FIND_FIRST_EX_LARGE_FETCH`. |
//! | macOS | `getattrlistbulk(2)` | 256 KB buffer, 4-byte-aligned records. Falls back to Unix on `ENOTSUP`. |
//! | Linux | `getdents64` + `statx(2)` | 32 KB buffer. `d_type` avoids `stx_mode` when available. Falls back to Unix on error. |
//! | Other Unix | `std::fs::read_dir` + `symlink_metadata` | Fallback for BSDs, older kernels, and platform backend errors. |

#[cfg(target_os = "linux")]
mod linux;
#[cfg(target_os = "macos")]
mod macos;
#[cfg(target_os = "windows")]
mod windows;
// Generic fallback for all non-Windows platforms (and used as fallback by macos/linux).
#[cfg(not(target_os = "windows"))]
mod unix;

use crate::entry::Entry;
use crate::error::Error;
use crate::walk::StorageHint;
use std::path::Path;

/// Scan a single directory, returning one [`Entry`] per item.
/// Symlinks are included as entries but not followed. Returned entries have
/// only the filename in `relative_path` and `depth` 0.
pub fn scan_dir(path: &Path) -> Result<Vec<Entry>, Error> {
    scan_dir_prefixed(path, "", StorageHint::Local)
}

/// Like [`scan_dir`] but accepts a [`StorageHint`] to tune platform-level I/O
/// for local vs network-attached storage.
pub fn scan_dir_with_hint(path: &Path, hint: StorageHint) -> Result<Vec<Entry>, Error> {
    scan_dir_prefixed(path, "", hint)
}

/// Like `scan_dir` but prepends `prefix + MAIN_SEPARATOR` to each entry's `relative_path`
/// in a single allocation, avoiding a separate path-building step in the walker.
pub(crate) fn scan_dir_prefixed(
    path: &Path,
    prefix: &str,
    hint: StorageHint,
) -> Result<Vec<Entry>, Error> {
    #[cfg(target_os = "windows")]
    {
        windows::scan_dir_platform(path, prefix, hint)
    }
    #[cfg(target_os = "macos")]
    {
        macos::scan_dir_platform(path, prefix, hint)
    }
    #[cfg(target_os = "linux")]
    {
        linux::scan_dir_platform(path, prefix, hint)
    }
    #[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
    {
        unix::scan_dir_platform(path, prefix, hint)
    }
}