xnu-7195.101.1.tar.gz

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

<h2>task_set_special_port</h2>
<hr>
<p>
<strong>Function</strong> - Set the indicated special port.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   task_set_special_port</strong>
                <strong>(task_t</strong>                                    <var>task</var>,
                 <strong>int</strong>                                 <var>which_port</var>,
                 <strong>mach_port_t</strong>                       <var>special_port</var><strong>);</strong>


<strong>Macro forms:</strong>


<strong>kern_return_t   task_set_bootstrap_port</strong>
                <strong>(task_t</strong>                                    <var>task</var>,
                 <strong>int</strong>                                 <var>which_port</var>,
                 <strong>mach_port_t</strong>                       <var>special_port</var><strong>);</strong>


<strong>kern_return_t   task_set_kernel_port</strong>
                <strong>(task_t</strong>                                    <var>task</var>,
                 <strong>int</strong>                                 <var>which_port</var>,
                 <strong>mach_port_t</strong>                       <var>special_port</var><strong>);</strong>


<strong>kern_return_t   task_set_host_name_port</strong>
                <strong>(task_t</strong>                                    <var>task</var>,
                 <strong>mach_port_t</strong>                       <var>special_port</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>task</var> 
<dd>
[in task send right]
The port for the task for which to set the port.
<p>
<dt> <var>which_port</var> 
<dd>
[in scalar]
The special port to be set.  Valid values are:
<dl>
<p>
<dt> <strong>TASK_BOOTSTRAP_PORT</strong>
<dd>
[bootstrap send right] The task's bootstrap port.  Used to send 
messages requesting return of other system service ports.
<p>
<dt> <strong>TASK_KERNEL_PORT</strong>
<dd>
[task-self send right] The task's kernel port.  Used by the
kernel to receive messages to manipulate the task. This is the movable task 
port and different from the one returned by <strong>mach_task_self</strong> 
(immovable). Setting this special port does not change the identity of the 
kernel port that names the task; this simply changes the value returned as the kernel
special port.
<p>
<dt> <strong>TASK_HOST_NAME_PORT</strong>
<dd>
[host-self send right] The task's host self port.  Used by the 
task to request information about its containing host.  This is 
the port returned by <strong>mach_host_self</strong>.  Setting this special port 
does not change the identity of the kernel port that names the 
host; this simply changes the value returned as the host
special port.
<p>
<dt> <strong>TASK_WIRED_LEDGER_PORT</strong>
<dd>
[ledger send right] The resource ledger from which the task 
draws its wired kernel memory.  Setting this special port does 
not change the ledger from which the task draws its resources; 
this simply changes the value returned as the ledger special 
port.
<p>
<dt> <strong>TASK_PAGED_LEDGER_PORT</strong>
<dd>
[ledger send right] The resource ledger from which the task 
draws its default memory managed memory.  Setting this
special port does not change the ledger from which the task 
draws its resources; this simply changes the value returned as 
the ledger special port.
</dl>
<p>
<dt> <var>special_port</var> 
<dd>
[in task-special send right]
The value for the port.
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>task_set_special_port</strong> function sets a special port
belonging to <var>task</var>.
<h3>NOTES</h3>
<p>
The current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong>
features associated with this interface.
<h3>RETURN VALUES</h3>
<p>
Only generic errors apply.
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="task_create.html"><strong>task_create</strong></a>,
<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
<a href="mach_host_self.html"><strong>mach_host_self</strong></a>.