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_destroy.man,v $
29 .\" Revision 2.6 93/05/10 19:31:08 rvb
30 .\" updated
31 .\" [93/04/21 16:03:19 lli]
32 .\"
33 .\" Revision 2.5 91/12/11 08:42:49 jsb
34 .\" Changed <mach/mach.h> to <mach.h>.
35 .\" [91/11/25 10:55:18 rpd]
36 .\"
37 .\" Revision 2.4 91/05/14 17:06:07 mrt
38 .\" Correcting copyright
39 .\"
40 .\" Revision 2.3 91/02/14 14:11:07 mrt
41 .\" Changed to new Mach copyright
42 .\" [91/02/12 18:11:19 mrt]
43 .\"
44 .\" Revision 2.2 90/08/07 18:36:28 rpd
45 .\" Created.
46 .\"
47 .TH mach_port_destroy 2 9/19/86
48 .CM 4
49 .SH NAME
50 .nf
51 mach_port_destroy \- removes a task's rights for a name
52 .SH SYNOPSIS
53 .nf
54 .ft B
55 #include <mach.h>
56
57 kern_return_t
58 mach_port_destroy(task, name)
59 mach_port_t task;
60 mach_port_t name;
61 .fi
62 .ft P
63 .SH ARGUMENTS
64 .TP 12
65 .B
66 task
67 The task holding the right.
68 .TP 12
69 .B
70 name
71 The task's name for the right.
72 .SH DESCRIPTION
73 \fBmach_port_destroy\fR deallocates all rights denoted by a name.
74 The name becomes immediately available for reuse.
75
76 For most purposes, \fBmach_port_mod_refs\fR
77 and \fBmach_port_deallocate\fR are preferable.
78
79 If \fBname\fR denotes a port set, then all members of the port set
80 are implicitly removed from the port set.
81
82 If \fBname\fR denotes a receive right that is a member of a port set,
83 the receive right is implicitly removed from the port set. If there
84 is a port-destroyed request registered for the port, then the receive
85 right is not actually destroyed, but instead is sent in a port-destroyed
86 notification to the backup port. If there is no registered
87 port-destroyed request, remaining messages queued to the port are destroyed
88 and extant send and send-once rights turn into dead names. If those
89 send and send-once rights have dead-name requests registered, then
90 dead-name notifications are generated for them.
91
92 If \fBname\fR denotes a send-once right, then the send-once right
93 is used to produce a send-once notification for the port.
94
95 If \fBname\fR denotes a send-once, send, and/or receive right, and it has a
96 dead-name request registered, then the registered send-once right
97 is used to produce a port-deleted notification for the name.
98 .SH DIAGNOSTICS
99 .TP 25
100 KERN_SUCCESS
101 The call succeeded.
102 .TP 25
103 KERN_INVALID_TASK
104 \fBtask\fR was invalid.
105 .TP 25
106 KERN_INVALID_NAME
107 \fBname\fR did not denote a right.
108 .PP
109 The \fBmach_port_destroy\fR call is actually an RPC to \fBtask\fR,
110 normally a send right for a task port, but potentially any send right.
111 In addition to the normal diagnostic
112 return codes from the call's server (normally the kernel),
113 the call may return \fBmach_msg(2)\fR return codes.
114 .SH SEE ALSO
115 mach_port_mod_refs(2), mach_port_deallocate(2),
116 mach_port_request_notification(2).
Cache object: 6bdccc588aaa74821ae76e9a0795c09b
|