1<h2>mach_port_deallocate</h2>
2<hr>
3<p>
4<strong>Function</strong> - Decrement the target port right's user reference count.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_port_deallocate</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_deallocate</strong> function releases a user reference
27for a right.  It is 
28an alternate form of <strong>mach_port_mod_refs</strong> that allows
29a task to release a user 
30reference for a send or send-once right without failing if the
31port has died and 
32the right is now actually a dead name.
33<p>
34If <var>name</var> denotes a dead name, send right, or send-once right,
35then the right loses 
36one user reference.  If it only had one user reference, then
37the right is destroyed. 
38If <var>name</var> does not denote an element in the port name space, the
39function returns 
40success.
41<h3>NOTES</h3>
42<p>
43This interface is machine word length specific because of the port name
44parameter.
45<h3>RETURN VALUES</h3>
46<dl>
47<p>
48<dt> <strong>KERN_INVALID_RIGHT</strong>
49<dd>
50The <var>name</var> parameter denoted an invalid right.
51</dl>
52<h3>RELATED INFORMATION</h3>
53<p>
54Functions:
55<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
56<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
57<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>.
58