vmsplice(2)

💖 vmsplice(2) 💖

okay bestie, welcome to the System Calls Manual, section 2. this is the one, this is the girl. let's get into it 🫶

---

✨ NAME ✨

vmsplice — splice user pages to/from a pipe

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🎀 SYNOPSIS 🎀

#define _GNU_SOURCE         /* See feature_test_macros(7) */
#include <fcntl.h>

ssize_t vmsplice(int fd, const struct iovec *iov,
                 size_t nr_segs, unsigned int flags);

---

🌸 DESCRIPTION 🌸

so here's the tea, bestie. if fd is opened for writing, vmsplice() takes nr_segs ranges of your user memory — the ones described by iov — and maps them into a pipe. and if fd is opened for reading, it does the opposite: it fills nr_segs ranges of user memory described by iov from a pipe. 🦋

the file descriptor fd must refer to a pipe. no pipe, no party. 💅

the pointer iov points at an array of iovec structures, exactly as described in iovec(3type).

the flags argument is a bit mask that you build by ORing together zero or more of these values:

SPLICE_F_MOVE

unused for vmsplice(). literally just hanging out. go read splice(2) if you're curious. 🙈

SPLICE_F_NONBLOCK

do not block on I/O. that's it, that's the vibe. more deets in splice(2).

SPLICE_F_MORE

currently has no effect for vmsplice(), but it might get implemented in the future. she's booked but not confirmed. see splice(2).

SPLICE_F_GIFT

ok this one's the main character. 👑

the user pages are a gift to the kernel. and when i say gift i mean it — the application may not modify this memory ever, otherwise the page cache and on-disk data may differ. no takebacks, no regifting, no editing. 😭

why would you do this? because gifting pages to the kernel means a subsequent splice(2) SPLICE_F_MOVE can actually move the pages. if you don't specify this flag, then a subsequent splice(2) SPLICE_F_MOVE has to copy the pages instead. move > copy, obviously.

also, data must be properly page aligned — both in memory and in length. both!! if your length is off, we have a problem.

---

🫶 RETURN VALUE 🫶

on a successful slay, vmsplice() returns the number of bytes transferred to the pipe.

on error, it returns -1 and errno is set to tell you what went wrong. 💀

---

🚨 ERRORS 🚨

• EAGAIN — SPLICE_F_NONBLOCK was specified in flags, and the operation would block.
• EBADF — fd is either not valid, or doesn't refer to a pipe.
• EINVAL — nr_segs is greater than IOV_MAX; or memory not aligned if SPLICE_F_GIFT set.
• ENOMEM — out of memory.

---

⭐ STANDARDS ⭐

Linux. that's the whole list, bestie.

---

🌈 HISTORY 🌈

Linux 2.6.17, glibc 2.5. a classic, an icon, a legend. ✨

---

💜 NOTES 💜

vmsplice() follows the other vectorized read/write type functions when it comes to limitations on the number of segments being passed in. that limit is IOV_MAX, as defined in <limits.h>. and currently? that limit is 1024. periodt.

and here's the plot twist 🍓 — vmsplice() really supports true splicing only from user memory to a pipe. in the opposite direction, it actually just copies the data to user space. it's not actually splicing, it's cosplaying as splicing. 🙈

but lowkey that's fine, because it makes the interface nice and symmetric and enables people to build on vmsplice() with room for future improvement in performance. she's got potential, okay?? 👑

---

👀 SEE ALSO 👀

splice(2), tee(2), pipe(7)

---

and that's the whole page, bestie!! this was pulled from Linux man-pages 6.20, dated 2026-02-08, and it's the vmsplice(2) page itself. go forth and splice responsibly. no cap. 💅💖✨