Debian Codegraph @

upstream/debian-unstable/man2/splice.2

raw
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)