| blob | d168f190df8f27796050b1f580fa70080a4a9ab4 |
1 .\" Copyright (C) 2011 Christopher Yeoh <cyeoh@au1.ibm.com>
2 .\" and Copyright (C) 2012 Mike Frysinger <vapier@gentoo.org>
3 .\" and Copyright (C) 2012 Michael Kerrisk <mtk.man-pages@gmail.com>
4 .\"
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
9 .\"
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
14 .\"
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
21 .\" professionally.
22 .\"
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" %%%LICENSE_END
26 .\"
27 .\" Commit fcf634098c00dd9cd247447368495f0b79be12d1
28 .\"
29 .TH PROCESS_VM_READV 2 2021-03-22 "Linux" "Linux Programmer's Manual"
30 .SH NAME
31 process_vm_readv, process_vm_writev \- transfer data between process address spaces
32 .SH SYNOPSIS
33 .nf
34 .B #include <sys/uio.h>
35 .PP
36 .BI "ssize_t process_vm_readv(pid_t " pid ,
37 .BI " const struct iovec *" local_iov ,
38 .BI " unsigned long " liovcnt ,
39 .BI " const struct iovec *" remote_iov ,
40 .BI " unsigned long " riovcnt ,
41 .BI " unsigned long " flags ");"
42 .BI "ssize_t process_vm_writev(pid_t " pid ,
43 .BI " const struct iovec *" local_iov ,
44 .BI " unsigned long " liovcnt ,
45 .BI " const struct iovec *" remote_iov ,
46 .BI " unsigned long " riovcnt ,
47 .BI " unsigned long " flags ");"
48 .fi
49 .PP
50 .RS -4
51 Feature Test Macro Requirements for glibc (see
52 .BR feature_test_macros (7)):
53 .RE
54 .PP
55 .BR process_vm_readv (),
56 .BR process_vm_writev ():
57 .nf
58 _GNU_SOURCE
59 .fi
60 .SH DESCRIPTION
61 These system calls transfer data between the address space
62 of the calling process ("the local process") and the process identified by
63 .IR pid
64 ("the remote process").
65 The data moves directly between the address spaces of the two processes,
66 without passing through kernel space.
67 .PP
68 The
69 .BR process_vm_readv ()
70 system call transfers data from the remote process to the local process.
71 The data to be transferred is identified by
72 .IR remote_iov
73 and
74 .IR riovcnt :
75 .IR remote_iov
76 is a pointer to an array describing address ranges in the process
77 .IR pid ,
78 and
79 .IR riovcnt
80 specifies the number of elements in
81 .IR remote_iov .
82 The data is transferred to the locations specified by
83 .IR local_iov
84 and
85 .IR liovcnt :
86 .IR local_iov
87 is a pointer to an array describing address ranges in the calling process,
88 and
89 .IR liovcnt
90 specifies the number of elements in
91 .IR local_iov .
92 .PP
93 The
94 .BR process_vm_writev ()
95 system call is the converse of
96 .BR process_vm_readv ()\(emit
97 transfers data from the local process to the remote process.
98 Other than the direction of the transfer, the arguments
99 .IR liovcnt ,
100 .IR local_iov ,
101 .IR riovcnt ,
102 and
103 .IR remote_iov
104 have the same meaning as for
105 .BR process_vm_readv ().
106 .PP
107 The
108 .I local_iov
109 and
110 .I remote_iov
111 arguments point to an array of
112 .I iovec
113 structures, defined in
114 .IR <sys/uio.h>
115 as:
116 .PP
117 .in +4n
118 .EX
119 struct iovec {
120 void *iov_base; /* Starting address */
121 size_t iov_len; /* Number of bytes to transfer */
122 };
123 .EE
124 .in
125 .PP
126 Buffers are processed in array order.
127 This means that
128 .BR process_vm_readv ()
129 completely fills
130 .I local_iov[0]
131 before proceeding to
132 .IR local_iov[1] ,
133 and so on.
134 Likewise,
135 .I remote_iov[0]
136 is completely read before proceeding to
137 .IR remote_iov[1] ,
138 and so on.
139 .PP
140 Similarly,
141 .BR process_vm_writev ()
142 writes out the entire contents of
143 .I local_iov[0]
144 before proceeding to
145 .IR local_iov[1] ,
146 and it completely fills
147 .I remote_iov[0]
148 before proceeding to
149 .IR remote_iov[1] .
150 .PP
151 The lengths of
152 .I remote_iov[i].iov_len
153 and
154 .I local_iov[i].iov_len
155 do not have to be the same.
156 Thus, it is possible to split a single local buffer
157 into multiple remote buffers, or vice versa.
158 .PP
159 The
160 .I flags
161 argument is currently unused and must be set to 0.
162 .PP
163 The values specified in the
164 .I liovcnt
165 and
166 .I riovcnt
167 arguments must be less than or equal to
168 .BR IOV_MAX
169 (defined in
170 .I <limits.h>
171 or accessible via the call
172 .IR sysconf(_SC_IOV_MAX) ).
173 .\" In time, glibc might provide a wrapper that works around this limit,
174 .\" as is done for readv()/writev()
175 .PP
176 The count arguments and
177 .IR local_iov
178 are checked before doing any transfers.
179 If the counts are too big, or
180 .I local_iov
181 is invalid,
182 or the addresses refer to regions that are inaccessible to the local process,
183 none of the vectors will be processed
184 and an error will be returned immediately.
185 .PP
186 Note, however, that these system calls do not check the memory regions
187 in the remote process until just before doing the read/write.
188 Consequently, a partial read/write (see RETURN VALUE)
189 may result if one of the
190 .I remote_iov
191 elements points to an invalid memory region in the remote process.
192 No further reads/writes will be attempted beyond that point.
193 Keep this in mind when attempting to read data of unknown length
194 (such as C strings that are null-terminated) from a remote process,
195 by avoiding spanning memory pages (typically 4\ KiB) in a single remote
196 .I iovec
197 element.
198 (Instead, split the remote read into two
199 .I remote_iov
200 elements and have them merge back into a single write
201 .I local_iov
202 entry.
203 The first read entry goes up to the page boundary,
204 while the second starts on the next page boundary.)
205 .PP
206 Permission to read from or write to another process
207 is governed by a ptrace access mode
208 .B PTRACE_MODE_ATTACH_REALCREDS
209 check; see
210 .BR ptrace (2).
211 .SH RETURN VALUE
212 On success,
213 .BR process_vm_readv ()
214 returns the number of bytes read and
215 .BR process_vm_writev ()
216 returns the number of bytes written.
217 This return value may be less than the total number of requested bytes,
218 if a partial read/write occurred.
219 (Partial transfers apply at the granularity of
220 .I iovec
221 elements.
222 These system calls won't perform a partial transfer that splits a single
223 .I iovec
224 element.)
225 The caller should check the return value to determine whether
226 a partial read/write occurred.
227 .PP
228 On error, \-1 is returned and
229 .I errno
230 is set to indicate the error.
231 .SH ERRORS
232 .TP
233 .B EFAULT
234 The memory described by
235 .I local_iov
236 is outside the caller's accessible address space.
237 .TP
238 .B EFAULT
239 The memory described by
240 .I remote_iov
241 is outside the accessible address space of the process
242 .IR pid .
243 .TP
244 .B EINVAL
245 The sum of the
246 .I iov_len
247 values of either
248 .I local_iov
249 or
250 .I remote_iov
251 overflows a
252 .I ssize_t
253 value.
254 .TP
255 .B EINVAL
256 .I flags
257 is not 0.
258 .TP
259 .B EINVAL
260 .I liovcnt
261 or
262 .I riovcnt
263 is too large.
264 .TP
265 .B ENOMEM
266 Could not allocate memory for internal copies of the
267 .I iovec
268 structures.
269 .TP
270 .B EPERM
271 The caller does not have permission to access the address space of the process
272 .IR pid .
273 .TP
274 .B ESRCH
275 No process with ID
276 .I pid
277 exists.
278 .SH VERSIONS
279 These system calls were added in Linux 3.2.
280 Support is provided in glibc since version 2.15.
281 .SH CONFORMING TO
282 These system calls are nonstandard Linux extensions.
283 .SH NOTES
284 The data transfers performed by
285 .BR process_vm_readv ()
286 and
287 .BR process_vm_writev ()
288 are not guaranteed to be atomic in any way.
289 .PP
290 These system calls were designed to permit fast message passing
291 by allowing messages to be exchanged with a single copy operation
292 (rather than the double copy that would be required
293 when using, for example, shared memory or pipes).
294 .\" Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/
295 .\" See also some benchmarks at http://lwn.net/Articles/405284/
296 .\" and http://marc.info/?l=linux-mm&m=130105930902915&w=2
297 .SH EXAMPLES
298 The following code sample demonstrates the use of
299 .BR process_vm_readv ().
300 It reads 20 bytes at the address 0x10000 from the process with PID 10
301 and writes the first 10 bytes into
302 .I buf1
303 and the second 10 bytes into
304 .IR buf2 .
305 .PP
306 .EX
307 #include <sys/uio.h>
309 int
310 main(void)
311 {
312 struct iovec local[2];
313 struct iovec remote[1];
314 char buf1[10];
315 char buf2[10];
316 ssize_t nread;
317 pid_t pid = 10; /* PID of remote process */
319 local[0].iov_base = buf1;
320 local[0].iov_len = 10;
321 local[1].iov_base = buf2;
322 local[1].iov_len = 10;
323 remote[0].iov_base = (void *) 0x10000;
324 remote[0].iov_len = 20;
326 nread = process_vm_readv(pid, local, 2, remote, 1, 0);
327 if (nread != 20)
328 return 1;
329 else
330 return 0;
331 }
332 .EE
333 .SH SEE ALSO
334 .BR readv (2),
335 .BR writev (2)