[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 (2).

.TP 1.9i
.B SPLICE_F_MOVE
See
.BR splice (2).
.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.
.TP
.B ENOMEM
Ran out of memory.

.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 HISTORY
The
.BR vmsplice (2)
system call first appeared in Linux-2.6.17.

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

.SH AUTHORS
Jens Axboe <axboe@kernel.dk>
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
db093e53	42	.BR splice (2).
f758e908 JA	43
	44	.TP 1.9i
	45	.B SPLICE_F_MOVE
db093e53 JA	46	See
db093e53 JA	47	.BR splice (2).
f758e908 JA	48	.TP
	49	.B SPLICE_F_NONBLOCK
	50	Do not block on io.
	51	.TP
	52	.B SPLICE_F_MORE
	53	More data will be coming in a subsequent splice.
	54	.TP
	55	.B SPLICE_F_GIFT
	56	The user pages are a gift to the kernel. The application may not reuse this
	57	memory ever, or page cache and on disk data may differ. Data must also be
8d2541ed	58	properly page aligned, both in memory and length.
f758e908 JA	59
f758e908 JA	60	.SH RETURN VALUE
8d2541ed JA	61	Upon successful completion,
	62	.BR vmsplice ()
	63	shall return the number of bytes spliced to the pipe. Otherwise, it shall
	64	return a value of -1 and
	65	.I errno
f758e908 JA	66	shall be set to indicate an error.
	67
	68	.SH ERRORS
8d2541ed JA	69	.TP 1.1i
	70	.B EBADF
	71	.I fd
	72	either not valid, or doesn't refer to a pipe.
	73	.TP
	74	.B EINVAL
	75	.I nr_segs
	76	not valid, memory not aligned if
	77	.I SPLICE_F_GIFT
f758e908	78	set.
8736f97c JA	79	.TP
	80	.B ENOMEM
	81	Ran out of memory.
f758e908 JA	82
f758e908 JA	83	.SH NOTES
8d2541ed JA	84	.BR vmsplice ()
	85	follows the other vectorized read/write type functions when it comes to
	86	limitations on number of segments being passed in. This limit is
	87	.B IOV_MAX
	88	as defined in
	89	.IR <limits.h> .
	90	At the time of this writing, that limit is 1024.
	91
5d79a465 JA	92	.SH HISTORY
	93	The
	94	.BR vmsplice (2)
	95	system call first appeared in Linux-2.6.17.
	96
8d2541ed JA	97	.SH SEE ALSO
	98	.BR splice (2),
	99	.BR tee (2)
f758e908 JA	100
f758e908 JA	101	.SH AUTHORS
92f10c2d	102	Jens Axboe <axboe@kernel.dk>