| 9bccf70c |
1 | <h2>mach_port_request_notification</h2>\r<hr>\r<p>\r<strong>Function</strong> - Request notification of the specified port event type.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t mach_port_request_notification</strong>\r <strong>(ipc_space_t</strong> <var>task</var>,\r <strong>mach_port_name_t</strong> <var>name</var>,\r <strong>mach_msg_id_t</strong> <var>variant</var>,\r <strong>mach_port_mscount_t</strong> <var>sync</var>,\r <strong>mach_port_send_once_t</strong> <var>notify</var>,\r <strong>mach_msg_type_name_t</strong> <var>notify_type</var>,\r <strong>mach_port_send_once_t</strong> <var>*previous</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>task</var> \r<dd>\r[in task send right]\rThe task holding the specified right.\r<p>\r<dt> <var>name</var> \r<dd>\r[in scalar]\rThe task's name for the right.\r<p>\r<dt> <var>variant</var> \r<dd>\r[in scalar]\rThe type of notification.\r<p>\r<dt> <var>sync</var> \r<dd>\r[in scalar]\rSome variants use this value to overcome race conditions.\r<p>\r<dt> <var>notify</var> \r<dd>\r[in notify send-once or receive (to be converted to send-once) right]\rA \rsend-once right, to which the notification will be sent.\r<p>\r<dt> <var>notify_type</var> \r<dd>\r[in scalar]\rIPC type of the <var>notify</var> right; either\r<strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>.\r<p>\r<dt> <var>previous</var> \r<dd>\r[out notify send-once right]\rThe previously registered send-once right.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>mach_port_request_notification</strong> function registers a request for a\rnotification and supplies a send-once right that the notification\rwill use. It is an atomic \rswap, returning the previously registered send-once right (or\r<strong>MACH_PORT_NULL</strong> for none). A notification request may be\rcancelled by providing <strong>MACH_PORT_NULL</strong>.\r<p>\rThe <var>variant</var> argument takes the following values:\r<dl>\r<dt> <strong>MACH_NOTIFY_PORT_DESTROYED</strong>\r<dd>\r<var>sync</var> must be zero. The <var>name</var> must specify a receive right,\rand the call requests a port-destroyed notification for the receive\rright. If the receive right were to have been destroyed, for instance\rby <strong>mach_port_destroy</strong>, then instead the receive right will be\rsent in a port-destroyed notification to the registered send-once right.\r<p>\r<dt> <strong>MACH_NOTIFY_DEAD_NAME</strong>\r<dd>\rThe call requests a dead-name notification. <var>name</var> specifies send,\rreceive, or send-once rights for a port. If the port is destroyed (and the \rright remains, becoming a dead name), then a dead-name notification \rwhich carries the name of the right will be sent to the registered\rsend-once right. If <var>sync</var> is non-zero, \rthe <var>name</var> may specify a dead name, and \ra dead-name notification is immediately generated.\r<p>\rWhenever a dead-name notification is generated, the user reference \rcount of the dead name is incremented. For example, a send right with \rtwo user refs has a registered dead-name request. If the port is\rdestroyed, the send right turns into a dead name with three user refs\r(instead of two), and a dead-name notification is generated. \r<p>\rIf the name is made available for reuse, perhaps because of\r<strong>mach_port_destroy</strong> or <strong>mach_port_mod_refs</strong>,\ror the name denotes a\rsend-once right which has a message sent to it, then the registered send-once \rright is used to generate a port-deleted notification instead.\r<p>\r<dt> <strong>MACH_NOTIFY_NO_SENDERS</strong>\r<dd>\rThe call requests a no-senders notification. <var>name</var> must specify a\rreceive right. If the receive right's make-send count is greater than or \requal to the sync value, and it has no extant send rights, than an\rimmediate no-senders notification is generated. Otherwise the notification is \rgenerated when the receive right next loses its last extant send right. In \reither case, any previously registered send-once right is returned.\r<p>\rThe no-senders notification carries the value the port's make-send \rcount had when it was generated. The make-send count is incremented \rwhenever a send right is made directly from a receive right. The\rmake-send count is reset to zero when the receive right is carried in a\rmessage.\r<p>\rWhen moving a receive right, no-senders notifications are canceled, \rwith a send-once notification sent to indicate the cancelation.\r</dl>\r<h3>NOTES</h3>\r<p>\rThis interface is machine word length specific because of the port name\rparameter.\r<h3>RETURN VALUES</h3>\r<dl>\r<p>\r<dt> <strong>KERN_INVALID_NAME</strong>\r<dd>\r<var>name</var> did not denote a right.\r<p>\r<dt> <strong>KERN_INVALID_RIGHT</strong>\r<dd>\r<var>name</var> denoted an invalid right.\r<p>\r<dt> <strong>KERN_INVALID_CAPABILITY</strong>\r<dd>\r<var>notify</var> was invalid.\r</dl>\r<p>\rWhen using <strong>MACH_NOTIFY_DEAD_NAME</strong>:\r<dl>\r<p>\r<dt> <strong>KERN_UREFS_OVERFLOW</strong>\r<dd>\r<var>name</var> denotes a dead name, but generating an immediate dead-name \rnotification would overflow the name's user-reference count.\r</dl>\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.\r |
projects / apple / xnu.git / blame