xfs/error.rs
1//! Error types for the XFS reader.
2
3use thiserror::Error;
4
5/// Errors surfaced while parsing XFS on-disk structures.
6///
7/// Every variant names the offending value so an "unknown/invalid" report hands
8/// the investigator the evidence (raw bytes / offset), never a bare "invalid".
9#[derive(Debug, Error, PartialEq, Eq)]
10#[non_exhaustive]
11pub enum XfsError {
12 /// The buffer was too small to hold the structure being parsed.
13 #[error("buffer too small for {structure}: need {need} bytes, have {have}")]
14 Truncated {
15 /// Name of the structure that could not be read.
16 structure: &'static str,
17 /// Minimum byte length required.
18 need: usize,
19 /// Byte length actually available.
20 have: usize,
21 },
22
23 /// The superblock magic number did not match `XFSB` (`0x5846_5342`).
24 ///
25 /// Carries the four bytes actually found so the caller can identify what the
26 /// image really is (fail-loud with the offending value).
27 #[error("bad superblock magic: found {found:#010x} (bytes {bytes:02x?}), expected 0x58465342 (\"XFSB\")")]
28 BadMagic {
29 /// The 32-bit big-endian value read at offset 0.
30 found: u32,
31 /// The four raw bytes at offset 0.
32 bytes: [u8; 4],
33 },
34
35 /// A directory used a format this reader does not yet handle (leaf / node /
36 /// btree), or a block directory carried an unrecognized data-block magic.
37 ///
38 /// Fail-loud rather than return an empty listing: `detail` names the format
39 /// and the offending value (magic bytes / size), so the investigator sees
40 /// *what* could not be read, never a silently-empty directory.
41 #[error("unsupported directory: {detail}")]
42 UnsupportedDir {
43 /// Human description naming the format and the offending value.
44 detail: String,
45 },
46
47 /// A path component did not resolve during [`crate::read_by_path`]: the named
48 /// component was not found in its parent directory, or a non-final component
49 /// was not itself a directory. Carries the offending path and component.
50 #[error("path not found: component {component:?} of {path:?} did not resolve")]
51 PathNotFound {
52 /// The full path being resolved.
53 path: String,
54 /// The specific component that failed to resolve.
55 component: String,
56 },
57}