Introduction

btrfsutils is a Rust implementation of the btrfs filesystem utilities. It provides three command-line tools: btrfs, for managing and inspecting btrfs filesystems; btrfs-mkfs, for creating new ones; and btrfs-tune, for offline superblock tuning. All three aim to be drop-in replacements for the tools provided by btrfs-progs.

Most commands are fully implemented and produce output matching the C reference. The explicit goal is to be drop-in compatible with the reference implementation, with additional features. This is currently in a beta (pre-1.0) version, so it should not be used in production, but the commands that are implemented are thoroughly tested and can be assumed to be correctly implemented.

It also provides library crates that can be used to access kernel APIs to manage btrfs filesystems, decode and write on-disk structures and decode and handle the btrfs send format.

Source Code

The source is available on github and gitlab.

Installation

While these tools are still in their beta (pre-1.0 release) phase, you can already install them and try them out. Currently, the recommended way to install them is using Cargo, there are no binary builds to download.

Cargo

If you have cargo installed, you can install the utilities with it.

cargo install btrfs-cli
cargo install btrfs-tune
cargo install btrfs-mkfs

Nix

If you use Nix with flakes enabled, you can run the tool directly without installing it:

nix run github:rustutils/btrfsutils -- filesystem show /mnt

Or install it into your profile:

nix profile install github:rustutils/btrfsutils

From source

See Building from Source for instructions on compiling btrfsutils yourself from the repository.

Requirements

btrfsutils runs on Linux. Most commands that interact with a mounted filesystem require CAP_SYS_ADMIN (i.e. root, or a process with that capability granted). The exceptions are btrfs inspect-internal dump-super and dump-tree, which only require read access to the block device or image file.

Building from Source

Prerequisites

You need a Rust toolchain matching the version in rust-toolchain.toml — running rustup toolchain install in the project directory will pick it up automatically. You also need clang and libclang for bindgen, which generates Rust bindings from the kernel UAPI headers at build time.

On Fedora/RHEL:

sudo dnf install clang

On Debian/Ubuntu:

sudo apt install clang libclang-dev

Building with Cargo

cargo build --release

The resulting binaries are target/release/btrfs, target/release/btrfs-mkfs, and target/release/btrfs-tune.

Building with Nix

The project includes a Nix flake that provides a fully reproducible build with all dependencies pinned:

nix build

Outputs land in result/bin/btrfs, result/bin/btrfs-mkfs, result/bin/btrfs-tune, and result/share/man/man1/.

To enter a development shell with all tools available (including nightly rustfmt, cargo-insta, and cargo-llvm-cov):

nix develop

Contributors who want to run the full lint sweep (just check) on a non-Nix machine may also need a host-arch musl cross-compiler — see the “Static checks” section of the testing guide for setup instructions.

Concepts

This page defines the terms used throughout the btrfs documentation and command output.

Filesystem

A btrfs filesystem is a single logical storage pool. It has a UUID and an optional human-readable label, and it can span one or more physical block devices. All data and metadata stored in the filesystem is distributed across its devices according to the configured RAID profiles.

A filesystem is accessed by mounting it at a path. Most btrfs commands take that mount point (or any path within it) as their argument.

Device

A device is a block device — a disk partition or a whole disk — that belongs to a filesystem. Every filesystem has at least one device. Additional devices can be added or removed while the filesystem is mounted, allowing online capacity changes.

Subvolume

A subvolume is an independently managed subtree within a filesystem. It looks like a directory, but it has its own inode namespace and can be snapshotted, sent, or deleted independently from the rest of the filesystem.

When you mount a btrfs filesystem, you are mounting one of its subvolumes (the default subvolume, unless you specify otherwise). Other subvolumes appear as directories within it but can also be mounted directly with the subvol= or subvolid= mount options.

Snapshot

A snapshot is a copy-on-write copy of a subvolume taken at a point in time. It initially shares all of its data with the source subvolume; pages diverge as either copy is written. Snapshots can be read-write or read-only. Read-only snapshots are required for btrfs send.

Chunk

btrfs divides storage into chunks — large, contiguous regions of logical address space (typically 256 MiB for metadata, 1 GiB for data). Each chunk is backed by one or more physical stripes on the underlying devices, according to the RAID profile in use. The mapping from logical addresses to physical device locations is stored in the chunk tree.

Extent

An extent is a contiguous run of bytes within a chunk. File data is stored in data extents; the B-trees that make up btrfs metadata are stored in metadata extents. btrfs uses copy-on-write: modifying data creates a new extent rather than overwriting the old one, which is what makes snapshots cheap.

Generation

Every committed transaction increments the filesystem’s generation number. Subvolumes track the generation at which they were last modified (their generation) and the generation at which they were originally created (their ogeneration, or original generation). These are used by tools like btrfs subvolume find-new to identify recently changed files, and by btrfs send to select an appropriate incremental parent.

qgroup

A quota group (qgroup) tracks and optionally limits the amount of space used by a set of subvolumes. qgroups can be nested into a hierarchy, which allows shared space (space that would not be freed even if one subvolume were deleted) to be accounted at the group level. Quotas must be enabled on the filesystem before qgroups can be used.

Commands

btrfsutils implements the same command structure as the upstream btrfs tool. Commands are organized into groups:

btrfs filesystem

Manage and inspect mounted filesystems.

btrfs subvolume

Create and manage subvolumes and snapshots.

btrfs device

Manage devices in a multi-device filesystem.

btrfs balance

Rebalance data and metadata across devices or profiles.

Balance filters (-d, -m, -s) accept filter strings such as usage=50,profiles=raid1|single.

btrfs scrub

Verify data and metadata checksums.

btrfs replace

Replace a device in a filesystem.

btrfs send / receive

Stream filesystem data between systems.

btrfs send supports full sends and incremental sends (-p parent, -c clone sources). btrfs receive supports v1, v2 (compressed data), and v3 (fs-verity) stream formats.

btrfs inspect-internal

Low-level inspection tools.

dump-super and dump-tree read directly from a block device or image file and do not require a mounted filesystem or elevated privileges.

btrfs quota / qgroup

Manage filesystem quotas.

btrfs property

Get and set filesystem object properties.

Supported properties: ro (subvolumes), label (filesystem/device), compression (inodes).

btrfs restore

Recover files from a damaged or unmounted filesystem by reading on-disk structures directly.

Supports regular files, directories, symlinks (-S), extended attributes (-x), metadata (owner/mode/times with -m), and compressed extents (zlib/zstd/lzo). Use --path-regex to filter restored files and -s to include snapshots.

btrfs rescue

Emergency recovery tools for damaged filesystems.

btrfs rescue chunk-recover has argument parsing scaffolded but is not yet implemented.

btrfs-mkfs

Create a new btrfs filesystem on a block device or image file.

btrfs-mkfs [options] <device> [device...]

Supports single-device and multi-device filesystems with all RAID profiles (SINGLE, DUP, RAID0, RAID1, RAID1C3, RAID1C4, RAID10, RAID5, RAID6), all four checksum algorithms (crc32c, xxhash, sha256, blake2b), quota and simple quota setup, custom nodesize/sectorsize, labels, UUIDs, feature flags, and directory population via --rootdir.

btrfs-tune

Modify btrfs filesystem parameters on an unmounted device.

btrfs-tune [options] <device>

Global flags

These flags are accepted by all btrfs commands:

Output Format

Many commands accept a --format json which will cause them to output JSON-formatte data.

Differences from btrfs-progs

btrfsutils aims to be a drop-in replacement for btrfs-progs. Most commands produce identical output and accept the same flags. This page lists the known gaps and the features that go beyond what btrfs-progs offers.

What’s not yet supported

These features from btrfs-progs are not yet implemented:

• btrfs check --repair and related write-mode flags (--init-csum-tree, --init-extent-tree, etc.). Read-only checking works.
• btrfs check --mode lowmem (currently only the default mode is supported).
• btrfs rescue chunk-recover. Other write-mode rescue subcommands (fix-device-size, clear-space-cache, clear-uuid-tree, clear-ino-cache, fix-data-checksum) are implemented.
• btrfs filesystem resize --offline.
• btrfs-mkfs zoned device support.
• btrfs-tune --convert-to-free-space-tree and --convert-to-block-group-tree.

What’s added beyond btrfs-progs

These features are original additions not present in the C tools:

• --format modern (or BTRFS_OUTPUT_FORMAT=modern): opt-in improved output with adaptive column widths and tree views. Supported by most tabular commands including device stats, device usage, subvolume list, inspect list-chunks, filesystem du/df/show/usage, qgroup show, quota status, scrub start/status.
• btrfs filesystem du --depth N: limit display depth while computing full totals.
• btrfs filesystem du --sort: sort entries by path, total, exclusive, or shared.
• btrfs inspect list-chunks --offline: read chunks directly from an unmounted device or image file without CAP_SYS_ADMIN.
• btrfs inspect min-dev-size --offline: compute minimum device size from an unmounted device or image file.
• btrfs device stats --offline: read device error statistics from the on-disk device tree without requiring a mounted filesystem.

Architecture

Crate structure

The project follows a strict layering: lower crates have no knowledge of the layers above them.

btrfs-uapi wraps kernel ioctls, sysfs reads, and procfs reads into safe Rust APIs. It is Linux-only and the only crate that talks directly to the kernel.

btrfs-disk parses on-disk structures — superblocks, B-tree nodes, item payloads — from raw byte buffers. It is platform-independent and does not depend on btrfs-uapi, so it can be used to inspect filesystem images on any OS.

btrfs-stream parses the btrfs send stream wire format. The core parser is platform-independent. The optional receive feature is Linux-only and applies a parsed stream to a mounted filesystem via btrfs-uapi.

btrfs-mkfs implements the mkfs.btrfs tool. It constructs B-tree nodes as raw byte buffers and writes them directly to a block device or image file using pwrite. It does not use ioctls.

btrfs-tune implements the btrfstune tool. It modifies on-disk superblock parameters (feature flags, seeding, filesystem UUIDs) on unmounted devices. For lightweight UUID changes it only rewrites the superblock; for full fsid rewrites it traverses every tree block on disk via btrfs-disk.

btrfs-cli implements the btrfs tool. It handles argument parsing via clap, calls into btrfs-uapi and btrfs-disk as needed, and formats all output. Optionally, this tool can also embed the btrfs-tune and btrfs-mkfs tools as subcommands, for easier single-file deployment.

The two-layer model

Every feature that involves kernel communication is split across two layers. The uapi/ layer provides a safe Rust function: it takes typed arguments, calls the ioctl, and returns a typed result, with no unsafe in the public API and no knowledge of CLI concerns. The cli/ layer provides a clap subcommand that calls into uapi/ and formats the result for the user, with no ioctl calls or raw kernel types.

This rule applies to all kernel interfaces — btrfs ioctls, standard VFS ioctls like FS_IOC_FIEMAP, and block device ioctls like BLKGETSIZE64 all live in uapi/, never in cli/.

The same principle applies to disk/: it parses raw bytes into typed structs, and cli/ handles all display formatting. The disk/ crate never calls println!.

How Commands Work

Every command in btrfsutils is implemented across two layers: a safe kernel interface wrapper in btrfs-uapi, and a CLI command in btrfs-cli. This page walks through a concrete example — btrfs filesystem label — to show how the two layers fit together and why the split exists.

The uapi layer

The uapi layer lives in uapi/src/. Its job is to translate between Rust types and the raw kernel interfaces — allocating ioctl argument buffers, calling the ioctl, and converting the result into something the rest of the code can use without touching any unsafe code or bindgen types.

For btrfs filesystem label, that looks like this (from uapi/src/filesystem.rs):

#![allow(unused)]
fn main() {
pub fn label_get(fd: BorrowedFd) -> nix::Result<CString> {
    let mut buf = [0i8; BTRFS_LABEL_SIZE as usize];
    unsafe { btrfs_ioc_get_fslabel(fd.as_raw_fd(), &mut buf) }?;
    let cstr = unsafe { CStr::from_ptr(buf.as_ptr()) };
    Ok(cstr.to_owned())
}

pub fn label_set(fd: BorrowedFd, label: &CStr) -> nix::Result<()> {
    let bytes = label.to_bytes();
    if bytes.len() >= BTRFS_LABEL_SIZE as usize {
        return Err(nix::errno::Errno::EINVAL);
    }
    let mut buf = [0i8; BTRFS_LABEL_SIZE as usize];
    for (i, &b) in bytes.iter().enumerate() {
        buf[i] = b as c_char;
    }
    unsafe { btrfs_ioc_set_fslabel(fd.as_raw_fd(), &buf) }?;
    Ok(())
}
}

The function signatures use BorrowedFd rather than a raw integer, CString rather than a byte array, and nix::Result rather than checking errno manually. The caller never sees btrfs_ioctl_* types. The unsafe is contained to the ioctl call itself, with surrounding logic that is safe and testable.

The cli layer

The CLI layer lives in cli/src/. Its job is to parse arguments, call the uapi function, and format the output. It never calls ioctls directly.

The same command in cli/src/filesystem/label.rs:

#![allow(unused)]
fn main() {
#[derive(Parser, Debug)]
pub struct FilesystemLabelCommand {
    /// The device or mount point to operate on
    pub path: PathBuf,
    /// The new label to set (if omitted, the current label is printed)
    pub new_label: Option<OsString>,
}

impl Runnable for FilesystemLabelCommand {
    fn run(&self, _format: Format, _dry_run: bool) -> Result<()> {
        let file = open_path(&self.path)?;
        match &self.new_label {
            None => {
                let label = label_get(file.as_fd())
                    .with_context(|| format!("failed to get label for '{}'", self.path.display()))?;
                println!("{}", label.to_bytes().escape_ascii());
            }
            Some(new_label) => {
                let cstring = CString::new(new_label.as_bytes())
                    .context("label must not contain null bytes")?;
                label_set(file.as_fd(), &cstring)
                    .with_context(|| format!("failed to set label for '{}'", self.path.display()))?;
            }
        }
        Ok(())
    }
}
}

The struct derives Parser from clap — the field doc comments become the help text. Runnable::run handles the two cases (get and set) by opening the path, calling the appropriate uapi function, and either printing the result or reporting an error. Error messages include the path so the user knows which filesystem failed.

Why the split

The separation keeps each layer focused and independently testable. The uapi layer can be tested with unit tests that mock the ioctl, or with integration tests that operate on a real filesystem, without any CLI machinery involved. The CLI layer can be tested with argument parsing snapshot tests (no filesystem needed at all) and help text snapshot tests.

It also keeps the library crates clean. Because btrfs-uapi, btrfs-disk, and btrfs-stream contain no CLI logic and no GPL-derived code, they can be licensed MIT/Apache-2.0 and used by other projects independently of the CLI tools.

Routing

Each top-level command group has a router in cli/src/ (e.g. cli/src/filesystem.rs) that defines a FilesystemCommand enum with a variant per subcommand. The Runnable implementation for the router matches on the variant and delegates to the subcommand’s own run method. Adding a new subcommand means adding a variant to the enum, a mod declaration, and a run dispatch arm.

Kernel Interfaces

All kernel communication lives in btrfs-uapi. This page describes the patterns used to wrap the three main kernel interface types: ioctls, sysfs, and tree search.

Binding ioctls

Raw bindgen output is in uapi::raw, generated from uapi/src/raw/btrfs.h and btrfs_tree.h. Ioctl wrappers are declared in uapi/src/raw.rs using nix macros:

