]> git.saurik.com Git - apple/xnu.git/blame_incremental - osfmk/man/mach_port_allocate_name.html
xnu-792.24.17.tar.gz
[apple/xnu.git] / osfmk / man / mach_port_allocate_name.html
... / ...
CommitLineData
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>.