4.3.8 Request Notifications

Function: kern_return_t mach_port_request_notification (ipc_space_t task, mach_port_t name, mach_msg_id_t variant, mach_port_mscount_t sync, mach_port_t notify, mach_msg_type_name_t notify_type, mach_port_t *previous)

The function mach_port_request_notification registers a request for a notification and supplies the send-once right notify to which the notification will be sent. The notify_type denotes the IPC type for the send-once right, which can be MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE. It is an atomic swap, returning the previously registered send-once right (or MACH_PORT_NULL for none) in previous. A previous notification request may be cancelled by providing MACH_PORT_NULL for notify.

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, say 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 notify is not null and 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.

MACH_NOTIFY_NO_SENDERS

The call requests a no-senders notification. name must specify a receive right. If notify is not null, and 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 MACH_MSG_TYPE_MAKE_SEND is used to create a new send right from the receive right. The make-send count is reset to zero when the receive right is carried in a message.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if variant was invalid, KERN_INVALID_NAME if name did not denote a right, KERN_INVALID_RIGHT if name denoted an invalid right and KERN_INVALID_CAPABILITY if notify was invalid.

When using MACH_NOTIFY_PORT_DESTROYED, the function returns KERN_INVALID_VALUE if sync wasn’t zero.

When using MACH_NOTIFY_DEAD_NAME, the function returns KERN_RESOURCE_SHORTAGE if the kernel ran out of memory, KERN_INVALID_ARGUMENT if name denotes a dead name, but sync is zero or notify is MACH_PORT_NULL, and KERN_UREFS_OVERFLOW if name denotes a dead name, but generating an immediate dead-name notification would overflow the name’s user-reference count.

The mach_port_request_notification call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call’s server (normally the kernel), the call may return mach_msg return codes.