#![allow(unused)]
fn main() {
ioctl_write_ptr!(btrfs_ioc_resize, BTRFS_IOCTL_MAGIC, 3, btrfs_ioctl_vol_args);
ioctl_read!(btrfs_ioc_fs_info, BTRFS_IOCTL_MAGIC, 31, btrfs_ioctl_fs_info_args);
ioctl_readwrite!(btrfs_ioc_balance_v2, BTRFS_IOCTL_MAGIC, 32, btrfs_ioctl_balance_args);
ioctl_none!(btrfs_ioc_scrub_cancel, BTRFS_IOCTL_MAGIC, 28);
ioctl_write_int!(btrfs_ioc_balance_ctl, BTRFS_IOCTL_MAGIC, 33);
}

The macro to use is determined by the ioctl direction in the C header:

Flexible array member ioctls

Some ioctls return variable-length arrays (e.g. btrfs_ioctl_space_args with a trailing spaces[] field). The pattern is a two-phase call:

1. Call with zero slots to get the count from the kernel.
2. Allocate a Vec<u64> (for 8-byte alignment) sized to base_size + count * item_size.
3. Cast the vec’s pointer to the struct type, set the slot count, call again.
4. Read results via __IncompleteArrayField::as_slice(count).

See uapi/src/space.rs for a worked example.

The btrfs_ioctl_vol_args_v2 union

Several subvolume and device ioctls share btrfs_ioctl_vol_args_v2. Bindgen generates two anonymous union fields:

• __bindgen_anon_1 — the {size, qgroup_inherit} / unused[4] union
• __bindgen_anon_2 — the name[4040] / devid / subvolid union

#![allow(unused)]
fn main() {
// Set a name:
let name_buf: &mut [c_char] = unsafe { &mut args.__bindgen_anon_2.name };

// Set devid (no unsafe needed for plain integer writes):
args.flags = BTRFS_DEVICE_SPEC_BY_ID as u64;
args.__bindgen_anon_2.devid = devid;
}

Tree search (BTRFS_IOC_TREE_SEARCH)

The tree search ioctl is the primary way to read data from btrfs B-trees from userspace. It is wrapped in uapi/src/tree_search.rs as a callback-based cursor:

#![allow(unused)]
fn main() {
tree_search(fd, SearchFilter::for_type(tree_id, item_type), |hdr, data| {
    // hdr: SearchHeader — objectid, offset, item_type, len (host byte order)
    // data: &[u8] — raw on-disk item payload (little-endian)
    Ok(())
})?;
}

Common SearchFilter constructors:

#![allow(unused)]
fn main() {
// All items of a specific type across all objectids:
SearchFilter::for_type(raw::BTRFS_CHUNK_TREE_OBJECTID as u64,
                       raw::BTRFS_CHUNK_ITEM_KEY as u32)

// Items of a specific type within an objectid range:
SearchFilter::for_objectid_range(tree_id, item_type, min_oid, max_oid)
}

For searches spanning multiple item types (e.g. the quota tree walk that reads STATUS, INFO, LIMIT, and RELATION keys in one pass), construct SearchFilter directly with start and end Key values spanning the desired type range.

Important: The start and end keys form compound bounds on the B-tree key order (objectid, item_type, offset). They are not independent per-field filters. Items with unexpected types can appear if their compound key falls between start and end. Callbacks should filter on hdr.item_type when they need a single type.

Bindgen type note

Tree objectid constants from btrfs_tree.h bind as u32 in Rust despite being ULL in C (e.g. BTRFS_ROOT_TREE_OBJECTID: u32 = 1). Always cast at the use site. BTRFS_LAST_FREE_OBJECTID binds as i32 = -256; cast to u64 gives 0xFFFFFFFF_FFFFFF00 as expected.

Cursor advancement

This is the most common source of bugs with tree search. The kernel interprets (min_objectid, min_type, min_offset) as a compound tuple key, not three independent range filters. After each batch, all three fields must be advanced together past the last returned item:

• Normal case (offset does not overflow u64): set min_objectid = last.objectid, min_type = last.item_type, min_offset = last.offset + 1.
• Offset overflow: set min_offset = 0, keep min_objectid = last.objectid, set min_type = last.item_type + 1.
• Type also overflows u32: set min_offset = 0, min_type = 0, min_objectid = last.objectid + 1.

Advancing only min_offset while leaving min_objectid unchanged causes items from lower objectids to match the new minimum on every subsequent batch, producing an infinite loop.

Sysfs

Some data is read from sysfs rather than ioctls — for example, scrub throughput limits and quota state. The SysfsBtrfs type in uapi/src/sysfs.rs provides typed access to /sys/fs/btrfs/<uuid>/. The filesystem UUID is obtained from fs_info() (BTRFS_IOC_FS_INFO).

Send and Receive

btrfs send and btrfs receive transfer filesystem state between two btrfs filesystems as a byte stream. This page explains how the mechanism works and how to use the btrfs-stream and btrfs-uapi crates to implement receive in your own application.

How send works

btrfs send asks the kernel to generate a stream representing the contents of a read-only subvolume. The kernel traverses the subvolume’s B-trees and emits a sequence of commands describing every file, directory, symlink, and extent. For an incremental send (with -p <parent>), only the differences from the parent subvolume are emitted.

The kernel is invoked via BTRFS_IOC_SEND, which writes the stream to a file descriptor (typically the write end of a pipe). A reader thread on the other end consumes the stream and writes it to a file or stdout.

The stream format

The stream is a binary format consisting of a header followed by a sequence of commands.

The stream header identifies the format version (v1, v2, or v3) and contains a magic number (btrfs-stream\0). After the header, commands follow back-to-back until an END command signals completion.

Each command has the following structure:

u32  total_length    (length of the entire command, including this header)
u16  command_type    (BTRFS_SEND_C_* constant)
u32  crc32c          (checksum of the command, with the crc field zeroed)
     attributes...   (variable-length TLV list)

Attributes are TLV-encoded:

u16  attribute_type  (BTRFS_SEND_A_* constant)
u16  length
     data...

The CRC32C used by btrfs is the raw variant (initial seed 0, no final XOR), not the standard ISO 3309 variant (initial seed 0xFFFFFFFF). When computing or verifying a checksum, use:

#![allow(unused)]
fn main() {
let crc = !crc32c::crc32c_append(!0u32, data);
}

Parsing a stream with btrfs-stream

The btrfs-stream crate provides StreamReader, which parses commands one at a time from any Read source:

#![allow(unused)]
fn main() {
use btrfs_stream::{StreamReader, StreamCommand};

let mut reader = StreamReader::new(input)?; // reads and validates the header
while let Some(command) = reader.read_command()? {
    match command {
        StreamCommand::Subvol { path, uuid, ctransid } => { /* create subvolume */ }
        StreamCommand::MkFile { path } => { /* create file */ }
        StreamCommand::Write { path, offset, data } => { /* write data */ }
        StreamCommand::Rename { path, path_to } => { /* rename */ }
        StreamCommand::End => break,
        // ... all 22+ command types
    }
}
}

StreamReader::new reads the stream header and returns an error if the magic is wrong or the version is unsupported. read_command returns None at EOF.

Applying a stream with btrfs-uapi

To implement receive, you need to apply each command to a mounted btrfs filesystem. The relevant operations are:

Subvolume and snapshot creation (BTRFS_IOC_SUBVOL_CREATE, BTRFS_IOC_SNAP_CREATE_V2): for Subvol commands, create a new empty subvolume. For Snapshot commands, look up the source subvolume by UUID using subvolume_search_by_received_uuid or subvolume_search_by_uuid, then create a writable snapshot.

File operations: standard POSIX calls — open/create, unlink, mkdir, rmdir, symlink, link, rename. btrfs does not require any special ioctls for these.

Write (BTRFS_IOC_ENCODED_WRITE or pwrite): v2 streams may send pre-compressed data via ENCODED_WRITE. If the kernel supports it, this can be passed directly; otherwise decompress and fall back to pwrite.

Clone (BTRFS_IOC_CLONE_RANGE): shares an extent between two files without copying data. The source file is found by resolving its UUID via the UUID tree.

Subvolume finalization: once all commands for a subvolume have been processed, call BTRFS_IOC_SET_RECEIVED_SUBVOL to record the UUID and ctransid, then set the subvolume read-only with BTRFS_IOC_SUBVOL_SETFLAGS.

Using ReceiveContext

If you want a complete, ready-to-use receive implementation rather than building your own, the receive feature of btrfs-stream provides ReceiveContext:

btrfs-stream = { version = "0.5", features = ["receive"] }

#![allow(unused)]
fn main() {
use btrfs_stream::ReceiveContext;

let mut ctx = ReceiveContext::new(destination_dir)?;
ctx.receive(input_stream)?;
}

ReceiveContext handles all command types including v2 encoded writes (with decompression fallback for zlib, zstd, and lzo) and v3 fs-verity. It uses an fd cache to avoid reopening the same file for sequential writes, which is important for performance when receiving large files.

Parsing

The btrfs-disk crate parses btrfs on-disk structures from raw byte buffers. It is platform-independent — it works on any OS and can be used to inspect filesystem images without a running kernel.

Reading a filesystem

The typical entry point is filesystem_open, which bootstraps from the superblock:

superblock → sys_chunk_array → chunk tree → root tree

The returned OpenFilesystem contains a BlockReader (for reading tree blocks by logical address) and a map of tree root locations. From there, tree_walk traverses any tree in BFS or DFS order, calling a visitor callback for each block:

#![allow(unused)]
fn main() {
let open = filesystem_open(file)?;
let mut reader = open.reader;
tree_walk(&mut reader, root_bytenr, Traversal::Bfs, &mut |block| {
    // block: &TreeBlock — either a Node (internal) or Leaf
    Ok(())
})?;
}

Item payloads

Leaf blocks contain items, each with a DiskKey (objectid, type, offset) and a raw payload. parse_item_payload dispatches to a typed parser based on the key type:

#![allow(unused)]
fn main() {
let payload = parse_item_payload(&key, data);
match payload {
    ItemPayload::InodeItem(inode) => { /* ... */ }
    ItemPayload::RootItem(root) => { /* ... */ }
    ItemPayload::FileExtentItem(extent) => { /* ... */ }
    // ...
}
}

Reading on-disk fields safely

On-disk structs are packed and little-endian. Casting a *const u8 pointer directly to a packed struct is undefined behaviour due to potential misalignment.

btrfs-disk: bytes::Buf / bytes::BufMut

The disk crate uses the bytes crate for all parsing and serialization. A &[u8] implements Buf, so you can read fields sequentially with methods like get_u64_le(), which advances the cursor automatically:

#![allow(unused)]
fn main() {
let mut buf = data;
let generation = buf.get_u64_le();
let size = buf.get_u64_le();
let mode = buf.get_u32_le();
}

For serialization, BufMut provides the inverse (put_u64_le, put_slice, etc.). This approach avoids manual offset arithmetic and makes it impossible to read past the end of the buffer (it panics instead of silently producing garbage).

btrfs-uapi: offset-based LE readers

The uapi crate parses tree search results returned by the kernel, which are raw &[u8] buffers at known offsets. It uses explicit offset-based helpers from uapi/src/util.rs:

#![allow(unused)]
fn main() {
use btrfs_uapi::util::read_le_u64;
use std::mem::offset_of;

let size = read_le_u64(data, offset_of!(raw::btrfs_inode_item, size));
}

Always use std::mem::offset_of! and std::mem::size_of to derive offsets and sizes from the bindgen struct definitions — never hard-code numeric byte offsets. The field_size!(T, field) macro (from crate::util) gives the size of an individual field.

Superblock mirrors

btrfs writes up to three superblock copies at fixed offsets. super_mirror_offset(n) returns the byte offset for mirror n (0, 1, or 2). read_superblock reads and validates a superblock — checking the magic number and CRC — from any seekable reader.

Display logic belongs in cli/

The disk/ crate only produces typed structs. All formatting and human-readable output lives in cli/src/inspect/. The disk/ crate never calls println! or constructs output strings.

Testing

The goal for this project is to maintain a high test coverage, to make sure that these tools function correctly.

Running tests

Running the tests for this project is complicated by the fact that many btrfs operations talk directly to the kernel and require elevated privileges.

You can run all non-privileged tests with regular cargo test commands. This will still build the privileged tests, but they are skipped.

cargo test

In order to run privileged tests, there is a just target that will build them, and run (only the test binaries, not cargo itself) using sudo. This is the recommended way to run the full test suite on this project.

just test

You can build a coverage report (requires cargo-llvm-cov) of the full test suite similarly, using the coverage target.

just coverage
# open target/coverage/llvm-cov/html/index.html

Static checks

Before committing, run just check. This wraps the formatter check (nightly rustfmt), cargo deny, taplo for Cargo.toml formatting, cargo doc (with -Dwarnings), cargo clippy --all-features, per-libc cargo check for the host arch, the optional CLI features, and cargo msrv verify against every publishable crate’s declared rust-version.

The host-arch detection means just check works on x86_64 and aarch64 alike. The musl half (<host>-unknown-linux-musl) needs a matching C cross-compiler on PATH, since the zstd-sys and lzo-sys build scripts compile C code:

• Nix devshell (nix develop) provides everything; you don’t need any of the steps below.

• Fedora aarch64: dnf install musl-gcc ships musl-gcc as a thin wrapper around the host gcc plus musl specs. cc-rs looks for the target-prefixed aarch64-linux-musl-gcc name, so symlink it once:

  sudo ln -s /usr/bin/musl-gcc /usr/local/bin/aarch64-linux-musl-gcc
  

  (or set CC_aarch64_unknown_linux_musl=musl-gcc and AR_aarch64_unknown_linux_musl=ar if you prefer to avoid touching /usr/local/bin.)

• Debian / Ubuntu: apt install musl-tools (host arch) or one of the gcc-<arch>-linux-musl-cross packages for cross builds; same target-prefix handling applies if cc-rs doesn’t pick it up automatically.

If the cross C compiler isn’t on PATH, just check prints skipping <triple> check: <prefix>-linux-musl-gcc not on PATH and keeps going — only CI is expected to fail on a missing musl toolchain.

Unit tests

Unit tests live as #[cfg(test)] mod tests blocks within the module they test. They require no privileges and run with cargo test.

Coverage spans all pure logic across the crates: LE readers, struct size assertions, tree search cursor arithmetic, stream parsing (all 22 v1 command types, CRC validation), superblock parsing, B-tree node parsing, size/time formatting, argument parsing helpers, balance filter parsing, and property classification.

When adding a new feature, add unit tests for any logic that doesn’t require a real kernel or filesystem.

Integration tests

Integration tests live in uapi/tests/ and cli/tests/commands/ and are marked:

#![allow(unused)]
fn main() {
#[ignore = "requires elevated privileges"]
}

They are skipped by cargo test and run only via just test.

Fixture tests (commands/fixture.rs)

Read-only snapshot tests against a pre-built filesystem image (cli/tests/commands/fixture.img.gz). The image has a fixed UUID, label, and subvolume layout, so output is fully deterministic. These tests cover all read-only commands: filesystem df/show/usage/label/du, subvolume list/show, device stats/usage, all inspect-internal commands, and property get/list.

dump-tree and dump-super tests read the image file directly and do not require mounting, so they run without elevated privileges even within the privileged test suite.

Live tests (commands/live.rs)

Tests that create and mutate real btrfs filesystems on loopback devices. These cover all mutating commands: subvolume create/delete/snapshot, send/receive, scrub, balance, device add/remove, quota, qgroup, label set, resize, defrag, replace, and more.

Test helpers

cli/tests/common.rs provides RAII helpers that clean up automatically on drop:

BackingFile → LoopbackDevice → Mount

Convenience functions:

Snapshot testing with insta

CLI output tests use insta for snapshot testing. Snapshots live in cli/tests/snapshots/ and are checked in to the repository.

Four snapshot categories:

