]>
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 | .\" |
45186a5d | 6 | .TH VMSPLICE 2 2021-03-22 "Linux man-pages (unreleased)" |
2bc4bb77 | 7 | .SH NAME |
dc7b1aab | 8 | vmsplice \- splice user pages to/from a pipe |
351ed1c7 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 |
52520fb5 | 17 | .BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov , |
2b83f493 | 18 | .BI " size_t " nr_segs ", unsigned int " flags ); |
2bc4bb77 | 19 | .fi |
52520fb5 | 20 | .\" Return type was long before glibc 2.7 |
2bc4bb77 | 21 | .SH DESCRIPTION |
c13182ef MK |
22 | .\" Linus: vmsplice() system call to basically do a "write to |
23 | .\" the buffer", but using the reference counting and VM traversal | |
24 | .\" to actually fill the buffer. This means that the user needs to | |
3b777aff | 25 | .\" be careful not to reuse the user-space buffer it spliced into |
c13182ef | 26 | .\" the kernel-space one (contrast this to "write()", which copies |
3b777aff | 27 | .\" the actual data, and you can thus reuse the buffer immediately |
c13182ef | 28 | .\" after a successful write), but that is often easy to do. |
dc7b1aab AV |
29 | If |
30 | .I fd | |
b94a87a5 | 31 | is opened for writing, the |
2bc4bb77 MK |
32 | .BR vmsplice () |
33 | system call maps | |
34 | .I nr_segs | |
35 | ranges of user memory described by | |
36 | .I iov | |
c13182ef | 37 | into a pipe. |
dc7b1aab AV |
38 | If |
39 | .I fd | |
40 | is opened for reading, | |
41 | .\" Since Linux 2.6.23 | |
42 | .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7 | |
43 | the | |
44 | .BR vmsplice () | |
45 | system call fills | |
46 | .I nr_segs | |
47 | ranges of user memory described by | |
48 | .I iov | |
49 | from a pipe. | |
2bc4bb77 | 50 | The file descriptor |
c13182ef | 51 | .I fd |
2bc4bb77 | 52 | must refer to a pipe. |
efeece04 | 53 | .PP |
2bc4bb77 MK |
54 | The pointer |
55 | .I iov | |
56 | points to an array of | |
57 | .I iovec | |
cb336616 AC |
58 | structures as described in |
59 | .BR iovec (3type). | |
efeece04 | 60 | .PP |
2bc4bb77 MK |
61 | The |
62 | .I flags | |
63 | argument is a bit mask that is composed by ORing together | |
64 | zero or more of the following values: | |
c6228d17 | 65 | .TP |
2bc4bb77 MK |
66 | .B SPLICE_F_MOVE |
67 | Unused for | |
68 | .BR vmsplice (); | |
69 | see | |
70 | .BR splice (2). | |
71 | .TP | |
72 | .B SPLICE_F_NONBLOCK | |
73 | .\" Not used for vmsplice | |
74 | .\" May be in the future -- therefore EAGAIN | |
c13182ef MK |
75 | Do not block on I/O; see |
76 | .BR splice (2) | |
2bc4bb77 MK |
77 | for further details. |
78 | .TP | |
79 | .B SPLICE_F_MORE | |
c13182ef | 80 | Currently has no effect for |
2bc4bb77 MK |
81 | .BR vmsplice (), |
82 | but may be implemented in the future; see | |
83 | .BR splice (2). | |
84 | .TP | |
85 | .B SPLICE_F_GIFT | |
c13182ef MK |
86 | The user pages are a gift to the kernel. |
87 | The application may not modify this memory ever, | |
bea08fec | 88 | .\" FIXME . Explain the following line in a little more detail: |
8031e529 | 89 | otherwise the page cache and on-disk data may differ. |
2bc4bb77 | 90 | Gifting pages to the kernel means that a subsequent |
0bfa087b | 91 | .BR splice (2) |
2bc4bb77 MK |
92 | .B SPLICE_F_MOVE |
93 | can successfully move the pages; | |
94 | if this flag is not specified, then a subsequent | |
0bfa087b | 95 | .BR splice (2) |
2bc4bb77 MK |
96 | .B SPLICE_F_MOVE |
97 | must copy the pages. | |
98 | Data must also be properly page aligned, both in memory and length. | |
ced56703 | 99 | .\" FIXME |
68c11e15 MK |
100 | .\" It looks like the page-alignment requirement went away with |
101 | .\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d | |
ced56703 | 102 | .\" |
2bc4bb77 MK |
103 | .\" .... if we expect to later SPLICE_F_MOVE to the cache. |
104 | .SH RETURN VALUE | |
105 | Upon successful completion, | |
106 | .BR vmsplice () | |
c13182ef MK |
107 | returns the number of bytes transferred to the pipe. |
108 | On error, | |
d504a994 | 109 | .BR vmsplice () |
2bc4bb77 MK |
110 | returns \-1 and |
111 | .I errno | |
112 | is set to indicate the error. | |
113 | .SH ERRORS | |
114 | .TP | |
56cb0650 MK |
115 | .B EAGAIN |
116 | .B SPLICE_F_NONBLOCK | |
117 | was specified in | |
118 | .IR flags , | |
119 | and the operation would block. | |
120 | .TP | |
2bc4bb77 MK |
121 | .B EBADF |
122 | .I fd | |
123 | either not valid, or doesn't refer to a pipe. | |
124 | .TP | |
125 | .B EINVAL | |
126 | .I nr_segs | |
a2cf8898 | 127 | is greater than |
4df883b9 | 128 | .BR IOV_MAX ; |
2bc4bb77 MK |
129 | or memory not aligned if |
130 | .B SPLICE_F_GIFT | |
131 | set. | |
132 | .TP | |
133 | .B ENOMEM | |
134 | Out of memory. | |
2dd578fd MK |
135 | .SH VERSIONS |
136 | The | |
2777b1ca | 137 | .BR vmsplice () |
c95b6ae1 MK |
138 | system call first appeared in Linux 2.6.17; |
139 | library support was added to glibc in version 2.5. | |
3113c7f3 | 140 | .SH STANDARDS |
8382f16d | 141 | This system call is Linux-specific. |
2bc4bb77 MK |
142 | .SH NOTES |
143 | .BR vmsplice () | |
144 | follows the other vectorized read/write type functions when it comes to | |
8031e529 | 145 | limitations on the number of segments being passed in. |
2bc4bb77 MK |
146 | This limit is |
147 | .B IOV_MAX | |
148 | as defined in | |
149 | .IR <limits.h> . | |
8031e529 MK |
150 | Currently, |
151 | .\" UIO_MAXIOV in kernel source | |
152 | this limit is 1024. | |
dc7b1aab AV |
153 | .PP |
154 | .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7 | |
155 | .BR vmsplice () | |
b94a87a5 | 156 | really supports true splicing only from user memory to a pipe. |
ba2c4752 | 157 | In the opposite direction, it actually just copies the data to user space. |
b94a87a5 MK |
158 | But this makes the interface nice and symmetric and enables people to build on |
159 | .BR vmsplice () | |
dc7b1aab | 160 | with room for future improvement in performance. |
2bc4bb77 MK |
161 | .SH SEE ALSO |
162 | .BR splice (2), | |
6c97eb40 MK |
163 | .BR tee (2), |
164 | .BR pipe (7) |