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