Snapshot workflow

# Run tests; fails if any snapshot has changed:
cargo test

# Run tests and collect pending snapshot changes:
cargo insta test

# Interactively review each changed snapshot:
cargo insta review

# Accept all pending changes at once:
cargo insta accept --all

After running privileged tests via just test, the Justfile fixes ownership of any root-owned snapshot files and sets INSTA_WORKSPACE_ROOT so snapshots land in the right directory.

Adding tests for a new subcommand

1. Argument parsing: add cases to cli/tests/arguments.rs following the existing pattern.
2. Help text: cli/tests/help.rs auto-discovers all subcommands by walking the clap tree — no changes needed.
3. Read-only output: if the fixture image has suitable content, add snapshot tests to commands/fixture.rs.
4. Mutating commands: add tests to commands/live.rs using the RAII helpers.

Use the snap!("description", output) macro for snapshot tests — the description appears in the snapshot file header.

Conventions

The goal is to write idiomatic Rust code that is consistent across the whole codebase. btrfsutils spans several crates with different roles (kernel interface wrappers, on-disk parsers, CLI tools) and each has its own patterns. Following these conventions makes it easier to navigate unfamiliar code and to understand what a function or type is responsible for at a glance.

Where possible, lean on the Rust ecosystem rather than reinventing things: uuid for UUIDs, bitflags for flag sets, nix for syscalls and ioctls, anyhow for error context in the CLI. This keeps the code readable to anyone already familiar with those crates.

Naming

Module names are usually generic nouns. For example, in the uapi crate, the ioctl call wrappers are organized by the thing they operate on, and live in modules like filesystem, device, sync.

For the btrfs-cli crate, the module naming structure matches the subcommand hierarchy. Meaning: the btrfs subvolume create command is implemented in cli/src/subvolume/create.rs.

Types are named with the general concept first: SysfsBtrfs, BlockGroupFlags, BalanceArgs — never BtrfsSysfs.

Functions follow a noun_verb pattern: label_get, label_set — never get_label. Ioctl wrapper functions match the lowercased C macro name: btrfs_ioc_balance_v2.

Avoid abbreviations. For example, use ChecksumType instead of CsumType.

Types

Always prefer proper typed values. For example, use Uuid from the uuid crate, never [u8; 16]. In the CLI, if there is an argument that can take one of multiple options, don’t represent it as a string, but instead create an enum and derive clap::ValueEnum.

Null-terminated kernel strings (labels, device paths) use CString/CStr. Make sure that allocation and deallocation is handled properly.

File descriptors passed to uapi functions use BorrowedFd.

Kernel flag fields use bitflags!, usually with a Display implementation so they can be formatted with {}.

Complex argument structs (BalanceArgs, DefragRangeArgs) use the builder pattern with new(), chained setters, and Default.

Never expose bindgen types (btrfs_ioctl_*) in public uapi APIs, instead create idiomatic Rust structs.

Error handling

In uapi/, almost every function just performs a single syscall, so we return the raw nix::Result<T>. Where possible, list potential error codes and their meanings in the documentation comments.

Map specific errnos to Option or a typed error at the call site where appropriate (ENODEV → None, etc.).

In cli/, mkfs/, and tune/, use anyhow::Result<T> and convert at the uapi boundary with .with_context(). Always include the relevant path or resource in the error message.

Constants

All BTRFS_* constants are available via crate::raw::* in the uapi and disk crates. Unless you have a good reason to, import from crate::raw and don’t define local copies. Size constants like SZ_1M that are not part of the btrfs UAPI headers are the exception; define those locally with a comment.

There should not be any stray constants in the code. For example, use std::mem::offset_of!() or std::mem::size_of!() macros to compute offsets and sizes, and if there are any magic constants, give them a name.

Don’t redefine things that are already defined in crate::raw::*.

Parsing on-disk structures

In disk/ and mkfs/, use bytes::Buf for reading and bytes::BufMut for writing on-disk fields. Sequential get_u64_le() / put_u64_le() calls advance the cursor automatically, eliminating manual offset arithmetic. See the Parsing page for details.

In uapi/, tree search results are parsed with explicit offset-based LE readers (read_le_u64, read_le_u32) from uapi/src/util.rs, since those buffers are accessed at known offsets rather than sequentially.

Style

Keep unsafe blocks as small as possible; non-trivial ones get a // SAFETY: comment. For packed structs, copy fields to locals before taking references to avoid misaligned reference UB. Use escape_ascii() when printing byte strings that may be non-UTF-8. Import symbols used more than once rather than qualifying them at every call site (single-use qualified paths are fine).

Shared CLI helpers live in cli/src/util.rs, these include utilities to format sizes, bytes, time, and parse various types.

Doc comments

In uapi/, module-level docs start with a # heading describing the module’s purpose. Function docs explain what the function does and why; the ioctl name is a parenthetical in the implementation, not the primary description.

In cli/, don’t put doc comments on subcommand enum variants — clap uses the variant doc in preference to the struct doc, forcing duplication. Don’t use Markdown in clap struct doc comments: wrap_help reflows all text and destroys formatting. Use plain prose paragraphs instead.

Btrfs On-Disk Format Specification

This document describes the binary layout of btrfs on-disk structures as understood from the parser in disk/src/ and the serializer in mkfs/src/. All multi-byte integer fields are little-endian. All byte offsets in this document are zero-based unless noted otherwise.

Kernel header names are referenced in parentheses where helpful (e.g. btrfs_super_block, btrfs_header). The authoritative source is the Linux kernel UAPI headers btrfs.h and btrfs_tree.h.

Conventions used in this document:

• “LE u64” means a 64-bit unsigned integer stored in little-endian byte order.
• Byte offsets are from the start of the enclosing structure.
• Field sizes are in bytes unless noted otherwise.
• “Logical address” refers to an address in btrfs’s virtual address space, which must be resolved to a physical device offset via the chunk tree.
• “Physical address” refers to a byte offset on a specific block device.

Overview

Btrfs is a copy-on-write (COW) B-tree filesystem. All persistent data is organized into B-trees, and all B-trees share a single logical address space that is mapped to physical device locations through a chunk/stripe layer.

Architecture: trees within trees

The fundamental architecture is “trees within trees”:

• The superblock (at fixed offsets on disk) bootstraps access to the chunk tree and root tree.
• The chunk tree maps logical addresses to physical device locations. A small subset of the chunk tree is embedded in the superblock to bootstrap access to the full tree.
• The root tree is the directory of all other trees: it contains a ROOT_ITEM for each tree, pointing to that tree’s root block.
• Content trees (FS tree, extent tree, checksum tree, etc.) store the actual filesystem data and metadata.

Copy-on-write semantics

Every modification creates new copies of affected blocks (COW), from the modified leaf up through the root of the tree. The final step atomically updates the superblock to point to the new root tree root. This ensures crash consistency without a journal: at any point, the last successfully written superblock points to a fully consistent tree hierarchy.

The COW property means that tree blocks are never modified in place. Instead:

1. The leaf containing the modified item is written to a new location.
2. The parent node’s key-pointer is updated to reference the new leaf, and the parent is written to a new location.
3. This propagates up to the tree root.
4. The root tree’s ROOT_ITEM is updated with the new root block address.
5. The root tree itself is COWed up to its root.
6. The superblock is written with the new root tree root address.

The generation counter is incremented with each transaction. All blocks written in a transaction share the same generation number.

Shared format

All trees share the same block format (header + items or key-pointers) and the same key structure (objectid, type, offset). The block size (nodesize) is uniform across the filesystem, typically 16384 bytes. The sectorsize (typically 4096 bytes) is the minimum I/O unit for data.

Multi-device support

Btrfs supports multiple devices in a single filesystem. The chunk tree maps logical addresses to physical offsets on specific devices. RAID profiles (SINGLE, DUP, RAID0, RAID1, RAID5, RAID6, RAID10, RAID1C3, RAID1C4) determine how chunks are distributed across devices.

Bootstrap sequence

Reading a btrfs filesystem from a raw device follows this sequence:

1. Read the superblock at offset 64 KiB (try mirrors if primary fails).
2. Parse sys_chunk_array from the superblock to seed the chunk cache with system chunk mappings.
3. Resolve chunk_root through the chunk cache to a physical address.
4. Read the chunk tree root block and all chunk items to populate the full chunk cache.
5. Resolve root (root tree root) through the chunk cache.
6. Read the root tree to discover all other trees via ROOT_ITEM entries.
7. Access any tree by resolving its root block address through the chunk cache.

Superblock

The superblock (btrfs_super_block) is a 4096-byte structure stored at fixed offsets on each device. It is the entry point for reading the filesystem.

Mirror locations

Three copies (mirrors) of the superblock are maintained:

Mirror 0 is always present. Mirrors 1 and 2 are written only if the device is large enough. The offsets are computed as:

mirror 0:  64 KiB
mirror i:  16 KiB << (12 * i)    for i > 0

On read, all mirrors present on the device are checked and the one with the highest valid generation is used.

Binary layout

Total: 4096 bytes (BTRFS_SUPER_INFO_SIZE).

System chunk array bootstrap

The sys_chunk_array field embeds a subset of the chunk tree sufficient to locate the full chunk tree on disk. It contains a sequence of (disk_key, chunk_item) pairs:

For each entry:
  17 bytes   btrfs_disk_key     (objectid, type, offset) -- offset = logical addr
  variable   btrfs_chunk        Chunk item (see Section 8.9)

The array is parsed sequentially until sys_chunk_array_size bytes are consumed. These entries typically contain the SYSTEM chunk(s) that map the chunk tree and root tree blocks.

Backup roots

The super_roots array contains four rotating backup copies of critical tree root pointers. The kernel updates one entry per transaction, cycling through indices 0-3. Each backup root entry (btrfs_root_backup) is 168 bytes:

Superblock checksum

The checksum field (csum, bytes 0..31) covers everything from byte 32 through byte 4095 (inclusive). For CRC32C, the 4-byte result is stored little-endian at bytes 0..3 and bytes 4..31 are zeroed.

The magic number _BHRfS_M (hex 0x4D5F53665248425F) must be present at offset 64 for a valid superblock.

Superblock validity is determined by checking both magic and checksum match. When multiple valid mirrors exist, the one with the highest generation is used.

Tree Block Format

Every B-tree block (node or leaf) is exactly nodesize bytes. The block begins with a 101-byte header (btrfs_header), followed by either item descriptors (leaves) or key-pointer entries (nodes).

Header

Total header size: 101 bytes.

The flags field combines two values:

• Bits 0-55: block flags (BTRFS_HEADER_FLAG_WRITTEN = 1, BTRFS_HEADER_FLAG_RELOC = 2)
• Bits 56-63: backref revision (BTRFS_MIXED_BACKREF_REV = 1 for modern filesystems)

The header checksum covers bytes 32 through nodesize - 1. For CRC32C, the result is stored as a 4-byte LE value at bytes 0..3 with bytes 4..31 zeroed.

Leaf vs node distinction

The level field determines the block type:

• level == 0: leaf block, containing items
• level > 0: internal node, containing key-pointers to child blocks

The maximum tree depth is bounded by the number of key-pointers that fit in a node. For a 16 KiB nodesize, a node holds up to:

max_ptrs = (nodesize - HEADER_SIZE) / KEY_PTR_SIZE
         = (16384 - 101) / 33
         = 493 key-pointers

With 493 children per node, a tree of depth 2 (root node + leaf) can hold 493 * 651 = ~320,000 items. A tree of depth 3 can hold 493^2 * 651 = ~158 million items. In practice, trees rarely exceed depth 3 or 4.

Leaf Format

A leaf block (level 0) contains sorted item descriptors followed by a data area. Item descriptors grow forward from the header; item data grows backward from the end of the block.

+-------------------------------------------+
| Header (101 bytes)                        |
+-------------------------------------------+
| Item descriptor 0  (25 bytes)             |
| Item descriptor 1  (25 bytes)             |
| ...                                       |
| Item descriptor N-1 (25 bytes)            |
+-------------------------------------------+
| (free space)                              |
+-------------------------------------------+
| Item data N-1                             |
| ...                                       |
| Item data 1                               |
| Item data 0                               |
+-------------------------------------------+

Item descriptor

Each item descriptor (btrfs_item) is 25 bytes:

The first 17 bytes form a btrfs_disk_key. The data_offset field is relative to the start of the leaf data area, which begins immediately after the header. To locate item data in the raw block buffer:

absolute_offset = HEADER_SIZE + data_offset

where HEADER_SIZE = 101 bytes.

Data area layout

Item data is packed from the end of the block backward. The first item pushed has its data at the highest offset; subsequent items have data at progressively lower offsets. This means:

• Item descriptors grow forward: HEADER_SIZE + i * 25
• Item data grows backward: starting from nodesize and moving toward the descriptor area

The free space in a leaf is the gap between the end of the last descriptor and the start of the earliest (lowest-offset) item data.

Offset bookkeeping

When building a leaf (as the mkfs LeafBuilder does), the bookkeeping works as follows:

Initial state:
  item_offset = HEADER_SIZE (101)    // next descriptor position
  data_end    = nodesize (16384)     // next data write position

For each item pushed (key, data[N bytes]):
  1. data_end -= N                   // reserve space for item data
  2. Write data at buf[data_end .. data_end + N]
  3. data_offset = data_end - HEADER_SIZE   // relative to header end
  4. Write descriptor at buf[item_offset]:
       key (17 bytes) + data_offset (LE u32) + data_size (LE u32)
  5. item_offset += 25               // advance to next descriptor slot

The available space for additional items is:

space_left = data_end - (item_offset + ITEM_SIZE)

This must accommodate both the 25-byte descriptor and the item data.

Key ordering invariant

Items within a leaf are sorted by their keys in lexicographic order: first by objectid, then by type, then by offset. This invariant is maintained by the B-tree insertion logic and verified by btrfs check.

Capacity

For a 16384-byte leaf, the maximum number of items depends on their data sizes. With zero-length data items (such as TREE_BLOCK_REF or FREE_SPACE_EXTENT), the theoretical maximum is:

max_items = (nodesize - HEADER_SIZE) / ITEM_SIZE
          = (16384 - 101) / 25
          = 651 items

In practice, most items have data payloads that reduce this number significantly.

Node Format

An internal node (level > 0) contains sorted key-pointer entries (btrfs_key_ptr). Each entry points to a child block and records the lowest key in that child’s subtree.

Key-pointer entry

Each key-pointer (btrfs_key_ptr) is 33 bytes:

The first 17 bytes form the btrfs_disk_key representing the lowest key in the child subtree. The generation field is used for consistency checks: when reading the child block, its header generation must match this value.

Layout

+-------------------------------------------+
| Header (101 bytes)                        |
+-------------------------------------------+
| Key-pointer 0  (33 bytes)                 |
| Key-pointer 1  (33 bytes)                 |
| ...                                       |
| Key-pointer N-1 (33 bytes)                |
+-------------------------------------------+
| (unused space to nodesize)                |
+-------------------------------------------+

Key-pointers are sorted by their key in the same lexicographic order as leaf items. The child block referenced by key-pointer i contains all items with keys >= key-pointer[i].key and < key-pointer[i+1].key (or unbounded above for the last pointer).

Key Structure

Every item and key-pointer is addressed by a three-part key (btrfs_disk_key):

Total: 17 bytes.

Lexicographic ordering

Keys are compared as a tuple (objectid, type, offset) in that order. The objectid is compared first; on a tie, type is compared; on a further tie, offset breaks the tie. All comparisons are unsigned integer comparisons.

Field semantics by tree

The meaning of the three key fields varies depending on the tree and item type:

FS tree:

