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

<h2>mach_port_insert_right</h2>\r<hr>\r<p>\r<strong>Function</strong> - Insert the specified port right into the target task.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   mach_port_insert_right</strong>\r                <strong>(ipc_space_t</strong>                               <var>task</var>,\r                 <strong>mach_port_name_t</strong>                          <var>name</var>,\r                 <strong>mach_port_poly_t</strong>                         <var>right</var>,\r                 <strong>mach_msg_type_name_t</strong>                <var>right_type</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>task</var> \r<dd>\r[in task send right]\rThe task which gets the caller's right.\r<p>\r<dt> <var>name</var> \r<dd>\r[in scalar]\rThe name by which <var>task</var> will know the right.\r<p>\r<dt> <var>right</var> \r<dd>\r[in random right]\rThe port right.\r<p>\r<dt> <var>right_type</var> \r<dd>\r[in scalar]\rIPC type of the sent right; e.g., \r<strong>MACH_MSG_TYPE_COPY_SEND</strong> or <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>mach_port_insert_right</strong> function inserts into <var>task</var>\rthe caller's right for a \rport, using a specified name for the right in the target task. \r<p>\rThe specified <var>name</var> can't be one of the reserved values <strong>MACH_PORT_NULL</strong> \ror <strong>MACH_PORT_DEAD</strong>.  The <var>right</var> can't be <strong>MACH_PORT_NULL</strong> or \r<strong>MACH_PORT_DEAD</strong>. \r<p>\rThe argument <var>right_type</var> specifies a right to be inserted and how that right \rshould be extracted from the caller.  It should be a value appropriate for \r<strong>mach_msg</strong>.\r<p>\rIf <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>,\ror \r<strong>MACH_MSG_TYPE_COPY_SEND</strong>, then a send right is inserted.  If the target \ralready holds send or receive rights for the port, then <var>name</var> \rshould denote those rights in the target.  Otherwise, <var>name</var> should \rbe unused in \rthe target.  If the target already has send rights, then those\rsend rights gain an\radditional user reference.  Otherwise, the target gains a send\rright, with a user\rreference count of one.\r<p>\rIf <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or \r<strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>, then a send-once right is inserted.  \rThe <var>name</var> should be unused in the target.  The \rtarget gains a send-once right. \r<p>\rIf <var>right_type</var> is <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>, then a receive right is \rinserted.  If the target already holds send rights for the port,\rthen <var>name</var> should\rdenote those rights in the target.  Otherwise, <var>name</var> should be\runused in the target. \rThe receive right is moved into the target task.\r<h3>NOTES</h3>\r<p>\rThis interface is machine word length specific because of the port name\rparameter.\r<h3>RETURN VALUES</h3>\r<dl>\r<p>\r<dt> <strong>KERN_NAME_EXISTS</strong>\r<dd>\r<var>name</var> already denoted a right.\r<p>\r<dt> <strong>KERN_INVALID_CAPABILITY</strong>\r<dd>\r<var>right</var> was null or dead.\r<p>\r<dt> <strong>KERN_UREFS_OVERFLOW</strong>\r<dd>\rInserting the right would overflow <var>name</var>'s user-reference count.\r<p>\r<dt> <strong>KERN_RIGHT_EXISTS</strong>\r<dd>\r<var>task</var> already had rights for the port, with a different name.\r</dl>\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>,\r<a href="mach_msg.html"><strong>mach_msg</strong></a>.\r