1<h2>mach_port_allocate_name</h2>
2<hr>
3<p>
4<strong>Function</strong> - Create a port right with the caller-specified name.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_port_allocate_name</strong>
8                <strong>(ipc_space_t</strong>                               <var>task</var>,
9                 <strong>mach_port_right_t</strong>                        <var>right</var>,
10                 <strong>mach_port_name_t</strong>                          <var>name</var><strong>);</strong>
11</pre>
12<h3>PARAMETERS</h3>
13<dl>
14<p>
15<dt> <var>task</var> 
16<dd>
17[in task send right]
18The task acquiring the port right.
19<p>
20<dt> <var>right</var> 
21<dd>
22[in scalar]
23The kind of entity to be created.  This is one of the following:
24<dl>
25<p>
26<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong>
27<dd>
28<strong>mach_port_allocate_name</strong> creates a port.  The new port is 
29not a member of any port set.  It doesn't have any extant send 
30or send-once rights.  Its make-send count is zero, its sequence 
31number is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>, 
32and it has no queued messages. 
33<var>name</var> denotes the receive right for the new port.
34<var>task</var> does not hold send rights for the new port, only the
35receive right.  <strong>mach_port_insert_right</strong> and
36<strong>mach_port_extract_right</strong> can be used to convert the receive right into a 
37combined send/receive right.
38<p>
39<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong>
40<dd>
41<strong>mach_port_allocate_name</strong> creates a port set.  The new port 
42set has no members.
43<p>
44<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
45<dd>
46<strong>mach_port_allocate_name</strong> creates a dead name.  The new 
47dead name has one user reference.
48</dl>
49<p>
50<dt> <var>name</var> 
51<dd>
52[in scalar]
53The task's name for the port right. name must not already be 
54in use for some right, and it can't be the reserved values 
55<strong>MACH_PORT_NULL</strong> and <strong>MACH_PORT_DEAD</strong>. 
56</dl>
57<h3>DESCRIPTION</h3>
58<p>
59The <strong>mach_port_allocate_name</strong> function creates a new
60right in the specified 
61task, with a specified name for the new right.
62<h3>NOTES</h3>
63<p>
64This interface is machine word length specific because of the port name
65parameter.
66<h3>RETURN VALUES</h3>
67<dl>
68<p>
69<dt> <strong>KERN_NAME_EXISTS</strong>
70<dd>
71name was already in use for a port right.
72</dl>
73<h3>RELATED INFORMATION</h3>
74<p>
75Functions:
76<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
77<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
78<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
79<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
80