• objectid = inode number (starting at 256 = BTRFS_FIRST_FREE_OBJECTID)
• type = item type (INODE_ITEM, DIR_ITEM, EXTENT_DATA, etc.)
• offset = type-dependent (0 for INODE_ITEM, name hash for DIR_ITEM, file byte offset for EXTENT_DATA, parent inode for INODE_REF, etc.)

Root tree:

• objectid = tree objectid (e.g. 5 for FS_TREE, 256+ for subvolumes)
• type = ROOT_ITEM, ROOT_REF, or ROOT_BACKREF
• offset = 0 for ROOT_ITEM, child/parent tree ID for refs

Extent tree:

• objectid = logical byte address of the extent
• type = EXTENT_ITEM, METADATA_ITEM, or backref type
• offset = extent length (EXTENT_ITEM), level (METADATA_ITEM), or backref-specific (root objectid, parent bytenr, hash)

Chunk tree:

• objectid = BTRFS_FIRST_CHUNK_TREE_OBJECTID (256) for CHUNK_ITEM
• type = CHUNK_ITEM
• offset = logical byte address of the chunk

Device tree:

• objectid = device ID for DEV_EXTENT; BTRFS_DEV_ITEMS_OBJECTID (1) for DEV_ITEM
• type = DEV_EXTENT or DEV_ITEM
• offset = physical offset for DEV_EXTENT; device ID for DEV_ITEM

Checksum tree:

• objectid = BTRFS_EXTENT_CSUM_OBJECTID
• type = EXTENT_CSUM
• offset = logical byte address of the first checksummed sector

Free space tree:

• objectid = block group logical offset (for FREE_SPACE_INFO) or extent start (for FREE_SPACE_EXTENT/BITMAP)
• type = FREE_SPACE_INFO, FREE_SPACE_EXTENT, or FREE_SPACE_BITMAP
• offset = block group length (for INFO) or extent length (for EXTENT/BITMAP)

UUID tree:

• objectid = upper 8 bytes of UUID interpreted as LE u64
• type = UUID_KEY_SUBVOL or UUID_KEY_RECEIVED_SUBVOL
• offset = lower 8 bytes of UUID interpreted as LE u64

Quota tree:

• objectid = packed qgroupid (level << 48) | subvolid
• type = QGROUP_STATUS, QGROUP_INFO, QGROUP_LIMIT, QGROUP_RELATION
• offset = packed qgroupid for relations, 0 otherwise

Key type values

Well-known objectid values

Negative objectids are stored as their unsigned 64-bit two’s complement representation. For example, BALANCE_OBJECTID = -4 is stored as 0xFFFFFFFF_FFFFFFFC.

Trees

Btrfs uses multiple B-trees, each identified by a well-known objectid. The root tree stores a ROOT_ITEM for each tree, pointing to its root block.

Root tree (objectid 1)

The directory of all other trees. Contains:

• ROOT_ITEM for each tree (objectid = tree ID, type = ROOT_ITEM, offset = 0)
• ROOT_REF for parent-to-child subvolume links
• ROOT_BACKREF for child-to-parent subvolume links
• ROOT_TREE_DIR directory entry linking to the default subvolume
• TEMPORARY_ITEM for balance status persistence
• PERSISTENT_ITEM for device statistics and replace status

Extent tree (objectid 2)

Tracks all allocated space (data extents and metadata tree blocks) with reference counting and backreferences. Contains:

• EXTENT_ITEM for data and non-skinny metadata extents
• METADATA_ITEM for skinny metadata extents
• TREE_BLOCK_REF for direct metadata backrefs
• SHARED_BLOCK_REF for shared metadata backrefs (snapshots)
• EXTENT_DATA_REF for direct data backrefs
• SHARED_DATA_REF for shared data backrefs (snapshots)
• BLOCK_GROUP_ITEM for each block group (unless block_group_tree feature)

Chunk tree (objectid 3)

Maps logical address ranges to physical device stripes. Contains:

• CHUNK_ITEM for each chunk (logical-to-physical mapping)
• DEV_ITEM for each device

The chunk tree is bootstrapped from the superblock’s sys_chunk_array.

Device tree (objectid 4)

Tracks per-device physical extent allocations. Contains:

• DEV_EXTENT for each allocated physical range on each device

FS tree (objectid 5, 256+)

Holds the filesystem content for a subvolume. The default subvolume uses objectid 5; additional subvolumes and snapshots use objectids starting at 256. Contains:

• INODE_ITEM for each inode
• INODE_REF / INODE_EXTREF for hard links
• DIR_ITEM for directory entries (keyed by name hash)
• DIR_INDEX for directory entries (keyed by sequence number)
• EXTENT_DATA for file extent descriptors
• XATTR_ITEM for extended attributes
• ORPHAN_ITEM for unlinked but still open inodes

Checksum tree (objectid 7)

Stores per-sector data checksums. Contains:

• EXTENT_CSUM items: each item covers a contiguous range of data sectors, storing an array of per-sector checksums

Quota tree (objectid 8)

Tracks quota group accounting. Contains:

• QGROUP_STATUS (one per filesystem)
• QGROUP_INFO for each qgroup
• QGROUP_LIMIT for each qgroup with limits
• QGROUP_RELATION for parent-child qgroup relationships

UUID tree (objectid 9)

Provides fast UUID-to-subvolume lookups for send/receive. Contains:

• UUID_KEY_SUBVOL mapping subvolume UUID to objectid
• UUID_KEY_RECEIVED_SUBVOL mapping received UUID to objectid

Free space tree (objectid 10)

Tracks free space per block group, replacing the older free space cache (v1). Contains:

• FREE_SPACE_INFO for each block group
• FREE_SPACE_EXTENT for free ranges
• FREE_SPACE_BITMAP for bitmap-tracked regions

Requires the free_space_tree compat_ro feature flag.

Block group tree (objectid 11)

Separates block group items from the extent tree for faster mount times. Contains:

• BLOCK_GROUP_ITEM for each block group

Requires the block_group_tree compat_ro feature flag. When this tree is absent, block group items live in the extent tree.

Data relocation tree (objectid (u64)-9)

A temporary FS tree used during balance to hold relocated data extents. Uses the same item types as a regular FS tree.

RAID stripe tree (objectid 12)

Maps logical extents to per-device physical stripe offsets. Contains:

• RAID_STRIPE items

Requires the raid_stripe_tree incompat feature flag.

Item Types

This section documents the key format and payload layout for each major item type.

INODE_ITEM (type 1)

Key: (inode_number, INODE_ITEM, 0)

Exactly one per inode. Stores POSIX attributes, timestamps, and btrfs-specific flags.

Payload (btrfs_inode_item, 160 bytes):

Each btrfs_timespec is 12 bytes:

Inode flags (bitmask):

INODE_REF (type 12)

Key: (inode_number, INODE_REF, parent_dir_inode)

Hard-link reference from an inode to a directory entry. Multiple refs can be packed into a single item when an inode has several hard links in the same parent directory.

Payload (variable, packed sequence of entries):

For each ref:

Multiple refs are concatenated without padding.

INODE_EXTREF (type 13)

Key: (inode_number, INODE_EXTREF, crc32c(parent_ino, name))

Extended inode reference. Unlike INODE_REF, the parent inode is stored in the struct, allowing references from different parent directories. Requires the extended_iref incompat feature.

Payload (variable, packed sequence):

For each ref:

DIR_ITEM (type 84) / DIR_INDEX (type 96)

Key for DIR_ITEM: (dir_inode, DIR_ITEM, crc32c(name)) Key for DIR_INDEX: (dir_inode, DIR_INDEX, sequence)

Both use the same on-disk format. DIR_ITEM entries are keyed by the CRC32C hash of the filename (raw CRC32C, not standard). DIR_INDEX entries are keyed by a monotonically increasing sequence number for ordered directory iteration.

Multiple entries can be packed into a single DIR_ITEM when names hash to the same value (hash collision).

Payload (btrfs_dir_item, variable, packed sequence):

For each entry:

The location field is a btrfs_disk_key pointing to the target. For regular directory entries, this typically has objectid = target inode, type = INODE_ITEM, offset = 0. For subvolume entries, type = ROOT_ITEM and objectid = the subvolume’s tree objectid.

File type values:

FILE_EXTENT_ITEM (type 108)

Key: (inode_number, EXTENT_DATA, file_byte_offset)

Describes how a range of file bytes maps to on-disk storage. Three extent types exist: inline, regular, and preallocated.

Common header (21 bytes):

Inline extent (type 0):

After the 21-byte header, the remaining bytes in the item are the file data itself. The data length is item_size - 21. For compressed inline extents, the data is compressed and ram_bytes gives the uncompressed size.

Total item size: 21 + data_length.

Regular extent (type 1) and prealloc extent (type 2):

Total item size: 53 bytes.

A disk_bytenr of 0 indicates a hole (sparse region). For compressed extents, disk_num_bytes is the compressed size on disk and ram_bytes is the uncompressed size. The offset field allows referencing into the middle of a shared extent (e.g., after COW of part of a cloned extent).

Prealloc extents (type 2) are reserved but unwritten; reads return zeroes.

EXTENT_ITEM (type 168) / METADATA_ITEM (type 169)

Key for EXTENT_ITEM: (logical_bytenr, EXTENT_ITEM, extent_length) Key for METADATA_ITEM: (logical_bytenr, METADATA_ITEM, level)

Tracks reference counts and backreferences for allocated space. METADATA_ITEM is the “skinny” variant (when skinny_metadata incompat flag is set): the extent length is implicit (= nodesize) and the key offset stores the tree block level instead.

Base payload (btrfs_extent_item, 24 bytes):

Extent flags:

Tree block info (for non-skinny EXTENT_ITEM with TREE_BLOCK flag):

After the base extent item, non-skinny tree block extents include a btrfs_tree_block_info (18 bytes):

This is absent for skinny metadata items (METADATA_ITEM), where the level is encoded in the key offset.

Inline backreferences:

After the extent item header (and tree_block_info if present), zero or more inline backreferences may be packed. Each starts with a 1-byte type tag followed by type-specific data:

Note that for EXTENT_DATA_REF, the 8-byte offset field that normally follows the type byte is absent; the struct fields begin immediately after the type byte:

For other inline ref types, the format is:

For SHARED_DATA_REF, an additional 4 bytes follow:

9       4     count       Number of references (LE u32)

Standalone backreference items

When backreferences do not fit inline in the extent item, they are stored as separate items in the extent tree:

TREE_BLOCK_REF (type 176): Key: (extent_bytenr, TREE_BLOCK_REF, root_objectid). No data payload; the key offset encodes the owning root.

SHARED_BLOCK_REF (type 182): Key: (extent_bytenr, SHARED_BLOCK_REF, parent_bytenr). No data payload; the key offset encodes the parent block.

EXTENT_DATA_REF (type 178): Key: (extent_bytenr, EXTENT_DATA_REF, hash). The hash is computed from (root, objectid, offset) using two CRC32C passes:

high_crc = raw_crc32c(0xFFFFFFFF, root_le_bytes)
low_crc  = raw_crc32c(0xFFFFFFFF, objectid_le_bytes)
low_crc  = raw_crc32c(low_crc,    offset_le_bytes)
hash     = (high_crc << 31) ^ low_crc

Payload (btrfs_extent_data_ref, 28 bytes):

SHARED_DATA_REF (type 184): Key: (extent_bytenr, SHARED_DATA_REF, parent_bytenr). Payload (4 bytes):

EXTENT_OWNER_REF (type 172): Key: (extent_bytenr, EXTENT_OWNER_REF, root_objectid). No data payload. Used with the simple_quota feature.

DEV_ITEM (type 216)

Key: (DEV_ITEMS_OBJECTID [1], DEV_ITEM, devid)

Stored in the chunk tree. Also embedded in the superblock at offset 201.

Payload (btrfs_dev_item, 98 bytes):

CHUNK_ITEM (type 228)

Key: (FIRST_CHUNK_TREE_OBJECTID [256], CHUNK_ITEM, logical_offset)

Maps a range of logical addresses to physical device locations. Stored in the chunk tree and (for system chunks) in the superblock’s sys_chunk_array.

Payload (btrfs_chunk + stripes, variable):

Each stripe entry (btrfs_stripe, 32 bytes):

Total payload size: 48 + num_stripes * 32 bytes.

Chunk type flags (bitmask, same as block group flags):

When no RAID profile bits are set, the chunk is SINGLE profile.

DEV_EXTENT (type 204)

Key: (devid, DEV_EXTENT, physical_offset)

The inverse of a chunk stripe: maps a physical range on a device back to the owning chunk.

Payload (btrfs_dev_extent, 48 bytes):

BLOCK_GROUP_ITEM (type 192)

Key: (logical_offset, BLOCK_GROUP_ITEM, length)

Tracks space usage for a chunk. Stored in the extent tree (or block group tree when the block_group_tree feature is enabled).

Payload (btrfs_block_group_item, 24 bytes):

The flags field uses the same bitmask as chunk type flags (Section 8.9).

ROOT_ITEM (type 132)

Key: (tree_objectid, ROOT_ITEM, 0)

Stored in the root tree. Describes a tree root: its block address, generation, subvolume UUIDs, and timestamps.

Payload (btrfs_root_item, 439 bytes):

The embedded inode_item at the start describes the root directory inode (objectid 256 = BTRFS_FIRST_FREE_OBJECTID for FS trees).

Older filesystems may store a shorter v1 root item without the UUID, transaction, and timestamp fields. The parser handles both formats.

Root item flags:

SUBVOL_DEAD (bit 48, value 0x1000000000000) marks a deleted subvolume pending cleanup.

ROOT_REF (type 156) / ROOT_BACKREF (type 144)

Key for ROOT_REF: (parent_tree_id, ROOT_REF, child_tree_id) Key for ROOT_BACKREF: (child_tree_id, ROOT_BACKREF, parent_tree_id)

Forward and backward references linking subvolumes to their parent directories. Both use the same on-disk format.

Payload (btrfs_root_ref, 18 bytes + name):

FREE_SPACE_INFO (type 198)

Key: (block_group_offset, FREE_SPACE_INFO, block_group_length)

Metadata about free space tracking for a block group.

Payload (btrfs_free_space_info, 8 bytes):

Flags:

FREE_SPACE_EXTENT (type 199)

Key: (start, FREE_SPACE_EXTENT, length)

Represents a contiguous free range within a block group. The item has no data payload; the key itself encodes the start address and length.

FREE_SPACE_BITMAP (type 200)

Key: (start, FREE_SPACE_BITMAP, length)

A bitmap covering a portion of a block group’s address range. The item data is the raw bitmap, where each bit represents one sector of space. Bit set = free, bit clear = allocated.

XATTR_ITEM (type 24)

Key: (inode_number, XATTR_ITEM, crc32c(name))

Extended attribute storage. Uses the same on-disk format as DIR_ITEM (Section 8.4), but with:

• location = zeroed key
• data_len = length of the xattr value
• type = FT_XATTR (8)
• name = xattr name (e.g. user.myattr)
• data = xattr value

EXTENT_CSUM (type 128)

Key: (EXTENT_CSUM_OBJECTID, EXTENT_CSUM, logical_bytenr)

Stores an array of per-sector checksums for a contiguous range of data blocks. The item data is a packed array of checksums, one per sector.

For CRC32C, each checksum is 4 bytes (LE u32), so the item covers item_size / 4 sectors. The logical byte range covered is:

start = key.offset
end   = key.offset + (item_size / csum_size) * sectorsize

QGROUP_STATUS (type 240)

Key: (0, QGROUP_STATUS, 0)

One per filesystem. Tracks the overall state of quota accounting.

Payload (btrfs_qgroup_status_item, 32-40 bytes):

