1PROCESS_VM_READV(2) Linux Programmer's Manual PROCESS_VM_READV(2)
2
6 process_vm_readv, process_vm_writev - transfer data between process
7 address spaces
8
10 #include <sys/uio.h>
11 ssize_t process_vm_readv(pid_t pid,
13 const struct iovec *local_iov,
14 unsigned long liovcnt,
15 const struct iovec *remote_iov,
16 unsigned long riovcnt,
17 unsigned long flags);
18 ssize_t process_vm_writev(pid_t pid,
20 const struct iovec *local_iov,
21 unsigned long liovcnt,
22 const struct iovec *remote_iov,
23 unsigned long riovcnt,
24 unsigned long flags);
25 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
27 process_vm_readv(), process_vm_writev():
29 _GNU_SOURCE
30
32 These system calls transfer data between the address space of the call‐
33 ing process ("the local process") and the process identified by pid
34 ("the remote process"). The data moves directly between the address
35 spaces of the two processes, without passing through kernel space.
36 The process_vm_readv() system call transfers data from the remote
38 process to the local process. The data to be transferred is identified
39 by remote_iov and riovcnt: remote_iov is a pointer to an array describ‐
40 ing address ranges in the process pid, and riovcnt specifies the number
41 of elements in remote_iov. The data is transferred to the locations
42 specified by local_iov and liovcnt: local_iov is a pointer to an array
43 describing address ranges in the calling process, and liovcnt specifies
44 the number of elements in local_iov.
45 The process_vm_writev() system call is the converse of
47 process_vm_readv()—it transfers data from the local process to the
48 remote process. Other than the direction of the transfer, the argu‐
49 ments liovcnt, local_iov, riovcnt, and remote_iov have the same meaning
50 as for process_vm_readv().
51 The local_iov and remote_iov arguments point to an array of iovec
53 structures, defined in <sys/uio.h> as:
54 struct iovec {
56 void *iov_base; /* Starting address */
57 size_t iov_len; /* Number of bytes to transfer */
58 };
59 Buffers are processed in array order. This means that
61 process_vm_readv() completely fills local_iov[0] before proceeding to
62 local_iov[1], and so on. Likewise, remote_iov[0] is completely read
63 before proceeding to remote_iov[1], and so on.
64 Similarly, process_vm_writev() writes out the entire contents of
66 local_iov[0] before proceeding to local_iov[1], and it completely fills
67 remote_iov[0] before proceeding to remote_iov[1].
68 The lengths of remote_iov[i].iov_len and local_iov[i].iov_len do not
70 have to be the same. Thus, it is possible to split a single local buf‐
71 fer into multiple remote buffers, or vice versa.
72 The flags argument is currently unused and must be set to 0.
74 The values specified in the liovcnt and riovcnt arguments must be less
76 than or equal to IOV_MAX (defined in <limits.h> or accessible via the
77 call sysconf(_SC_IOV_MAX)).
78 The count arguments and local_iov are checked before doing any trans‐
80 fers. If the counts are too big, or local_iov is invalid, or the
81 addresses refer to regions that are inaccessible to the local process,
82 none of the vectors will be processed and an error will be returned
83 immediately.
84 Note, however, that these system calls do not check the memory regions
86 in the remote process until just before doing the read/write. Conse‐
87 quently, a partial read/write (see RETURN VALUE) may result if one of
88 the remote_iov elements points to an invalid memory region in the
89 remote process. No further reads/writes will be attempted beyond that
90 point. Keep this in mind when attempting to read data of unknown
91 length (such as C strings that are null-terminated) from a remote
92 process, by avoiding spanning memory pages (typically 4 KiB) in a sin‐
93 gle remote iovec element. (Instead, split the remote read into two
94 remote_iov elements and have them merge back into a single write
95 local_iov entry. The first read entry goes up to the page boundary,
96 while the second starts on the next page boundary.)
97 Permission to read from or write to another process is governed by a
99 ptrace access mode PTRACE_MODE_ATTACH_REALCREDS check; see ptrace(2).
100
102 On success, process_vm_readv() returns the number of bytes read and
103 process_vm_writev() returns the number of bytes written. This return
104 value may be less than the total number of requested bytes, if a par‐
105 tial read/write occurred. (Partial transfers apply at the granularity
106 of iovec elements. These system calls won't perform a partial transfer
107 that splits a single iovec element.) The caller should check the
108 return value to determine whether a partial read/write occurred.
109 On error, -1 is returned and errno is set appropriately.
111
113 EFAULT The memory described by local_iov is outside the caller's acces‐
114 sible address space.
115 EFAULT The memory described by remote_iov is outside the accessible
117 address space of the process pid.
118 EINVAL The sum of the iov_len values of either local_iov or remote_iov
120 overflows a ssize_t value.
121 EINVAL flags is not 0.
123 EINVAL liovcnt or riovcnt is too large.
125 ENOMEM Could not allocate memory for internal copies of the iovec
127 structures.
128 EPERM The caller does not have permission to access the address space
130 of the process pid.
131 ESRCH No process with ID pid exists.
133
135 These system calls were added in Linux 3.2. Support is provided in
136 glibc since version 2.15.
137
139 These system calls are nonstandard Linux extensions.
140
142 The data transfers performed by process_vm_readv() and
143 process_vm_writev() are not guaranteed to be atomic in any way.
144 These system calls were designed to permit fast message passing by
146 allowing messages to be exchanged with a single copy operation (rather
147 than the double copy that would be required when using, for example,
148 shared memory or pipes).
149
151 The following code sample demonstrates the use of process_vm_readv().
152 It reads 20 bytes at the address 0x10000 from the process with PID 10
153 and writes the first 10 bytes into buf1 and the second 10 bytes into
154 buf2.
155 #include <sys/uio.h>
157 int
159 main(void)
160 {
161 struct iovec local[2];
162 struct iovec remote[1];
163 char buf1[10];
164 char buf2[10];
165 ssize_t nread;
166 pid_t pid = 10; /* PID of remote process */
167 local[0].iov_base = buf1;
169 local[0].iov_len = 10;
170 local[1].iov_base = buf2;
171 local[1].iov_len = 10;
172 remote[0].iov_base = (void *) 0x10000;
173 remote[0].iov_len = 20;
174 nread = process_vm_readv(pid, local, 2, remote, 1, 0);
176 if (nread != 20)
177 return 1;
178 else
179 return 0;
180 }
181
183 readv(2), writev(2)
184
186 This page is part of release 4.16 of the Linux man-pages project. A
187 description of the project, information about reporting bugs, and the
188 latest version of this page, can be found at
189 https://www.kernel.org/doc/man-pages/.
190Linux 2017-09-15 PROCESS_VM_READV(2)