Debian Codegraph @

upstream/debian-trixie/man2/process_vm_readv.2

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