Commit | Line | Data |
---|---|---|
f758e908 JA |
1 | .TH vmsplice 2 2006-04-28 "Linux 2.6.17" "Linux Programmer's Manual" |
2 | .SH NAME | |
3 | vmsplice \- splice user pages into a pipe | |
4 | .SH SYNOPSIS | |
5 | .B #include <sys/uio.h> | |
6 | ||
7 | .B long vmsplice(int fd, const struct iovec *iov, unsigned long nr_segs, unsigned ing flags); | |
8 | ||
9 | .SH DESCRIPTION | |
8d2541ed JA |
10 | The |
11 | .BR vmsplice () | |
12 | function maps | |
13 | .I nr_segs | |
14 | range(s) of | |
15 | .I iov | |
16 | described user memory into a pipe. The | |
17 | .I fd must refer to a pipe. | |
f758e908 | 18 | |
8d2541ed JA |
19 | The pointer |
20 | .I iov | |
21 | points to an array of | |
22 | .I struct iovec | |
23 | entries as defined in | |
24 | .IR <sys/uio.h> : | |
f758e908 JA |
25 | |
26 | .nf | |
27 | struct iovec { | |
28 | void *iov_base; /* Starting address */ | |
29 | size_t iov_len; /* Number of bytes */ | |
30 | }; | |
31 | .fi | |
32 | ||
8d2541ed JA |
33 | The |
34 | .I flags | |
35 | argument is a series of modifier flags. Only | |
f758e908 JA |
36 | .B SPLICE_F_NONBLOCK |
37 | and | |
38 | .B SPLICE_F_GIFT | |
8d2541ed JA |
39 | really apply to |
40 | .BR vmsplice () | |
41 | , the but the scope is shared with | |
db093e53 | 42 | .BR splice (2). |
f758e908 JA |
43 | |
44 | .TP 1.9i | |
45 | .B SPLICE_F_MOVE | |
db093e53 JA |
46 | See |
47 | .BR splice (2). | |
f758e908 JA |
48 | .TP |
49 | .B SPLICE_F_NONBLOCK | |
50 | Do not block on io. | |
51 | .TP | |
52 | .B SPLICE_F_MORE | |
53 | More data will be coming in a subsequent splice. | |
54 | .TP | |
55 | .B SPLICE_F_GIFT | |
56 | The user pages are a gift to the kernel. The application may not reuse this | |
57 | memory ever, or page cache and on disk data may differ. Data must also be | |
8d2541ed | 58 | properly page aligned, both in memory and length. |
f758e908 JA |
59 | |
60 | .SH RETURN VALUE | |
8d2541ed JA |
61 | Upon successful completion, |
62 | .BR vmsplice () | |
63 | shall return the number of bytes spliced to the pipe. Otherwise, it shall | |
64 | return a value of -1 and | |
65 | .I errno | |
f758e908 JA |
66 | shall be set to indicate an error. |
67 | ||
68 | .SH ERRORS | |
8d2541ed JA |
69 | .TP 1.1i |
70 | .B EBADF | |
71 | .I fd | |
72 | either not valid, or doesn't refer to a pipe. | |
73 | .TP | |
74 | .B EINVAL | |
75 | .I nr_segs | |
76 | not valid, memory not aligned if | |
77 | .I SPLICE_F_GIFT | |
f758e908 | 78 | set. |
8736f97c JA |
79 | .TP |
80 | .B ENOMEM | |
81 | Ran out of memory. | |
f758e908 JA |
82 | |
83 | .SH NOTES | |
8d2541ed JA |
84 | .BR vmsplice () |
85 | follows the other vectorized read/write type functions when it comes to | |
86 | limitations on number of segments being passed in. This limit is | |
87 | .B IOV_MAX | |
88 | as defined in | |
89 | .IR <limits.h> . | |
90 | At the time of this writing, that limit is 1024. | |
91 | ||
5d79a465 JA |
92 | .SH HISTORY |
93 | The | |
94 | .BR vmsplice (2) | |
95 | system call first appeared in Linux-2.6.17. | |
96 | ||
8d2541ed JA |
97 | .SH SEE ALSO |
98 | .BR splice (2), | |
99 | .BR tee (2) | |
f758e908 JA |
100 | |
101 | .SH AUTHORS | |
92f10c2d | 102 | Jens Axboe <axboe@kernel.dk> |