1<h2>mach_port_extract_right</h2>
2<hr>
3<p>
4<strong>Function</strong> - Remove the specified right from the target task and return it to the caller.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_port_extract_right</strong>
8                <strong>(ipc_space_t</strong>                               <var>task</var>,
9                 <strong>mach_port_name_t</strong>                          <var>name</var>,
10                 <strong>mach_msg_type_name_t</strong>              <var>desired_type</var>,
11                 <strong>mach_port_poly_t</strong>                        <var>*right</var>,
12                 <strong>mach_msg_type_name_</strong>             <var>*acquired_type</var><strong>);</strong>
13</pre>
14<h3>PARAMETERS</h3>
15<dl>
16<p>
17<dt> <var>task</var> 
18<dd>
19[in task send right]
20The task holding the port right.
21<p>
22<dt> <var>name</var> 
23<dd>
24[in scalar]
25The task's name for the port right.
26<p>
27<dt> <var>desired_type</var> 
28<dd>
29[in scalar]
30IPC type, specifying how the right should be extracted.
31<p>
32<dt> <var>right</var> 
33<dd>
34[out random right]
35The extracted right.
36<p>
37<dt> <var>acquired_type</var> 
38<dd>
39[out scalar]
40The type of the extracted right.
41</dl>
42<h3>DESCRIPTION</h3>
43<p>
44The <strong>mach_port_extract_right</strong> function extracts a port
45right from the target 
46task and returns it to the caller as if the task sent the right
47voluntarily, using
48<var>desired_type</var> as the disposition for the right.  See <strong>mach_msg</strong>.
49<p>
50The returned value of <var>acquired_type</var> will be
51<strong>MACH_MSG_TYPE_PORT_SEND</strong> if a send right is extracted, 
52<strong>MACH_MSG_TYPE_PORT_RECEIVE</strong> if a 
53receive right is extracted, and <strong>MACH_MSG_TYPE_PORT_SEND_ONCE</strong> if a 
54send-once right is extracted.
55<h3>NOTES</h3>
56<p>
57This interface is machine word length specific because of the port name
58parameter.
59<h3>RETURN VALUES</h3>
60<dl>
61<p>
62<dt> <strong>KERN_INVALID_NAME</strong>
63<dd>
64<var>name</var> did not denote a right.
65<p>
66<dt> <strong>KERN_INVALID_RIGHT</strong>
67<dd>
68<var>name</var> denoted an invalid right.
69</dl>
70<h3>RELATED INFORMATION</h3>
71<p>
72Functions:
73<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
74<a href="mach_msg.html"><strong>mach_msg</strong></a>.
75