Expand description
§btrfs-uapi: typed Rust wrappers around the btrfs kernel interface
This crate provides typed, safe access to the btrfs kernel interface. Kernel communication uses two mechanisms:
- ioctls for most operations (balance, scrub, subvolume management, …)
- sysfs under
/sys/fs/btrfs/<uuid>/for status that the kernel does not expose via ioctl (quota state, commit statistics, scrub speed limits)
§Safety
All unsafe code is confined to the raw module, which contains
bindgen-generated types from the kernel UAPI headers (btrfs.h and
btrfs_tree.h) and nix ioctl macro declarations for every BTRFS_IOC_*
call.
Every other module wraps raw into a public API that is entirely safe,
exposes no kernel types, and uses idiomatic Rust types throughout:
BorrowedFd, Uuid, bitflags, SystemTime, CString, and so on.
§Usage
Every function that issues an ioctl takes a BorrowedFd
open on any file within the target btrfs filesystem. Functions in sysfs
instead take a uuid::Uuid, which can be obtained from
filesystem::fs_info.
Most ioctl-based operations require CAP_SYS_ADMIN.
§Portability
btrfs is Linux-only; this crate does not support other operating systems.
Some ioctls used here were introduced in relatively recent kernel versions;
this crate targets modern kernels (5.x and later) and does not attempt to
detect or work around missing ioctls on older kernels. It is only tested
on amd64, but all architectures supported by the kernel (and Rust) should
work.
Modules§
- balance
- Balance operations: redistributing data and metadata across devices
- chunk
- Per-device physical allocation data from the chunk tree
- defrag
- File defragmentation: rewriting fragmented extents into contiguous runs
- dev_
extent - Device extent tree: per-device physical extent layout
- device
- Device management: adding, removing, and querying block devices in a filesystem
- fiemap
- Physical extent layout of files via
FS_IOC_FIEMAP - filesystem
- Filesystem-level metadata: UUID, device count, node size, and generation
- inode
- Inode and path resolution: mapping between inodes, logical addresses, and paths
- label
- Filesystem label: reading and writing the human-readable name of a filesystem
- qgroup
- Quota group (qgroup) management: hierarchical accounting of disk usage
- quota
- Filesystem quota: enabling, disabling, and rescanning quota accounting
- raw
- Raw bindgen output and ioctl declarations for the btrfs UAPI
- replace
- Device replacement: replacing a device with another while the filesystem is online
- resize
- Device resizing: growing or shrinking a device within a mounted filesystem
- scrub
- Data integrity scrubbing: verifying and repairing filesystem checksums
- space
- Block group space usage: how much space each chunk type allocates and uses
- subvolume
- Subvolume and snapshot management: creating, deleting, and querying subvolumes
- sync
- Filesystem sync: flushing all pending writes to disk
- sysfs
- Sysfs interface: reading filesystem and device state from
/sys/fs/btrfs/ - tree_
search - Generic B-tree search: walking any internal btrfs tree via
BTRFS_IOC_TREE_SEARCH
Macros§
- field_
size - Return the size in bytes of a single field within a struct.