osfmk/man/MP_request_notification.html
Function - Request notification of the specified port event type.
**kern\_return\_t mach\_port\_request\_notification**** (ipc\_space\_t **task,** mach\_port\_name\_t **name,** mach\_msg\_id\_t **variant,** mach\_port\_mscount\_t **sync,** mach\_port\_send\_once\_t **notify,** mach\_msg\_type\_name\_t **notify\_type,** mach\_port\_send\_once\_t **\*previous** );**
task[in task send right] The task holding the specified right.
name[in scalar] The task's name for the right.
variant[in scalar] The type of notification.
sync[in scalar] Some variants use this value to overcome race conditions.
notify[in notify send-once or receive (to be converted to send-once) right] A send-once right, to which the notification will be sent.
notify_type[in scalar] IPC type of the notify right; either MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE.
previous[out notify send-once right] The previously registered send-once right.
The mach_port_request_notification function registers a request for a notification and supplies a send-once right that the notification will use. It is an atomic swap, returning the previously registered send-once right (or MACH_PORT_NULL for none). A notification request may be cancelled by providing MACH_PORT_NULL.
The variant argument takes the following values:
MACH_NOTIFY_PORT_DESTROYED sync must be zero. The name must specify a receive right, and the call requests a port-destroyed notification for the receive right. If the receive right were to have been destroyed, for instance by mach_port_destroy , then instead the receive right will be sent in a port-destroyed notification to the registered send-once right.
MACH_NOTIFY_DEAD_NAME The call requests a dead-name notification. name specifies send, receive, or send-once rights for a port. If the port is destroyed (and the right remains, becoming a dead name), then a dead-name notification which carries the name of the right will be sent to the registered send-once right. If sync is non-zero, the name may specify a dead name, and a dead-name notification is immediately generated.
Whenever a dead-name notification is generated, the user reference count of the dead name is incremented. For example, a send right with two user refs has a registered dead-name request. If the port is destroyed, the send right turns into a dead name with three user refs (instead of two), and a dead-name notification is generated.
If the name is made available for reuse, perhaps because of mach_port_destroy or mach_port_mod_refs , or the name denotes a send-once right which has a message sent to it, then the registered send-once right is used to generate a port-deleted notification instead.
MACH_NOTIFY_NO_SENDERS The call requests a no-senders notification. name must specify a receive right. If the receive right's make-send count is greater than or equal to the sync value, and it has no extant send rights, than an immediate no-senders notification is generated. Otherwise the notification is generated when the receive right next loses its last extant send right. In either case, any previously registered send-once right is returned.
The no-senders notification carries the value the port's make-send count had when it was generated. The make-send count is incremented whenever a send right is made directly from a receive right. The make-send count is reset to zero when the receive right is carried in a message.
When moving a receive right, no-senders notifications are canceled, with a send-once notification sent to indicate the cancelation.
This interface is machine word length specific because of the port name parameter.
KERN_INVALID_NAME name did not denote a right.
KERN_INVALID_RIGHT name denoted an invalid right.
KERN_INVALID_CAPABILITY notify was invalid.
When using MACH_NOTIFY_DEAD_NAME :
KERN_UREFS_OVERFLOW name denotes a dead name, but generating an immediate dead-name notification would overflow the name's user-reference count.
Functions: mach_msg, mach_port_get_attributes.