osfmk/man/vm_inherit.html

   1 <h2>vm_inherit</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Set a VM region's inheritance attribute.
   5 <p>
   6 <h3>SYNOPSIS</h3>
   7 <pre>
   8 <strong>kern_return_t   vm_inherit</strong>
   9                  <strong>(vm_task_t</strong>                   <var>target_task</var>,
  10                   <strong>vm_address_t</strong>                    <var>address</var>,
  11                   <strong>vm_size_t</strong>                          <var>size</var>,
  12                   <strong>vm_inherit_t</strong>            <var>new_inheritance</var><strong>);</strong>
  13 </pre>
  14 <h3>PARAMETERS</h3>
  15 <dl>
  16 <p>
  17 <dt> <var>target_task</var>
  18 <dd>
  19 [in task send right]
  20 The port for the task whose address space contains
  21 the region.
  22 <p>
  23 <dt> <var>address</var>
  24 <dd>
  25 [in scalar]
  26 The starting address for the region.
  27 <p>
  28 <dt> <var>size</var>
  29 <dd>
  30 [in scalar]
  31 The number of bytes in the region.
  32 <p>
  33 <dt> <var>new_inheritance</var>
  34 <dd>
  35 [in scalar]
  36 The new inheritance attribute for the region.  Valid values are:
  37 <dl>
  38 <p>
  39 <dt> <strong>VM_INHERIT_SHARE</strong>
  40 <dd>
  41 Allows child tasks to share the region.
  42 <p>
  43 <dt> <strong>VM_INHERIT_COPY</strong>
  44 <dd>
  45 Gives child tasks a copy of the region.
  46 <p>
  47 <dt> <strong>VM_INHERIT_NONE</strong>
  48 <dd>
  49 Provides no access to the region for child tasks.
  50 </dl>
  51 </dl>
  52 <h3>DESCRIPTION</h3>
  53 <p>
  54 The <strong>vm_inherit</strong> function sets the inheritance attribute
  55 for a region within the
  56 specified task's address space.  The inheritance attribute determines
  57 the type of
  58 access established for child tasks at task creation.
  59 <p>
  60 Because inheritance applies to virtual pages, the specified <var>address</var>
  61 and <var>size</var> are
  62 rounded to page boundaries, as follows: the region starts at
  63 the beginning of the
  64 virtual page containing <var>address</var>; it ends at the end of the virtual
  65 page containing
  66 <var>address</var> + <var>size</var> - 1.
  67 Because of this rounding to virtual page boundaries, the
  68 amount of memory affected may be greater than <var>size</var>.  Use
  69 <strong>host_page_size</strong> to find the current virtual page size.
  70 <p>
  71 A parent and a child task can share the same physical memory only if the
  72 inheritance for the memory is set to <strong>VM_INHERIT_SHARE</strong> before
  73 the child task is
  74 created.  Other than through the use of an external memory manager (see
  75 <strong>vm_map</strong>), this is the only way that two tasks can share memory.
  76 <p>
  77 Note that all the threads within a task share the task's memory.
  78 <h3>NOTES</h3>
  79 <p>
  80 This interface is machine word length specific because of the virtual address
  81 parameter.
  82 <h3>RETURN VALUES</h3>
  83 <dl>
  84 <p>
  85 <dt> <strong>KERN_INVALID_ADDRESS</strong>
  86 <dd>
  87 The address is illegal or specifies a non-allocated region.
  88 </dl>
  89 <h3>RELATED INFORMATION</h3>
  90 <p>
  91 Functions:
  92 <a href="task_create.html"><strong>task_create</strong></a>,
  93 <a href="vm_map.html"><strong>vm_map</strong></a>,
  94 <a href="vm_region.html"><strong>vm_region</strong></a>,