reflink · shipping

Reflink

A reflink shares physical extents between files on one filesystem until one copy is modified, instead of duplicating the data.

Related Observatory article: Read on hesela.com

Linux FICLONE isolates later writes and requires the same filesystem; its concurrent-write atomicity applies to the clone operation, not an entire recursive directory copy. [1] GNU cp may use reflinks by default, and errors in shared blocks can affect both files. [3]

FICLONERANGE takes a struct file_clone_range of four 64-bit fields, 32 bytes in total. A src_length of 0 clones to the end of the source file. Disk filesystems generally require block-aligned offsets and lengths, and XFS and Btrfs reject overlapping ranges in the same file. [1]

Btrfs defragmentation may break sharing even without an application-level content change, so clone allocation is not a permanent space-saving guarantee. [5]

FIDEDUPERANGE instead compares existing ranges and shares them only when equal; it does not replace different destination content. [6]

Durability: a clone's concurrency guarantee is not a crash-recovery protocol. Synchronize the destination file and required directory entries before claiming durable publication. File fsync alone need not persist its name. [7]

Snapshot example: famus_snap orders snapshot-data fsync, a permission-based completion marker, then snapshot fsync again. Recovery selects a completed snapshot. Its erratum corrects a comment that named the backing file instead of the snapshot. [8] [9]

Relations

related
Copy-on-write (storage), Storage snapshot, File extent, File preallocation, copy_file_range, Copy-on-abundant-write, Filesystem defragmentation, Transparent filesystem compression, Btrfs filesystem du, FIDEDUPERANGE, XFS deferred operation, NVMe Copy, FALLOC_FL_UNSHARE_RANGE, Failure-atomic msync, fsync

Advantages

  • The clone operation captures a file consistently against concurrent writes; a multi-file application checkpoint still needs its own coordination. [1]
  • In GNU coreutils 9.12, cp --reflink=always reports a failure when sharing is unsupported, while --reflink=auto falls back to an ordinary copy. [3]

Limitations

  • Shared allocation neither reserves capacity for future copy-on-write nor establishes an independent backup. [1, 3]
  • fallocate may unshare shared blocks so that later writes cannot fail for lack of space, which removes the saving. [1]
  • Cloning fails with EXDEV across mounted filesystems and with ETXTBSY for swap files. [1]

Citations

  1. Linux man-pages: FICLONE and FICLONERANGE sharing semantics (accessed 2026-10-23)
  2. GNU coreutils: cp invocation, reflink modes and shared-block caveat (accessed 2026-10-23)
  3. Btrfs-progs v6.16: Defragmentation, extent sharing and compression (accessed 2026-10-16)
  4. Linux man-pages: FIDEDUPERANGE, compare-and-share and per-destination results (accessed 2026-10-20)
  5. Linux man-pages: fsync(2), file and directory persistence (accessed 2026-11-21)
  6. Terence Kelly. Good Old-Fashioned Persistent Memory. USENIX ;login:, Winter 2019, pp. 29-34. (accessed 2026-11-21)
  7. Good Old-Fashioned Persistent Memory: erratum, 19 February 2020 (accessed 2026-11-21)

Further reading

  1. Sparse files, preallocation and thin-pool capacity (accessed 2026-10-13)
  2. Hesela: Fast file clones and deferred copying costs (accessed 2026-10-15)
Sources & caveats
  • ficlone is the Linux man-pages 6.19 FICLONE(2const) page, re-read for the 32-byte range structure, alignment and overlap errors, atomicity and the Linux 4.5 history. The layout was checked in include/uapi/linux/fs.h at v7.3.
  • gnu-cp is the GNU coreutils 9.12 cp invocation manual, re-read for the always, auto and never reflink modes and the shared-block caveat.
  • The qcow2 entry links here because it also shares stored data between copies until a write diverges them.
  • The concurrency, capacity and persistence contracts are compared from primary documentation and the complete 2019 article with its erratum; this is not a power-cut experiment.

JSON: /data/terms/reflink.json

Published by Hesela team · Updated

Report a correction · Editorial standards · Reuse guidance

Cite this page
Hesela team. Reflink. Hesela. 2026-11-21. https://hesela.dev/terms/reflink/