btrfs_uapi/
scrub.rs

1//! # Data integrity scrubbing: verifying and repairing filesystem checksums
2//!
3//! A scrub reads every data and metadata block on the filesystem, verifies it
4//! against its stored checksum, and repairs any errors it finds using redundant
5//! copies where available (e.g. RAID profiles).  Scrubbing is the primary way
6//! to proactively detect silent data corruption.
7//!
8//! Requires `CAP_SYS_ADMIN`.
9
10use crate::raw::{
11    BTRFS_SCRUB_READONLY, btrfs_ioc_scrub, btrfs_ioc_scrub_cancel, btrfs_ioc_scrub_progress,
12    btrfs_ioctl_scrub_args,
13};
14use std::{
15    mem,
16    os::{fd::AsRawFd, unix::io::BorrowedFd},
17};
18
19/// Progress counters for a scrub operation, as returned by `BTRFS_IOC_SCRUB`
20/// or `BTRFS_IOC_SCRUB_PROGRESS`.
21#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
22pub struct ScrubProgress {
23    /// Number of data extents scrubbed.
24    pub data_extents_scrubbed: u64,
25    /// Number of tree (metadata) extents scrubbed.
26    pub tree_extents_scrubbed: u64,
27    /// Number of data bytes scrubbed.
28    pub data_bytes_scrubbed: u64,
29    /// Number of tree (metadata) bytes scrubbed.
30    pub tree_bytes_scrubbed: u64,
31    /// Number of read errors encountered.
32    pub read_errors: u64,
33    /// Number of checksum errors.
34    pub csum_errors: u64,
35    /// Number of metadata verification errors.
36    pub verify_errors: u64,
37    /// Number of data blocks with no checksum.
38    pub no_csum: u64,
39    /// Number of checksums with no corresponding data extent.
40    pub csum_discards: u64,
41    /// Number of bad superblock copies encountered.
42    pub super_errors: u64,
43    /// Number of internal memory allocation errors.
44    pub malloc_errors: u64,
45    /// Number of errors that could not be corrected.
46    pub uncorrectable_errors: u64,
47    /// Number of errors that were successfully corrected.
48    pub corrected_errors: u64,
49    /// Last physical byte address scrubbed (useful for resuming).
50    pub last_physical: u64,
51    /// Number of transient read errors (re-read succeeded).
52    pub unverified_errors: u64,
53}
54
55impl ScrubProgress {
56    /// Total number of hard errors (read, super, verify, checksum).
57    pub fn error_count(&self) -> u64 {
58        self.read_errors + self.super_errors + self.verify_errors + self.csum_errors
59    }
60
61    /// Total bytes scrubbed (data + tree).
62    pub fn bytes_scrubbed(&self) -> u64 {
63        self.data_bytes_scrubbed + self.tree_bytes_scrubbed
64    }
65
66    /// Returns `true` if no errors of any kind were found.
67    pub fn is_clean(&self) -> bool {
68        self.error_count() == 0 && self.corrected_errors == 0 && self.uncorrectable_errors == 0
69    }
70}
71
72fn from_raw(raw: &btrfs_ioctl_scrub_args) -> ScrubProgress {
73    let p = &raw.progress;
74    ScrubProgress {
75        data_extents_scrubbed: p.data_extents_scrubbed,
76        tree_extents_scrubbed: p.tree_extents_scrubbed,
77        data_bytes_scrubbed: p.data_bytes_scrubbed,
78        tree_bytes_scrubbed: p.tree_bytes_scrubbed,
79        read_errors: p.read_errors,
80        csum_errors: p.csum_errors,
81        verify_errors: p.verify_errors,
82        no_csum: p.no_csum,
83        csum_discards: p.csum_discards,
84        super_errors: p.super_errors,
85        malloc_errors: p.malloc_errors,
86        uncorrectable_errors: p.uncorrectable_errors,
87        corrected_errors: p.corrected_errors,
88        last_physical: p.last_physical,
89        unverified_errors: p.unverified_errors,
90    }
91}
92
93/// Start a scrub on the device identified by `devid` within the filesystem
94/// referred to by `fd`.
95///
96/// This call **blocks** until the scrub completes or is cancelled. On
97/// completion the final [`ScrubProgress`] counters are returned.
98///
99/// Set `readonly` to `true` to check for errors without attempting repairs.
100pub fn scrub_start(fd: BorrowedFd, devid: u64, readonly: bool) -> nix::Result<ScrubProgress> {
101    let mut args: btrfs_ioctl_scrub_args = unsafe { mem::zeroed() };
102    args.devid = devid;
103    args.start = 0;
104    args.end = u64::MAX;
105    if readonly {
106        args.flags = BTRFS_SCRUB_READONLY as u64;
107    }
108    unsafe { btrfs_ioc_scrub(fd.as_raw_fd(), &mut args) }?;
109    Ok(from_raw(&args))
110}
111
112/// Cancel the scrub currently running on the filesystem referred to by `fd`.
113pub fn scrub_cancel(fd: BorrowedFd) -> nix::Result<()> {
114    unsafe { btrfs_ioc_scrub_cancel(fd.as_raw_fd()) }?;
115    Ok(())
116}
117
118/// Query the progress of the scrub currently running on the device identified
119/// by `devid` within the filesystem referred to by `fd`.
120///
121/// Returns `None` if no scrub is running on that device (`ENOTCONN`).
122pub fn scrub_progress(fd: BorrowedFd, devid: u64) -> nix::Result<Option<ScrubProgress>> {
123    let mut args: btrfs_ioctl_scrub_args = unsafe { mem::zeroed() };
124    args.devid = devid;
125    args.start = 0;
126    args.end = u64::MAX;
127
128    match unsafe { btrfs_ioc_scrub_progress(fd.as_raw_fd(), &mut args) } {
129        Err(nix::errno::Errno::ENOTCONN) => Ok(None),
130        Err(e) => Err(e),
131        Ok(_) => Ok(Some(from_raw(&args))),
132    }
133}
btrfs_uapi/scrub.rs

btrfs_uapi/
scrub.rs
