.TH vmsplice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
.SH NAME
vmsplice \- splice user pages into a pipe
.SH SYNOPSIS
.B #include <sys/uio.h>

.B long vmsplice(int fd, const struct iovec *iov, unsigned long nr_segs, unsigned ing flags);

.SH DESCRIPTION
The \fIvmsplice\fR() function maps \fInr_segs\fR range(s) of \fIiov\fR described user memory into a pipe. The \fIfd\fR must refer to a pipe.

The pointer \fIiov\fR points to an array of \fIstruct iovec\fR entries as
defined in \fI<sys/uio.h>\fR:

.nf
  struct iovec {
	void *iov_base;		/* Starting address */
	size_t iov_len;		/* Number of bytes */
  };
.fi

The \fIflags\fR argument is a series of modifier flags. Only
.B SPLICE_F_NONBLOCK
and
.B SPLICE_F_GIFT
really apply to \fIvmsplice\fR(), the but the scope is shared with
\fBsplice\fR().

.TP 1.9i
.B SPLICE_F_MOVE
Attempt to move pages instead of copying.
.TP
.B SPLICE_F_NONBLOCK
Do not block on io.
.TP
.B SPLICE_F_MORE
More data will be coming in a subsequent splice.
.TP
.B SPLICE_F_GIFT
The user pages are a gift to the kernel. The application may not reuse this
memory ever, or page cache and on disk data may differ. Data must also be
properly page aligned.

.SH RETURN VALUE
Upon successful completion, \fIvmsplice\fR() shall return the number of bytes
spliced to the pipe. Otherwise, it shall return a value of -1 and \fIerrno\fR
shall be set to indicate an error.

.SH ERRORS
.B EBADF \fIfd\fR either not valid, or doesn't refer to a pipe.
.TP 7
.B EINVAL \fInr_segs\fR not valid, memory not aligned if \fISPLICE_F_GIFT\fR
set.

.SH NOTES
\fIvmsplice\fR() follows the other vectorized read/write type functions when
it comes to limitations on number of segments being passed in. This limit
is \fBIOV_MAX\fR as defined in \fI<limits.h>\fR. At the time of this writing,
that limit is 1024.

.SH AUTHORS
Jens Axboe <axboe@suse.de>