btrfs_uapi/
dedupe.rs

1//! # Extent deduplication: comparing and deduplicating file extents
2//!
3//! Wraps `BTRFS_IOC_FILE_EXTENT_SAME` to request that the kernel compare a
4//! byte range in a source file against ranges in one or more destination files.
5//! Where the data is identical, the destination extents are replaced with
6//! references to the source extent, saving space.
7
8use crate::raw::{
9    BTRFS_SAME_DATA_DIFFERS, btrfs_ioc_file_extent_same, btrfs_ioctl_same_args,
10    btrfs_ioctl_same_extent_info,
11};
12use std::{
13    mem,
14    os::{fd::AsRawFd, unix::io::BorrowedFd},
15};
16
17/// A destination file and offset to deduplicate against the source range.
18#[derive(Debug, Clone)]
19pub struct DedupeTarget {
20    /// File descriptor of the destination file (passed as raw fd).
21    pub fd: BorrowedFd<'static>,
22    /// Byte offset in the destination file to compare from.
23    pub logical_offset: u64,
24}
25
26/// Result of a single dedupe comparison against one destination.
27#[derive(Debug, Clone, Copy, PartialEq, Eq)]
28pub enum DedupeResult {
29    /// Deduplication succeeded; the given number of bytes were deduped.
30    Deduped(u64),
31    /// The data differs between source and destination.
32    DataDiffers,
33    /// The kernel returned an error for this particular destination.
34    Error(i32),
35}
36
37/// Deduplicate a source range against one or more destination ranges.
38///
39/// Compares `length` bytes starting at `src_offset` in the file referred to
40/// by `src_fd` against each target. Where data matches, the destination
41/// extents are replaced with shared references to the source extent.
42///
43/// Returns one [`DedupeResult`] per target, in the same order.
44///
45/// Errors (ioctl-level): EINVAL if `src_offset` or `length` are not
46/// sector-aligned, or if `targets` is empty. EPERM if the destination
47/// files are not writable.
48pub fn file_extent_same(
49    src_fd: BorrowedFd<'_>,
50    src_offset: u64,
51    length: u64,
52    targets: &[DedupeTarget],
53) -> nix::Result<Vec<DedupeResult>> {
54    let count = targets.len();
55
56    // Flexible array member pattern: allocate header + count info entries.
57    let base_size = mem::size_of::<btrfs_ioctl_same_args>();
58    let info_size = mem::size_of::<btrfs_ioctl_same_extent_info>();
59    let total_bytes = base_size + count * info_size;
60    let num_u64s = total_bytes.div_ceil(mem::size_of::<u64>());
61    let mut buf = vec![0u64; num_u64s];
62
63    // SAFETY: buf is correctly sized and aligned for btrfs_ioctl_same_args.
64    // We populate the header and info entries before calling the ioctl, and
65    // read the results only after a successful return.
66    unsafe {
67        let args_ptr = buf.as_mut_ptr() as *mut btrfs_ioctl_same_args;
68        (*args_ptr).logical_offset = src_offset;
69        (*args_ptr).length = length;
70        (*args_ptr).dest_count = count as u16;
71
72        let info_slice = (*args_ptr).info.as_mut_slice(count);
73        for (i, target) in targets.iter().enumerate() {
74            info_slice[i].fd = target.fd.as_raw_fd() as i64;
75            info_slice[i].logical_offset = target.logical_offset;
76        }
77
78        btrfs_ioc_file_extent_same(src_fd.as_raw_fd(), &mut *args_ptr)?;
79
80        let info_slice = (*args_ptr).info.as_slice(count);
81        Ok(info_slice
82            .iter()
83            .map(|info| {
84                if info.status == 0 {
85                    DedupeResult::Deduped(info.bytes_deduped)
86                } else if info.status == BTRFS_SAME_DATA_DIFFERS as i32 {
87                    DedupeResult::DataDiffers
88                } else {
89                    DedupeResult::Error(info.status)
90                }
91            })
92            .collect())
93    }
94}
95
96#[cfg(test)]
97mod tests {
98    use super::*;
99
100    #[test]
101    fn dedupe_result_deduped_debug() {
102        let r = DedupeResult::Deduped(4096);
103        assert_eq!(format!("{r:?}"), "Deduped(4096)");
104    }
105
106    #[test]
107    fn dedupe_result_data_differs_debug() {
108        let r = DedupeResult::DataDiffers;
109        assert_eq!(format!("{r:?}"), "DataDiffers");
110    }
111
112    #[test]
113    fn dedupe_result_error_debug() {
114        let r = DedupeResult::Error(-22);
115        assert_eq!(format!("{r:?}"), "Error(-22)");
116    }
117
118    #[test]
119    fn dedupe_result_equality() {
120        assert_eq!(DedupeResult::Deduped(100), DedupeResult::Deduped(100));
121        assert_ne!(DedupeResult::Deduped(100), DedupeResult::Deduped(200));
122        assert_eq!(DedupeResult::DataDiffers, DedupeResult::DataDiffers);
123        assert_ne!(DedupeResult::DataDiffers, DedupeResult::Deduped(0));
124        assert_eq!(DedupeResult::Error(-1), DedupeResult::Error(-1));
125        assert_ne!(DedupeResult::Error(-1), DedupeResult::Error(-2));
126    }
127
128    #[test]
129    fn allocation_sizing() {
130        // Verify the flexible array member allocation produces enough space.
131        let base_size = mem::size_of::<btrfs_ioctl_same_args>();
132        let info_size = mem::size_of::<btrfs_ioctl_same_extent_info>();
133
134        for count in [0, 1, 2, 5, 16, 255] {
135            let total_bytes = base_size + count * info_size;
136            let num_u64s = total_bytes.div_ceil(mem::size_of::<u64>());
137            let allocated = num_u64s * mem::size_of::<u64>();
138            assert!(
139                allocated >= total_bytes,
140                "count={count}: allocated {allocated} < needed {total_bytes}"
141            );
142        }
143    }
144
145    #[test]
146    fn btrfs_same_data_differs_value() {
147        // Sanity check: the constant should be 1 per the kernel header.
148        assert_eq!(BTRFS_SAME_DATA_DIFFERS, 1);
149    }
150}
btrfs_uapi/dedupe.rs

btrfs_uapi/
dedupe.rs
