summaryrefslogtreecommitdiffstats
path: root/man2/splice.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/splice.2')
-rw-r--r--man2/splice.2266
1 files changed, 0 insertions, 266 deletions
diff --git a/man2/splice.2 b/man2/splice.2
deleted file mode 100644
index ff39e03..0000000
--- a/man2/splice.2
+++ /dev/null
@@ -1,266 +0,0 @@
-.\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)