X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/743b15655a24ee3fe9f458f383003e011db0558f..13fec9890cf095cc781fdf7b8917cb03bf32dd4c:/osfmk/man/MP_request_notification.html
diff --git a/osfmk/man/MP_request_notification.html b/osfmk/man/MP_request_notification.html
index 1d41e4b74..34125f0ad 100755
--- a/osfmk/man/MP_request_notification.html
+++ b/osfmk/man/MP_request_notification.html
@@ -1 +1,147 @@
-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.
\ No newline at end of file
+
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.