btrfs_stream/lib.rs
1//! # btrfs-stream: btrfs send stream parser and receive operations
2//!
3//! This crate handles the btrfs send stream format: a binary TLV protocol
4//! used by `btrfs send` / `btrfs receive` to serialize and replay filesystem
5//! changes between subvolume snapshots.
6//!
7//! ## Stream parsing (default, platform-independent)
8//!
9//! The default feature set provides a zero-copy stream parser that works on
10//! any platform:
11//!
12//! - [`StreamReader`] reads a btrfs send stream from any `impl Read`,
13//! validates the stream header (magic, protocol version 1-3), and yields
14//! [`StreamCommand`] values with CRC32C integrity checks on every command.
15//! - [`StreamCommand`] is an enum covering all v1, v2, and v3 command types
16//! (subvol, snapshot, write, clone, encoded write, fallocate, enable
17//! verity, and so on).
18//! - [`Timespec`] represents timestamps carried in the stream.
19//!
20//! ## Receive operations (feature `receive`, Linux-only)
21//!
22//! Enable the `receive` feature to get [`ReceiveContext`], which applies a
23//! parsed stream to a mounted btrfs filesystem. It creates subvolumes and
24//! snapshots, writes files, clones extents, sets xattrs and permissions, and
25//! finalizes received subvolumes with their received UUID. It handles v2
26//! encoded writes with automatic decompression fallback (zlib, zstd, lzo)
27//! and v3 fs-verity enablement.
28//!
29//! This feature depends on `btrfs-uapi` for ioctl access and requires
30//! `CAP_SYS_ADMIN` on Linux.
31
32#![warn(clippy::pedantic)]
33#![allow(clippy::module_name_repetitions)]
34// Test code uses literal byte buffers and small cast conversions that
35// pedantic clippy flags but that are intentional in unit tests.
36#![cfg_attr(
37 test,
38 allow(
39 clippy::cast_lossless,
40 clippy::cast_possible_truncation,
41 clippy::cast_possible_wrap,
42 clippy::cast_sign_loss,
43 clippy::identity_op,
44 clippy::match_wildcard_for_single_variants,
45 clippy::semicolon_if_nothing_returned,
46 clippy::unreadable_literal,
47 )
48)]
49
50mod consts;
51mod send;
52mod stream;
53
54#[cfg(feature = "receive")]
55mod receive;
56#[cfg(feature = "receive")]
57mod verity;
58
59#[cfg(feature = "receive")]
60pub use receive::ReceiveContext;
61pub use send::StreamWriter;
62pub use stream::{StreamCommand, StreamError, StreamReader, Timespec};