--- /dev/null
+.TH splice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
+.SH NAME
+splice \- splice data to/from a pipe.
+.SH SYNOPSIS
+.B #include <sys/splice.h>
+
+.B long splice(int fd_in, loff_t *off_in, int fd_out, loff_t *off_out, size_t bytes, unsigned int flags);
+
+.SH DESCRIPTION
+The act of splicing can be seen as a way to connect two ends of a rope
+through a kernel buffer, where that buffer is implemented as a pipe. It
+provides a means to move data around without copying it to/from kernel/user
+address space.
+
+The
+.BR splice ()
+function splices
+.I bytes
+of data between file descriptor
+.I fd_in
+and
+.IR fd_out ,
+where one of the descriptors must refer to a pipe. The
+.I flags
+argument is a series of modifier flags:
+
+.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. This is a helpful hint when
+the output descriptor refers to a socket, see also
+.B MSG_MORE
+(see
+.BR send (2)
+and
+.B TCP_CORK
+.BR tcp (7))
+.TP
+.B SPLICE_F_GIFT
+See
+.BR vmsplice (2).
+
+.SH RETURN VALUE
+Upon successful completion,
+.BR splice ()
+shall return the number of bytes
+spliced to or from 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 none of the descriptors refer to a pipe.
+.TP
+.B EINVAL
+Target file system doesn't support splicing, none of the descriptors refer
+to a pipe or offset given for non-seekable device.
+
+.SH SEE ALSO
+.BR splice (2),
+.BR tee (2)
+
+.SH AUTHORS
+Jens Axboe <axboe@suse.de>
--- /dev/null
+.TH tee 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual"
+.SH NAME
+tee \- duplicating pipe content.
+.SH SYNOPSIS
+.B #include <sys/splice.h>
+
+.B long tee(int fd_in, int fd_out, size_t bytes, unsigned int flags);
+
+.SH DESCRIPTION
+.BR tee ()
+duplicates at most
+.I bytes
+of content from pipe
+.I fd_in
+to pipe
+.IR fd_out .
+.I flags
+is a series of modifier flags, which share the name space with
+.BR splice (2)
+and
+.BR vmsplice (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
+See
+.BR vmsplice (2)
+
+.PP
+.BR tee ()
+doesn't copy any data around, it simply references the input data and
+links it to the output pipe.
+
+.SH RETURN VALUE
+Upon successful completion,
+.BR tee ()
+shall return the number of bytes that was duplicated between the input
+and output. 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 none of the descriptors refer to a pipe.
+.TP
+.B EINVAL
+Target file system doesn't support splicing, none of the descriptors refer
+to a pipe or offset given for non-seekable device.
+
+.SH SEE ALSO
+.BR splice (2),
+.BR vmsplice (2)
+
+.SH AUTHORS
+Jens Axboe <axboe@suse.de>
.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
+.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 \fIiov\fR points to an array of \fIstruct iovec\fR entries as
-defined in \fI<sys/uio.h>\fR:
+The pointer
+.I iov
+points to an array of
+.I struct iovec
+entries as defined in
+.IR <sys/uio.h> :
.nf
struct iovec {
};
.fi
-The \fIflags\fR argument is a series of modifier flags. Only
+The
+.I flags
+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().
+really apply to
+.BR vmsplice ()
+, the but the scope is shared with
+.BR splice ().
.TP 1.9i
.B SPLICE_F_MOVE
.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.
+properly page aligned, both in memory and length.
.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
+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
-.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
+.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
-\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.
+.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>
projects / splice.git / commitdiff