1<h2>mach_port_destroy</h2> 2<hr> 3<p> 4<strong>Function</strong> - Deallocate all port rights associated with specified name. 5<h3>SYNOPSIS</h3> 6<pre> 7<strong>kern_return_t mach_port_destroy</strong> 8 <strong>(ipc_space_t</strong> <var>task</var>, 9 <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong> 10</pre> 11<h3>PARAMETERS</h3> 12<dl> 13<p> 14<dt> <var>task</var> 15<dd> 16[in task send right] 17The task holding the right. 18<p> 19<dt> <var>name</var> 20<dd> 21[in scalar] 22The task's name for the right. 23</dl> 24<h3>DESCRIPTION</h3> 25<p> 26The <strong>mach_port_destroy</strong> function de-allocates all rights 27denoted by a name. 28The name becomes immediately available for reuse. 29<p> 30For most purposes, 31<strong>mach_port_mod_refs</strong> and <strong>mach_port_deallocate</strong> are 32preferable. 33<p> 34If <var>name</var> denotes a port set, then all members of the port set are implicitly 35removed from the port set. 36<p> 37If <var>name</var> denotes a receive right that is a member of a port set, 38the receive right is 39implicitly removed from the port set. Remaining messages queued to the port 40are destroyed and extant send and send-once rights turn into dead names. If 41those send and send-once rights have dead-name requests registered, then 42dead-name notifications are generated for them. 43<p> 44If <var>name</var> denotes a send-once right, then 45the destruction of the send-once right 46produces a send-once notification for the port. 47<p> 48If <var>name</var> denotes a send-once, send, and/or receive right, and 49it has a dead-name 50request registered, then a port-deleted notification is generated 51(as opposed to a 52dead-name notification). 53<h3>NOTES</h3> 54<p> 55This interface is machine word length specific because of the port name 56parameter. 57<h3>RETURN VALUES</h3> 58<dl> 59<p> 60<dt> <strong>KERN_INVALID_NAME</strong> 61<dd> 62The <var>name</var> parameter did not denote a right. 63</dl> 64<h3>RELATED INFORMATION</h3> 65<p> 66Functions: 67<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>, 68<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>, 69<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>, 70<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>, 71<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>. 72