Debian Codegraph @

upstream/debian-unstable/man2/vmsplice.2

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