Debian Codegraph @

upstream/debian-unstable/man2/process_vm_readv.2

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