btrfs_uapi/lib.rs
1//! # btrfs-uapi: typed Rust wrappers around the btrfs kernel interface
2//!
3//! This crate provides typed, safe access to the btrfs kernel interface.
4//! Kernel communication uses two mechanisms:
5//!
6//! - **ioctls** for most operations (balance, scrub, subvolume management, ...)
7//! - **sysfs** under `/sys/fs/btrfs/<uuid>/` for status that the kernel does
8//! not expose via ioctl (quota state, commit statistics, scrub speed limits)
9//!
10//! ## Safety
11//!
12//! All `unsafe` code is confined to the [`raw`] module, which contains
13//! bindgen-generated types from the kernel UAPI headers (`btrfs.h` and
14//! `btrfs_tree.h`) and `nix` ioctl macro declarations for every `BTRFS_IOC_*`
15//! call.
16//!
17//! Every other module wraps [`raw`] into a public API that is entirely safe,
18//! exposes no kernel types, and uses idiomatic Rust types throughout:
19//! `BorrowedFd`, `Uuid`, `bitflags`, `SystemTime`, `CString`, and so on.
20//!
21//! ## Usage
22//!
23//! Every function that issues an ioctl takes a [`BorrowedFd`][`std::os::unix::io::BorrowedFd`]
24//! open on any file within the target btrfs filesystem. Functions in [`sysfs`]
25//! instead take a [`uuid::Uuid`], which can be obtained from
26//! [`filesystem::filesystem_info`].
27//!
28//! Most ioctl-based operations require `CAP_SYS_ADMIN`.
29//!
30//! ## Portability
31//!
32//! btrfs is Linux-only; this crate does not support other operating systems.
33//! Some ioctls used here were introduced in relatively recent kernel versions;
34//! this crate targets modern kernels (5.x and later) and does not attempt to
35//! detect or work around missing ioctls on older kernels. It is only tested
36//! on `amd64`, but all architectures supported by the kernel (and Rust) should
37//! work.
38
39#![warn(missing_docs)]
40#![warn(clippy::pedantic)]
41#![allow(clippy::module_name_repetitions)]
42
43pub mod balance;
44pub mod blkdev;
45pub mod chunk;
46pub mod dedupe;
47pub mod defrag;
48pub mod device;
49pub mod features;
50pub mod fiemap;
51pub mod filesystem;
52pub mod inode;
53pub mod quota;
54#[allow(missing_docs)]
55pub mod raw;
56pub mod replace;
57pub mod scrub;
58pub mod send_receive;
59pub mod space;
60pub mod subvolume;
61pub mod sysfs;
62pub mod tree_search;
63pub mod util;