mach_port_get_set_status.html   [plain text]

<strong>Function</strong> - Return the port right names contained in the target port set.
<strong>kern_return_t   mach_port_get_set_status</strong>
                <strong>(ipc_space_t</strong>                               <var>task</var>,
                 <strong>mach_port_name_t</strong>                          <var>name</var>,
                 <strong>mach_port_name_array_t</strong>                <var>*members</var>,
                 <strong>task</strong>                                     <var>count</var><strong>);</strong>
<dt> <var>task</var> 
[in task send right]
The task holding the port set.
<dt> <var>name</var> 
[in scalar]
The task's name for the port set.
<dt> <var>members</var> 
[out pointer to dynamic array of <var>mach_port_name_t</var>]
The task's names 
for the port set's members.
<dt> <var>count</var> 
[out scalar]
The number of member names returned.
The <strong>mach_port_get_set_status</strong> function returns the individual port 
right names for all port rights contained in the specified port set.
The <var>members</var> parameter is an array that is automatically 
allocated when the reply message is received.  Note that
<strong>vm_deallocate</strong> should be used to free the array.
Note that this interface, unlike others such as <strong>task_threads</strong>,
returns a collection of port right names, NOT a collection of port rights themselves.
In other words, this function does not insert port rights into the caller's
port right name space; consequently, a call to  <strong>mach_port_get_set_status</strong>
does not affect the reference count of each port right within the target port set.
This interface is machine word length specific because of the port name
parameter and the returned port names.
<dt> <strong>KERN_INVALID_NAME</strong>
<var>name</var> did not denote a right.
<dt> <strong>KERN_INVALID_RIGHT</strong>
<var>name</var> denoted a right, but not a port set.
<a href="mach_port_insert_member.html"><strong>mach_port_insert_member</strong></a>,
<a href="mach_port_extract_member.html"><strong>mach_port_extract_member</strong></a>,
<a href="mach_port_move_member.html"><strong>mach_port_move_member</strong></a>,
<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>.