1 files changed, 162 insertions, 0 deletions
diff --git a/man2/vmsplice.2 b/man2/vmsplice.2
new file mode 100644
index 0000000..4520b8a
--- /dev/null
+++ b/man2/vmsplice.2
@@ -0,0 +1,162 @@
+.\" This manpage is Copyright (C) 2006 Jens Axboe
+.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH vmsplice 2 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+vmsplice \- splice user pages to/from a pipe
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <fcntl.h>
+.PP
+.BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov ,
+.BI "                 size_t " nr_segs ", unsigned int " flags );
+.fi
+.\" Return type was long before glibc 2.7
+.SH DESCRIPTION
+.\" Linus: vmsplice() system call to basically do a "write to
+.\" the buffer", but using the reference counting and VM traversal
+.\" to actually fill the buffer. This means that the user needs to
+.\" be careful not to reuse the user-space buffer it spliced into
+.\" the kernel-space one (contrast this to "write()", which copies
+.\" the actual data, and you can thus reuse the buffer immediately
+.\" after a successful write), but that is often easy to do.
+If
+.I fd
+is opened for writing, the
+.BR vmsplice ()
+system call maps
+.I nr_segs
+ranges of user memory described by
+.I iov
+into a pipe.
+If
+.I fd
+is opened for reading,
+.\" Since Linux 2.6.23
+.\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
+the
+.BR vmsplice ()
+system call fills
+.I nr_segs
+ranges of user memory described by
+.I iov
+from a pipe.
+The file descriptor
+.I fd
+must refer to a pipe.
+.PP
+The pointer
+.I iov
+points to an array of
+.I iovec
+structures as described in
+.BR iovec (3type).
+.PP
+The
+.I flags
+argument is a bit mask that is composed by ORing together
+zero or more of the following values:
+.TP
+.B SPLICE_F_MOVE
+Unused for
+.BR vmsplice ();
+see
+.BR splice (2).
+.TP
+.B SPLICE_F_NONBLOCK
+.\" Not used for vmsplice
+.\" May be in the future -- therefore EAGAIN
+Do not block on I/O; see
+.BR splice (2)
+for further details.
+.TP
+.B SPLICE_F_MORE
+Currently has no effect for
+.BR vmsplice (),
+but may be implemented in the future; see
+.BR splice (2).
+.TP
+.B SPLICE_F_GIFT
+The user pages are a gift to the kernel.
+The application may not modify this memory ever,
+.\" FIXME . Explain the following line in a little more detail:
+otherwise the page cache and on-disk data may differ.
+Gifting pages to the kernel means that a subsequent
+.BR splice (2)
+.B SPLICE_F_MOVE
+can successfully move the pages;
+if this flag is not specified, then a subsequent
+.BR splice (2)
+.B SPLICE_F_MOVE
+must copy the pages.
+Data must also be properly page aligned, both in memory and length.
+.\" FIXME
+.\" It looks like the page-alignment requirement went away with
+.\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d
+.\"
+.\" .... if we expect to later SPLICE_F_MOVE to the cache.
+.SH RETURN VALUE
+Upon successful completion,
+.BR vmsplice ()
+returns the number of bytes transferred to the pipe.
+On error,
+.BR vmsplice ()
+returns \-1 and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+.B SPLICE_F_NONBLOCK
+was specified in
+.IR flags ,
+and the operation would block.
+.TP
+.B EBADF
+.I fd
+either not valid, or doesn't refer to a pipe.
+.TP
+.B EINVAL
+.I nr_segs
+is greater than
+.BR IOV_MAX ;
+or memory not aligned if
+.B SPLICE_F_GIFT
+set.
+.TP
+.B ENOMEM
+Out of memory.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.17,
+glibc 2.5.
+.SH NOTES
+.BR vmsplice ()
+follows the other vectorized read/write type functions when it comes to
+limitations on the number of segments being passed in.
+This limit is
+.B IOV_MAX
+as defined in
+.IR <limits.h> .
+Currently,
+.\" UIO_MAXIOV in kernel source
+this limit is 1024.
+.PP
+.\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
+.BR 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.
+But this makes the interface nice and symmetric and enables people to build on
+.BR vmsplice ()
+with room for future improvement in performance.
+.SH SEE ALSO
+.BR splice (2),
+.BR tee (2),
+.BR pipe (7)