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