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