QGROUP_INFO (type 242)

Key: (packed_qgroupid, QGROUP_INFO, 0)

where packed_qgroupid = (level << 48) | subvolid.

Payload (btrfs_qgroup_info_item, 40 bytes):

QGROUP_LIMIT (type 244)

Key: (packed_qgroupid, QGROUP_LIMIT, 0)

Payload (btrfs_qgroup_limit_item, 40 bytes):

QGROUP_RELATION (type 246)

Key: (child_qgroupid, QGROUP_RELATION, parent_qgroupid)

Defines a parent-child relationship between qgroups. No data payload; the relationship is fully encoded in the key.

UUID_KEY_SUBVOL (type 251) / UUID_KEY_RECEIVED_SUBVOL (type 252)

Key: (upper_half_uuid, UUID_KEY_SUBVOL, lower_half_uuid)

Maps a UUID to one or more subvolume objectids. The UUID is split: the upper 8 bytes are stored as a LE u64 in the objectid field, the lower 8 bytes as a LE u64 in the offset field.

Payload (variable, array of u64):

For each associated subvolume:
  8 bytes   subvolid   Subvolume tree objectid (LE u64)

STRING_ITEM (type 253)

Key: (BTRFS_FREE_SPACE_OBJECTID, STRING_ITEM, 0)

Raw byte string. Typically stores the filesystem label in the root tree.

Payload: Raw bytes (length = item data size).

TEMPORARY_ITEM (type 248) / BALANCE_ITEM

Key: (BALANCE_OBJECTID, TEMPORARY_ITEM, 0)

Persists in-progress balance state across reboots.

Payload: The first 8 bytes are balance flags (LE u64). The remainder contains btrfs_balance_args structures for data, metadata, and system filters.

PERSISTENT_ITEM (type 249) / DEV_STATS

Key for device stats: (DEV_STATS_OBJECTID [0], PERSISTENT_ITEM, devid) Key for device replace: (DEV_REPLACE_OBJECTID, DEV_REPLACE, 0)

Device stats payload (40 bytes):

Device replace payload (btrfs_dev_replace_item, 72+ bytes):

ORPHAN_ITEM (type 48)

Key: (ORPHAN_OBJECTID, ORPHAN_ITEM, inode_number)

Marks an inode that has been unlinked but is still open. The item has no data payload. Orphan items are cleaned up on mount or by the kernel’s orphan cleanup thread.

RAID_STRIPE (type 230)

Key: (logical_offset, RAID_STRIPE, length)

Maps logical extents to per-device physical stripe offsets. Requires the raid_stripe_tree incompat feature.

Payload (variable):

Each stripe entry (16 bytes):

Checksums

Btrfs uses two distinct CRC32C computation modes:

Standard CRC32C (on-disk structures)

Used for all on-disk checksums: superblocks, tree block headers, and data checksums (EXTENT_CSUM items).

This is ISO 3309 / Castagnoli CRC32C: seed = 0xFFFFFFFF, result is XORed with 0xFFFFFFFF. Equivalent to the standard crc32c() function in most libraries.

checksum = crc32c(data)    // standard ISO 3309 CRC32C

The 4-byte LE result is stored in the checksum field. For superblocks and tree blocks, the checksum covers everything after the 32-byte csum field to the end of the structure.

Raw CRC32C (hash computations)

Used for internal hash computations where the kernel calls crc32c_le() directly:

• Name hashes for DIR_ITEM keys (crc32c(name))
• Name hashes for XATTR_ITEM keys
• Name hashes for INODE_EXTREF keys
• extent_data_ref key hash computation
• Send stream CRC32C

The raw CRC32C passes the seed through without inversion:

raw_crc32c(seed, data) = !crc32c_append(!seed, data)

This is NOT the standard ISO 3309 algorithm. The seed is typically 0xFFFFFFFF (which is ~0u32), but unlike the standard algorithm, the output is not inverted.

Supported checksum algorithms

The csum_type field in the superblock selects the algorithm:

The maximum checksum size is 32 bytes (BTRFS_CSUM_SIZE), which is also the size of the checksum field in headers.

Feature Flags

Feature flags are stored in three fields in the superblock. A filesystem implementation must understand all set flags to correctly operate:

• compat_flags: features that are backward-compatible (no known flags currently defined)
• compat_ro_flags: features compatible for read-only mounting
• incompat_flags: features that are fully incompatible

Incompatible feature flags (incompat_flags)

MIXED_BACKREF (bit 0): Indicates the filesystem uses mixed backref format (revision 1). All modern filesystems set this. Old filesystems without it use revision 0 backrefs.

DEFAULT_SUBVOL (bit 1): Set when a non-default subvolume has been configured as the default mount target via btrfs subvolume set-default.

MIXED_GROUPS (bit 2): Allows data and metadata to share the same block group. Unusual; typically used only on very small filesystems.

COMPRESS_LZO (bit 3): Set when any file on the filesystem uses LZO compression. Once set, it is never cleared.

COMPRESS_ZSTD (bit 4): Set when any file uses Zstandard compression.

BIG_METADATA (bit 5): Set when nodesize > sectorsize, allowing metadata blocks to span multiple sectors. Always set on modern filesystems with the typical 16384-byte nodesize and 4096-byte sectorsize.

EXTENDED_IREF (bit 6): Enables INODE_EXTREF items for inodes with hard links from multiple parent directories. Without this, only INODE_REF is used (keyed by single parent inode, limiting hard links per parent directory).

SKINNY_METADATA (bit 8): Uses METADATA_ITEM (type 169) instead of EXTENT_ITEM (type 168) for tree block extent records. The tree block level is encoded in the key offset, eliminating the separate btrfs_tree_block_info structure and saving 18 bytes per metadata extent item.

NO_HOLES (bit 9): File extents do not require explicit hole entries. Without this flag, holes in sparse files are represented by FILE_EXTENT_ITEM with disk_bytenr = 0; with it, holes are implicit (no item needed for the gap).

METADATA_UUID (bit 10): The metadata_uuid field in the superblock differs from fsid. This allows changing the user-visible filesystem UUID without rewriting every tree block header.

Compatible read-only feature flags (compat_ro_flags)

FREE_SPACE_TREE (bit 0) + FREE_SPACE_TREE_VALID (bit 1): When both are set, the free space tree (objectid 10) is used instead of the legacy free space cache (v1). Both bits must be set for the tree to be considered valid.

VERITY (bit 2): Indicates that fs-verity has been enabled on at least one file, and the filesystem contains VERITY_DESC_ITEM and VERITY_MERKLE_ITEM entries.

BLOCK_GROUP_TREE (bit 3): Block group items are stored in a dedicated block group tree (objectid 11) instead of the extent tree. This improves mount time by avoiding a full extent tree scan to find block groups.

Appendix A: Transaction Model

Btrfs uses a generation-based transaction model. Each transaction is identified by a monotonically increasing generation counter stored in the superblock.

Transaction commit

A transaction commit involves:

1. All modified tree blocks are written to new locations (COW). Each block’s header records the current generation.
2. The superblock is updated with:
   • Incremented generation
   • New root (root tree root address)
   • New chunk_root (if chunk tree changed)
   • Updated bytes_used and total_bytes
   • Rotated super_roots backup entry
3. The superblock is written to all mirrors that fit on the device.

The superblock write is the atomic commit point. If the system crashes before the superblock is fully written, the previous superblock (with the previous generation) remains valid and the filesystem rolls back to that state.

Generation consistency

The generation field appears in multiple places, all of which must be consistent:

• Superblock generation: the current transaction counter
• Tree block header generation: must equal the generation when the block was last COWed
• Node key-pointer generation: must match the child block’s header generation (used for read-time validation)
• ROOT_ITEM.generation: the generation when the tree was last modified
• Backup root *_gen fields: generation of each tree root at backup time

When reading a tree, the kernel validates that each block’s generation matches the expected generation from its parent’s key-pointer. A mismatch indicates corruption or a torn write.

Superblock flag: CHANGING_FSID

The BTRFS_SUPER_FLAG_CHANGING_FSID flag (bit 2 of flags) is set during an offline fsid rewrite operation. If the system crashes while this flag is set, the rewrite must be completed or rolled back on the next access. This provides crash safety for the multi-block fsid change operation.

Appendix B: Size Constants

Appendix C: Logical-to-Physical Address Resolution

All tree block addresses and extent addresses in btrfs are logical addresses. To read a logical address from disk, it must be resolved to a physical device offset through the chunk tree.

The resolution process:

1. Bootstrap: Parse the superblock’s sys_chunk_array to seed an initial chunk cache with system chunk mappings.

2. Read the chunk tree: Using the system chunk mappings, resolve superblock.chunk_root to a physical address and read the chunk tree. Add all CHUNK_ITEM entries to the cache.

3. Resolve: For any logical address, find the chunk whose range contains that address. The physical address is:

   physical = stripe.offset + (logical - chunk.logical)
   

   For SINGLE and DUP profiles, any stripe yields a valid copy. For RAID1, all stripes hold identical copies. For RAID0/5/6/10, stripe index calculation is needed.

4. Read the root tree: Using the full chunk cache, resolve superblock.root to a physical address and read the root tree. From here, all other trees can be located via their ROOT_ITEM entries.

Appendix D: File Data Layout

A regular file’s on-disk data is described by a sequence of FILE_EXTENT_ITEM entries in the FS tree, keyed by (inode, EXTENT_DATA, file_offset).

Inline extents: Small files (typically < sectorsize) store their data directly in the tree leaf. No separate disk allocation is needed.

Regular extents: Larger files reference data stored in data chunks. The extent is described by disk_bytenr (logical address) and disk_num_bytes (on-disk size). The offset field allows partial references into shared extents (e.g., after COW or clone operations).

Compressed extents: When compression is enabled, the compression field is nonzero, disk_num_bytes is the compressed size, and ram_bytes is the uncompressed size. Inline compressed extents store the compressed data directly in the item.

Sparse files: With the NO_HOLES feature, gaps between extent items are implicit holes. Without it, explicit hole entries with disk_bytenr = 0 fill the gaps.

The file size is stored in INODE_ITEM.size and is authoritative even if the extent items would suggest a different range.

Extent sharing and cloning

When a file extent is cloned (via cp --reflink or BTRFS_IOC_CLONE), both the source and destination inodes reference the same on-disk extent via their FILE_EXTENT_ITEM entries. The reference count in the extent tree’s EXTENT_ITEM is incremented.

The offset field in FILE_EXTENT_ITEM allows each reference to start at a different position within the shared extent:

File A:  [--- extent X (offset=0, num_bytes=4096) ---]
File B:  [--- extent X (offset=2048, num_bytes=2048) ---]

Both reference the same disk_bytenr, but File B starts reading 2048 bytes into the extent.

Compression type encoding

The compression field in FILE_EXTENT_ITEM uses these values:

When compression is used with inline extents, the stored data is compressed and the inline data size may differ from ram_bytes.

Appendix E: Subvolume and Snapshot Model

Subvolumes

Each subvolume is an independent FS tree with its own tree objectid (5 for the default, 256+ for user-created subvolumes). The root tree stores:

• A ROOT_ITEM for each subvolume, recording the root block address, generation, UUIDs, and timestamps.
• ROOT_REF / ROOT_BACKREF pairs linking parent and child subvolumes.

Snapshots

A snapshot is a subvolume created by COWing the root block of another subvolume. At creation time, the snapshot shares all tree blocks with the source. As either the source or snapshot is modified, shared blocks are COWed on demand, gradually diverging.

The parent_uuid field in ROOT_ITEM links a snapshot back to its source subvolume. The received_uuid field tracks the source across send/receive operations.

Subvolume deletion

Deleted subvolumes are marked with the SUBVOL_DEAD flag in their ROOT_ITEM.flags. The kernel cleans up the tree blocks asynchronously, tracking progress via the drop_progress key and drop_level fields.

Read-only snapshots

A subvolume can be made read-only by setting the SUBVOL_RDONLY flag in ROOT_ITEM.flags. This is required for send operations (the source subvolume must be read-only).

Appendix F: Name Hashing

Directory entries (DIR_ITEM) and extended attributes (XATTR_ITEM) are keyed by a CRC32C hash of the name. The hash uses raw CRC32C (see Section 9.2) with seed ~0:

hash = raw_crc32c(0xFFFFFFFF, name_bytes)

This hash determines the key offset for the DIR_ITEM. If two names hash to the same value (collision), their DIR_ITEM entries are packed into a single item, concatenated one after another.

DIR_INDEX entries use a monotonically increasing sequence number instead of a hash, providing deterministic iteration order independent of name hashing.

For INODE_EXTREF, the hash combines the parent inode number and name:

hash = raw_crc32c(raw_crc32c(0xFFFFFFFF, parent_ino_le_bytes), name_bytes)

Appendix G: Block Group and Chunk Relationship

The relationship between chunks, block groups, and device extents forms the space allocation layer:

Chunk (chunk tree)
  |
  +-- maps logical range [L, L+length) to physical stripes
  |   on one or more devices
  |
  +-- Block Group (extent tree or block group tree)
  |     tracks used/free space within the logical range
  |     type flags must match the chunk type
  |
  +-- Device Extent(s) (device tree)
        one per stripe, maps physical range back to the chunk

Allocation order: mkfs creates chunks by:

1. Choosing a physical region on each device (creating device extents)
2. Assigning a logical address range (creating the chunk item)
3. Creating a block group covering the logical range
4. For the free space tree, creating a FREE_SPACE_INFO and initial FREE_SPACE_EXTENT entries

Consistency invariant: For every chunk, there must be:

• Exactly one BLOCK_GROUP_ITEM with matching logical offset and length
• One DEV_EXTENT per stripe, with chunk_offset pointing back to the chunk
• The block group flags must match the chunk type field

These cross-references are verified by btrfs check.

Appendix H: Default Feature Set

A modern btrfs filesystem created by mkfs.btrfs (or this project’s btrfs-mkfs) typically has the following features enabled:

Incompatible features:

• MIXED_BACKREF (bit 0) – always set
• BIG_METADATA (bit 5) – set because nodesize (16384) > sectorsize (4096)
• EXTENDED_IREF (bit 6) – enables extended inode references
• SKINNY_METADATA (bit 8) – compact metadata extent records
• NO_HOLES (bit 9) – implicit holes in sparse files

Compatible read-only features:

• FREE_SPACE_TREE (bit 0) – free space tracking tree
• FREE_SPACE_TREE_VALID (bit 1) – free space tree is valid

These are the extref, skinny-metadata, no-holes, and free-space-tree features referenced in mkfs output.

Default parameters:

• nodesize = 16384 (16 KiB)
• sectorsize = 4096 (4 KiB), matching the device sector size
• stripesize = 65536 (64 KiB)
• csum_type = 0 (CRC32C)
• Metadata profile: DUP (two copies on the same device)
• Data profile: SINGLE (no redundancy)
• System profile: DUP (for single-device) or RAID1 (for multi-device)

Appendix I: Extent Reference Counting

Btrfs tracks references to every allocated extent (both data and metadata) in the extent tree. The reference count in EXTENT_ITEM.refs (or METADATA_ITEM.refs) records how many times the extent is referenced.

Metadata extents

A metadata extent (tree block) is referenced by key-pointers in parent nodes. When a snapshot is created, the snapshot initially shares all tree blocks with the source. Each shared block has refs >= 2. When either tree COWs a shared block, the old block’s refcount is decremented and the new copy gets refs = 1.

Backreferences track which tree(s) own each block:

• TREE_BLOCK_REF (inline or standalone): direct ownership by a tree root
• SHARED_BLOCK_REF (inline or standalone): ownership via a parent block that is itself shared between trees

