.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
-.TH SPLICE 2 2014-12-31 "Linux" "Linux Programmer's Manual"
+.TH SPLICE 2 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
splice \- splice data to/from a pipe
.SH SYNOPSIS
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <fcntl.h>
-
+.PP
.BI "ssize_t splice(int " fd_in ", loff_t *" off_in ", int " fd_out ,
.BI " loff_t *" off_out ", size_t " len \
", unsigned int " flags );
.I fd_in
to the file descriptor
.IR fd_out ,
-where one of the descriptors must refer to a pipe.
-
+where one of the file descriptors must refer to a pipe.
+.PP
The following semantics apply for
.I fd_in
and
.I off_in
is NULL, then bytes are read from
.I fd_in
-starting from the current file offset,
-and the current file offset is adjusted appropriately.
+starting from the file offset,
+and the file offset is adjusted appropriately.
.IP *
If
.I fd_in
must point to a buffer which specifies the starting
offset from which bytes will be read from
.IR fd_in ;
-in this case, the current file offset of
+in this case, the file offset of
.I fd_in
is not changed.
.PP
.I fd_out
and
.IR off_out .
-
+.PP
The
.I flags
argument is a bit mask that is composed by ORing together
zero or more of the following values:
-.TP 1.9i
+.TP
.B SPLICE_F_MOVE
Attempt to move pages instead of copying.
This is only a hint to the kernel:
and the description of
.B TCP_CORK
in
-.BR tcp (7))
+.BR tcp (7)).
.TP
.B SPLICE_F_GIFT
Unused for
.BR splice ()
returns the number of bytes
spliced to or from the pipe.
-A return value of 0 means that there was no data to transfer,
-and it would not make sense to block, because there are no
-writers connected to the write end of the pipe referred to by
-.IR fd_in .
-
+.PP
+A return value of 0 means end of input.
+If
+.I fd_in
+refers to a pipe, then this means that there was no data to transfer,
+and it would not make sense to block because there are no writers
+connected to the write end of the pipe.
+.PP
On error,
.BR splice ()
returns \-1 and
or do not have proper read-write mode.
.TP
.B EINVAL
-Target filesystem doesn't support splicing;
-target file is opened in append mode;
+The target filesystem doesn't support splicing.
+.TP
+.B EINVAL
+The target file is opened in append mode.
.\" The append-mode error is given since 2.6.27; in earlier kernels,
.\" splice() in append mode was broken
-neither of the descriptors refers to a pipe; or
-offset given for nonseekable device.
+.TP
+.B EINVAL
+Neither of the file descriptors refers to a pipe.
+.TP
+.B EINVAL
+An offset was given for nonseekable device (e.g., a pipe).
+.TP
+.B EINVAL
+.I fd_in
+and
+.I fd_out
+refer to the same pipe.
.TP
.B ENOMEM
Out of memory.
.\" the data and choose to forward it to two or more different
.\" users - for things like logging etc.).
.\"
+.PP
+In Linux 2.6.30 and earlier,
+exactly one of
+.I fd_in
+and
+.I fd_out
+was required to be a pipe.
+Since Linux 2.6.31,
+.\" commit 7c77f0b3f9208c339a4b40737bb2cb0f0319bb8d
+both arguments may refer to pipes.
.SH EXAMPLE
See
.BR tee (2).
.SH SEE ALSO
+.BR copy_file_range (2),
.BR sendfile (2),
.BR tee (2),
-.BR vmsplice (2)
+.BR vmsplice (2),
+.BR pipe (7)