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