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// Test code uses literal byte buffers, raw pointer casts (for crafting
43// kernel-shaped data structures by hand), and small cast conversions
44// that pedantic clippy flags but that are intentional in unit tests.
45#![cfg_attr(
46    test,
47    allow(
48        clippy::cast_lossless,
49        clippy::cast_possible_truncation,
50        clippy::cast_possible_wrap,
51        clippy::cast_sign_loss,
52        clippy::decimal_bitwise_operands,
53        clippy::identity_op,
54        clippy::items_after_test_module,
55        clippy::match_wildcard_for_single_variants,
56        clippy::ptr_cast_constness,
57        clippy::semicolon_if_nothing_returned,
58        clippy::uninlined_format_args,
59        clippy::unreadable_literal,
60    )
61)]
62
63pub mod balance;
64pub mod blkdev;
65pub mod chunk;
66pub mod dedupe;
67pub mod defrag;
68pub mod device;
69pub mod features;
70pub mod fiemap;
71pub mod filesystem;
72pub mod inode;
73pub mod quota;
74#[allow(missing_docs)]
75pub mod raw;
76pub mod replace;
77pub mod scrub;
78pub mod send_receive;
79pub mod space;
80pub mod subvolume;
81pub mod sysfs;
82pub mod tree_search;
83pub mod util;
btrfs_uapi/lib.rs

btrfs_uapi/
lib.rs
