diff options
Diffstat (limited to 'man2/splice.2')
| -rw-r--r-- | man2/splice.2 | 253 |
1 files changed, 0 insertions, 253 deletions
diff --git a/man2/splice.2 b/man2/splice.2 deleted file mode 100644 index dd78e8cd4..000000000 --- a/man2/splice.2 +++ /dev/null @@ -1,253 +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 (date) "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 #include <fcntl.h> -.PP -.BI "ssize_t splice(int " fd_in ", off64_t *_Nullable " off_in , -.BI " int " fd_out ", off64_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. -.PP -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. -.PP -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 -.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. -.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 -.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. -.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 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. -.PP -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.). -.\" -.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) |