Data extents

A data extent is referenced by FILE_EXTENT_ITEM entries in FS trees. Multiple files (or multiple positions in the same file) can reference the same data extent through reflink cloning.

Backreferences track which file inodes reference each extent:

• EXTENT_DATA_REF (inline or standalone): records (root, inode, offset, count)
• SHARED_DATA_REF (inline or standalone): records (parent_block, count)

Reference count invariant

The refs field must equal the sum of all backreference counts for the extent. btrfs check verifies this invariant by walking the extent tree and cross-referencing with the FS trees.

When refs reaches 0, the extent is freed and its space returned to the block group’s free space pool.

Chunks and Block Groups

This document describes the btrfs chunk and block group system: how the filesystem maps logical addresses to physical device locations, how space is organized into typed block groups, and how these structures relate to each other on disk.

All multi-byte integers in btrfs on-disk structures are little-endian.

Address Spaces

Btrfs uses two distinct address spaces:

Logical address space. Every byte of allocated space in the filesystem has a logical address. Tree node pointers, extent references, block group descriptors, and file extent records all use logical addresses. The logical address space is a flat 64-bit namespace shared across all devices in the filesystem. There is no inherent relationship between a logical address and any particular physical device.

Physical address space. Each device has its own independent physical address space, starting at byte 0. Physical addresses identify actual byte offsets on a block device.

The separation exists for several reasons:

1. Multi-device support. A single logical address can map to stripes on multiple physical devices (RAID1, DUP, RAID0, etc.) without the upper layers of the filesystem needing to know which devices are involved.

2. Relocation. The balance and resize operations can move data between physical locations while logical addresses remain stable. Since all internal pointers use logical addresses, no tree rewriting is needed when physical locations change.

3. Redundancy profiles. The same logical address range can have multiple physical copies (DUP, RAID1) or be striped across devices (RAID0) — this is invisible to everything above the chunk layer.

The mapping between the two address spaces is maintained by three cooperating data structures: chunks (logical to physical), device extents (physical to logical), and block groups (space accounting).

Chunks

A chunk maps a contiguous range of logical addresses to one or more physical locations on devices. Chunks are the fundamental unit of the logical-to-physical translation.

CHUNK_ITEM On-Disk Structure

Chunks are stored in the chunk tree. Each chunk item has a key:

Key: (FIRST_CHUNK_TREE_OBJECTID, CHUNK_ITEM, logical_offset)
      objectid = 256                type = 228    offset = start of logical range

The item payload is a btrfs_chunk structure followed by an array of btrfs_stripe structures:

btrfs_chunk (48 bytes):

btrfs_stripe (32 bytes each, num_stripes entries):

The total item size is 48 + num_stripes * 32 bytes.

Logical-to-Physical Resolution

To resolve a logical address to a physical location:

1. Find the chunk whose logical range contains the address. The chunk tree is a B-tree keyed by (256, CHUNK_ITEM, logical_offset), so a lookup finds the entry with the largest logical_offset <= target.

2. Verify the address falls within the chunk: logical_offset <= target < logical_offset + length.

3. Compute the offset within the chunk: within = target - logical_offset.

4. For simple profiles (SINGLE, DUP, RAID1): the physical address on stripe i is stripe[i].offset + within.

5. For striped profiles (RAID0, RAID10, RAID5, RAID6): the stripe index and offset within the stripe are computed from within, stripe_len, and num_stripes/sub_stripes.

The ChunkTreeCache in disk/src/chunk.rs implements this as a BTreeMap keyed by logical start address, with resolve() returning the physical offset on the first stripe (sufficient for SINGLE, DUP, and RAID1 reads).

Chunk Ownership

The owner field in the chunk item is always BTRFS_EXTENT_TREE_OBJECTID (2). This is a historical artifact — it does not mean the extent tree “owns” the chunk in any meaningful sense. The chunk tree is its own independent tree (tree objectid 3) with its root pointer stored directly in the superblock.

Block Groups

A block group is the unit of space management in btrfs. Each block group corresponds to exactly one chunk and tracks how much of that chunk’s space is used. Block groups carry type information that determines what kind of data can be stored in them.

BLOCK_GROUP_ITEM On-Disk Structure

Block group items are stored either in the extent tree (traditional layout) or in the dedicated block-group tree (when the BLOCK_GROUP_TREE compat_ro feature is enabled).

Key: (logical_offset, BLOCK_GROUP_ITEM, length)
      objectid = chunk start    type = 192    offset = chunk length

The item payload is a btrfs_block_group_item (24 bytes):

Type Flags

The flags field is a bitfield combining a chunk type (what gets stored) and a RAID profile (how it is stored):

Chunk type bits (mutually exclusive in practice):

The kernel also supports DATA|METADATA (0x005) for the mixed-bg feature, where data and metadata share block groups.

RAID profile bits:

For example, a metadata block group using DUP has flags 0x024 (METADATA | DUP). A system block group with no profile bits set is SYSTEM|single (0x002).

The BlockGroupFlags type in disk/src/items.rs represents these flags as a bitflags struct with methods type_name() (returns “Data”, “Metadata”, “System”, etc.) and profile_name() (returns “RAID1”, “DUP”, “single”, etc.).

Block Group to Chunk Relationship

Every block group has a 1:1 correspondence with a chunk. The block group’s key (logical_offset, BLOCK_GROUP_ITEM, length) must match a chunk item’s (256, CHUNK_ITEM, logical_offset) with matching length. The block group’s flags must agree with the chunk item’s type field.

This invariant is verified by btrfs check (see section 8).

Device Extents

Device extents are the inverse mapping of chunks: they record which ranges of physical space on each device are allocated to which chunks.

DEV_EXTENT On-Disk Structure

Device extents are stored in the device tree (tree objectid 4).

Key: (devid, DEV_EXTENT, physical_offset)
      objectid = device ID    type = 204    offset = start byte on device

The item payload is a btrfs_dev_extent (48 bytes):

Relationship to Chunks and Stripes

For each stripe in a chunk item, there is a corresponding device extent. If a chunk at logical address L has num_stripes stripes, then:

• Stripe 0: (stripe[0].devid, DEV_EXTENT, stripe[0].offset) with chunk_offset = L and length = chunk.length (for SINGLE/DUP/RAID1).

• Stripe 1 (for DUP/RAID1): (stripe[1].devid, DEV_EXTENT, stripe[1].offset) with chunk_offset = L and length = chunk.length.

For a DUP metadata chunk on a single device, both stripes have the same devid but different physical offsets, producing two device extents on the same device.

Device Items

Each device in the filesystem also has a DEV_ITEM in the chunk tree:

Key: (DEV_ITEMS_OBJECTID, DEV_ITEM, devid)
      objectid = 1              type = 216    offset = device ID

The item payload is a btrfs_dev_item (98 bytes):

The bytes_used field is the sum of the lengths of all device extents on that device. A copy of the device item for device 1 is also embedded in the superblock.

The Bootstrap Problem

Circular Dependency

To read any tree, you need to resolve logical addresses to physical offsets, which requires the chunk tree. But the chunk tree is itself stored at a logical address that needs resolution. This creates a circular dependency.

sys_chunk_array

Btrfs solves this with the sys_chunk_array — a 2048-byte buffer embedded directly in the superblock. This array contains a subset of the chunk tree: specifically, the chunk items for SYSTEM-type block groups.

The SYSTEM block group contains the chunk tree’s root block. By parsing the sys_chunk_array, the filesystem driver can locate the chunk tree on disk without needing a chunk tree to find it.

The array format is a packed sequence of (btrfs_disk_key, btrfs_chunk) pairs:

sys_chunk_array[0..sys_chunk_array_size]:
  repeat {
    btrfs_disk_key (17 bytes):
      objectid: u64_le      (always FIRST_CHUNK_TREE_OBJECTID = 256)
      type:     u8           (always CHUNK_ITEM = 228)
      offset:   u64_le       (logical offset of the chunk)
    btrfs_chunk + stripes:
      (same format as the chunk item payload described in section 2.1)
  }

The sys_chunk_array_size field in the superblock records how many bytes of the 2048-byte buffer are valid.

Bootstrap Sequence

The full bootstrap sequence for reading a btrfs filesystem is:

1. Read the superblock at the primary offset (64 KiB). Verify the magic number, checksum, and fsid. The superblock provides:

   • sys_chunk_array + sys_chunk_array_size
   • chunk_root (logical address of the chunk tree root)
   • root (logical address of the root tree root)
   • nodesize, sectorsize, csum_type

2. Parse the sys_chunk_array to build an initial ChunkTreeCache. This cache contains only the SYSTEM chunk(s), which is enough to resolve the chunk tree root address.

3. Read the chunk tree starting from chunk_root. For each CHUNK_ITEM found, add the mapping to the ChunkTreeCache. After this step, the cache can resolve any logical address in the filesystem.

4. Read the root tree starting from root. This tree contains ROOT_ITEM entries for every other tree (extent, device, FS, csum, free-space, etc.), providing their root block logical addresses.

5. Read any other tree by looking up its ROOT_ITEM in the root tree and using the ChunkTreeCache to resolve addresses.

The seed_from_sys_chunk_array() function in disk/src/chunk.rs implements step 2. The BlockReader in disk/src/reader.rs orchestrates the full bootstrap sequence.

RAID Profiles

The RAID profile determines how a chunk’s logical space maps to physical device locations. The profile affects num_stripes, sub_stripes, and the interpretation of stripe entries.

SINGLE

num_stripes = 1
sub_stripes = 0

One stripe, one device. Logical offset maps 1:1 to a physical offset on a single device. No redundancy.

Logical:   [--------chunk------]
Physical:  [dev1: stripe 0     ]

DUP

num_stripes = 2
sub_stripes = 0

Two stripes on the same device at different physical offsets. Both stripes contain identical data. Provides protection against localized media errors but not device failure.

Logical:   [--------chunk------]
Physical:  [dev1: stripe 0     ]
           [dev1: stripe 1     ]  (different offset, same data)

DUP is the default metadata profile for single-device filesystems. The logical size of the chunk equals one stripe size. The physical space consumed is 2 * stripe_size.

In mkfs, DUP metadata stripes are laid out sequentially after the system group:

Physical layout on device 1:
  [0..1M)          reserved (superblock at 64K)
  [1M..5M)         system chunk (4 MiB)
  [5M..5M+meta)    metadata stripe 0
  [5M+meta..5M+2*meta)  metadata stripe 1
  [5M+2*meta..)    data stripe 0

RAID1

num_stripes = 2  (RAID1C3: 3, RAID1C4: 4)
sub_stripes = 0

One stripe per device, each containing identical data. RAID1 uses 2 devices, RAID1C3 uses 3, RAID1C4 uses 4.

Logical:   [--------chunk------]
Physical:  [dev1: stripe 0     ]
           [dev2: stripe 1     ]  (same data, different device)

For RAID1 metadata on a 2-device filesystem, mkfs places one stripe on each device at the same physical offset (CHUNK_START):

Device 1: [system][meta stripe 0][data stripe 0]
Device 2:        [meta stripe 1]

RAID0

num_stripes = N  (number of devices)
sub_stripes = 0

Data is striped across N devices in stripe_len-sized (64 KiB) units. No redundancy. The logical chunk size equals N * physical_stripe_size.

Logical:   [--A--][--B--][--C--][--A--][--B--][--C--]
Physical:  dev1: [--A--]       [--A--]
           dev2:        [--B--]       [--B--]
           dev3:               [--C--]       [--C--]

To resolve a logical address within a RAID0 chunk:

1. offset = logical - chunk_start
2. stripe_nr = offset / stripe_len
3. stripe_index = stripe_nr % num_stripes
4. stripe_offset = (stripe_nr / num_stripes) * stripe_len + (offset % stripe_len)
5. Physical address = stripes[stripe_index].offset + stripe_offset

RAID10

num_stripes = N  (must be even, >= 4)
sub_stripes = 2

Striped mirrors: data is striped across N/2 mirror groups, each group having sub_stripes (2) copies. Combines RAID0 throughput with RAID1 redundancy.

RAID5 and RAID6

RAID5: num_stripes = N, sub_stripes = 0, one parity stripe
RAID6: num_stripes = N, sub_stripes = 0, two parity stripes

Data is striped with rotating parity. RAID5 tolerates one device failure; RAID6 tolerates two.

Allocation Sizing

When creating a new filesystem (mkfs), the initial chunk sizes are computed from the total device size. The formulas, implemented in mkfs/src/layout.rs (ChunkLayout::new), are:

System Block Group

Fixed size and position:

• Offset: SYSTEM_GROUP_OFFSET = 1 MiB (0x100000)
• Size: SYSTEM_GROUP_SIZE = 4 MiB (0x400000)
• Profile: always SINGLE
• Contains: the chunk tree root block

The first 1 MiB of the device is reserved. The primary superblock sits at offset 64 KiB within this reserved area.

Metadata Block Group

meta_size = clamp(total_bytes / 10, 32 MiB, 256 MiB)
meta_size = round_down(meta_size, STRIPE_LEN)

where STRIPE_LEN = 64 KiB and total_bytes is the sum across all devices.

The metadata chunk starts at logical offset CHUNK_START = 5 MiB (SYSTEM_GROUP_OFFSET + SYSTEM_GROUP_SIZE). For DUP, two physical stripes are placed sequentially on device 1. For RAID1, one stripe is placed on each of the first two devices.

Examples:

• 256 MiB device: clamp(25.6M, 32M, 256M) = 32 MiB
• 1 GiB device: clamp(102.4M, 32M, 256M) = 102 MiB (rounded to 64K)
• 10 GiB device: clamp(1G, 32M, 256M) = 256 MiB

Data Block Group

data_size = clamp(total_bytes / 10, 64 MiB, 1 GiB)
data_size = round_down(data_size, STRIPE_LEN)

The data chunk follows the metadata chunk in both logical and physical address spaces. Logical offset = CHUNK_START + meta_size.

Examples:

• 256 MiB device: clamp(25.6M, 64M, 1G) = 64 MiB
• 1 GiB device: clamp(102.4M, 64M, 1G) = 102 MiB (rounded to 64K)
• 10 GiB device: clamp(1G, 64M, 1G) = 1 GiB

Minimum Device Size

For a single-device filesystem with DUP metadata and SINGLE data, the minimum physical space needed is:

1 MiB (reserved) + 4 MiB (system) + 2 * meta_size + data_size

With the minimum sizes (meta = 32 MiB, data = 64 MiB), this works out to approximately 133 MiB. A 100 MiB device will fail with “device too small”.

Physical Layout Summary

For a single-device DUP-metadata SINGLE-data filesystem:

Physical byte offset:
  [0 .. 1M)                          Reserved (superblock at 64K)
  [1M .. 5M)                         System block group (4 MiB)
  [5M .. 5M + meta_size)             Metadata stripe 0
  [5M + meta_size .. 5M + 2*meta)    Metadata stripe 1 (DUP copy)
  [5M + 2*meta .. 5M + 2*meta + data)  Data

Logical address space:
  [1M .. 5M)                         System chunk
  [5M .. 5M + meta_size)             Metadata chunk
  [5M + meta_size .. 5M + meta + data)  Data chunk

Note the physical space for DUP metadata is 2 * meta_size, but the logical address range is only meta_size. Both physical stripes map to the same logical range.

Cross-Checks

The btrfs check command (implemented in cli/src/check/chunks.rs) verifies the consistency of the chunk/block-group/device-extent triad.

Chunk-to-Block-Group Check

For every chunk in the chunk tree, there must be a matching block group item. The check walks the chunk tree cache and verifies that block_groups.contains_key(chunk.logical) for each chunk.

