btrfs_uapi/
device.rs

1//! # Device management: adding, removing, and querying block devices in a filesystem
2//!
3//! Covers adding and removing devices from a mounted filesystem, scanning a
4//! device to register it with the kernel, querying per-device I/O error
5//! statistics, and checking whether all devices of a multi-device filesystem
6//! are present and ready.
7//!
8//! Most operations require `CAP_SYS_ADMIN`.
9
10use crate::{
11    filesystem::FsInfo,
12    raw::{
13        BTRFS_DEV_STATS_RESET, BTRFS_DEVICE_SPEC_BY_ID,
14        btrfs_dev_stat_values_BTRFS_DEV_STAT_CORRUPTION_ERRS,
15        btrfs_dev_stat_values_BTRFS_DEV_STAT_FLUSH_ERRS,
16        btrfs_dev_stat_values_BTRFS_DEV_STAT_GENERATION_ERRS,
17        btrfs_dev_stat_values_BTRFS_DEV_STAT_READ_ERRS,
18        btrfs_dev_stat_values_BTRFS_DEV_STAT_VALUES_MAX,
19        btrfs_dev_stat_values_BTRFS_DEV_STAT_WRITE_ERRS, btrfs_ioc_add_dev, btrfs_ioc_dev_info,
20        btrfs_ioc_devices_ready, btrfs_ioc_forget_dev, btrfs_ioc_get_dev_stats, btrfs_ioc_rm_dev,
21        btrfs_ioc_rm_dev_v2, btrfs_ioc_scan_dev, btrfs_ioctl_dev_info_args,
22        btrfs_ioctl_get_dev_stats, btrfs_ioctl_vol_args, btrfs_ioctl_vol_args_v2,
23    },
24};
25use nix::{errno::Errno, libc::c_char};
26use std::{
27    ffi::CStr,
28    fs::OpenOptions,
29    mem,
30    os::{fd::AsRawFd, unix::io::BorrowedFd},
31};
32use uuid::Uuid;
33
34/// Information about a single device within a btrfs filesystem, as returned
35/// by `BTRFS_IOC_DEV_INFO`.
36#[derive(Debug, Clone)]
37pub struct DevInfo {
38    /// Device ID.
39    pub devid: u64,
40    /// Device UUID.
41    pub uuid: Uuid,
42    /// Number of bytes used on this device.
43    pub bytes_used: u64,
44    /// Total size of this device in bytes.
45    pub total_bytes: u64,
46    /// Path to the block device, e.g. `/dev/sda`.
47    pub path: String,
48}
49
50/// Specifies a device for operations that can address by either path or ID.
51#[derive(Debug, Clone)]
52pub enum DeviceSpec<'a> {
53    /// A block device path (e.g. `/dev/sdb`), or the special strings
54    /// `"missing"` or `"cancel"` accepted by the remove ioctl.
55    Path(&'a CStr),
56    /// A btrfs device ID as reported by `BTRFS_IOC_DEV_INFO`.
57    Id(u64),
58}
59
60/// Per-device I/O error statistics, as returned by `BTRFS_IOC_GET_DEV_STATS`.
61#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
62pub struct DevStats {
63    /// Device ID these stats belong to.
64    pub devid: u64,
65    /// Number of write I/O errors (EIO/EREMOTEIO from lower layers).
66    pub write_errs: u64,
67    /// Number of read I/O errors (EIO/EREMOTEIO from lower layers).
68    pub read_errs: u64,
69    /// Number of flush I/O errors (EIO/EREMOTEIO from lower layers).
70    pub flush_errs: u64,
71    /// Number of checksum or bytenr corruption errors detected on read.
72    pub corruption_errs: u64,
73    /// Number of generation errors (blocks not written where expected).
74    pub generation_errs: u64,
75}
76
77impl DevStats {
78    /// Sum of all error counters.
79    pub fn total_errs(&self) -> u64 {
80        self.write_errs
81            + self.read_errs
82            + self.flush_errs
83            + self.corruption_errs
84            + self.generation_errs
85    }
86
87    /// Returns `true` if every counter is zero.
88    pub fn is_clean(&self) -> bool {
89        self.total_errs() == 0
90    }
91}
92
93/// Copy the bytes of `path` (without the nul terminator) into `name`,
94/// returning `ENAMETOOLONG` if the path (including the terminator that the
95/// kernel expects to already be present via zeroing) does not fit.
96fn copy_path_to_name(name: &mut [c_char], path: &CStr) -> nix::Result<()> {
97    let bytes = path.to_bytes(); // excludes nul terminator
98    if bytes.len() >= name.len() {
99        return Err(Errno::ENAMETOOLONG);
100    }
101    for (i, &b) in bytes.iter().enumerate() {
102        name[i] = b as c_char;
103    }
104    // The remainder of `name` is already zeroed by the caller (mem::zeroed).
105    Ok(())
106}
107
108/// Open `/dev/btrfs-control` for read+write, mapping any `std::io::Error` to
109/// the appropriate `nix::errno::Errno`.
110fn open_control() -> nix::Result<std::fs::File> {
111    OpenOptions::new()
112        .read(true)
113        .write(true)
114        .open("/dev/btrfs-control")
115        .map_err(|e| Errno::from_raw(e.raw_os_error().unwrap_or(nix::libc::ENODEV)))
116}
117
118/// Query information about the device with the given `devid` on the filesystem
119/// referred to by `fd`.
120///
121/// Returns `None` if no device with that ID exists (`ENODEV`).
122pub fn device_info(fd: BorrowedFd, devid: u64) -> nix::Result<Option<DevInfo>> {
123    let mut raw: btrfs_ioctl_dev_info_args = unsafe { mem::zeroed() };
124    raw.devid = devid;
125
126    match unsafe { btrfs_ioc_dev_info(fd.as_raw_fd(), &mut raw) } {
127        Err(Errno::ENODEV) => return Ok(None),
128        Err(e) => return Err(e),
129        Ok(_) => {}
130    }
131
132    let path = unsafe { CStr::from_ptr(raw.path.as_ptr() as *const _) }
133        .to_string_lossy()
134        .into_owned();
135
136    Ok(Some(DevInfo {
137        devid: raw.devid,
138        uuid: Uuid::from_bytes(raw.uuid),
139        bytes_used: raw.bytes_used,
140        total_bytes: raw.total_bytes,
141        path,
142    }))
143}
144
145/// Query information about all devices in the filesystem referred to by `fd`,
146/// using the device count from a previously obtained [`FsInfo`].
147///
148/// Iterates devids `1..=max_id`, skipping any that return `ENODEV` (holes in
149/// the devid space are normal when devices have been removed).
150pub fn device_info_all(fd: BorrowedFd, fs_info: &FsInfo) -> nix::Result<Vec<DevInfo>> {
151    let mut devices = Vec::with_capacity(fs_info.num_devices as usize);
152    for devid in 1..=fs_info.max_id {
153        if let Some(info) = device_info(fd, devid)? {
154            devices.push(info);
155        }
156    }
157    Ok(devices)
158}
159
160/// Add a device to the btrfs filesystem referred to by `fd`.
161///
162/// `path` must be the path to an unmounted block device. The kernel requires
163/// `CAP_SYS_ADMIN`.
164pub fn device_add(fd: BorrowedFd, path: &CStr) -> nix::Result<()> {
165    let mut raw: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
166    copy_path_to_name(&mut raw.name, path)?;
167    unsafe { btrfs_ioc_add_dev(fd.as_raw_fd(), &raw) }?;
168    Ok(())
169}
170
171/// Remove a device from the btrfs filesystem referred to by `fd`.
172///
173/// The device can be specified either by path or by its btrfs device ID via
174/// [`DeviceSpec`]. Uses `BTRFS_IOC_RM_DEV_V2` and falls back to the older
175/// `BTRFS_IOC_RM_DEV` ioctl on kernels that do not support the v2 variant
176/// (only possible when removing by path). The kernel requires `CAP_SYS_ADMIN`.
177pub fn device_remove(fd: BorrowedFd, spec: DeviceSpec) -> nix::Result<()> {
178    let mut args: btrfs_ioctl_vol_args_v2 = unsafe { mem::zeroed() };
179
180    match spec {
181        DeviceSpec::Id(devid) => {
182            args.flags = BTRFS_DEVICE_SPEC_BY_ID as u64;
183            // SAFETY: devid is the active union member when BTRFS_DEVICE_SPEC_BY_ID is set.
184            args.__bindgen_anon_2.devid = devid;
185            unsafe { btrfs_ioc_rm_dev_v2(fd.as_raw_fd(), &args) }?;
186        }
187        DeviceSpec::Path(path) => {
188            // SAFETY: name is the active union member when flags == 0.
189            unsafe { copy_path_to_name(&mut args.__bindgen_anon_2.name, path) }?;
190            match unsafe { btrfs_ioc_rm_dev_v2(fd.as_raw_fd(), &args) } {
191                Ok(_) => {}
192                // Fall back to the old single-arg ioctl on kernels that either
193                // don't know about v2 (ENOTTY) or don't recognise our flags (EOPNOTSUPP).
194                Err(Errno::ENOTTY) | Err(Errno::EOPNOTSUPP) => {
195                    let mut old: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
196                    copy_path_to_name(&mut old.name, path)?;
197                    unsafe { btrfs_ioc_rm_dev(fd.as_raw_fd(), &old) }?;
198                }
199                Err(e) => return Err(e),
200            }
201        }
202    }
203
204    Ok(())
205}
206
207/// Register a block device with the kernel's btrfs device scanner so that
208/// multi-device filesystems containing it can be mounted.
209///
210/// Opens `/dev/btrfs-control` and issues `BTRFS_IOC_SCAN_DEV`. `path` must
211/// be the path to a block device that contains a btrfs filesystem member.
212pub fn device_scan(path: &CStr) -> nix::Result<()> {
213    let ctl = open_control()?;
214    let mut raw: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
215    copy_path_to_name(&mut raw.name, path)?;
216    unsafe { btrfs_ioc_scan_dev(ctl.as_raw_fd(), &raw) }?;
217    Ok(())
218}
219
220/// Unregister a device (or all stale devices) from the kernel's btrfs device
221/// scanner.
222///
223/// Opens `/dev/btrfs-control` and issues `BTRFS_IOC_FORGET_DEV`. If `path`
224/// is `None`, all devices that are not part of a currently mounted filesystem
225/// are unregistered. If `path` is `Some`, only that specific device path is
226/// unregistered.
227pub fn device_forget(path: Option<&CStr>) -> nix::Result<()> {
228    let ctl = open_control()?;
229    let mut raw: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
230    if let Some(p) = path {
231        copy_path_to_name(&mut raw.name, p)?;
232    }
233    unsafe { btrfs_ioc_forget_dev(ctl.as_raw_fd(), &raw) }?;
234    Ok(())
235}
236
237/// Check whether all member devices of the filesystem that contains `path`
238/// are available and the filesystem is ready to mount.
239///
240/// Opens `/dev/btrfs-control` and issues `BTRFS_IOC_DEVICES_READY`. `path`
241/// must be the path to one of the block devices belonging to the filesystem.
242/// Returns `Ok(())` when all devices are present; returns an error (typically
243/// `ENOENT` or `ENXIO`) if the set is incomplete.
244pub fn device_ready(path: &CStr) -> nix::Result<()> {
245    let ctl = open_control()?;
246    // BTRFS_IOC_DEVICES_READY is declared _IOR but the kernel reads the device
247    // path from args.name, so we pass a mut pointer as ioctl_read! requires.
248    let mut raw: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
249    copy_path_to_name(&mut raw.name, path)?;
250    unsafe { btrfs_ioc_devices_ready(ctl.as_raw_fd(), &mut raw) }?;
251    Ok(())
252}
253
254/// Query I/O error statistics for the device identified by `devid` within the
255/// filesystem referred to by `fd`.
256///
257/// If `reset` is `true`, the kernel atomically returns the current values and
258/// then resets all counters to zero. The kernel requires `CAP_SYS_ADMIN`.
259pub fn device_stats(fd: BorrowedFd, devid: u64, reset: bool) -> nix::Result<DevStats> {
260    let mut raw: btrfs_ioctl_get_dev_stats = unsafe { mem::zeroed() };
261    raw.devid = devid;
262    raw.nr_items = btrfs_dev_stat_values_BTRFS_DEV_STAT_VALUES_MAX as u64;
263    if reset {
264        raw.flags = BTRFS_DEV_STATS_RESET as u64;
265    }
266
267    unsafe { btrfs_ioc_get_dev_stats(fd.as_raw_fd(), &mut raw) }?;
268
269    Ok(DevStats {
270        devid,
271        write_errs: raw.values[btrfs_dev_stat_values_BTRFS_DEV_STAT_WRITE_ERRS as usize],
272        read_errs: raw.values[btrfs_dev_stat_values_BTRFS_DEV_STAT_READ_ERRS as usize],
273        flush_errs: raw.values[btrfs_dev_stat_values_BTRFS_DEV_STAT_FLUSH_ERRS as usize],
274        corruption_errs: raw.values[btrfs_dev_stat_values_BTRFS_DEV_STAT_CORRUPTION_ERRS as usize],
275        generation_errs: raw.values[btrfs_dev_stat_values_BTRFS_DEV_STAT_GENERATION_ERRS as usize],
276    })
277}
btrfs_uapi/device.rs

btrfs_uapi/
device.rs
