1<h2>mach_port_get_set_status</h2>
2<hr>
3<p>
4<strong>Function</strong> - Return the port right names contained in the target port set.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_port_get_set_status</strong>
8                <strong>(ipc_space_t</strong>                               <var>task</var>,
9                 <strong>mach_port_name_t</strong>                          <var>name</var>,
10                 <strong>mach_port_name_array_t</strong>                <var>*members</var>,
11                 <strong>task</strong>                                     <var>count</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 port set.
20<p>
21<dt> <var>name</var> 
22<dd>
23[in scalar]
24The task's name for the port set.
25<p>
26<dt> <var>members</var> 
27<dd>
28[out pointer to dynamic array of <var>mach_port_name_t</var>]
29The task's names 
30for the port set's members.
31<p>
32<dt> <var>count</var> 
33<dd>
34[out scalar]
35The number of member names returned.
36</dl>
37<h3>DESCRIPTION</h3>
38<p>
39The <strong>mach_port_get_set_status</strong> function returns the individual port 
40right names for all port rights contained in the specified port set.
41The <var>members</var> parameter is an array that is automatically 
42allocated when the reply message is received.  Note that
43<strong>vm_deallocate</strong> should be used to free the array.
44<p>
45Note that this interface, unlike others such as <strong>task_threads</strong>,
46returns a collection of port right names, NOT a collection of port rights themselves.
47In other words, this function does not insert port rights into the caller's
48port right name space; consequently, a call to  <strong>mach_port_get_set_status</strong>
49does not affect the reference count of each port right within the target port set.
50<h3>NOTES</h3>
51<p>
52This interface is machine word length specific because of the port name
53parameter and the returned port names.
54<h3>RETURN VALUES</h3>
55<dl>
56<p>
57<dt> <strong>KERN_INVALID_NAME</strong>
58<dd>
59<var>name</var> did not denote a right.
60<p>
61<dt> <strong>KERN_INVALID_RIGHT</strong>
62<dd>
63<var>name</var> denoted a right, but not a port set.
64</dl>
65<h3>RELATED INFORMATION</h3>
66<p>
67Functions:
68<a href="mach_port_insert_member.html"><strong>mach_port_insert_member</strong></a>,
69<a href="mach_port_extract_member.html"><strong>mach_port_extract_member</strong></a>,
70<a href="mach_port_move_member.html"><strong>mach_port_move_member</strong></a>,
71<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>.
72