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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
//! On-disk structures: the pure byte layer where a one-byte offset error is a silent
//! corruption.
//!
//! Every btrfs metadata object this crate reads is defined here as a Rust value with symmetric
//! serialization: a `write_to` that produces its little-endian on-disk form and a `read_from`
//! that recovers it. btrfs is little-endian on disk regardless of host byte order, so every
//! field is read and written through an accessor naming its offset, its width, and its byte
//! order rather than through any reinterpret-cast; there is no `unsafe`, no `transmute`, and
//! no `#[repr(C)]` reliance.
//!
//! The layer has six parts, and they stack:
//!
//! - **[`DiskKey`] and [`ItemType`]** — the 17-byte tuple every tree is sorted by, and the
//! byte that says what a record is. Nothing else in the format records an item's kind.
//! - **[`Header`], [`Item`], [`KeyPtr`]** — a tree block, and the two things one may hold.
//! - **[`SuperBlock`], [`RootBackup`], [`DevItem`], [`Chunk`], [`Stripe`], [`DevExtent`],
//! [`DevStats`], [`RootItem`]** — where the filesystem begins, where it began four
//! transactions ago, how logical space maps onto a device and back, and where each of its
//! trees starts.
//! - **[`ExtentItem`], [`InlineRef`], [`BlockGroupItem`], [`FreeSpaceInfo`]** — what is
//! allocated, who holds it, and what is free.
//! - **[`InodeItem`], [`DirItem`], [`FileExtentItem`], [`InodeRef`], [`InodeExtref`],
//! [`RootRef`]** — what a filesystem tree holds: a file's metadata, the names it is known
//! by, where its bytes are, and how a subvolume is reachable. Several of these pack into one
//! item, and [`for_each_packed`] is the one place that framing is bounded.
//! - **[`checksum`] and [`seal`]** — the recipe covering the tree blocks, which the format
//! arranges to be one recipe by giving a superblock and a tree block the same first field,
//! and the writing of it that is the last thing done to either.
//!
//! # What is not here
//!
//! **Validation beyond recovery.** These types recover fields, and report the two things that
//! make recovery impossible: there were not enough bytes, or a structure carrying a signature
//! did not carry the right one. Whether the recovered fields describe a filesystem this crate
//! can read — a node size the format forbids, an `nritems` past what a block could hold, a
//! feature bit nothing here understands — is a separate question with a separate answer,
//! asked one layer out where the answer can name what it would take to read it.
//!
//! **The chunk map.** A [`Chunk`] and its [`Stripe`]s are a mapping written down; turning an
//! address into a place on a device means holding every chunk of the filesystem at once,
//! ordered and checked for overlap, which is [`ChunkMap`](crate::btrfs::ChunkMap)'s job.
//!
//! **A block's own length.** Only the superblock has a fixed width. A tree block is as long as
//! the filesystem's node size, which is a field of the superblock — so every bound over a
//! block is computed from a number the caller holds rather than from a constant here, and a
//! constant would have been right on one filesystem.
//!
//! This module is pure: it moves bytes to and from values and returns numbers. It allocates
//! nothing and performs no I/O.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
/// A failure recovering an on-disk structure from bytes.
///
/// The two variants are the whole of what parsing a btrfs structure can fail on: there were
/// not enough bytes, or the one structure that carries a signature did not carry it.
/// Everything else a reader objects to — a node size the format does not define, an item whose
/// data escapes its leaf, a feature bit nothing here implements — is a judgment about
/// recovered fields rather than a failure to recover them, and is reported by the layer that
/// can say what it means.