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