| 1 |
.\" Copyright 2006, Jens Axboe <[email protected]> |
| 2 |
.\" Copyright 2006, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH splice 2 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
splice \- splice data to/from a pipe |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| 16 |
.B #define _FILE_OFFSET_BITS 64 |
| 17 |
.B #include <fcntl.h> |
| 18 |
.P |
| 19 |
.BI "ssize_t splice(int " fd_in ", off_t *_Nullable " off_in , |
| 20 |
.BI " int " fd_out ", off_t *_Nullable " off_out , |
| 21 |
.BI " size_t " size ", unsigned int " flags ); |
| 22 |
.\" Return type was long before glibc 2.7 |
| 23 |
.fi |
| 24 |
.SH DESCRIPTION |
| 25 |
.BR splice () |
| 26 |
moves data between two file descriptors |
| 27 |
without copying between kernel address space and user address space. |
| 28 |
It transfers up to |
| 29 |
.I size |
| 30 |
bytes of data from the file descriptor |
| 31 |
.I fd_in |
| 32 |
to the file descriptor |
| 33 |
.IR fd_out , |
| 34 |
where one of the file descriptors must refer to a pipe. |
| 35 |
.P |
| 36 |
The following semantics apply for |
| 37 |
.I fd_in |
| 38 |
and |
| 39 |
.IR off_in : |
| 40 |
.IP \[bu] 3 |
| 41 |
If |
| 42 |
.I fd_in |
| 43 |
refers to a pipe, then |
| 44 |
.I off_in |
| 45 |
must be NULL. |
| 46 |
.IP \[bu] |
| 47 |
If |
| 48 |
.I fd_in |
| 49 |
does not refer to a pipe and |
| 50 |
.I off_in |
| 51 |
is NULL, then bytes are read from |
| 52 |
.I fd_in |
| 53 |
starting from the file offset, |
| 54 |
and the file offset is adjusted appropriately. |
| 55 |
.IP \[bu] |
| 56 |
If |
| 57 |
.I fd_in |
| 58 |
does not refer to a pipe and |
| 59 |
.I off_in |
| 60 |
is not NULL, then |
| 61 |
.I off_in |
| 62 |
must point to a buffer which specifies the starting |
| 63 |
offset from which bytes will be read from |
| 64 |
.IR fd_in ; |
| 65 |
in this case, the file offset of |
| 66 |
.I fd_in |
| 67 |
is not changed, |
| 68 |
and the offset pointed to by |
| 69 |
.I off_in |
| 70 |
is adjusted appropriately instead. |
| 71 |
.P |
| 72 |
Analogous statements apply for |
| 73 |
.I fd_out |
| 74 |
and |
| 75 |
.IR off_out . |
| 76 |
.P |
| 77 |
The |
| 78 |
.I flags |
| 79 |
argument is a bit mask that is composed by ORing together |
| 80 |
zero or more of the following values: |
| 81 |
.TP |
| 82 |
.B SPLICE_F_MOVE |
| 83 |
Attempt to move pages instead of copying. |
| 84 |
This is only a hint to the kernel: |
| 85 |
pages may still be copied if the kernel cannot move the |
| 86 |
pages from the pipe, or if |
| 87 |
the pipe buffers don't refer to full pages. |
| 88 |
The initial implementation of this flag was buggy: |
| 89 |
therefore starting in Linux 2.6.21 it is a no-op |
| 90 |
(but is still permitted in a |
| 91 |
.BR splice () |
| 92 |
call); |
| 93 |
in the future, a correct implementation may be restored. |
| 94 |
.TP |
| 95 |
.B SPLICE_F_NONBLOCK |
| 96 |
Do not block on I/O. |
| 97 |
This makes the splice pipe operations nonblocking, but |
| 98 |
.BR splice () |
| 99 |
may nevertheless block because the file descriptors that |
| 100 |
are spliced to/from may block (unless they have the |
| 101 |
.B O_NONBLOCK |
| 102 |
flag set). |
| 103 |
.TP |
| 104 |
.B SPLICE_F_MORE |
| 105 |
More data will be coming in a subsequent splice. |
| 106 |
This is a helpful hint when |
| 107 |
the |
| 108 |
.I fd_out |
| 109 |
refers to a socket (see also the description of |
| 110 |
.B MSG_MORE |
| 111 |
in |
| 112 |
.BR send (2), |
| 113 |
and the description of |
| 114 |
.B TCP_CORK |
| 115 |
in |
| 116 |
.BR tcp (7)). |
| 117 |
.TP |
| 118 |
.B SPLICE_F_GIFT |
| 119 |
Unused for |
| 120 |
.BR splice (); |
| 121 |
see |
| 122 |
.BR vmsplice (2). |
| 123 |
.SH RETURN VALUE |
| 124 |
Upon successful completion, |
| 125 |
.BR splice () |
| 126 |
returns the number of bytes |
| 127 |
spliced to or from the pipe. |
| 128 |
.P |
| 129 |
A return value of 0 means end of input. |
| 130 |
If |
| 131 |
.I fd_in |
| 132 |
refers to a pipe, then this means that there was no data to transfer, |
| 133 |
and it would not make sense to block because there are no writers |
| 134 |
connected to the write end of the pipe. |
| 135 |
.P |
| 136 |
On error, |
| 137 |
.BR splice () |
| 138 |
returns \-1 and |
| 139 |
.I errno |
| 140 |
is set to indicate the error. |
| 141 |
.SH ERRORS |
| 142 |
.TP |
| 143 |
.B EAGAIN |
| 144 |
.B SPLICE_F_NONBLOCK |
| 145 |
was specified in |
| 146 |
.I flags |
| 147 |
or one of the file descriptors had been marked as nonblocking |
| 148 |
.RB ( O_NONBLOCK ) , |
| 149 |
and the operation would block. |
| 150 |
.TP |
| 151 |
.B EBADF |
| 152 |
One or both file descriptors are not valid, |
| 153 |
or do not have proper read-write mode. |
| 154 |
.TP |
| 155 |
.B EINVAL |
| 156 |
The target filesystem doesn't support splicing. |
| 157 |
.TP |
| 158 |
.B EINVAL |
| 159 |
The target file is opened in append mode. |
| 160 |
.\" The append-mode error is given since Linux 2.6.27; in earlier kernels, |
| 161 |
.\" splice() in append mode was broken |
| 162 |
.TP |
| 163 |
.B EINVAL |
| 164 |
Neither of the file descriptors refers to a pipe. |
| 165 |
.TP |
| 166 |
.B EINVAL |
| 167 |
An offset was given for nonseekable device (e.g., a pipe). |
| 168 |
.TP |
| 169 |
.B EINVAL |
| 170 |
.I fd_in |
| 171 |
and |
| 172 |
.I fd_out |
| 173 |
refer to the same pipe. |
| 174 |
.TP |
| 175 |
.B ENOMEM |
| 176 |
Out of memory. |
| 177 |
.TP |
| 178 |
.B ESPIPE |
| 179 |
Either |
| 180 |
.I off_in |
| 181 |
or |
| 182 |
.I off_out |
| 183 |
was not NULL, but the corresponding file descriptor refers to a pipe. |
| 184 |
.SH STANDARDS |
| 185 |
Linux. |
| 186 |
.SH HISTORY |
| 187 |
Linux 2.6.17, |
| 188 |
glibc 2.5. |
| 189 |
.P |
| 190 |
In Linux 2.6.30 and earlier, |
| 191 |
exactly one of |
| 192 |
.I fd_in |
| 193 |
and |
| 194 |
.I fd_out |
| 195 |
was required to be a pipe. |
| 196 |
Since Linux 2.6.31, |
| 197 |
.\" commit 7c77f0b3f9208c339a4b40737bb2cb0f0319bb8d |
| 198 |
both arguments may refer to pipes. |
| 199 |
.SH NOTES |
| 200 |
The three system calls |
| 201 |
.BR splice (), |
| 202 |
.BR vmsplice (2), |
| 203 |
and |
| 204 |
.BR tee (2), |
| 205 |
provide user-space programs with full control over an arbitrary |
| 206 |
kernel buffer, implemented within the kernel using the same type |
| 207 |
of buffer that is used for a pipe. |
| 208 |
In overview, these system calls perform the following tasks: |
| 209 |
.TP |
| 210 |
.BR splice () |
| 211 |
moves data from the buffer to an arbitrary file descriptor, or vice versa, |
| 212 |
or from one buffer to another. |
| 213 |
.TP |
| 214 |
.BR tee (2) |
| 215 |
"copies" the data from one buffer to another. |
| 216 |
.TP |
| 217 |
.BR vmsplice (2) |
| 218 |
"copies" data from user space into the buffer. |
| 219 |
.P |
| 220 |
Though we talk of copying, actual copies are generally avoided. |
| 221 |
The kernel does this by implementing a pipe buffer as a set |
| 222 |
of reference-counted pointers to pages of kernel memory. |
| 223 |
The kernel creates "copies" of pages in a buffer by creating new |
| 224 |
pointers (for the output buffer) referring to the pages, |
| 225 |
and increasing the reference counts for the pages: |
| 226 |
only pointers are copied, not the pages of the buffer. |
| 227 |
.\" |
| 228 |
.\" Linus: Now, imagine using the above in a media server, for example. |
| 229 |
.\" Let's say that a year or two has passed, so that the video drivers |
| 230 |
.\" have been updated to be able to do the splice thing, and what can |
| 231 |
.\" you do? You can: |
| 232 |
.\" |
| 233 |
.\" - splice from the (mpeg or whatever - let's just assume that the video |
| 234 |
.\" input is either digital or does the encoding on its own - like they |
| 235 |
.\" pretty much all do) video input into a pipe (remember: no copies - the |
| 236 |
.\" video input will just DMA directly into memory, and splice will just |
| 237 |
.\" set up the pages in the pipe buffer) |
| 238 |
.\" - tee that pipe to split it up |
| 239 |
.\" - splice one end to a file (ie "save the compressed stream to disk") |
| 240 |
.\" - splice the other end to a real-time video decoder window for your |
| 241 |
.\" real-time viewing pleasure. |
| 242 |
.\" |
| 243 |
.\" Linus: Now, the advantage of splice()/tee() is that you can |
| 244 |
.\" do zero-copy movement of data, and unlike sendfile() you can |
| 245 |
.\" do it on _arbitrary_ data (and, as shown by "tee()", it's more |
| 246 |
.\" than just sending the data to somebody else: you can duplicate |
| 247 |
.\" the data and choose to forward it to two or more different |
| 248 |
.\" users - for things like logging etc.). |
| 249 |
.\" |
| 250 |
.P |
| 251 |
.B _FILE_OFFSET_BITS |
| 252 |
should be defined to be 64 in code that uses non-null |
| 253 |
.I off_in |
| 254 |
or |
| 255 |
.I off_out |
| 256 |
or that takes the address of |
| 257 |
.BR splice , |
| 258 |
if the code is intended to be portable |
| 259 |
to traditional 32-bit x86 and ARM platforms where |
| 260 |
.BR off_t 's |
| 261 |
width defaults to 32 bits. |
| 262 |
.SH EXAMPLES |
| 263 |
See |
| 264 |
.BR tee (2) |
| 265 |
for another example. |
| 266 |
.P |
| 267 |
.\" SRC BEGIN (splice.c) |
| 268 |
.EX |
| 269 |
\& |
| 270 |
#define _GNU_SOURCE |
| 271 |
#define _FILE_OFFSET_BITS 64 |
| 272 |
#include <err.h> |
| 273 |
#include <fcntl.h> |
| 274 |
#include <stdint.h> |
| 275 |
#include <stdio.h> |
| 276 |
#include <stdlib.h> |
| 277 |
#include <sys/types.h> |
| 278 |
#include <unistd.h> |
| 279 |
\& |
| 280 |
int |
| 281 |
main(void) |
| 282 |
{ |
| 283 |
int fd; |
| 284 |
int pfd[2]; |
| 285 |
off_t off; |
| 286 |
[[gnu::nonstring]] |
| 287 |
const char s[12] = "Hello, world"; |
| 288 |
\& |
| 289 |
fd = open("out", O_WRONLY | O_CREAT | O_EXCL, 0666); |
| 290 |
if (fd == \-1) |
| 291 |
err(EXIT_FAILURE, "open"); |
| 292 |
\& |
| 293 |
if (pipe(pfd) == \-1) |
| 294 |
err(EXIT_FAILURE, "pipe"); |
| 295 |
\& |
| 296 |
if (write(pfd[1], s, sizeof(s)) != sizeof(s)) |
| 297 |
err(EXIT_FAILURE, "write"); |
| 298 |
if (close(pfd[1]) == \-1) |
| 299 |
err(EXIT_FAILURE, "close"); |
| 300 |
\& |
| 301 |
off = 10; |
| 302 |
if (splice(pfd[0], NULL, fd, &off, sizeof(s), 0) != sizeof(s)) |
| 303 |
err(EXIT_FAILURE, "splice"); |
| 304 |
if (close(pfd[0]) == \-1) |
| 305 |
err(EXIT_FAILURE, "close"); |
| 306 |
\& |
| 307 |
printf("New offset is %jd\[rs]n", (intmax_t) off); |
| 308 |
\& |
| 309 |
if (close(fd) == \-1) |
| 310 |
err(EXIT_FAILURE, "close"); |
| 311 |
exit(EXIT_SUCCESS); |
| 312 |
} |
| 313 |
.EE |
| 314 |
.\" SRC END |
| 315 |
.SH SEE ALSO |
| 316 |
.BR copy_file_range (2), |
| 317 |
.BR sendfile (2), |
| 318 |
.BR tee (2), |
| 319 |
.BR vmsplice (2), |
| 320 |
.BR pipe (7) |