mach_port_request_notificationregisters 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_MOVE_SEND_ONCE. It is an atomic swap, returning the previously registered send-once right (or
MACH_PORT_NULLfor none) in previous. A previous notification request may be cancelled by providing
The variant argument takes the following values:
- 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.
- 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_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.
- 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_SENDis 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_SUCCESSif the call succeeded,
KERN_INVALID_TASKif task was invalid,
KERN_INVALID_VALUEif variant was invalid,
KERN_INVALID_NAMEif name did not denote a right,
KERN_INVALID_RIGHTif name denoted an invalid right and
KERN_INVALID_CAPABILITYif notify was invalid.
MACH_NOTIFY_PORT_DESTROYED, the function returns
KERN_INVALID_VALUEif sync wasn't zero.
MACH_NOTIFY_DEAD_NAME, the function returns
KERN_RESOURCE_SHORTAGEif the kernel ran out of memory,
KERN_INVALID_ARGUMENTif name denotes a dead name, but sync is zero or notify is
KERN_UREFS_OVERFLOWif name denotes a dead name, but generating an immediate dead-name notification would overflow the name's user-reference count.
mach_port_request_notificationcall 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