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