If a chunk has no corresponding block group, btrfs check reports:

ChunkMissingBlockGroup { logical }

Block-Group-to-Chunk Check

For every block group item (from the extent tree or block-group tree), there must be a matching chunk. The check verifies that chunk_cache.lookup(bg_logical) succeeds for each block group.

If a block group has no corresponding chunk, btrfs check reports:

BlockGroupMissingChunk { logical }

Device Extent Overlap Check

All device extents for each device are collected from the device tree, sorted by physical offset, and checked for overlaps. For consecutive extents on the same device, the check verifies:

extent[i].offset >= extent[i-1].offset + extent[i-1].length

If two device extents overlap, btrfs check reports:

DeviceExtentOverlap { devid, offset }

Block Group Source

When the BLOCK_GROUP_TREE compat_ro feature is enabled, block group items are stored in a separate tree (tree objectid 10) rather than in the extent tree. The check code handles both cases by selecting the appropriate tree root:

#![allow(unused)]
fn main() {
let bg_root = block_group_tree_root.unwrap_or(extent_root);
}

The Chunk Tree

The chunk tree (tree objectid 3) stores two kinds of items:

1. DEV_ITEM entries for each device in the filesystem: (DEV_ITEMS_OBJECTID=1, DEV_ITEM=216, devid)

2. CHUNK_ITEM entries for each chunk: (FIRST_CHUNK_TREE_OBJECTID=256, CHUNK_ITEM=228, logical_offset)

Items are sorted by key, so DEV_ITEMs (objectid 1) come before CHUNK_ITEMs (objectid 256).

The chunk tree root pointer is stored directly in the superblock’s chunk_root field — it does not go through the root tree like other trees. This is because the chunk tree is needed to read the root tree itself.

mkfs Chunk Tree Construction

When mkfs builds the chunk tree (build_chunk_tree in mkfs/src/mkfs.rs), it creates:

1. One DEV_ITEM per device, with bytes_used set to the sum of all chunk stripes on that device.

2. Three CHUNK_ITEM entries:

   • System chunk at SYSTEM_GROUP_OFFSET (1 MiB), size 4 MiB
   • Metadata chunk at CHUNK_START (5 MiB), with profile-dependent stripes
   • Data chunk after metadata, with profile-dependent stripes

The system chunk item uses sectorsize for io_align and io_width (matching the kernel’s bootstrap behavior), while the metadata and data chunks use STRIPE_LEN (64 KiB).

The Device Tree

The device tree (tree objectid 4) stores:

1. DEV_STATS (PERSISTENT_ITEM) for each device: per-device I/O error counters, initialized to zero by mkfs.

2. DEV_EXTENT entries for each physical stripe of each chunk.

Items are sorted by key: (objectid=devid, type=DEV_EXTENT, offset=physical_byte_offset).

mkfs Device Tree Construction

When mkfs builds the device tree (build_dev_tree in mkfs/src/mkfs.rs), it creates:

1. One DEV_STATS item per device (zeroed counters).

2. Device extents for each stripe:

   • System chunk: one DEV_EXTENT on device 1 at SYSTEM_GROUP_OFFSET
   • Metadata chunk: one DEV_EXTENT per stripe (two for DUP on device 1, or one per device for RAID1)
   • Data chunk: one DEV_EXTENT per stripe

All device tree items are collected, sorted by key, and written in order. This is necessary because items span multiple device IDs and physical offsets that are not naturally ordered by construction.

Superblock Mirrors

The superblock is written at up to three fixed physical offsets on each device:

The formula is: mirror 0 at 65536 bytes; mirror N (N > 0) at 16384 << (12 * N) bytes. Mirrors are only written if the device is large enough to contain them.

The superblock contains the sys_chunk_array bootstrap data, root pointers for the chunk tree and root tree, the embedded device item for device 1, and all filesystem-level metadata (UUID, label, feature flags, generation counter, bytes_used, etc.).

All three mirrors contain identical data for a given generation. On mount, the kernel reads all available mirrors and uses the one with the highest valid generation, providing resilience against corruption of the primary superblock.

Tree Block Placement in mkfs

During filesystem creation, tree blocks must be placed at specific logical addresses within the chunks. The BlockLayout struct in mkfs/src/layout.rs assigns addresses:

Chunk tree block: placed at SYSTEM_GROUP_OFFSET (1 MiB) in the system chunk. This is the only tree block in the system block group.

All other tree blocks (root, extent, device, FS, csum, free-space, data-reloc, and optionally block-group): placed sequentially in the metadata chunk starting at meta_logical = 5 MiB. With a 16 KiB nodesize:

For --rootdir mode, where trees may require multiple blocks, the BlockAllocator hands out sequential addresses from the system and metadata chunks, supporting trees of arbitrary size.

System chunk bytes used = nodesize (one chunk tree block). Metadata chunk bytes used = 7 * nodesize (or 8 with block-group tree).

Extent Tree and Backrefs

This document describes the btrfs extent tree: how every allocated byte on disk is tracked, how reference counting works, and how backreferences link extents to the trees and files that use them.

All multi-byte integers in btrfs on-disk structures are little-endian.

Purpose

The extent tree is the central allocator of the btrfs filesystem. It records every contiguous range of allocated disk space (both data extents used by files and metadata blocks used by trees) and tracks who references each extent.

The extent tree serves three purposes:

1. Allocation tracking. The set of extent items defines which logical byte ranges are in use. The free-space tree (or free-space cache) is derived from the gaps between extent items.

2. Reference counting. Each extent has a declared reference count. Snapshots and clones share extents by incrementing this count rather than copying data. When the count drops to zero, the extent can be freed.

3. Backreferences. Each extent stores references back to the trees, inodes, and file offsets that use it. This enables the filesystem to find all users of an extent (for relocation during balance, for example) and to verify consistency (during btrfs check).

The extent tree is stored in tree objectid 2 (BTRFS_EXTENT_TREE_OBJECTID). Its root pointer is stored in the root tree via a ROOT_ITEM entry.

EXTENT_ITEM vs METADATA_ITEM

There are two key types used to record allocated extents:

EXTENT_ITEM (type 168)

The original extent item format, used for both data and metadata extents.

Key: (bytenr, EXTENT_ITEM, length)
      objectid = logical start    type = 168    offset = size in bytes

For data extents, length is the extent’s size on disk. For metadata extents (tree blocks), length equals the filesystem’s nodesize.

METADATA_ITEM (type 169) — Skinny Metadata

When the SKINNY_METADATA incompat feature is enabled (the default since Linux 3.10), metadata extents use a more compact key:

Key: (bytenr, METADATA_ITEM, level)
      objectid = logical start    type = 169    offset = tree level (0..7)

The extent’s length is implicitly nodesize (not stored in the key). The level field in the key offset records the B-tree level of the tree block, which is useful for verification without reading the block itself.

Skinny metadata items are called “skinny refs” because they eliminate the need for the btrfs_tree_block_info structure that non-skinny EXTENT_ITEM entries for tree blocks carry.

Key Differences

In mkfs, the choice is controlled by the skinny_metadata() config flag:

#![allow(unused)]
fn main() {
let (item_type, offset) = if skinny {
    (BTRFS_METADATA_ITEM_KEY, 0u64)   // level 0 for leaf blocks
} else {
    (BTRFS_EXTENT_ITEM_KEY, nodesize as u64)
};
}

The Extent Item Header

Both EXTENT_ITEM and METADATA_ITEM share the same header structure, btrfs_extent_item (24 bytes):

Extent Flags

The flags field uses these bits:

A data extent has flags = DATA (0x01). A metadata extent has flags = TREE_BLOCK (0x02). The FULL_BACKREF flag is set when the extent uses shared backreferences (after a snapshot) rather than normal tree backreferences.

The ExtentFlags type in disk/src/items.rs represents these flags as a bitflags struct.

Tree Block Info (Non-Skinny Only)

For non-skinny EXTENT_ITEM entries with TREE_BLOCK flag, the header is followed by btrfs_tree_block_info (25 bytes):

This structure is omitted when using METADATA_ITEM (skinny metadata), since the level is stored in the key offset and the first key is not needed.

Full Item Layout

For a skinny metadata extent item with one inline TREE_BLOCK_REF:

For a data extent item with one inline EXTENT_DATA_REF:

Inline Backrefs

After the extent item header (and tree_block_info for non-skinny metadata), zero or more inline backreferences are packed contiguously. Each inline ref starts with a 1-byte type code, followed by type-specific data.

Inline refs are the common case: they are stored directly inside the extent item, avoiding the overhead of separate B-tree items. When an extent item grows too large to fit in a leaf (due to many references), backrefs are stored as standalone items instead.

TREE_BLOCK_REF (type 176)

Direct backref from a metadata extent to the tree that owns it.

The root field identifies the tree that owns this metadata block. For example, root = 5 means the FS tree, root = 2 means the extent tree itself.

Total size: 9 bytes.

SHARED_BLOCK_REF (type 182)

Shared backref from a metadata extent to a parent tree block. Used when a tree block is shared between snapshots — the backref points to a parent node rather than a root.

The parent field is the logical byte address of the tree node that contains a pointer to this extent.

Total size: 9 bytes.

EXTENT_DATA_REF (type 178)

Backref from a data extent to a specific file inode. This is the most common inline ref type for data extents.

Note that unlike other inline ref types, EXTENT_DATA_REF does not have an 8-byte offset field between the type byte and the struct body. The struct starts immediately after the type byte. The parser in disk/src/items.rs handles this by reinterpreting the speculatively consumed offset bytes as the root field:

#![allow(unused)]
fn main() {
raw::BTRFS_EXTENT_DATA_REF_KEY => {
    let root = ref_offset; // already read as u64_le
    let oid = buf.get_u64_le();
    let off = buf.get_u64_le();
    let count = buf.get_u32_le();
    // ...
}
}

The count field represents how many times this particular (root, objectid, offset) triple references the extent. For a normal file with one reference, count = 1. For a file cloned via reflink, each clone adds a new EXTENT_DATA_REF with its own triple and count.

Total size: 29 bytes.

SHARED_DATA_REF (type 184)

Shared data backref, used when data extents are shared between snapshots.

Total size: 13 bytes.

EXTENT_OWNER_REF (type 172)

Simple ownership reference, used with the simple_quota feature. Records which tree root owns the extent without full backref details.

Total size: 9 bytes.

Standalone Backrefs

When inline backrefs do not fit inside the extent item (because the item would exceed the available leaf space), they are stored as separate items in the extent tree. Standalone backrefs use the same type codes as inline refs but are encoded as independent key/value pairs.

Standalone TREE_BLOCK_REF

Key: (bytenr, TREE_BLOCK_REF, root_objectid)
      objectid = extent start    type = 176    offset = owning tree

Item payload: empty (zero bytes). The backref information is entirely in the key.

Standalone SHARED_BLOCK_REF

Key: (bytenr, SHARED_BLOCK_REF, parent_bytenr)
      objectid = extent start    type = 182    offset = parent block

Item payload: empty.

Standalone EXTENT_DATA_REF

Key: (bytenr, EXTENT_DATA_REF, hash)
      objectid = extent start    type = 178    offset = CRC32C hash

The key offset is a hash of (root, objectid, offset) computed by:

#![allow(unused)]
fn main() {
fn extent_data_ref_hash(root: u64, objectid: u64, offset: u64) -> u64 {
    let high_crc = raw_crc32c(!0u32, &root.to_le_bytes());
    let low_crc = raw_crc32c(!0u32, &objectid.to_le_bytes());
    let low_crc = raw_crc32c(low_crc, &offset.to_le_bytes());
    (u64::from(high_crc) << 31) ^ u64::from(low_crc)
}
}

This hash function uses raw CRC32C (seed = !0, i.e. 0xFFFFFFFF, without final complement) applied independently to the root (high part) and objectid+offset (low part), then combined with a shift and XOR.

Item payload (28 bytes):

Standalone SHARED_DATA_REF

Key: (bytenr, SHARED_DATA_REF, parent_bytenr)
      objectid = extent start    type = 184    offset = parent block

Item payload (4 bytes):

Reference Counting

The refs Field

The refs field in btrfs_extent_item is the declared total reference count for the extent. It equals the sum of all references from both inline and standalone backrefs.

For TREE_BLOCK_REF, SHARED_BLOCK_REF, and EXTENT_OWNER_REF, each backref contributes 1 to the total. For EXTENT_DATA_REF and SHARED_DATA_REF, each backref contributes its count field to the total.

Counting Rules

The total reference count is computed as:

total = 0
for each inline ref:
    if EXTENT_DATA_REF:  total += count
    if SHARED_DATA_REF:  total += count
    otherwise:           total += 1
for each standalone ref:
    if EXTENT_DATA_REF:  total += count  (from item payload)
    if SHARED_DATA_REF:  total += count  (from item payload)
    otherwise:           total += 1

The declared refs in the extent item header must equal this computed total. A mismatch indicates corruption.

Example: Simple File

A newly created file with one 4 KiB extent in the FS tree (root 5):

Key: (bytenr, EXTENT_ITEM, 4096)
  refs = 1
  generation = 100
  flags = DATA
  inline EXTENT_DATA_REF:
    root = 5, objectid = 257, offset = 0, count = 1

Total refs: count(1) = 1. Matches declared refs.

Example: Snapshot

After taking a snapshot of the FS tree, the same extent is now referenced by both the original and the snapshot. The extent item is updated:

Key: (bytenr, EXTENT_ITEM, 4096)
  refs = 2
  generation = 100
  flags = DATA
  inline EXTENT_DATA_REF:
    root = 5, objectid = 257, offset = 0, count = 1
  inline EXTENT_DATA_REF:
    root = 260, objectid = 257, offset = 0, count = 1

Total refs: count(1) + count(1) = 2. Matches declared refs.

Example: Reflink Clone

A reflink clone within the same tree adds another backref with a different file offset:

Key: (bytenr, EXTENT_ITEM, 4096)
  refs = 2
  generation = 100
  flags = DATA
  inline EXTENT_DATA_REF:
    root = 5, objectid = 257, offset = 0, count = 1
  inline EXTENT_DATA_REF:
    root = 5, objectid = 258, offset = 0, count = 1

Example: Metadata Block

A metadata block owned by the FS tree:

Key: (bytenr, METADATA_ITEM, 0)    // level 0 = leaf
  refs = 1
  generation = 100
  flags = TREE_BLOCK
  inline TREE_BLOCK_REF:
    root = 5

Data Extent Backrefs in Detail

The EXTENT_DATA_REF Triple

Each data extent backref identifies its user by a (root, objectid, offset) triple:

• root: the tree objectid containing the referencing inode. For user files this is the FS tree (5) or a subvolume/snapshot tree ID.

• objectid: the inode number of the file that references the extent. Regular file inodes start at 257 (BTRFS_FIRST_FREE_OBJECTID + 1).

• offset: the byte offset within the file where this extent is referenced. This is the key offset of the EXTENT_DATA item in the FS tree.

The count Field

The count field records how many times the exact same (root, objectid, offset) triple references this extent. In normal operation, count = 1. It can be greater than 1 in specific scenarios involving log replay or certain reflink patterns.

Hash Computation for Standalone Keys

When an EXTENT_DATA_REF is stored as a standalone item, the key offset is not the file offset but rather a hash of the full triple. This allows multiple data refs with different triples to be stored as separate items under the same extent bytenr.

The hash function (from disk/src/items.rs) computes:

high = CRC32C(seed=0xFFFFFFFF, root_le_bytes)
low  = CRC32C(seed=0xFFFFFFFF, objectid_le_bytes)
low  = CRC32C(seed=low,        offset_le_bytes)
hash = (high << 31) ^ low

