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
39pub mod balance;
40pub mod blkdev;
41pub mod chunk;
42pub mod defrag;
43pub mod device;
44pub mod fiemap;
45pub mod filesystem;
46pub mod inode;
47pub mod quota;
48pub mod raw;
49pub mod replace;
50pub mod scrub;
51pub mod send_receive;
52pub mod space;
53pub mod subvolume;
54pub mod sysfs;
55pub mod tree_search;
56pub(crate) mod util;