1<h2>mach_port_request_notification</h2>
2<hr>
3<p>
4<strong>Function</strong> - Request notification of the specified port event type.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_port_request_notification</strong>
8                <strong>(ipc_space_t</strong>                               <var>task</var>,
9                 <strong>mach_port_name_t</strong>                          <var>name</var>,
10                 <strong>mach_msg_id_t</strong>                          <var>variant</var>,
11                 <strong>mach_port_mscount_t</strong>                       <var>sync</var>,
12                 <strong>mach_port_send_once_t</strong>                   <var>notify</var>,
13                 <strong>mach_msg_type_name_t</strong>               <var>notify_type</var>,
14                 <strong>mach_port_send_once_t</strong>                <var>*previous</var><strong>);</strong>
15</pre>
16<h3>PARAMETERS</h3>
17<dl>
18<p>
19<dt> <var>task</var> 
20<dd>
21[in task send right]
22The task holding the specified right.
23<p>
24<dt> <var>name</var> 
25<dd>
26[in scalar]
27The task's name for the right.
28<p>
29<dt> <var>variant</var> 
30<dd>
31[in scalar]
32The type of notification.
33<p>
34<dt> <var>sync</var> 
35<dd>
36[in scalar]
37Some variants use this value to overcome race conditions.
38<p>
39<dt> <var>notify</var> 
40<dd>
41[in notify send-once or receive (to be converted to send-once) right]
42A 
43send-once right, to which the notification will be sent.
44<p>
45<dt> <var>notify_type</var> 
46<dd>
47[in scalar]
48IPC type of the <var>notify</var> right; either
49<strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>.
50<p>
51<dt> <var>previous</var> 
52<dd>
53[out notify send-once right]
54The previously registered send-once right.
55</dl>
56<h3>DESCRIPTION</h3>
57<p>
58The <strong>mach_port_request_notification</strong> function registers a request for a
59notification and supplies a send-once right that the notification
60will use.  It is an atomic 
61swap, returning the previously registered send-once right (or
62<strong>MACH_PORT_NULL</strong> for none).  A notification request may be
63cancelled by providing <strong>MACH_PORT_NULL</strong>.
64<p>
65The <var>variant</var> argument takes the following values:
66<dl>
67<dt> <strong>MACH_NOTIFY_PORT_DESTROYED</strong>
68<dd>
69<var>sync</var> must be zero.  The <var>name</var> must specify a receive right,
70and the call requests a port-destroyed notification for the receive
71right.  If the receive right were to have been destroyed, for instance
72by <strong>mach_port_destroy</strong>, then instead the receive right will be
73sent in a port-destroyed notification to the registered send-once right.
74<p>
75<dt> <strong>MACH_NOTIFY_DEAD_NAME</strong>
76<dd>
77The call requests a dead-name notification.  <var>name</var> specifies send,
78receive, or send-once rights for a port.  If the port is destroyed (and the 
79right remains, becoming a dead name), then a dead-name notification 
80which carries the name of the right will be sent to the registered
81send-once right.  If <var>sync</var> is non-zero, 
82the <var>name</var> may specify a dead name, and 
83a dead-name notification is immediately generated.
84<p>
85Whenever a dead-name notification is generated, the user reference 
86count of the dead name is incremented.  For example, a send right with 
87two user refs has a registered dead-name request.  If the port is
88destroyed, the send right turns into a dead name with three user refs
89(instead of two), and a dead-name notification is generated. 
90<p>
91If the name is made available for reuse, perhaps because of
92<strong>mach_port_destroy</strong> or <strong>mach_port_mod_refs</strong>,
93or the name denotes a
94send-once right which has a message sent to it, then the registered send-once 
95right is used to generate a port-deleted notification instead.
96<p>
97<dt> <strong>MACH_NOTIFY_NO_SENDERS</strong>
98<dd>
99The call requests a no-senders notification.  <var>name</var> must specify a
100receive right.  If the receive right's make-send count is greater than or 
101equal to the sync value, and it has no extant send rights, than an
102immediate no-senders notification is generated.  Otherwise the notification is 
103generated when the receive right next loses its last extant send right.  In 
104either case, any previously registered send-once right is returned.
105<p>
106The no-senders notification carries the value the port's make-send 
107count had when it was generated.  The make-send count is incremented 
108whenever a send right is made directly from a receive right.  The
109make-send count is reset to zero when the receive right is carried in a
110message.
111<p>
112When moving a receive right, no-senders notifications are canceled, 
113with a send-once notification sent to indicate the cancelation.
114</dl>
115<h3>NOTES</h3>
116<p>
117This interface is machine word length specific because of the port name
118parameter.
119<h3>RETURN VALUES</h3>
120<dl>
121<p>
122<dt> <strong>KERN_INVALID_NAME</strong>
123<dd>
124<var>name</var> did not denote a right.
125<p>
126<dt> <strong>KERN_INVALID_RIGHT</strong>
127<dd>
128<var>name</var> denoted an invalid right.
129<p>
130<dt> <strong>KERN_INVALID_CAPABILITY</strong>
131<dd>
132<var>notify</var> was invalid.
133</dl>
134<p>
135When using <strong>MACH_NOTIFY_DEAD_NAME</strong>:
136<dl>
137<p>
138<dt> <strong>KERN_UREFS_OVERFLOW</strong>
139<dd>
140<var>name</var> denotes a dead name, but generating an immediate dead-name 
141notification would overflow the name's user-reference count.
142</dl>
143<h3>RELATED INFORMATION</h3>
144<p>
145Functions:
146<a href="mach_msg.html"><strong>mach_msg</strong></a>,
147<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
148