forked from apple/darwin-xnu
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathMP_request_notification.html
147 lines (147 loc) · 5.4 KB
/
MP_request_notification.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
<h2>mach_port_request_notification</h2>
<hr>
<p>
<strong>Function</strong> - Request notification of the specified port event type.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t mach_port_request_notification</strong>
<strong>(ipc_space_t</strong> <var>task</var>,
<strong>mach_port_name_t</strong> <var>name</var>,
<strong>mach_msg_id_t</strong> <var>variant</var>,
<strong>mach_port_mscount_t</strong> <var>sync</var>,
<strong>mach_port_send_once_t</strong> <var>notify</var>,
<strong>mach_msg_type_name_t</strong> <var>notify_type</var>,
<strong>mach_port_send_once_t</strong> <var>*previous</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>task</var>
<dd>
[in task send right]
The task holding the specified right.
<p>
<dt> <var>name</var>
<dd>
[in scalar]
The task's name for the right.
<p>
<dt> <var>variant</var>
<dd>
[in scalar]
The type of notification.
<p>
<dt> <var>sync</var>
<dd>
[in scalar]
Some variants use this value to overcome race conditions.
<p>
<dt> <var>notify</var>
<dd>
[in notify send-once or receive (to be converted to send-once) right]
A
send-once right, to which the notification will be sent.
<p>
<dt> <var>notify_type</var>
<dd>
[in scalar]
IPC type of the <var>notify</var> right; either
<strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>.
<p>
<dt> <var>previous</var>
<dd>
[out notify send-once right]
The previously registered send-once right.
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>mach_port_request_notification</strong> 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
<strong>MACH_PORT_NULL</strong> for none). A notification request may be
cancelled by providing <strong>MACH_PORT_NULL</strong>.
<p>
The <var>variant</var> argument takes the following values:
<dl>
<dt> <strong>MACH_NOTIFY_PORT_DESTROYED</strong>
<dd>
<var>sync</var> must be zero. The <var>name</var> 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 <strong>mach_port_destroy</strong>, then instead the receive right will be
sent in a port-destroyed notification to the registered send-once right.
<p>
<dt> <strong>MACH_NOTIFY_DEAD_NAME</strong>
<dd>
The call requests a dead-name notification. <var>name</var> 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 <var>sync</var> is non-zero,
the <var>name</var> may specify a dead name, and
a dead-name notification is immediately generated.
<p>
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.
<p>
If the name is made available for reuse, perhaps because of
<strong>mach_port_destroy</strong> or <strong>mach_port_mod_refs</strong>,
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.
<p>
<dt> <strong>MACH_NOTIFY_NO_SENDERS</strong>
<dd>
The call requests a no-senders notification. <var>name</var> 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.
<p>
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.
<p>
When moving a receive right, no-senders notifications are canceled,
with a send-once notification sent to indicate the cancelation.
</dl>
<h3>NOTES</h3>
<p>
This interface is machine word length specific because of the port name
parameter.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>KERN_INVALID_NAME</strong>
<dd>
<var>name</var> did not denote a right.
<p>
<dt> <strong>KERN_INVALID_RIGHT</strong>
<dd>
<var>name</var> denoted an invalid right.
<p>
<dt> <strong>KERN_INVALID_CAPABILITY</strong>
<dd>
<var>notify</var> was invalid.
</dl>
<p>
When using <strong>MACH_NOTIFY_DEAD_NAME</strong>:
<dl>
<p>
<dt> <strong>KERN_UREFS_OVERFLOW</strong>
<dd>
<var>name</var> denotes a dead name, but generating an immediate dead-name
notification would overflow the name's user-reference count.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="mach_msg.html"><strong>mach_msg</strong></a>,
<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.