xnu-7195.60.75.tar.gz

[apple/xnu.git] / osfmk / man / vm_inherit.html

<h2>vm_inherit</h2>
<hr>
<p>
<strong>Function</strong> - Set a VM region's inheritance attribute.
<p>
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   vm_inherit</strong>
                 <strong>(vm_task_t</strong>                   <var>target_task</var>,
                  <strong>vm_address_t</strong>                    <var>address</var>,
                  <strong>vm_size_t</strong>                          <var>size</var>,
                  <strong>vm_inherit_t</strong>            <var>new_inheritance</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>target_task</var> 
<dd>
[in task send right]
The port for the task whose address space contains 
the region.
<p>
<dt> <var>address</var> 
<dd>
[in scalar]
The starting address for the region.
<p>
<dt> <var>size</var> 
<dd>
[in scalar]
The number of bytes in the region.
<p>
<dt> <var>new_inheritance</var> 
<dd>
[in scalar]
The new inheritance attribute for the region.  Valid values are:
<dl>
<p>
<dt> <strong>VM_INHERIT_SHARE</strong>
<dd>
Allows child tasks to share the region.
<p>
<dt> <strong>VM_INHERIT_COPY</strong>
<dd>
Gives child tasks a copy of the region.
<p>
<dt> <strong>VM_INHERIT_NONE</strong>
<dd>
Provides no access to the region for child tasks.
</dl>
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>vm_inherit</strong> function sets the inheritance attribute
for a region within the 
specified task's address space.  The inheritance attribute determines
the type of 
access established for child tasks at task creation.
<p>
Because inheritance applies to virtual pages, the specified <var>address</var>
and <var>size</var> are 
rounded to page boundaries, as follows: the region starts at
the beginning of the 
virtual page containing <var>address</var>; it ends at the end of the virtual
page containing 
<var>address</var> + <var>size</var> - 1.  
Because of this rounding to virtual page boundaries, the 
amount of memory affected may be greater than <var>size</var>.  Use 
<strong>host_page_size</strong> to find the current virtual page size.
<p>
A parent and a child task can share the same physical memory only if the
inheritance for the memory is set to <strong>VM_INHERIT_SHARE</strong> before
the child task is 
created.  Other than through the use of an external memory manager (see
<strong>vm_map</strong>), this is the only way that two tasks can share memory.
<p>
Note that all the threads within a task share the task's memory.
<h3>NOTES</h3>
<p>
This interface is machine word length specific because of the virtual address
parameter.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>KERN_INVALID_ADDRESS</strong>
<dd>
The address is illegal or specifies a non-allocated region.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="task_create.html"><strong>task_create</strong></a>,
<a href="vm_map.html"><strong>vm_map</strong></a>,
<a href="vm_region.html"><strong>vm_region</strong></a>,