Commit | Line | Data |
---|---|---|
8d2541ed JA |
1 | .TH splice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual" |
2 | .SH NAME | |
3 | splice \- splice data to/from a pipe. | |
4 | .SH SYNOPSIS | |
5 | .B #include <sys/splice.h> | |
6 | ||
7 | .B long splice(int fd_in, loff_t *off_in, int fd_out, loff_t *off_out, size_t bytes, unsigned int flags); | |
8 | ||
9 | .SH DESCRIPTION | |
10 | The act of splicing can be seen as a way to connect two ends of a rope | |
11 | through a kernel buffer, where that buffer is implemented as a pipe. It | |
12 | provides a means to move data around without copying it to/from kernel/user | |
8736f97c JA |
13 | address space, basically a random kernel buffer that the user has full |
14 | control over. | |
8d2541ed JA |
15 | |
16 | The | |
17 | .BR splice () | |
18 | function splices | |
19 | .I bytes | |
20 | of data between file descriptor | |
21 | .I fd_in | |
22 | and | |
23 | .IR fd_out , | |
24 | where one of the descriptors must refer to a pipe. The | |
25 | .I flags | |
26 | argument is a series of modifier flags: | |
27 | ||
28 | .TP 1.9i | |
29 | .B SPLICE_F_MOVE | |
db093e53 JA |
30 | Attempt to move pages instead of copying. This is only a hint to the kernel, |
31 | pages may still be copied if we fail in stealing it out of the pipe or if | |
32 | the pipe buffers don't refer to full pages. | |
8d2541ed JA |
33 | .TP |
34 | .B SPLICE_F_NONBLOCK | |
35 | Do not block on io. | |
36 | .TP | |
37 | .B SPLICE_F_MORE | |
38 | More data will be coming in a subsequent splice. This is a helpful hint when | |
39 | the output descriptor refers to a socket, see also | |
40 | .B MSG_MORE | |
8736f97c | 41 | (see |
8d2541ed JA |
42 | .BR send (2) |
43 | and | |
44 | .B TCP_CORK | |
45 | .BR tcp (7)) | |
46 | .TP | |
47 | .B SPLICE_F_GIFT | |
48 | See | |
49 | .BR vmsplice (2). | |
50 | ||
51 | .SH RETURN VALUE | |
52 | Upon successful completion, | |
53 | .BR splice () | |
54 | shall return the number of bytes | |
55 | spliced to or from the pipe. Otherwise, it shall return a value of -1 and | |
56 | .I errno | |
57 | shall be set to indicate an error. | |
58 | ||
59 | .SH ERRORS | |
60 | .TP 1.1i | |
61 | .B EBADF | |
5d79a465 | 62 | File descriptors either not valid, or do not have proper rw permission. |
8d2541ed JA |
63 | .TP |
64 | .B EINVAL | |
65 | Target file system doesn't support splicing, none of the descriptors refer | |
66 | to a pipe or offset given for non-seekable device. | |
8736f97c JA |
67 | .TP |
68 | .B ENOMEM | |
69 | Ran out of memory. | |
8d2541ed | 70 | |
5d79a465 JA |
71 | .SH HISTORY |
72 | The | |
73 | .BR splice (2) | |
74 | system call first appeared in Linux-2.6.17. | |
75 | ||
8d2541ed JA |
76 | .SH SEE ALSO |
77 | .BR splice (2), | |
78 | .BR tee (2) | |
79 | ||
80 | .SH AUTHORS | |
81 | Jens Axboe <axboe@suse.de> |