| .\" This manpage is Copyright (C) 2006 Jens Axboe |
| .\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .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 ); |
| .\" 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 * 3 |
| If |
| .I fd_in |
| refers to a pipe, then |
| .I off_in |
| must be NULL. |
| .IP * |
| 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 * |
| 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 |
| .IR flags , |
| 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 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 VERSIONS |
| The |
| .BR splice () |
| system call first appeared in Linux 2.6.17; |
| library support was added to glibc in version 2.5. |
| .SH CONFORMING TO |
| This system call is Linux-specific. |
| .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 1.2i |
| .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.). |
| .\" |
| .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 pipe (7) |