COPYFILERANGE(1)

💖 COPYFILERANGE(1) — user commands, but make it iconic 💖

okay bestie, so we're doing copyfilerange(1) today and honestly? she's a baddie. let's get into it 🫶

---

✨ NAME ✨

copyfilerange — copy range(s) from source to destination file 💅

---

🌸 SYNOPSIS 🌸

copyfilerange [options] source destination range...

---

🦋 DESCRIPTION 🦋

so copyfilerange copies byte ranges from a source file to a destination file. that's it, that's the girl. she's a wrapper around the copy_file_range(2) system call, meaning she's basically the system call's glamorous publicist 🎀

the way she's useful?? you can use this command to create files with unallocated gaps (aka sparse files) and/or with shared blocks between multiple files (aka reflinks). not me being obsessed with efficient storage 💀

each range is shaped like this:

source_offset:destination_offset:length

and all those values are in bytes, no cap. if length is 0, then as much data as is available gets copied. you can also supply multiple ranges — she's flexible like that ✨

when one or both of the offsets are omitted, the operation uses the last-used file location, starting with 0. so she remembers where she left off, very main character of her 💖

---

💜 OPTIONS 💜

• -r, --ranges file — read range(s) separated by newlines from this file. yes, from a file, we're being organized 🗂️
• -v, --verbose — verbose output of the copied ranges. she will narrate her own life ✨
• -h, --help — display help text and exit. respect the classic 📖
• -V, --version — display version and exit. she'll tell you who she is 👑

---

🌈 EXIT STATUS 🌈

• 0 — success 🎉 (slay)
• 1 — unspecified failure 😭 (not slay)

---

⚠️ NOTES ⚠️

okay so this is the part where we get serious for a sec because the copy_file_range(2) system call has some serious caveats and i'm not gonna lie to you bestie:

• the source and destination files must use the same filesystem type 🔒
• some virtual filesystems (like procfs) won't work. like, at all. don't try it 🙈
• copy_file_range(2) will use reflinks when the filesystem supports this 👑
• but to actually use reflinks, the file range most often needs to align with the filesystem block size on both the source and destination file 📐

fr fr, read those caveats twice. this is not a drill 🚨

---

👑 AUTHORS 👑

Dick Marinus <dick@mrns.nl>

---

🎀 EXAMPLES 🎀

here's the part you actually came for, and honestly? these examples ate 💅

copyfilerange original-file reflink ::

copyfilerange original-file first-block ::4096

copyfilerange original-file even-blocks -r <(seq 0 8192 40960|awk '{print $1"::4096"}')

copyfilerange original-file sparse-file 0:1M:1

copyfilerange original-file split-first-mb ::1M

copyfilerange original-file split-remainder 1M::

copyfilerange split-first-mb join ::

copyfilerange split-remainder join :1M:

the way that <(...) process substitution is just sitting there in the middle of an example being all clever 🧚 lowkey iconic

---

🔥 SEE ALSO 🔥

copy_file_range(2) — the system call she's wrapping, iykyk

---

💀 REPORTING BUGS 💀

for bug reports, use the issue tracker:

https://github.com/util-linux/util-linux/issues

please be nice when you file them, the maintainers are people too 🫶

---

🌟 AVAILABILITY 🌟

the copyfilerange command is part of the util-linux package, which can be downloaded from the Linux Kernel Archive:

https://www.kernel.org/pub/linux/utils/util-linux/

---

okay that's the whole page bestie, you're officially a copyfilerange girlie now 💖 go make some sparse files, go make some reflinks, go be the main character of your own filesystem ✨

this has been util-linux 2.42.4, dated 2026-09-21, and yes i remembered the version and the date because that's what besties do 💅🦋