1<h2>memory_object_data_supply</h2>
2<hr>
3<p>
4<strong>Function</strong> - Provide kernel with data previously requested by the kernel's Memory Management facility.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   memory_object_data_supply</strong>
8                <strong>(mem_object_control_port_t</strong>       <var>memory_control</var>,
9                 <strong>vm_offset_t</strong>                             <var>offset</var>,
10                 <strong>pointer_t</strong>                                 <var>data</var>,
11                 <strong>mach_msg_type_number_t</strong>              <var>data_count</var>,
12                 <strong>boolean_t</strong>                           <var>deallocate</var>,
13                 <strong>vm_prot_t</strong>                           <var>lock_value</var>,
14                 <strong>boolean_t</strong>                             <var>precious</var>,
15                 <strong>mach_port_t</strong>                         <var>reply_port</var><strong>);</strong>
16</pre>
17<h3>PARAMETERS</h3>
18<dl>
19<dt> <var>memory_control</var> 
20<dd>
21[in memory-cache-control send right]
22The memory cache control port 
23to be used by the memory manager for cache management requests. 
24This port is provided by the kernel in a <strong>memory_object_init</strong>
25     or <strong>memory_object_create</strong> call.
26<p>
27<p>
28<dt> <var>offset</var> 
29<dd>
30[in scalar]
31The offset within the memory object, in bytes.
32<p>
33<p>
34<dt> <var>data</var> 
35<dd>
36[pointer to page aligned in array of bytes]
37The address of the data
38being provided to the kernel.
39<p>
40<p>
41<dt> <var>data_count</var> 
42<dd>
43[in scalar]
44The amount of data to be provided.  The number must be an 
45integral number of memory object pages.
46<p>
47<p>
48<dt> <var>deallocate</var> 
49<dd>
50[in scalar]
51If <strong>TRUE</strong>, the pages to be copied (starting at data) will be
52deallocated from the memory manager's address space as a result of
53being copied into the message, allowing the pages to be moved into the 
54kernel instead of being physically copied.
55<p>
56<p>
57<dt> <var>lock_value</var> 
58<dd>
59[in scalar]
60One or more forms of access <var>not</var> permitted for the specified 
61data.  Valid values are:
62<dl>
63<p>
64<p>
65<dt> <strong>VM_PROT_NONE</strong>
66<dd>
67Prohibits no access (that is, all forms of access are permitted).
68<p>
69<p>
70<dt> <strong>VM_PROT_READ</strong>
71<dd>
72Prohibits read access.
73<p>
74<p>
75<dt> <strong>VM_PROT_WRITE</strong>
76<dd>
77Prohibits write access.
78<p>
79<p>
80<dt> <strong>VM_PROT_EXECUTE</strong>
81<dd>
82Prohibits execute access.
83<p>
84<p>
85<dt> <strong>VM_PROT_ALL</strong>
86<dd>
87Prohibits all forms of access.
88</dl>
89<p>
90<p>
91<dt> <var>precious</var> 
92<dd>
93[in scalar]
94If <strong>TRUE</strong>, the pages being supplied are "precious," that is, 
95the memory manager is not (necessarily) retaining its own copy.  These 
96pages must be returned to the manager when evicted from memory, 
97even if not modified.
98<p>
99<p>
100<dt> <var>reply_port</var> 
101<dd>
102[in reply receive (to be converted to send) right]
103A port to which the 
104kernel should send a <strong>memory_object_supply_completed</strong> to indicate 
105the status of the accepted data.  <strong>MACH_PORT_NULL</strong> is allowed.  The 
106reply message indicates which pages have been accepted.
107</dl>
108<h3>DESCRIPTION</h3>
109<p>
110The <strong>memory_object_data_supply</strong> function supplies the
111kernel with a range of 
112data for the specified memory object.  A memory manager can only provide data 
113that was requested by a <strong>memory_object_data_request</strong>
114call from the kernel.
115<h3>NOTES</h3>
116<p>
117The kernel accepts only integral numbers of pages.  It discards
118any partial pages 
119without notification.
120<h3>CAUTIONS</h3>
121<p>
122A memory manager must be careful that it not attempt to provide data that has 
123not been explicitly requested.  In particular, a memory manager
124must ensure that 
125it does not provide writable data again before it receives back modifications 
126from the kernel.  This may require that the memory manager remember which 
127pages it has provided, or that it exercise other cache control functions (via
128<strong>memory_object_lock_request</strong>) before proceeding.  The kernel prohibits the
129overwriting of live data pages and will not accept pages it has not requested.
130<h3>RETURN VALUES</h3>
131<p>
132Only generic errors apply.
133<h3>RELATED INFORMATION</h3>
134<p>
135Functions:
136<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>,
137<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>,
138<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
139<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
140<a href="MO_supply_completed.html"><strong>memory_object_supply_completed</strong></a>.
141