Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 266 insertions, 0 deletions

diff --git a/man/man2/splice.2 b/man/man2/splice.2
new file mode 100644
index 0000000..9bc52ea
--- /dev/null
+++ b/man/man2/splice.2
@@ -0,0 +1,266 @@
+.\" This manpage is Copyright (C) 2006 Jens Axboe
+.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH splice 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+splice \- splice data to/from a pipe
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #define _FILE_OFFSET_BITS  64
+.B #include <fcntl.h>
+.P
+.BI "ssize_t splice(int " fd_in ", off_t *_Nullable " off_in ,
+.BI "               int " fd_out ", off_t *_Nullable " off_out ,
+.BI "               size_t " len ", unsigned int " flags );
+.\" Return type was long before glibc 2.7
+.fi
+.SH DESCRIPTION
+.BR splice ()
+moves data between two file descriptors
+without copying between kernel address space and user address space.
+It transfers up to
+.I len
+bytes of data from the file descriptor
+.I fd_in
+to the file descriptor
+.IR fd_out ,
+where one of the file descriptors must refer to a pipe.
+.P
+The following semantics apply for
+.I fd_in
+and
+.IR off_in :
+.IP \[bu] 3
+If
+.I fd_in
+refers to a pipe, then
+.I off_in
+must be NULL.
+.IP \[bu]
+If
+.I fd_in
+does not refer to a pipe and
+.I off_in
+is NULL, then bytes are read from
+.I fd_in
+starting from the file offset,
+and the file offset is adjusted appropriately.
+.IP \[bu]
+If
+.I fd_in
+does not refer to a pipe and
+.I off_in
+is not NULL, then
+.I off_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 file offset of
+.I fd_in
+is not changed.
+.P
+Analogous statements apply for
+.I fd_out
+and
+.IR off_out .
+.P
+The
+.I flags
+argument is a bit mask that is composed by ORing together
+zero or more of the following values:
+.TP
+.B SPLICE_F_MOVE
+Attempt to move pages instead of copying.
+This is only a hint to the kernel:
+pages may still be copied if the kernel cannot move the
+pages from the pipe, or if
+the pipe buffers don't refer to full pages.
+The initial implementation of this flag was buggy:
+therefore starting in Linux 2.6.21 it is a no-op
+(but is still permitted in a
+.BR splice ()
+call);
+in the future, a correct implementation may be restored.
+.TP
+.B SPLICE_F_NONBLOCK
+Do not block on I/O.
+This makes the splice pipe operations nonblocking, but
+.BR splice ()
+may nevertheless block because the file descriptors that
+are spliced to/from may block (unless they have the
+.B O_NONBLOCK
+flag set).
+.TP
+.B SPLICE_F_MORE
+More data will be coming in a subsequent splice.
+This is a helpful hint when
+the
+.I fd_out
+refers to a socket (see also the description of
+.B MSG_MORE
+in
+.BR send (2),
+and the description of
+.B TCP_CORK
+in
+.BR tcp (7)).
+.TP
+.B SPLICE_F_GIFT
+Unused for
+.BR splice ();
+see
+.BR vmsplice (2).
+.SH RETURN VALUE
+Upon successful completion,
+.BR splice ()
+returns the number of bytes
+spliced to or from the pipe.
+.P
+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.
+.P
+On error,
+.BR splice ()
+returns \-1 and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+.B SPLICE_F_NONBLOCK
+was specified in
+.I flags
+or one of the file descriptors had been marked as nonblocking
+.RB ( O_NONBLOCK ) ,
+and the operation would block.
+.TP
+.B EBADF
+One or both file descriptors are not valid,
+or do not have proper read-write mode.
+.TP
+.B EINVAL
+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 Linux 2.6.27; in earlier kernels,
+.\" splice() in append mode was broken
+.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.
+.TP
+.B ESPIPE
+Either
+.I off_in
+or
+.I off_out
+was not NULL, but the corresponding file descriptor refers to a pipe.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.17,
+glibc 2.5.
+.P
+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 NOTES
+The three system calls
+.BR splice (),
+.BR vmsplice (2),
+and
+.BR tee (2),
+provide user-space programs with full control over an arbitrary
+kernel buffer, implemented within the kernel using the same type
+of buffer that is used for a pipe.
+In overview, these system calls perform the following tasks:
+.TP
+.BR splice ()
+moves data from the buffer to an arbitrary file descriptor, or vice versa,
+or from one buffer to another.
+.TP
+.BR tee (2)
+"copies" the data from one buffer to another.
+.TP
+.BR vmsplice (2)
+"copies" data from user space into the buffer.
+.P
+Though we talk of copying, actual copies are generally avoided.
+The kernel does this by implementing a pipe buffer as a set
+of reference-counted pointers to pages of kernel memory.
+The kernel creates "copies" of pages in a buffer by creating new
+pointers (for the output buffer) referring to the pages,
+and increasing the reference counts for the pages:
+only pointers are copied, not the pages of the buffer.
+.\"
+.\" Linus: Now, imagine using the above in a media server, for example.
+.\" Let's say that a year or two has passed, so that the video drivers
+.\" have been updated to be able to do the splice thing, and what can
+.\" you do? You can:
+.\"
+.\" - splice from the (mpeg or whatever - let's just assume that the video
+.\"   input is either digital or does the encoding on its own - like they
+.\"   pretty much all do) video input into a pipe (remember: no copies - the
+.\"   video input will just DMA directly into memory, and splice will just
+.\"   set up the pages in the pipe buffer)
+.\" - tee that pipe to split it up
+.\" - splice one end to a file (ie "save the compressed stream to disk")
+.\" - splice the other end to a real-time video decoder window for your
+.\"   real-time viewing pleasure.
+.\"
+.\" Linus: Now, the advantage of splice()/tee() is that you can
+.\" do zero-copy movement of data, and unlike sendfile() you can
+.\" do it on _arbitrary_ data (and, as shown by "tee()", it's more
+.\" than just sending the data to somebody else: you can duplicate
+.\" the data and choose to forward it to two or more different
+.\" users - for things like logging etc.).
+.\"
+.P
+.B _FILE_OFFSET_BITS
+should be defined to be 64 in code that uses non-null
+.I off_in
+or
+.I off_out
+or that takes the address of
+.BR splice ,
+if the code is intended to be portable
+to traditional 32-bit x86 and ARM platforms where
+.BR off_t 's
+width defaults to 32 bits.
+.SH EXAMPLES
+See
+.BR tee (2).
+.SH SEE ALSO
+.BR copy_file_range (2),
+.BR sendfile (2),
+.BR tee (2),
+.BR vmsplice (2),
+.BR pipe (7)