original/man2/process_vm_readv.2

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