1<h2>memory_object_create</h2>
2<hr>
3<p>
4<strong>Function</strong> - Request that the default pager handle management requests on the specified memory object.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   memory_object_create</strong>
8                <strong>(memory_object_t</strong>                          <var>pager</var>,
9                 <strong>memory_object_t</strong>              <var>new_memory_object</var>,
10                 <strong>vm_size_t</strong>                      <var>new_object_size</var>,
11                 <strong>memory_object_control_t</strong>            <var>new_control</var>,
12                 <strong>vm_size_t</strong>                        <var>new_page_size</var><strong>);</strong>
13
14
15<strong>kern_return_t   seqnos_memory_object_create</strong>
16                <strong>(memory_object_t</strong>                          <var>pager</var>,
17                 <strong>mach_port_seqno_t</strong>                        <var>seqno</var>,
18                 <strong>memory_object_t</strong>              <var>new_memory_object</var>,
19                 <strong>vm_size_t</strong>                      <var>new_object_size</var>,
20                 <strong>memory_object_control_t</strong>            <var>new_control</var>,
21                 <strong>vm_size_t</strong>                        <var>new_page_size</var><strong>);</strong>
22</pre>
23<h3>PARAMETERS</h3>
24<dl>
25<p>
26<dt> <var>pager</var> 
27<dd>
28[in default-pager (receive) right]
29The default memory manager service 
30port.
31<p>
32<dt> <var>seqno</var> 
33<dd>
34[in scalar]
35The sequence number of this message relative to the pager 
36port.
37<p>
38<dt> <var>new_memory_object</var> 
39<dd>
40[in abstract-memory-object receive right]
41The port representing the 
42new abstract memory object created by the kernel.
43<p>
44<dt> <var>new_object_size</var> 
45<dd>
46[in scalar]
47The expected size for the new object, in bytes.
48<p>
49<dt> <var>new_control</var> 
50<dd>
51[in memory-cache-control send right]
52The memory cache control port 
53to be used by the memory manager when making cache management 
54requests for the new object.
55<p>
56<dt> <var>new_page_size</var> 
57<dd>
58[in scalar]
59The page size used by the kernel.  All calls involving this
60kernel must use data sizes that are integral multiples of this page size.
61</dl>
62<h3>DESCRIPTION</h3>
63<p>
64A <strong>memory_object_create</strong> function is called as the result
65of a message from the 
66kernel requesting that the default memory manager accept responsibility
67for the 
68new memory object created by the kernel.  The kernel makes this
69call only to the 
70system default memory manager.
71<p>
72The new memory object initially consists of zero-filled pages.  Only memory 
73pages that are actually written are provided to the memory manager.  When
74processing <strong>memory_object_data_request</strong> calls from the
75kernel, the default
76memory manager must use <strong>memory_object_data_unavailable</strong>
77for any pages that have not been written previously.
78<p>
79The kernel does not expect a reply to this call.  The kernel assumes that the
80default memory manager will be ready to handle data requests to this object and 
81does not need the confirmation of a <strong>memory_object_change_attributes</strong> call.
82<h3>NOTES</h3>
83<p>
84The kernel requires memory objects to provide temporary backing storage for 
85zero-filled memory created by <strong>vm_allocate</strong> calls, issued
86by both user tasks and 
87the kernel itself.  The kernel allocates an abstract memory object port to
88represent the temporary backing storage and uses <strong>memory_object_create</strong>
89to pass the 
90new memory object to the default memory manager, which provides the storage.
91<p>
92The default memory manager is a trusted system component that is identified to 
93the kernel at system initialization time.  The default memory manager can also 
94be changed at run time using the <strong>host_default_memory_manager</strong> call.
95<p>
96The contents of a kernel-created (as opposed to a user-created) memory object 
97can be modified only in main memory.  The default memory manager must not 
98change the contents of a temporary memory object, or allow unrelated tasks to 
99access the memory object, control, or name port.
100<p>
101The kernel provides the size of a temporary memory object based on the
102allocated size.  Since the object is not mapped by other tasks,
103the object will not grow 
104by explicit action.  However, the kernel may coalesce adjacent
105temporary objects 
106in such a way that this object may appear to grow.  As such,
107the supplied object 
108size is merely a hint as to the maximum size.
109<h3>RETURN VALUES</h3>
110<p>
111Only generic errors apply.
112<h3>RELATED INFORMATION</h3>
113<p>
114Functions:
115<a href="DP_object_create.html"><strong>default_pager_object_create</strong></a>,
116<a href="MO_data_initialize.html"><strong>memory_object_data_initialize</strong></a>,
117<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
118<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
119<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
120