This produces a 63-bit hash (the top bit is always the MSB of the high CRC, shifted to bit 62). The hash is deterministic and the same function is used in both the kernel and userspace tools.

Metadata Extent Backrefs in Detail

TREE_BLOCK_REF

A TREE_BLOCK_REF links a metadata block to the tree that owns it. The root field is the tree’s objectid:

• 1 = root tree
• 2 = extent tree
• 3 = chunk tree
• 4 = device tree
• 5 = FS tree (default subvolume)
• 6 = csum tree
• 7 = quota tree
• 10 = free-space tree

• = 256 = subvolume/snapshot trees

SHARED_BLOCK_REF

When a tree block is shared between a subvolume and its snapshot, the normal TREE_BLOCK_REF is replaced with a SHARED_BLOCK_REF that points to the parent node. This happens because the same physical block cannot be “owned” by two different trees simultaneously.

The parent field is the logical bytenr of the tree node whose key pointer array includes this block. When the filesystem needs to modify a shared block, it performs copy-on-write: allocating a new block, copying the data, and updating the parent’s pointer. This is how snapshots achieve their constant-time creation — they share all blocks with the source subvolume.

FULL_BACKREF Flag

The FULL_BACKREF flag in the extent item’s flags field indicates that this metadata extent uses only shared backrefs (no direct tree backrefs). This typically happens for tree blocks at levels > 0 after a snapshot, where the ownership is ambiguous until the block is CoW’d.

Cross-Referencing with Tree Ownership

btrfs check collects a map of (block_address -> owning_tree) during its tree walks. The owning tree for each block is determined by the owner field in the block’s header (btrfs_header). This map is then cross-referenced against the extent tree’s TREE_BLOCK_REF entries in both directions.

Block Group Items in the Extent Tree

Historically, BLOCK_GROUP_ITEM entries are stored directly in the extent tree alongside extent items. With the BLOCK_GROUP_TREE compat_ro feature (default since btrfs-progs 6.x), they are moved to a separate tree (objectid 10).

BLOCK_GROUP_ITEM Structure

Key: (logical_offset, BLOCK_GROUP_ITEM, length)
      objectid = group start    type = 192    offset = group size

Item payload (24 bytes):

The used field tracks how many bytes of the block group are currently allocated to extents. For a new filesystem:

• System block group: used = one nodesize (the chunk tree block)
• Metadata block group: used = N * nodesize (all non-chunk tree blocks)
• Data block group: used = 0 (no file data yet)

Ordering in the Extent Tree

When block group items are in the extent tree, they sort among the extent items by key. Since BLOCK_GROUP_ITEM has type 192 and EXTENT_ITEM has type 168 / METADATA_ITEM has type 169, block group items for a given logical offset sort after any extent item at the same address (because key comparison is (objectid, type, offset) and 192 > 169).

mkfs Construction

mkfs creates three block group items, one for each chunk:

#![allow(unused)]
fn main() {
add_block_group_items(extent_items, cfg, layout, chunks, data_used);
}

This adds entries for the system (SYSTEM flag), metadata (METADATA | profile flag), and data (DATA | profile flag) block groups.

When the BLOCK_GROUP_TREE feature is enabled, these items are placed in a separate tree instead (build_block_group_tree_with_used).

What btrfs check Verifies

The extent tree checker (implemented in cli/src/check/extents.rs) performs several categories of verification.

Reference Count Matching

For each extent item (EXTENT_ITEM or METADATA_ITEM) and its associated standalone backrefs, the checker computes the total reference count from inline + standalone refs and compares it to the declared refs field:

#![allow(unused)]
fn main() {
if state.pending_refs != state.pending_counted {
    results.report(CheckError::ExtentRefMismatch {
        bytenr, expected: state.pending_refs, found: state.pending_counted,
    });
}
}

The checker processes items in key order. When it encounters a new EXTENT_ITEM or METADATA_ITEM, it “flushes” the previous extent (checking its ref count) and begins accumulating refs for the new one. Standalone backref items (TREE_BLOCK_REF, SHARED_BLOCK_REF, EXTENT_DATA_REF, SHARED_DATA_REF, EXTENT_OWNER_REF) that follow an extent item with a matching objectid add to the running count.

Extent Overlap Detection

Extents in the extent tree are sorted by logical address. The checker tracks the end address of the previous extent and reports an error if the next extent starts before the previous one ends:

#![allow(unused)]
fn main() {
if length > 0 && bytenr < state.prev_end && state.prev_end > 0 {
    results.report(CheckError::OverlappingExtent {
        bytenr, length, prev_end: state.prev_end,
    });
}
}

Note that METADATA_ITEM entries store the tree level (not the length) in the key offset. Since the checker does not have access to the nodesize at this point, it uses length = 0 for metadata items and skips overlap detection for them.

Backref Owner Cross-Checks (Direction 1: Walk to Extent)

During tree walks in earlier check phases, the checker builds a map of tree_block_owners: HashMap<u64, u64> mapping each tree block’s logical address to the tree objectid that owns it (from the block header’s owner field).

After processing the extent tree, the checker verifies that every block encountered during walks has an extent item:

#![allow(unused)]
fn main() {
if !state.extent_item_addrs.contains(&addr) {
    results.report(CheckError::MissingExtentItem { bytenr: addr });
}
}

And that the extent tree’s backrefs agree with the actual owner:

#![allow(unused)]
fn main() {
if !claimed_owners.contains(&actual_owner) {
    results.report(CheckError::BackrefOwnerMismatch {
        bytenr: addr, actual_owner, claimed_owners,
    });
}
}

Backref Owner Cross-Checks (Direction 2: Extent to Walk)

The checker also verifies the reverse: every TREE_BLOCK_REF in the extent tree (both inline and standalone) must correspond to a tree block that was actually encountered during walks and is owned by the claimed tree:

#![allow(unused)]
fn main() {
let actual = tree_block_owners.get(&addr).copied();
if actual != Some(claimed) {
    results.report(CheckError::BackrefOrphan {
        bytenr: addr, claimed_owner: claimed,
    });
}
}

This catches “orphan” backrefs that point to blocks that either do not exist or are owned by a different tree than claimed.

Data Byte Accounting

The checker accumulates two statistics from data extents:

• data_bytes_allocated: the sum of length for all data extent items. This is the total physical space reserved for data.

• data_bytes_referenced: the sum of length * count for all data extent references. When data is shared (via snapshots or reflinks), referenced bytes exceed allocated bytes.

For inline-only data refs (no standalone ExtentDataRef items), referenced bytes are computed from the inline ref count. For standalone refs, each EXTENT_DATA_REF and SHARED_DATA_REF item contributes length * count.

Extent Item Construction in mkfs

Metadata Extent Items

For each tree block allocated during mkfs, the extent tree receives a metadata extent item with one inline TREE_BLOCK_REF:

#![allow(unused)]
fn main() {
fn metadata_extent_item(addr, skinny, generation, owner, nodesize) -> (Key, Vec<u8>) {
    let (item_type, offset) = if skinny {
        (BTRFS_METADATA_ITEM_KEY, 0u64)     // offset = level 0
    } else {
        (BTRFS_EXTENT_ITEM_KEY, nodesize)    // offset = nodesize
    };
    (
        Key::new(addr, item_type, offset),
        extent_item(1, generation, skinny, owner),
    )
}
}

The extent_item() function serializes:

1. btrfs_extent_item header: refs=1, generation, flags=TREE_BLOCK
2. For non-skinny: zero-filled btrfs_tree_block_info (25 bytes)
3. Inline TREE_BLOCK_REF: type byte (176) + root objectid (8 bytes)

Total item size: 33 bytes (skinny) or 58 bytes (non-skinny).

Data Extent Items

For each data extent written during --rootdir mode, the extent tree receives a data extent item with one inline EXTENT_DATA_REF:

#![allow(unused)]
fn main() {
fn data_extent_item(refs, generation, root, objectid, offset, count) -> Vec<u8> {
    // btrfs_extent_item header
    buf.put_u64_le(refs);
    buf.put_u64_le(generation);
    buf.put_u64_le(BTRFS_EXTENT_FLAG_DATA);
    // inline EXTENT_DATA_REF
    buf.put_u8(BTRFS_EXTENT_DATA_REF_KEY);
    buf.put_u64_le(root);
    buf.put_u64_le(objectid);
    buf.put_u64_le(offset);
    buf.put_u32_le(count);
}
}

Total item size: 53 bytes. The key is (extent_bytenr, EXTENT_ITEM, extent_length).

Self-Referential Convergence

The extent tree must contain entries for its own tree blocks. But the number of tree blocks needed depends on how many items the tree contains, which depends on how many extent items there are, which depends on the number of tree blocks… This creates a circular dependency.

The --rootdir code path solves this with a convergence loop (converge_extent_tree_block_count in mkfs/src/mkfs.rs):

1. Start with extent_tree_block_count = 1.
2. Build a trial extent tree with all items (including placeholder entries for the extent tree’s own blocks).
3. If the trial tree’s actual block count differs from the assumed count, update the count and repeat.
4. The loop converges quickly (usually in 1-2 iterations) because adding extent items for additional blocks only marginally increases the tree size.

After convergence, the real extent tree is built with actual logical addresses assigned by the BlockAllocator.

Extent Tree Key Ordering

Items in the extent tree are sorted by the standard btrfs key comparison (objectid, type, offset). Since objectid is the extent’s logical byte address, items are effectively sorted by logical address.

Within a single extent’s address, the ordering is:

1. EXTENT_ITEM or METADATA_ITEM (type 168 or 169) — the extent header
2. EXTENT_OWNER_REF (type 172) — if simple quotas are enabled
3. TREE_BLOCK_REF (type 176) — standalone metadata backrefs
4. EXTENT_DATA_REF (type 178) — standalone data backrefs
5. SHARED_BLOCK_REF (type 182) — standalone shared metadata backrefs
6. SHARED_DATA_REF (type 184) — standalone shared data backrefs
7. BLOCK_GROUP_ITEM (type 192) — if not using block-group tree

This ordering is a natural consequence of the type field values and ensures that btrfs check can process all backrefs for an extent by reading items sequentially until the objectid (bytenr) changes.

Relationship to File Extents

The connection between the extent tree and actual file data flows through EXTENT_DATA items in FS trees:

FS tree: (inode, EXTENT_DATA, file_offset)
  -> disk_bytenr, disk_num_bytes, offset, num_bytes

Extent tree: (disk_bytenr, EXTENT_ITEM, disk_num_bytes)
  -> refs, generation, flags=DATA
  -> inline EXTENT_DATA_REF(root, inode, file_offset, count)

The disk_bytenr in the file extent item is the logical address of the data extent. The extent tree entry at that address records who references the extent and how many times.

For inline file extents (small files where data is embedded directly in the tree leaf), there is no corresponding extent tree entry — the data does not occupy a separate extent.

For hole/sparse extents (disk_bytenr = 0), there is similarly no extent tree entry. The no-holes feature eliminates explicit hole extent items entirely.

Summary of Key Formats

All bytenr values are logical byte addresses. The extent tree provides the complete picture of space allocation and ownership across the entire filesystem.

Btrfs Transaction Infrastructure: On-Disk Format Specification

This document is the sole reference for implementing the btrfs-transaction crate. It describes the on-disk format, invariants, and protocols needed to safely modify a btrfs filesystem from userspace.

Tree block layout

A btrfs filesystem stores its metadata in a B-tree. Each tree block (also called a node or extent buffer) is nodesize bytes (typically 16,384, but can be 4,096 to 65,536). Tree blocks are identified by their logical byte address (bytenr), which is translated to a physical device offset via the chunk tree.

Every tree block begins with a 101-byte header, followed by either leaf items (level 0) or internal node key pointers (level > 0).

Header (101 bytes)

All multi-byte integers are little-endian on disk.

Key (17 bytes)

Every item and pointer in the B-tree is identified by a three-part key. On disk this is the btrfs_disk_key (little-endian):

Keys are compared as a tuple (objectid, type, offset) in that order, all as unsigned integers. This defines the sort order within every B-tree.

Leaf layout (level 0)

A leaf contains item descriptors that grow forward from the header, and item data payloads that grow backward from the end of the block. Free space is the gap between them.

Byte 0..100:                    Header
Byte 101..101+nritems*25-1:     Item descriptors [item0, item1, ..., itemN-1]
                                (25 bytes each, sorted by key ascending)
  ...free space...
Byte X..nodesize-1:             Item data [dataN-1, ..., data1, data0]
                                (packed from the end of the block backward)

Each item descriptor is 25 bytes:

Invariants:

• Items are sorted by key in ascending order.
• Item data regions must not overlap.
• The last item’s data starts at 101 + item[N-1].offset and extends for item[N-1].size bytes. Items with lower indices have data at higher offsets (data grows backward).
• The first item’s data ends at 101 + item[0].offset + item[0].size, which must be <= nodesize.
• Free space = (101 + item[N-1].offset) - (101 + nritems * 25). When this is < 25 + data_size for a new item, the leaf is full.

Data offset convention:

The offset field in btrfs_item counts from byte 101 (immediately after the header), not from the start of the block. When constructing a new leaf:

1. Start data_end at nodesize.
2. For each item (in key order): data_end -= data.len(), write data at data_end, store offset = data_end - 101 in the item descriptor.
3. Item descriptors are written at 101 + i * 25.

Internal node layout (level > 0)

An internal node contains key pointers that identify child subtrees.

Byte 0..100:                    Header
Byte 101..101+nritems*33-1:     Key pointers [ptr0, ptr1, ..., ptrN-1]
                                (33 bytes each, sorted by key ascending)

Each key pointer is 33 bytes:

Invariants:

• Key pointers are sorted by key in ascending order.
• blockptr must be a valid, allocated logical address.
• generation must match the generation in the child block’s header.

Maximum capacities

For a given nodesize:

• Leaf items per block: depends on item data size. The theoretical maximum number of zero-size items is (nodesize - 101) / 25 = 651 for 16 KiB.
• Key pointers per node: (nodesize - 101) / 33 = 493 for 16 KiB.
• Maximum tree depth: 8 levels (BTRFS_MAX_LEVEL). In practice, trees rarely exceed 3-4 levels.

Superblock

The superblock is the entry point for reading a btrfs filesystem. It is a 4,096-byte structure stored at fixed offsets on every device:

• Mirror 0: byte 65,536 (64 KiB)
• Mirror 1: byte 67,108,864 (64 MiB)
• Mirror 2: byte 274,877,906,944 (256 GiB), only if device is large enough

Superblock layout (4,096 bytes)

Fields updated on every transaction commit

When committing a transaction, the following superblock fields are updated:

1. generation — incremented by 1.
2. root — logical bytenr of the (possibly new) root tree root block.
3. root_level — level of the root tree root.
4. chunk_root — logical bytenr of the chunk tree root (if chunk tree was modified).
5. chunk_root_generation — generation of the chunk tree root.
6. chunk_root_level — level of the chunk tree root.
7. bytes_used — updated to reflect allocations/frees.
8. log_root — set to 0 after log replay, or updated if log is active.
9. super_roots — one of the 4 backup root slots is written (rotating).
10. csum — recomputed last, covering bytes 32..4095.

The commit writes the superblock to all mirrors. The superblock write is the atomic commit point: if power is lost before the superblock is written, the previous generation’s state is intact because COW ensures old blocks are never overwritten (see section 3).

Backup roots (167 bytes each, 4 entries)

The superblock contains 4 rotating backup root entries. On each commit, one slot is overwritten (cycling 0 → 1 → 2 → 3 → 0 → …). These are used for recovery when the primary root pointers are corrupt.

Superblock flags

Feature flags

Incompatible (incompat_flags):