1<h2>mach_port_get_refs</h2>
2<hr>
3<p>
4<strong>Function</strong> - Return the current count of user references on the target port right.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_port_get_refs</strong>
8                <strong>(ipc_space_t</strong>                               <var>task</var>,
9                 <strong>mach_port_name_t</strong>                          <var>name</var>,
10                 <strong>mach_port_right_t</strong>                        <var>right</var>,
11                 <strong>mach_port_urefs_t</strong>                        <var>*refs</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 holding the right.
20<p>
21<dt> <var>name</var> 
22<dd>
23[in scalar]
24The task's name for the right.
25<p>
26<dt> <var>right</var> 
27<dd>
28[in scalar]
29The type of right/entity being examined:
30<dl>
31<p>
32<dt> <dd>
33<strong>MACH_PORT_RIGHT_SEND</strong>
34<p>
35<dt> <dd>
36<strong>MACH_PORT_RIGHT_RECEIVE</strong>
37<p>
38<dt> <dd>
39<strong>MACH_PORT_RIGHT_SEND_ONCE</strong>
40<p>
41<dt> <dd>
42<strong>MACH_PORT_RIGHT_PORT_SET</strong>
43<p>
44<dt> <dd>
45<strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
46</dl>
47<p>
48<dt> <var>refs</var> 
49<dd>
50[out scalar]
51Number of user references.
52</dl>
53<h3>DESCRIPTION</h3>
54<p>
55The <strong>mach_port_get_refs</strong> function returns the number
56of user references a task 
57has for a right.
58<p>
59If <var>name</var> denotes a right, but not the type of right specified,
60then zero is returned. 
61Otherwise a positive number of user references is returned.  Note a name may
62simultaneously denote send and receive rights.  The number of references for
63send-once rights is always one.
64<h3>NOTES</h3>
65<p>
66This interface is machine word length specific because of the port name
67parameter.
68<h3>RETURN VALUES</h3>
69<dl>
70<p>
71<dt> <strong>KERN_INVALID_NAME</strong>
72<dd>
73<var>name</var> did not denote a right.
74</dl>
75<h3>RELATED INFORMATION</h3>
76<p>
77Functions:
78<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>.
79