]>
Commit | Line | Data |
---|---|---|
2bc4bb77 | 1 | .\" This manpage is Copyright (C) 2006 Jens Axboe |
c11b1abf | 2 | .\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
2bc4bb77 | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
2bc4bb77 | 5 | .\" |
4c1c5274 | 6 | .TH splice 2 (date) "Linux man-pages (unreleased)" |
2bc4bb77 MK |
7 | .SH NAME |
8 | splice \- splice data to/from a pipe | |
5d4199fe AC |
9 | .SH LIBRARY |
10 | Standard C library | |
8fc3b2cf | 11 | .RI ( libc ", " \-lc ) |
2bc4bb77 MK |
12 | .SH SYNOPSIS |
13 | .nf | |
b80f966b | 14 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
2bc4bb77 | 15 | .B #include <fcntl.h> |
dbfe9c70 | 16 | .PP |
9bebb17e AC |
17 | .BI "ssize_t splice(int " fd_in ", off64_t *" off_in ", int " fd_out , |
18 | .BI " off64_t *" off_out ", size_t " len \ | |
2bc4bb77 | 19 | ", unsigned int " flags ); |
52520fb5 | 20 | .\" Return type was long before glibc 2.7 |
2bc4bb77 MK |
21 | .fi |
22 | .SH DESCRIPTION | |
23 | .BR splice () | |
c13182ef | 24 | moves data between two file descriptors |
2bc4bb77 MK |
25 | without copying between kernel address space and user address space. |
26 | It transfers up to | |
27 | .I len | |
28 | bytes of data from the file descriptor | |
29 | .I fd_in | |
30 | to the file descriptor | |
31 | .IR fd_out , | |
d9cb0d7d | 32 | where one of the file descriptors must refer to a pipe. |
efeece04 | 33 | .PP |
2377c648 MK |
34 | The following semantics apply for |
35 | .I fd_in | |
36 | and | |
37 | .IR off_in : | |
22356d97 | 38 | .IP \(bu 3 |
2bc4bb77 | 39 | If |
ae39cf8f | 40 | .I fd_in |
2bc4bb77 | 41 | refers to a pipe, then |
c13182ef | 42 | .I off_in |
2bc4bb77 | 43 | must be NULL. |
22356d97 | 44 | .IP \(bu |
2bc4bb77 | 45 | If |
c13182ef | 46 | .I fd_in |
2bc4bb77 | 47 | does not refer to a pipe and |
ae39cf8f | 48 | .I off_in |
c13182ef | 49 | is NULL, then bytes are read from |
ae39cf8f | 50 | .I fd_in |
c72249c5 MK |
51 | starting from the file offset, |
52 | and the file offset is adjusted appropriately. | |
22356d97 | 53 | .IP \(bu |
2bc4bb77 | 54 | If |
c13182ef | 55 | .I fd_in |
2bc4bb77 | 56 | does not refer to a pipe and |
ae39cf8f | 57 | .I off_in |
c13182ef | 58 | is not NULL, then |
ae39cf8f | 59 | .I off_in |
2bc4bb77 MK |
60 | must point to a buffer which specifies the starting |
61 | offset from which bytes will be read from | |
ae39cf8f | 62 | .IR fd_in ; |
c72249c5 | 63 | in this case, the file offset of |
0daa9e92 | 64 | .I fd_in |
2bc4bb77 | 65 | is not changed. |
2377c648 | 66 | .PP |
2bc4bb77 | 67 | Analogous statements apply for |
e267688b | 68 | .I fd_out |
2bc4bb77 | 69 | and |
ae39cf8f | 70 | .IR off_out . |
efeece04 | 71 | .PP |
2bc4bb77 MK |
72 | The |
73 | .I flags | |
74 | argument is a bit mask that is composed by ORing together | |
75 | zero or more of the following values: | |
d467f87c | 76 | .TP |
2bc4bb77 | 77 | .B SPLICE_F_MOVE |
c13182ef | 78 | Attempt to move pages instead of copying. |
2bc4bb77 | 79 | This is only a hint to the kernel: |
c13182ef | 80 | pages may still be copied if the kernel cannot move the |
2bc4bb77 MK |
81 | pages from the pipe, or if |
82 | the pipe buffers don't refer to full pages. | |
986992f3 MK |
83 | The initial implementation of this flag was buggy: |
84 | therefore starting in Linux 2.6.21 it is a no-op | |
85 | (but is still permitted in a | |
86 | .BR splice () | |
87 | call); | |
88 | in the future, a correct implementation may be restored. | |
2bc4bb77 MK |
89 | .TP |
90 | .B SPLICE_F_NONBLOCK | |
91 | Do not block on I/O. | |
ff40dbb3 | 92 | This makes the splice pipe operations nonblocking, but |
2bc4bb77 MK |
93 | .BR splice () |
94 | may nevertheless block because the file descriptors that | |
95 | are spliced to/from may block (unless they have the | |
0daa9e92 | 96 | .B O_NONBLOCK |
2bc4bb77 MK |
97 | flag set). |
98 | .TP | |
99 | .B SPLICE_F_MORE | |
100 | More data will be coming in a subsequent splice. | |
101 | This is a helpful hint when | |
c13182ef | 102 | the |
2bc4bb77 MK |
103 | .I fd_out |
104 | refers to a socket (see also the description of | |
105 | .B MSG_MORE | |
106 | in | |
107 | .BR send (2), | |
108 | and the description of | |
109 | .B TCP_CORK | |
110 | in | |
6b991f94 | 111 | .BR tcp (7)). |
2bc4bb77 MK |
112 | .TP |
113 | .B SPLICE_F_GIFT | |
114 | Unused for | |
115 | .BR splice (); | |
116 | see | |
117 | .BR vmsplice (2). | |
118 | .SH RETURN VALUE | |
119 | Upon successful completion, | |
120 | .BR splice () | |
121 | returns the number of bytes | |
c13182ef | 122 | spliced to or from the pipe. |
efeece04 | 123 | .PP |
cc7b3603 AS |
124 | A return value of 0 means end of input. |
125 | If | |
126 | .I fd_in | |
127 | refers to a pipe, then this means that there was no data to transfer, | |
128 | and it would not make sense to block because there are no writers | |
129 | connected to the write end of the pipe. | |
efeece04 | 130 | .PP |
c13182ef | 131 | On error, |
2bc4bb77 MK |
132 | .BR splice () |
133 | returns \-1 and | |
134 | .I errno | |
135 | is set to indicate the error. | |
136 | .SH ERRORS | |
137 | .TP | |
0655aa15 MK |
138 | .B EAGAIN |
139 | .B SPLICE_F_NONBLOCK | |
140 | was specified in | |
1ae6b2c7 | 141 | .I flags |
4b5e7510 SK |
142 | or one of the file descriptors had been marked as nonblocking |
143 | .RB ( O_NONBLOCK ) , | |
0655aa15 MK |
144 | and the operation would block. |
145 | .TP | |
2bc4bb77 | 146 | .B EBADF |
c13182ef | 147 | One or both file descriptors are not valid, |
2bc4bb77 MK |
148 | or do not have proper read-write mode. |
149 | .TP | |
150 | .B EINVAL | |
be050b69 MK |
151 | The target filesystem doesn't support splicing. |
152 | .TP | |
153 | .B EINVAL | |
154 | The target file is opened in append mode. | |
28081592 MH |
155 | .\" The append-mode error is given since 2.6.27; in earlier kernels, |
156 | .\" splice() in append mode was broken | |
be050b69 MK |
157 | .TP |
158 | .B EINVAL | |
159 | Neither of the file descriptors refers to a pipe. | |
160 | .TP | |
161 | .B EINVAL | |
162 | An offset was given for nonseekable device (e.g., a pipe). | |
2bc4bb77 | 163 | .TP |
be338b52 MK |
164 | .B EINVAL |
165 | .I fd_in | |
166 | and | |
167 | .I fd_out | |
168 | refer to the same pipe. | |
169 | .TP | |
2bc4bb77 MK |
170 | .B ENOMEM |
171 | Out of memory. | |
172 | .TP | |
173 | .B ESPIPE | |
c13182ef | 174 | Either |
2bc4bb77 | 175 | .I off_in |
c13182ef | 176 | or |
2bc4bb77 MK |
177 | .I off_out |
178 | was not NULL, but the corresponding file descriptor refers to a pipe. | |
ff457ccb | 179 | .SH VERSIONS |
2bc4bb77 | 180 | The |
2777b1ca | 181 | .BR splice () |
c95b6ae1 MK |
182 | system call first appeared in Linux 2.6.17; |
183 | library support was added to glibc in version 2.5. | |
3113c7f3 | 184 | .SH STANDARDS |
8382f16d | 185 | This system call is Linux-specific. |
2bc4bb77 MK |
186 | .SH NOTES |
187 | The three system calls | |
2777b1ca | 188 | .BR splice (), |
2bc4bb77 MK |
189 | .BR vmsplice (2), |
190 | and | |
e267688b | 191 | .BR tee (2), |
7fac88a9 | 192 | provide user-space programs with full control over an arbitrary |
2bc4bb77 | 193 | kernel buffer, implemented within the kernel using the same type |
c13182ef | 194 | of buffer that is used for a pipe. |
2bc4bb77 | 195 | In overview, these system calls perform the following tasks: |
4279e42d | 196 | .TP |
2bc4bb77 MK |
197 | .BR splice () |
198 | moves data from the buffer to an arbitrary file descriptor, or vice versa, | |
199 | or from one buffer to another. | |
4279e42d | 200 | .TP |
0bfa087b | 201 | .BR tee (2) |
2bc4bb77 | 202 | "copies" the data from one buffer to another. |
4279e42d | 203 | .TP |
0bfa087b | 204 | .BR vmsplice (2) |
2bc4bb77 MK |
205 | "copies" data from user space into the buffer. |
206 | .PP | |
207 | Though we talk of copying, actual copies are generally avoided. | |
c13182ef | 208 | The kernel does this by implementing a pipe buffer as a set |
2bc4bb77 | 209 | of reference-counted pointers to pages of kernel memory. |
c13182ef MK |
210 | The kernel creates "copies" of pages in a buffer by creating new |
211 | pointers (for the output buffer) referring to the pages, | |
212 | and increasing the reference counts for the pages: | |
2bc4bb77 MK |
213 | only pointers are copied, not the pages of the buffer. |
214 | .\" | |
c13182ef MK |
215 | .\" Linus: Now, imagine using the above in a media server, for example. |
216 | .\" Let's say that a year or two has passed, so that the video drivers | |
217 | .\" have been updated to be able to do the splice thing, and what can | |
2bc4bb77 | 218 | .\" you do? You can: |
c13182ef | 219 | .\" |
2bc4bb77 MK |
220 | .\" - splice from the (mpeg or whatever - let's just assume that the video |
221 | .\" input is either digital or does the encoding on its own - like they | |
222 | .\" pretty much all do) video input into a pipe (remember: no copies - the | |
c13182ef | 223 | .\" video input will just DMA directly into memory, and splice will just |
2bc4bb77 MK |
224 | .\" set up the pages in the pipe buffer) |
225 | .\" - tee that pipe to split it up | |
226 | .\" - splice one end to a file (ie "save the compressed stream to disk") | |
c13182ef | 227 | .\" - splice the other end to a real-time video decoder window for your |
2bc4bb77 MK |
228 | .\" real-time viewing pleasure. |
229 | .\" | |
c13182ef MK |
230 | .\" Linus: Now, the advantage of splice()/tee() is that you can |
231 | .\" do zero-copy movement of data, and unlike sendfile() you can | |
232 | .\" do it on _arbitrary_ data (and, as shown by "tee()", it's more | |
233 | .\" than just sending the data to somebody else: you can duplicate | |
234 | .\" the data and choose to forward it to two or more different | |
0967c11f | 235 | .\" users - for things like logging etc.). |
2bc4bb77 | 236 | .\" |
4c3e1233 MK |
237 | .PP |
238 | In Linux 2.6.30 and earlier, | |
239 | exactly one of | |
240 | .I fd_in | |
241 | and | |
242 | .I fd_out | |
243 | was required to be a pipe. | |
244 | Since Linux 2.6.31, | |
245 | .\" commit 7c77f0b3f9208c339a4b40737bb2cb0f0319bb8d | |
246 | both arguments may refer to pipes. | |
a14af333 | 247 | .SH EXAMPLES |
2bc4bb77 MK |
248 | See |
249 | .BR tee (2). | |
2bc4bb77 | 250 | .SH SEE ALSO |
903b4807 | 251 | .BR copy_file_range (2), |
2bc4bb77 | 252 | .BR sendfile (2), |
0a90178c | 253 | .BR tee (2), |
6c97eb40 MK |
254 | .BR vmsplice (2), |
255 | .BR pipe (7) |