execve.2, exec.3: Consistently use the term 'pathname' (not 'path')

[thirdparty/man-pages.git] / man2 / splice.2

diff --git a/man2/splice.2 b/man2/splice.2
index f1d0b8a1fa7116a2b825177514ef998c6ba6eeb4..57988d9d641f86bfa4abd893a4e2283a6eee7024 100644 (file)
--- a/man2/splice.2
+++ b/man2/splice.2
@@ -23,14 +23,14 @@
 .\" 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 );
@@ -47,7 +47,7 @@ bytes of data from the file descriptor
 to the file descriptor
 .IR fd_out ,
 where one of the file descriptors must refer to a pipe.
-
+.PP
 The following semantics apply for
 .I fd_in
 and
@@ -85,12 +85,12 @@ Analogous statements apply for
 .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:
@@ -137,11 +137,14 @@ Upon successful completion,
 .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
@@ -160,12 +163,24 @@ One or both file descriptors are not valid,
 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 file 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.
@@ -234,10 +249,22 @@ only pointers are copied, not the pages of the buffer.
 .\" 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)