[[Reflink_Deduplication]]
= Sharing Data Blocks

On a traditional filesystem, there is a 1:1 mapping between a logical block
offset in a file and a physical block on disk, which is to say that physical
blocks are not shared.  However, there exist various use cases for being able
to share blocks between files -- deduplicating files saves space on archival
systems; creating space-efficient clones of disk images for virtual machines
and containers facilitates efficient datacenters; and deferring the payment of
the allocation cost of a file system tree copy as long as possible makes
regular work faster.  In all of these cases, a write to one of the shared
copies *must* not affect the other shared copies, which means that writes to
shared blocks must employ a copy-on-write strategy.  Sharing blocks in this
manner is commonly referred to as ``reflinking''.

XFS implements block sharing in a fairly straightforward manner.  All existing
data fork structures remain unchanged, save for the addition of a
per-allocation group xref:Reference_Count_Btree[reference count B+tree].  This
data structure tracks reference counts for all shared physical blocks, with a
few rules to maintain compatibility with existing code: If a block is free, it
will be tracked in the free space B+trees.  If a block is owned by a single
file, it appears in neither the free space nor the reference count B+trees.  If
a block is shared, it will appear in the reference count B+tree with a
reference count >= 2.  The first two cases are established precedent in XFS, so
the third case is the only behavioral change.

When a filesystem block is shared, the block mapping in the destination file is
updated to point to that filesystem block and the reference count B+tree records
are updated to reflect the increased refcount.  If a shared block is written, a
new block will be allocated, the dirty data written to this new block, and the
file's block mapping updated to point to the new block.  If a shared block is
unmapped, the reference count records are updated to reflect the decreased
refcount and the block is also freed if its reference count becomes zero.  This
enables users to create space efficient clones of disk images and to copy
filesystem subtrees quickly, using the standard Linux coreutils packages.

Deduplication employs the same mechanism to share blocks and copy them at write
time.  However, the kernel confirms that the contents of both files are
identical before updating the destination file's mapping.  This enables XFS to
be used by userspace deduplication programs such as +duperemove+.