[splice.git] / vmsplice.2

.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
.BR vmsplice ()
function maps
.I nr_segs
range(s) of
.I iov
described user memory into a pipe. The
.I fd must refer to a pipe.

The pointer
.I iov
points to an array of
.I struct iovec
entries as defined in
.IR <sys/uio.h> :

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

The
.I flags
argument is a series of modifier flags. Only
.B SPLICE_F_NONBLOCK
and
.B SPLICE_F_GIFT
really apply to
.BR vmsplice ()
, the but the scope is shared with
.BR splice ().

.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, both in memory and length.

.SH RETURN VALUE
Upon successful completion,
.BR vmsplice ()
shall return the number of bytes spliced to the pipe. Otherwise, it shall
return a value of -1 and
.I errno
shall be set to indicate an error.

.SH ERRORS
.TP 1.1i
.B EBADF
.I fd
either not valid, or doesn't refer to a pipe.
.TP
.B EINVAL
.I nr_segs
not valid, memory not aligned if
.I SPLICE_F_GIFT
set.

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

.SH SEE ALSO
.BR splice (2),
.BR tee (2)

.SH AUTHORS
Jens Axboe <axboe@suse.de>
Commit	Line	Data
f758e908 JA	1	.TH vmsplice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
	2	.SH NAME
	3	vmsplice \- splice user pages into a pipe
	4	.SH SYNOPSIS
	5	.B #include <sys/uio.h>
	6
	7	.B long vmsplice(int fd, const struct iovec *iov, unsigned long nr_segs, unsigned ing flags);
	8
	9	.SH DESCRIPTION
8d2541ed JA	10	The
	11	.BR vmsplice ()
	12	function maps
	13	.I nr_segs
	14	range(s) of
	15	.I iov
	16	described user memory into a pipe. The
	17	.I fd must refer to a pipe.
f758e908	18
8d2541ed JA	19	The pointer
	20	.I iov
	21	points to an array of
	22	.I struct iovec
	23	entries as defined in
	24	.IR <sys/uio.h> :
f758e908 JA	25
	26	.nf
	27	struct iovec {
	28	void iov_base; / Starting address */
	29	size_t iov_len; /* Number of bytes */
	30	};
	31	.fi
	32
8d2541ed JA	33	The
	34	.I flags
	35	argument is a series of modifier flags. Only
f758e908 JA	36	.B SPLICE_F_NONBLOCK
	37	and
	38	.B SPLICE_F_GIFT
8d2541ed JA	39	really apply to
	40	.BR vmsplice ()
	41	, the but the scope is shared with
	42	.BR splice ().
f758e908 JA	43
	44	.TP 1.9i
	45	.B SPLICE_F_MOVE
	46	Attempt to move pages instead of copying.
	47	.TP
	48	.B SPLICE_F_NONBLOCK
	49	Do not block on io.
	50	.TP
	51	.B SPLICE_F_MORE
	52	More data will be coming in a subsequent splice.
	53	.TP
	54	.B SPLICE_F_GIFT
	55	The user pages are a gift to the kernel. The application may not reuse this
	56	memory ever, or page cache and on disk data may differ. Data must also be
8d2541ed	57	properly page aligned, both in memory and length.
f758e908 JA	58
f758e908 JA	59	.SH RETURN VALUE
8d2541ed JA	60	Upon successful completion,
	61	.BR vmsplice ()
	62	shall return the number of bytes spliced to the pipe. Otherwise, it shall
	63	return a value of -1 and
	64	.I errno
f758e908 JA	65	shall be set to indicate an error.
	66
	67	.SH ERRORS
8d2541ed JA	68	.TP 1.1i
	69	.B EBADF
	70	.I fd
	71	either not valid, or doesn't refer to a pipe.
	72	.TP
	73	.B EINVAL
	74	.I nr_segs
	75	not valid, memory not aligned if
	76	.I SPLICE_F_GIFT
f758e908 JA	77	set.
	78
	79	.SH NOTES
8d2541ed JA	80	.BR vmsplice ()
	81	follows the other vectorized read/write type functions when it comes to
	82	limitations on number of segments being passed in. This limit is
	83	.B IOV_MAX
	84	as defined in
	85	.IR <limits.h> .
	86	At the time of this writing, that limit is 1024.
	87
	88	.SH SEE ALSO
	89	.BR splice (2),
	90	.BR tee (2)
f758e908 JA	91
	92	.SH AUTHORS
	93	Jens Axboe <axboe@suse.de>