hadris_ntfs/
lib.rs

1//! # hadris-ntfs
2//!
3//! A `no_std`-compatible library for reading NTFS filesystems (read-only).
4//!
5//! ## Quick Start
6//!
7//! ```rust,no_run
8//! use std::fs::File;
9//! use hadris_ntfs::sync::{NtfsFs, NtfsFsReadExt};
10//!
11//! let file = File::open("disk.img").unwrap();
12//! let fs = NtfsFs::open(file).unwrap();
13//! let root = fs.root_dir();
14//! let entries = root.entries().unwrap();
15//! for entry in &entries {
16//!     println!("{} ({})", entry.name(), if entry.is_directory() { "dir" } else { "file" });
17//! }
18//! ```
19//!
20//! ## Feature Flags
21//!
22//! | Feature  | Default | Description |
23//! |----------|---------|-------------|
24//! | `std`    | Yes     | Standard library support (enables `alloc`) |
25//! | `alloc`  | Yes     | Heap allocation without full std |
26//! | `sync`   | Yes     | Synchronous API via `hadris-io` sync traits |
27//! | `async`  | No      | Asynchronous API via `hadris-io` async traits |
28//! | `read`   | Yes     | Read operations (requires `alloc`) |
29//!
30//! ## Dual Sync/Async Architecture
31//!
32//! This crate provides both synchronous and asynchronous APIs through
33//! a compile-time code transformation system. The same implementation
34//! source is compiled twice:
35//!
36//! - **`sync`** module: synchronous API (enabled by the `sync` feature)
37//! - **`async`** module: asynchronous API (enabled by `async` feature)
38//!
39//! With the default `sync` and `read` features, the synchronous API types are
40//! re-exported at the crate root for convenience. The `std` feature does not
41//! select an I/O mode.
42//!
43//! ## Supported Scope
44//!
45//! The reader supports validated boot geometry, update-sequence-protected
46//! MFT/index records, resident and non-resident unnamed data, sparse runs,
47//! initialized-size zero filling, directory index allocation/bitmaps, NTFS
48//! filename namespaces, and `$UpCase` collation.
49//!
50//! It does not yet resolve `$ATTRIBUTE_LIST` extension records, recover from
51//! `$MFTMirr`, decode compressed or encrypted streams, expose named alternate
52//! data streams, or interpret reparse points. See the internal compliance
53//! matrix in `docs/spec-coverage.md`.
54
55#![no_std]
56#![allow(async_fn_in_trait)]
57#![allow(clippy::duplicate_mod)]
58#![deny(missing_docs)]
59
60#[cfg(feature = "std")]
61extern crate std;
62
63#[cfg(feature = "alloc")]
64extern crate alloc;
65
66// ---------------------------------------------------------------------------
67// Shared types (compiled once, not duplicated by sync/async modules)
68// ---------------------------------------------------------------------------
69
70#[cfg(feature = "read")]
71pub mod attr;
72pub mod error;
73pub mod raw;
74
75// ---------------------------------------------------------------------------
76// Sync module
77// ---------------------------------------------------------------------------
78
79#[cfg(all(feature = "sync", feature = "read"))]
80#[path = ""]
81pub mod sync {
82    //! Synchronous NTFS filesystem API.
83    //!
84    //! All I/O operations use synchronous `Read`/`Seek` traits.
85
86    pub use hadris_io::Result as IoResult;
87    pub use hadris_io::sync::{Parsable, Read, ReadExt, Seek};
88    pub use hadris_io::{Error, ErrorKind, SeekFrom};
89
90    macro_rules! io_transform {
91        ($($item:tt)*) => { hadris_macros::strip_async!{ $($item)* } };
92    }
93
94    #[allow(unused_macros)]
95    macro_rules! sync_only {
96        ($($item:tt)*) => { $($item)* };
97    }
98
99    #[allow(unused_macros)]
100    macro_rules! async_only {
101        ($($item:tt)*) => {};
102    }
103
104    #[path = "."]
105    mod __inner {
106        pub mod dir;
107        pub mod fs;
108        pub mod io;
109        pub mod read;
110    }
111    pub use __inner::*;
112
113    pub use __inner::dir::{NtfsDir, NtfsEntry};
114    pub use __inner::fs::NtfsFs;
115    pub use __inner::read::{FileReader, NtfsFsReadExt};
116}
117
118// ---------------------------------------------------------------------------
119// Async module
120// ---------------------------------------------------------------------------
121
122#[cfg(all(feature = "async", feature = "read"))]
123#[path = ""]
124pub mod r#async {
125    //! Asynchronous NTFS filesystem API.
126    //!
127    //! All I/O operations use async `Read`/`Seek` traits.
128
129    pub use hadris_io::Result as IoResult;
130    pub use hadris_io::r#async::{Parsable, Read, ReadExt, Seek};
131    pub use hadris_io::{Error, ErrorKind, SeekFrom};
132
133    macro_rules! io_transform {
134        ($($item:tt)*) => { $($item)* };
135    }
136
137    #[allow(unused_macros)]
138    macro_rules! sync_only {
139        ($($item:tt)*) => {};
140    }
141
142    #[allow(unused_macros)]
143    macro_rules! async_only {
144        ($($item:tt)*) => { $($item)* };
145    }
146
147    #[path = "."]
148    mod __inner {
149        pub mod dir;
150        pub mod fs;
151        pub mod io;
152        pub mod read;
153    }
154    pub use __inner::*;
155}
156
157// ---------------------------------------------------------------------------
158// Default re-exports (sync)
159// ---------------------------------------------------------------------------
160
161#[cfg(all(feature = "sync", feature = "read"))]
162pub use sync::*;
163
164pub use error::{NtfsError, Result};
165pub use raw::*;
hadris_ntfs/lib.rs

hadris_ntfs/
lib.rs
