{
  "slug": "falloc-fl-unshare-range",
  "term": "FALLOC_FL_UNSHARE_RANGE",
  "aliases": [
    "unshare range",
    "preemptive copy-on-write"
  ],
  "definition": "FALLOC_FL_UNSHARE_RANGE makes shared file data private ahead of later writes, preserving existing content while preparing its copy-on-write allocation.",
  "note": "Allocation timing: a reflink postpones copying until a write diverges the files. This Linux fallocate mode brings that allocation forward for the selected range, trading immediate space and I/O for protection against later lack-of-space failures there. Success must be checked; unsupported filesystems can return EOPNOTSUPP and insufficient space can return ENOSPC. [fallocate]\n\nMode boundaries: the Linux v6.16 UAPI assigns this flag 0x40 and describes content-preserving unsharing within file size. It belongs to allocation mode and cannot be combined with punch, zero, collapse or insert range modes. Filesystem-dependent granularity still applies. [uapi]\n\nCheckpoint trade-off: famus_snap deliberately avoids reserving worst-case space for complete divergence of a backing file and its snapshot, because doing so could remove the sharing benefit. An application choosing that optimization must budget future copy-on-write growth separately. [kelly19]\n\nPersistence: allocating private extents does not flush future writes or durably publish a pathname. File synchronization and required directory synchronization remain separate obligations. [fsync]",
  "status": "shipping",
  "advantages": [],
  "limitations": [
    "An unshare failure is not a capacity reservation; inspect the error before relying on subsequent writes. [fallocate]",
    "Neither private extents nor a cloned file provide an independent device-failure domain. [ficlone]"
  ],
  "related": [
    "reflink",
    "copy-on-write",
    "file-preallocation",
    "file-extent",
    "fsync",
    "failure-atomic-msync"
  ],
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-11-21",
  "citations": [
    {
      "id": "fallocate",
      "title": "Linux man-pages: fallocate(2), unshare allocation mode and errors",
      "url": "https://man7.org/linux/man-pages/man2/fallocate.2.html",
      "accessed": "2026-11-21"
    },
    {
      "id": "uapi",
      "title": "Linux v6.16: include/uapi/linux/falloc.h, unshare-range mode contract",
      "url": "https://raw.githubusercontent.com/torvalds/linux/v6.16/include/uapi/linux/falloc.h",
      "accessed": "2026-11-21"
    },
    {
      "id": "kelly19",
      "title": "Terence Kelly. Good Old-Fashioned Persistent Memory. USENIX ;login:, Winter 2019, pp. 29-34.",
      "url": "https://files.usenix.org/s3fs-public/cdn/login_winter19_08_kelly.pdf",
      "accessed": "2026-11-21"
    },
    {
      "id": "fsync",
      "title": "Linux man-pages: fsync(2), data, metadata and directory persistence",
      "url": "https://man7.org/linux/man-pages/man2/fsync.2.html",
      "accessed": "2026-11-21"
    },
    {
      "id": "ficlone",
      "title": "Linux man-pages: FICLONE(2const), shared storage and later allocation",
      "url": "https://man7.org/linux/man-pages/man2/FICLONE.2const.html",
      "accessed": "2026-11-21"
    },
    {
      "id": "hesela-allocation",
      "title": "Hesela: Sparse files, preallocation and thin-pool capacity",
      "url": "https://hesela.com/analyses/sparse-files-preallocation-thin-capacity/",
      "accessed": "2026-11-21"
    }
  ],
  "provenance": [
    "Source synthesis of Linux interface contracts and a snapshot implementation, not a filesystem benchmark or crash-recovery experiment.",
    "The flag's presence in a pinned UAPI header does not establish support on every filesystem or a date of first implementation."
  ]
}
