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
32mod stream;
33
34#[cfg(feature = "receive")]
35mod receive;
36#[cfg(feature = "receive")]
37mod verity;
38
39#[cfg(feature = "receive")]
40pub use receive::ReceiveContext;
41pub use stream::{StreamCommand, StreamReader, Timespec};