diff options
Diffstat (limited to 'man/man2/splice.2')
| -rw-r--r-- | man/man2/splice.2 | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/man/man2/splice.2 b/man/man2/splice.2 new file mode 100644 index 000000000..e5d05a05c --- /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 (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 #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) |