| blob | 9102c4c924839834ac0c2b54a8471c88c97fa539 |
1 .\" This manpage is Copyright (C) 2006 Jens Axboe
2 .\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
8 .\"
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
13 .\"
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
20 .\" professionally.
21 .\"
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" %%%LICENSE_END
25 .\"
26 .TH VMSPLICE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
27 .SH NAME
28 vmsplice \- splice user pages to/from a pipe
29 .SH SYNOPSIS
30 .nf
31 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
32 .B #include <fcntl.h>
33 .PP
34 .BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov ,
35 .BI " size_t " nr_segs ", unsigned int " flags );
36 .fi
37 .\" Return type was long before glibc 2.7
38 .SH DESCRIPTION
39 .\" Linus: vmsplice() system call to basically do a "write to
40 .\" the buffer", but using the reference counting and VM traversal
41 .\" to actually fill the buffer. This means that the user needs to
42 .\" be careful not to reuse the user-space buffer it spliced into
43 .\" the kernel-space one (contrast this to "write()", which copies
44 .\" the actual data, and you can thus reuse the buffer immediately
45 .\" after a successful write), but that is often easy to do.
46 If
47 .I fd
48 is opened for writing, the
49 .BR vmsplice ()
50 system call maps
51 .I nr_segs
52 ranges of user memory described by
53 .I iov
54 into a pipe.
55 If
56 .I fd
57 is opened for reading,
58 .\" Since Linux 2.6.23
59 .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
60 the
61 .BR vmsplice ()
62 system call fills
63 .I nr_segs
64 ranges of user memory described by
65 .I iov
66 from a pipe.
67 The file descriptor
68 .I fd
69 must refer to a pipe.
70 .PP
71 The pointer
72 .I iov
73 points to an array of
74 .I iovec
75 structures as defined in
76 .IR <sys/uio.h> :
77 .PP
78 .in +4n
79 .EX
80 struct iovec {
81 void *iov_base; /* Starting address */
82 size_t iov_len; /* Number of bytes */
83 };
84 .EE
85 .in
86 .PP
87 The
88 .I flags
89 argument is a bit mask that is composed by ORing together
90 zero or more of the following values:
91 .TP
92 .B SPLICE_F_MOVE
93 Unused for
94 .BR vmsplice ();
95 see
96 .BR splice (2).
97 .TP
98 .B SPLICE_F_NONBLOCK
99 .\" Not used for vmsplice
100 .\" May be in the future -- therefore EAGAIN
101 Do not block on I/O; see
102 .BR splice (2)
103 for further details.
104 .TP
105 .B SPLICE_F_MORE
106 Currently has no effect for
107 .BR vmsplice (),
108 but may be implemented in the future; see
109 .BR splice (2).
110 .TP
111 .B SPLICE_F_GIFT
112 The user pages are a gift to the kernel.
113 The application may not modify this memory ever,
114 .\" FIXME . Explain the following line in a little more detail:
115 otherwise the page cache and on-disk data may differ.
116 Gifting pages to the kernel means that a subsequent
117 .BR splice (2)
118 .B SPLICE_F_MOVE
119 can successfully move the pages;
120 if this flag is not specified, then a subsequent
121 .BR splice (2)
122 .B SPLICE_F_MOVE
123 must copy the pages.
124 Data must also be properly page aligned, both in memory and length.
125 .\" FIXME
126 .\" It looks like the page-alignment requirement went away with
127 .\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d
128 .\"
129 .\" .... if we expect to later SPLICE_F_MOVE to the cache.
130 .SH RETURN VALUE
131 Upon successful completion,
132 .BR vmsplice ()
133 returns the number of bytes transferred to the pipe.
134 On error,
135 .BR vmsplice ()
136 returns \-1 and
137 .I errno
138 is set to indicate the error.
139 .SH ERRORS
140 .TP
141 .B EAGAIN
142 .B SPLICE_F_NONBLOCK
143 was specified in
144 .IR flags ,
145 and the operation would block.
146 .TP
147 .B EBADF
148 .I fd
149 either not valid, or doesn't refer to a pipe.
150 .TP
151 .B EINVAL
152 .I nr_segs
153 is greater than
154 .BR IOV_MAX ;
155 or memory not aligned if
156 .B SPLICE_F_GIFT
157 set.
158 .TP
159 .B ENOMEM
160 Out of memory.
161 .SH VERSIONS
162 The
163 .BR vmsplice ()
164 system call first appeared in Linux 2.6.17;
165 library support was added to glibc in version 2.5.
166 .SH CONFORMING TO
167 This system call is Linux-specific.
168 .SH NOTES
169 .BR vmsplice ()
170 follows the other vectorized read/write type functions when it comes to
171 limitations on the number of segments being passed in.
172 This limit is
173 .B IOV_MAX
174 as defined in
175 .IR <limits.h> .
176 Currently,
177 .\" UIO_MAXIOV in kernel source
178 this limit is 1024.
179 .PP
180 .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
181 .BR vmsplice ()
182 really supports true splicing only from user memory to a pipe.
183 In the opposite direction, it actually just copies the data to user space.
184 But this makes the interface nice and symmetric and enables people to build on
185 .BR vmsplice ()
186 with room for future improvement in performance.
187 .SH SEE ALSO
188 .BR splice (2),
189 .BR tee (2),
190 .BR pipe (7)