osfmk/man/vm_read.html

   1 <h2>vm_read</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Read the specified range of target task's address space.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   vm_read</strong>
   8                 <strong>(vm_task_t</strong>                          <var>target_task</var>,
   9                  <strong>vm_address_t</strong>                           <var>address</var>,
  10                  <strong>vm_size_t</strong>                                 <var>size</var>,
  11                  <strong>size</strong>                                  <var>data_out</var>,
  12                  <strong>target_task</strong>                         <var>data_count</var><strong>);</strong>
  13 </pre>
  14
  15 <h4>Overwrite form:</h4>
  16 <pre>
  17 <strong>kern_return_t   vm_read_overwrite</strong>
  18                 <strong>(vm_task_t</strong>                          <var>target_task</var>,
  19                  <strong>vm_address_t</strong>                           <var>address</var>,
  20                  <strong>vm_size_t</strong>                                 <var>size</var>,
  21                  <strong>pointer_t</strong>                              <var>data_in</var>,
  22                  <strong>target_task</strong>                         <var>data_count</var><strong>);</strong>
  23 </pre>
  24 <h3>PARAMETERS</h3>
  25 <dl>
  26 <p>
  27 <dt> <var>target_task</var>
  28 <dd>
  29 [in task send right]
  30 The port for the task whose memory is to be read.
  31 <p>
  32 <dt> <var>address</var>
  33 <dd>
  34 [in scalar]
  35 The address at which to start the read.
  36 <p>
  37 <dt> <var>size</var>
  38 <dd>
  39 [in scalar]
  40 The number of bytes to read.
  41 <p>
  42 <dt> <var>data_out</var>
  43 <dd>
  44 Out-pointer to dynamic array of bytes returned by the read.
  45 <p>
  46 <dt> <var>data_in</var>
  47 <dd>
  48 In-pointer to array of bytes that will be overwritten with the data returned by the read.
  49 <p>
  50 <dt> <var>data_count</var>
  51 <dd>
  52 [in/out scalar]
  53 On input, the maximum size of the buffer; on output, the
  54 size returned (in natural-sized units).
  55 </dl>
  56 <h3>DESCRIPTION</h3>
  57 <p>
  58 The <strong>vm_read</strong> and <strong>vm_read_overwrite</strong>
  59 functions read a portion of a task's virtual
  60 memory (they enable tasks to read other tasks' memory).
  61 The <strong>vm_read</strong> function returns the data in a dynamically
  62 allocated array of bytes; the <strong>vm_read_overwrite</strong> function
  63 places the data into a caller-specified buffer (the <var>data_in</var>
  64 parameter).
  65 <h3>NOTES</h3>
  66 <p>
  67 This interface is machine word length specific because of the virtual address
  68 parameter.
  69 <h3>RETURN VALUES</h3>
  70 <dl>
  71 <p>
  72 <dt> <strong>KERN_PROTECTION_FAILURE</strong>
  73 <dd>
  74 Specified memory is valid, but does not permit reading.
  75 <p>
  76 <dt> <strong>KERN_INVALID_ADDRESS</strong>
  77 <dd>
  78 The address is illegal or specifies a non-allocated region, or there are
  79 less than <var>size</var> bytes of data following the address, or the region
  80 specified by the <var>data_in</var> parameter cannot be written to.
  81 </dl>
  82 <h3>RELATED INFORMATION</h3>
  83 <p>
  84 Functions:
  85 <a href="vm_copy.html"><strong>vm_copy</strong></a>,
  86 <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
  87 <a href="vm_write.html"><strong>vm_write</strong></a>.