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]
30The port for the task whose memory is to be read.
31<p>
32<dt> <var>address</var> 
33<dd>
34[in scalar]
35The address at which to start the read.
36<p>
37<dt> <var>size</var> 
38<dd>
39[in scalar]
40The number of bytes to read.
41<p>
42<dt> <var>data_out</var>
43<dd>
44Out-pointer to dynamic array of bytes returned by the read.
45<p>
46<dt> <var>data_in</var>
47<dd>
48In-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]
53On input, the maximum size of the buffer; on output, the 
54size returned (in natural-sized units).
55</dl>
56<h3>DESCRIPTION</h3>
57<p>
58The <strong>vm_read</strong> and <strong>vm_read_overwrite</strong>
59functions read a portion of a task's virtual
60memory (they enable tasks to read other tasks' memory).
61The <strong>vm_read</strong> function returns the data in a dynamically
62allocated array of bytes; the <strong>vm_read_overwrite</strong> function
63places the data into a caller-specified buffer (the <var>data_in</var>
64parameter).
65<h3>NOTES</h3>
66<p>
67This interface is machine word length specific because of the virtual address
68parameter.
69<h3>RETURN VALUES</h3>
70<dl>
71<p>
72<dt> <strong>KERN_PROTECTION_FAILURE</strong>
73<dd>
74Specified memory is valid, but does not permit reading.
75<p>
76<dt> <strong>KERN_INVALID_ADDRESS</strong>
77<dd>
78The address is illegal or specifies a non-allocated region, or there are 
79less than <var>size</var> bytes of data following the address, or the region
80specified by the <var>data_in</var> parameter cannot be written to.
81</dl>
82<h3>RELATED INFORMATION</h3>
83<p>
84Functions:
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>.
88