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