1<h2>mach_port_allocate</h2>
2<hr>
3<p>
4<strong>Function</strong> - Create caller-specified type of port right.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_port_allocate</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</strong> creates a port.  The new port is not a 
29member of any port set.  It doesn't have any extant send or 
30send-once rights.  Its make-send count is zero, its sequence 
31number is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>, and 
32it has no queued messages.  <var>name</var> denotes the 
33receive 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</strong> creates a port set.  The new port set has 
42no members.
43<p>
44<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
45<dd>
46<strong>mach_port_allocate</strong> creates a dead name.  The new dead 
47name has one user reference.
48</dl>
49<p>
50<dt> <var>name</var> 
51<dd>
52[out scalar]
53The task's name for the port right.  This can be any name 
54that wasn't in use.
55</dl>
56<h3>DESCRIPTION</h3>
57<p>
58The <strong>mach_port_allocate</strong> function creates a new right
59in the specified task.  The new right's name is returned in name.
60<p>
61Ports that are allocated via this call do not support the full set of
62Mach port semantics; in particular, the kernel will not provide no-more-senders
63notification service requests on such ports.  Any attempt to request  no-more-senders
64notification service
65will generate an error.  Use the <strong>mach_port_allocate_full</strong>
66interface to allocate ports that support the full set of Mach port semantics.
67<h3>NOTES</h3>
68<p>
69This interface is machine word length specific because of the port name
70parameter.
71<h3>RETURN VALUES</h3>
72<dl>
73<p>
74<dt> <strong>KERN_NO_SPACE</strong>
75<dd>
76There was no room in task's IPC name space for another right.
77</dl>
78<h3>RELATED INFORMATION</h3>
79<p>
80Functions:
81<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
82<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
83<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
84<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
85