1<h2>mach_port_insert_right</h2> 2<hr> 3<p> 4<strong>Function</strong> - Insert the specified port right into the target task. 5<h3>SYNOPSIS</h3> 6<pre> 7<strong>kern_return_t mach_port_insert_right</strong> 8 <strong>(ipc_space_t</strong> <var>task</var>, 9 <strong>mach_port_name_t</strong> <var>name</var>, 10 <strong>mach_port_poly_t</strong> <var>right</var>, 11 <strong>mach_msg_type_name_t</strong> <var>right_type</var><strong>);</strong> 12</pre> 13<h3>PARAMETERS</h3> 14<dl> 15<p> 16<dt> <var>task</var> 17<dd> 18[in task send right] 19The task which gets the caller's right. 20<p> 21<dt> <var>name</var> 22<dd> 23[in scalar] 24The name by which <var>task</var> will know the right. 25<p> 26<dt> <var>right</var> 27<dd> 28[in random right] 29The port right. 30<p> 31<dt> <var>right_type</var> 32<dd> 33[in scalar] 34IPC type of the sent right; e.g., 35<strong>MACH_MSG_TYPE_COPY_SEND</strong> or <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>. 36</dl> 37<h3>DESCRIPTION</h3> 38<p> 39The <strong>mach_port_insert_right</strong> function inserts into <var>task</var> 40the caller's right for a 41port, using a specified name for the right in the target task. 42<p> 43The specified <var>name</var> can't be one of the reserved values <strong>MACH_PORT_NULL</strong> 44or <strong>MACH_PORT_DEAD</strong>. The <var>right</var> can't be <strong>MACH_PORT_NULL</strong> or 45<strong>MACH_PORT_DEAD</strong>. 46<p> 47The argument <var>right_type</var> specifies a right to be inserted and how that right 48should be extracted from the caller. It should be a value appropriate for 49<strong>mach_msg</strong>. 50<p> 51If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>, 52or 53<strong>MACH_MSG_TYPE_COPY_SEND</strong>, then a send right is inserted. If the target 54already holds send or receive rights for the port, then <var>name</var> 55should denote those rights in the target. Otherwise, <var>name</var> should 56be unused in 57the target. If the target already has send rights, then those 58send rights gain an 59additional user reference. Otherwise, the target gains a send 60right, with a user 61reference count of one. 62<p> 63If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or 64<strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>, then a send-once right is inserted. 65The <var>name</var> should be unused in the target. The 66target gains a send-once right. 67<p> 68If <var>right_type</var> is <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>, then a receive right is 69inserted. If the target already holds send rights for the port, 70then <var>name</var> should 71denote those rights in the target. Otherwise, <var>name</var> should be 72unused in the target. 73The receive right is moved into the target task. 74<h3>NOTES</h3> 75<p> 76This interface is machine word length specific because of the port name 77parameter. 78<h3>RETURN VALUES</h3> 79<dl> 80<p> 81<dt> <strong>KERN_NAME_EXISTS</strong> 82<dd> 83<var>name</var> already denoted a right. 84<p> 85<dt> <strong>KERN_INVALID_CAPABILITY</strong> 86<dd> 87<var>right</var> was null or dead. 88<p> 89<dt> <strong>KERN_UREFS_OVERFLOW</strong> 90<dd> 91Inserting the right would overflow <var>name</var>'s user-reference count. 92<p> 93<dt> <strong>KERN_RIGHT_EXISTS</strong> 94<dd> 95<var>task</var> already had rights for the port, with a different name. 96</dl> 97<h3>RELATED INFORMATION</h3> 98<p> 99Functions: 100<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>, 101<a href="mach_msg.html"><strong>mach_msg</strong></a>. 102