mach_port_request_notification

Function - Request notification of the specified port event type.

SYNOPSIS

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);

PARAMETERS

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.

DESCRIPTION

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.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

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.

RELATED INFORMATION

Functions: mach_msg, mach_port_get_attributes.