1 .\"
2 .\" Mach Operating System
3 .\" Copyright (c) 1991,1990 Carnegie Mellon University
4 .\" All Rights Reserved.
5 .\"
6 .\" Permission to use, copy, modify and distribute this software and its
7 .\" documentation is hereby granted, provided that both the copyright
8 .\" notice and this permission notice appear in all copies of the
9 .\" software, derivative works or modified versions, and any portions
10 .\" thereof, and that both notices appear in supporting documentation.
11 .\"
12 .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
13 .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
14 .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
15 .\"
16 .\" Carnegie Mellon requests users of this software to return to
17 .\"
18 .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
19 .\" School of Computer Science
20 .\" Carnegie Mellon University
21 .\" Pittsburgh PA 15213-3890
22 .\"
23 .\" any improvements or extensions that they make and grant Carnegie Mellon
24 .\" the rights to redistribute these changes.
25 .\"
26 .\"
27 .\" HISTORY
28 .\" $Log: mach_port_request_notification.man,v $
29 .\" Revision 2.6 93/05/10 19:31:40 rvb
30 .\" updated
31 .\" [93/04/21 16:03:55 lli]
32 .\"
33 .\" Revision 2.5 91/12/11 08:43:16 jsb
34 .\" Changed <mach/mach.h> to <mach.h>.
35 .\" [91/11/25 10:55:53 rpd]
36 .\"
37 .\" Revision 2.4 91/05/14 17:07:28 mrt
38 .\" Correcting copyright
39 .\"
40 .\" Revision 2.3 91/02/14 14:11:53 mrt
41 .\" Changed to new Mach copyright
42 .\" [91/02/12 18:12:05 mrt]
43 .\"
44 .\" Revision 2.2 90/08/07 18:38:04 rpd
45 .\" Created.
46 .\"
47 .TH mach_port_request_notification 2 4/13/87
48 .CM 4
49 .SH NAME
50 .nf
51 mach_port_request_notification \- request a notification
52 .SH SYNOPSIS
53 .nf
54 .ft B
55 #include <mach.h>
56
57 kern_return_t
58 mach_port_request_notification(task, name, variant, sync,
59 notify, notify_type, previous)
60 mach_port_t task;
61 mach_port_t name;
62 mach_msg_id_t variant;
63 mach_port_mscount_t sync;
64 mach_port_t notify;
65 mach_msg_type_name_t notify_type;
66 mach_port_t *previous; /* out */
67 .fi
68 .ft P
69 .SH ARGUMENTS
70 .TP 12
71 .B
72 task
73 The task holding the specified right.
74 .TP 12
75 .B
76 name
77 The task's name for the right.
78 .TP 12
79 .B
80 variant
81 The type of notification.
82 .TP 12
83 .B
84 sync
85 Some variants use this value to overcome race conditions.
86 .TP 12
87 .B
88 notify
89 A send-once right, to which the notification will be sent.
90 .TP 12
91 .B
92 notify_type
93 IPC type of the sent right; either MACH_MSG_TYPE_MAKE_SEND_ONCE
94 or MACH_MSG_TYPE_MOVE_SEND_ONCE.
95 .TP 12
96 .B
97 previous
98 The previously registered send-once right.
99 .SH DESCRIPTION
100 \fBmach_port_request_notification\fR
101 registers a request for a notification and supplies a send-once right
102 that the notification will use. It is an atomic swap, returning
103 the previously registered send-once right (or MACH_PORT_NULL for none).
104 A previous notification request may be cancelled by providing MACH_PORT_NULL
105 for \fBnotify\fR.
106
107 The \fBvariant\fR argument takes the following values:
108 .TP 12
109 MACH_NOTIFY_PORT_DESTROYED
110 \fBsync\fR must be
111 zero. The \fBname\fR must specify a receive right, and the call
112 requests a port-destroyed notification for the receive right. If the
113 receive right were to have been destroyed, say by
114 \fBmach_port_destroy\fR, then instead the receive right will be sent
115 in a port-destroyed notification to the registered send-once right.
116 .TP 12
117 MACH_NOTIFY_DEAD_NAME
118 The call requests
119 a dead-name notification. \fBname\fR specifies send, receive, or
120 send-once rights for a port. If the port is destroyed (and the right
121 remains, becoming a dead name), then a dead-name
122 notification which carries the name of the right will be sent
123 to the registered send-once right. If \fBnotify\fR is not null
124 and \fBsync\fR is non-zero,
125 the \fBname\fR may specify a dead name, and a dead-name notification
126 is immediately generated.
127
128 Whenever a dead-name notification is generated, the user reference
129 count of the dead name is incremented. For example, a send right
130 with two user refs has a registered dead-name request. If the port
131 is destroyed, the send right turns into a dead name with three user
132 refs (instead of two), and a dead-name notification is generated.
133
134 If the name is made available for reuse, perhaps because of
135 \fBmach_port_destroy\fR or \fBmach_port_mod_refs\fR, or the name
136 denotes a send-once right which has a message sent to it,
137 then the registered send-once right is
138 used to generate a port-deleted notification.
139 .TP 12
140 MACH_NOTIFY_NO_SENDERS
141 The call requests
142 a no-senders notification. \fBname\fR must specify a receive right.
143 If \fBnotify\fR is not null,
144 and the receive right's make-send count is greater than or equal to
145 the sync value,
146 and it has no extant send rights, than an immediate no-senders
147 notification is generated. Otherwise the notification is generated
148 when the receive right next loses its last extant send right.
149 In either case, any previously registered send-once right is returned.
150
151 The no-senders notification carries the value the port's make-send
152 count had when it was generated. The make-send count is incremented
153 whenever MACH_MSG_TYPE_MAKE_SEND is used to create a new send right
154 from the receive right. The make-send count is reset to zero
155 when the receive right is carried in a message.
156 .SH DIAGNOSTICS
157 .TP 25
158 KERN_SUCCESS
159 The call succeeded.
160 .TP 25
161 KERN_INVALID_TASK
162 \fBtask\fR was invalid.
163 .TP 25
164 KERN_INVALID_VALUE
165 \fBvariant\fR was invalid.
166 .TP 25
167 KERN_INVALID_NAME
168 \fBname\fR did not denote a right.
169 .TP 25
170 KERN_INVALID_RIGHT
171 \fBname\fR denoted an invalid right.
172 .TP 25
173 KERN_INVALID_CAPABILITY
174 \fBnotify\fR was invalid.
175 .PP
176 When using MACH_NOTIFY_PORT_DESTROYED:
177 .TP 25
178 KERN_INVALID_VALUE
179 \fBsync\fR was not zero.
180 .PP
181 When using MACH_NOTIFY_DEAD_NAME:
182 .TP 25
183 KERN_RESOURCE_SHORTAGE
184 The kernel ran out of memory.
185 .TP 25
186 KERN_INVALID_ARGUMENT
187 \fBname\fR denotes a dead name, but \fBsync\fR is zero
188 or \fBnotify\fR is null.
189 .TP 25
190 KERN_UREFS_OVERFLOW
191 \fBname\fR denotes a dead name, but generating an immediate
192 dead-name notification would overflow the name's user-reference count.
193 .PP
194 The \fBmach_port_request_notification\fR call is actually an RPC to \fBtask\fR,
195 normally a send right for a task port, but potentially any send right.
196 In addition to the normal diagnostic
197 return codes from the call's server (normally the kernel),
198 the call may return \fBmach_msg(2)\fR return codes.
199 .SH SEE ALSO
200 mach_port_get_receive_status(2).
Cache object: e569461421e1d76c9b2a0004d1c1c183
|