xref: /xnu-11215/osfmk/man/memory_object_create.html (revision 186b8fce)

<h2>memory_object_create</h2>
<hr>
<p>
<strong>Function</strong> - Request that the default pager handle management requests on the specified memory object.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   memory_object_create</strong>
                <strong>(memory_object_t</strong>                          <var>pager</var>,
                 <strong>memory_object_t</strong>              <var>new_memory_object</var>,
                 <strong>vm_size_t</strong>                      <var>new_object_size</var>,
                 <strong>memory_object_control_t</strong>            <var>new_control</var>,
                 <strong>vm_size_t</strong>                        <var>new_page_size</var><strong>);</strong>


<strong>kern_return_t   seqnos_memory_object_create</strong>
                <strong>(memory_object_t</strong>                          <var>pager</var>,
                 <strong>mach_port_seqno_t</strong>                        <var>seqno</var>,
                 <strong>memory_object_t</strong>              <var>new_memory_object</var>,
                 <strong>vm_size_t</strong>                      <var>new_object_size</var>,
                 <strong>memory_object_control_t</strong>            <var>new_control</var>,
                 <strong>vm_size_t</strong>                        <var>new_page_size</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>pager</var>
<dd>
[in default-pager (receive) right]
The default memory manager service
port.
<p>
<dt> <var>seqno</var>
<dd>
[in scalar]
The sequence number of this message relative to the pager
port.
<p>
<dt> <var>new_memory_object</var>
<dd>
[in abstract-memory-object receive right]
The port representing the
new abstract memory object created by the kernel.
<p>
<dt> <var>new_object_size</var>
<dd>
[in scalar]
The expected size for the new object, in bytes.
<p>
<dt> <var>new_control</var>
<dd>
[in memory-cache-control send right]
The memory cache control port
to be used by the memory manager when making cache management
requests for the new object.
<p>
<dt> <var>new_page_size</var>
<dd>
[in scalar]
The page size used by the kernel.  All calls involving this
kernel must use data sizes that are integral multiples of this page size.
</dl>
<h3>DESCRIPTION</h3>
<p>
A <strong>memory_object_create</strong> function is called as the result
of a message from the
kernel requesting that the default memory manager accept responsibility
for the
new memory object created by the kernel.  The kernel makes this
call only to the
system default memory manager.
<p>
The new memory object initially consists of zero-filled pages.  Only memory
pages that are actually written are provided to the memory manager.  When
processing <strong>memory_object_data_request</strong> calls from the
kernel, the default
memory manager must use <strong>memory_object_data_unavailable</strong>
for any pages that have not been written previously.
<p>
The kernel does not expect a reply to this call.  The kernel assumes that the
default memory manager will be ready to handle data requests to this object and
does not need the confirmation of a <strong>memory_object_change_attributes</strong> call.
<h3>NOTES</h3>
<p>
The kernel requires memory objects to provide temporary backing storage for
zero-filled memory created by <strong>vm_allocate</strong> calls, issued
by both user tasks and
the kernel itself.  The kernel allocates an abstract memory object port to
represent the temporary backing storage and uses <strong>memory_object_create</strong>
to pass the
new memory object to the default memory manager, which provides the storage.
<p>
The default memory manager is a trusted system component that is identified to
the kernel at system initialization time.  The default memory manager can also
be changed at run time using the <strong>host_default_memory_manager</strong> call.
<p>
The contents of a kernel-created (as opposed to a user-created) memory object
can be modified only in main memory.  The default memory manager must not
change the contents of a temporary memory object, or allow unrelated tasks to
access the memory object, control, or name port.
<p>
The kernel provides the size of a temporary memory object based on the
allocated size.  Since the object is not mapped by other tasks,
the object will not grow
by explicit action.  However, the kernel may coalesce adjacent
temporary objects
in such a way that this object may appear to grow.  As such,
the supplied object
size is merely a hint as to the maximum size.
<h3>RETURN VALUES</h3>
<p>
Only generic errors apply.
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="DP_object_create.html"><strong>default_pager_object_create</strong></a>,
<a href="MO_data_initialize.html"><strong>memory_object_data_initialize</strong></a>,
<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.