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
27 These system calls transfer data between the address space of the call‐
28 ing process ("the local process") and the process identified by pid
29 ("the remote process"). The data moves directly between the address
30 spaces of the two processes, without passing through kernel space.
31 The process_vm_readv() system call transfers data from the remote
33 process to the local process. The data to be transferred is identified
34 by remote_iov and riovcnt: remote_iov is a pointer to an array describ‐
35 ing address ranges in the process pid, and riovcnt specifies the number
36 of elements in remote_iov. The data is transferred to the locations
37 specified by local_iov and liovcnt: local_iov is a pointer to an array
38 describing address ranges in the calling process, and liovcnt specifies
39 the number of elements in local_iov.
40 The process_vm_writev() system call is the converse of
42 process_vm_readv()—it transfers data from the local process to the
43 remote process. Other than the direction of the transfer, the argu‐
44 ments liovcnt, local_iov, riovcnt, and remote_iov have the same meaning
45 as for process_vm_readv().
46 The local_iov and remote_iov arguments point to an array of iovec
48 structures, defined in <sys/uio.h> as:
49 struct iovec {
51 void *iov_base; /* Starting address */
52 size_t iov_len; /* Number of bytes to transfer */
53 };
54 Buffers are processed in array order. This means that
56 process_vm_readv() completely fills local_iov[0] before proceeding to
57 local_iov[1], and so on. Likewise, remote_iov[0] is completely read
58 before proceeding to remote_iov[1], and so on.
59 Similarly, process_vm_writev() writes out the entire contents of
61 local_iov[0] before proceeding to local_iov[1], and it completely fills
62 remote_iov[0] before proceeding to remote_iov[1].
63 The lengths of remote_iov[i].iov_len and local_iov[i].iov_len do not
65 have to be the same. Thus, it is possible to split a single local buf‐
66 fer into multiple remote buffers, or vice versa.
67 The flags argument is currently unused and must be set to 0.
69 The values specified in the liovcnt and riovcnt arguments must be less
71 than or equal to IOV_MAX (defined in <limits.h> or accessible via the
72 call sysconf(_SC_IOV_MAX)).
73 The count arguments and local_iov are checked before doing any trans‐
75 fers. If the counts are too big, or local_iov is invalid, or the
76 addresses refer to regions that are inaccessible to the local process,
77 none of the vectors will be processed and an error will be returned
78 immediately.
79 Note, however, that these system calls do not check the memory regions
81 in the remote process until just before doing the read/write. Conse‐
82 quently, a partial read/write (see RETURN VALUE) may result if one of
83 the remote_iov elements points to an invalid memory region in the
84 remote process. No further reads/writes will be attempted beyond that
85 point. Keep this in mind when attempting to read data of unknown
86 length (such as C strings that are null-terminated) from a remote
87 process, by avoiding spanning memory pages (typically 4KiB) in a single
88 remote iovec element. (Instead, split the remote read into two
89 remote_iov elements and have them merge back into a single write
90 local_iov entry. The first read entry goes up to the page boundary,
91 while the second starts on the next page boundary.)
92 In order to read from or write to another process, either the caller
94 must have the capability CAP_SYS_PTRACE, or the real user ID, effective
95 user ID, and saved set-user-ID of the remote process must match the
96 real user ID of the caller and the real group ID, effective group ID,
97 and saved set-group-ID of the remote process must match the real group
98 ID of the caller. (The permission required is exactly the same as that
99 required to perform a ptrace(2) PTRACE_ATTACH on the remote process.)
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 EINVAL The sum of the iov_len values of either local_iov or remote_iov
114 overflows a ssize_t value.
115 EINVAL flags is not 0.
117 EINVAL liovcnt or riovcnt is too large.
119 EFAULT The memory described by local_iov is outside the caller's acces‐
121 sible address space.
122 EFAULT The memory described by remote_iov is outside the accessible
124 address space of the process pid.
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[1].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 3.53 of the Linux man-pages project. A
187 description of the project, and information about reporting bugs, can
188 be found at http://www.kernel.org/doc/man-pages/.
189Linux 2012-04-25 PROCESS_VM_READV(2)