osfmk/man/memory_object_create.html

   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]
  29 The default memory manager service
  30 port.
  31 <p>
  32 <dt> <var>seqno</var>
  33 <dd>
  34 [in scalar]
  35 The sequence number of this message relative to the pager
  36 port.
  37 <p>
  38 <dt> <var>new_memory_object</var>
  39 <dd>
  40 [in abstract-memory-object receive right]
  41 The port representing the
  42 new abstract memory object created by the kernel.
  43 <p>
  44 <dt> <var>new_object_size</var>
  45 <dd>
  46 [in scalar]
  47 The 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]
  52 The memory cache control port
  53 to be used by the memory manager when making cache management
  54 requests for the new object.
  55 <p>
  56 <dt> <var>new_page_size</var>
  57 <dd>
  58 [in scalar]
  59 The page size used by the kernel.  All calls involving this
  60 kernel must use data sizes that are integral multiples of this page size.
  61 </dl>
  62 <h3>DESCRIPTION</h3>
  63 <p>
  64 A <strong>memory_object_create</strong> function is called as the result
  65 of a message from the
  66 kernel requesting that the default memory manager accept responsibility
  67 for the
  68 new memory object created by the kernel.  The kernel makes this
  69 call only to the
  70 system default memory manager.
  71 <p>
  72 The new memory object initially consists of zero-filled pages.  Only memory
  73 pages that are actually written are provided to the memory manager.  When
  74 processing <strong>memory_object_data_request</strong> calls from the
  75 kernel, the default
  76 memory manager must use <strong>memory_object_data_unavailable</strong>
  77 for any pages that have not been written previously.
  78 <p>
  79 The kernel does not expect a reply to this call.  The kernel assumes that the
  80 default memory manager will be ready to handle data requests to this object and
  81 does not need the confirmation of a <strong>memory_object_change_attributes</strong> call.
  82 <h3>NOTES</h3>
  83 <p>
  84 The kernel requires memory objects to provide temporary backing storage for
  85 zero-filled memory created by <strong>vm_allocate</strong> calls, issued
  86 by both user tasks and
  87 the kernel itself.  The kernel allocates an abstract memory object port to
  88 represent the temporary backing storage and uses <strong>memory_object_create</strong>
  89 to pass the
  90 new memory object to the default memory manager, which provides the storage.
  91 <p>
  92 The default memory manager is a trusted system component that is identified to
  93 the kernel at system initialization time.  The default memory manager can also
  94 be changed at run time using the <strong>host_default_memory_manager</strong> call.
  95 <p>
  96 The contents of a kernel-created (as opposed to a user-created) memory object
  97 can be modified only in main memory.  The default memory manager must not
  98 change the contents of a temporary memory object, or allow unrelated tasks to
  99 access the memory object, control, or name port.
 100 <p>
 101 The kernel provides the size of a temporary memory object based on the
 102 allocated size.  Since the object is not mapped by other tasks,
 103 the object will not grow
 104 by explicit action.  However, the kernel may coalesce adjacent
 105 temporary objects
 106 in such a way that this object may appear to grow.  As such,
 107 the supplied object
 108 size is merely a hint as to the maximum size.
 109 <h3>RETURN VALUES</h3>
 110 <p>
 111 Only generic errors apply.
 112 <h3>RELATED INFORMATION</h3>
 113 <p>
 114 Functions:
 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>.