Struct ReflinkBlockBuilder

Source

pub struct ReflinkBlockBuilder<'from, 'to> { /* private fields */ }

Expand description

Creates a reflink of a specified block from one file to another.

This functionality is designed to be highly performant and does not perform any extra API calls. It is expected that the user takes care of necessary preliminary checks and preparations.

If you need to clone an entire file, consider using the reflink or reflink_or_copy functions instead.

Note: Currently the function works only for windows and linux platforms. It returns Err for any other platform.

§General restrictions

The source and destination regions must begin and end at a cluster boundary.
If the source and destination regions are in the same file, they must not overlap. (The application may able to proceed by splitting up the block clone operation into multiple block clones that no longer overlap.)
src_length equal to 0 is not supported.

§Linux specific restrictions and remarks

If the file size is not aligned to the cluster size, the reflink operation must not exceed the file length. For example, to reflink the whole file with size of 7000 bytes, src_length should be 7000 bytes.

More information about block cloning on Linux can be found by the link.

§Windows specific restrictions and remarks

The destination region must not extend past the end of file. If the application wishes to extend the destination with cloned data, it must first call File::set_len.
The source and destination files must be on the same ReFS volume.
The source and destination files must have the same Integrity Streams setting (that is, Integrity Streams must be enabled in both files, or disabled in both files).
If the source file is sparse, the destination file must also be sparse.
The block clone operation will break Shared Opportunistic Locks (also known as Level 2 Opportunistic Locks).
The ReFS volume must have been formatted with Windows Server 2016, and if Windows Failover Clustering is in use, the Clustering Functional Level must have been Windows Server 2016 or later at format time.
If the file size is not aligned to the cluster size, the reflink operation should still be aligned by the cluster size. For example, to reflink the whole file with size of 7000 bytes and a cluster size of 4096 bytes, src_length should be 8192 bytes.

Note: In order to handle blocks larger than 4GB, ReflinkBlockBuilder::reflink_block splits these big blocks into smaller ones. Each smaller block is 4GB minus the cluster size. This means there might be more than one API call needed for the larger blocks.

More information about block cloning on Windows can be found by the link.

§Examples

The example below demonstrates how to create a new file reusing blocks from another file.

use std::fs::File;
use std::num::NonZeroU64;

fn shuffle() -> std::io::Result<()> {
    let from_file = File::open("source.bin")?;
    let to_file = File::create("destination.bin")?;
    let cluster_size = NonZeroU64::new(4096).unwrap();
    let len = cluster_size.get() * 2;

    to_file.set_len(len)?;

    reflink_copy::ReflinkBlockBuilder::new(&from_file, &to_file, cluster_size)
        .from_offset(0)
        .to_offset(cluster_size.get())
        .reflink_block()?;

    reflink_copy::ReflinkBlockBuilder::new(&from_file, &to_file, cluster_size)
        .from_offset(cluster_size.get())
        .to_offset(0)
        .reflink_block()?;

    Ok(())
}