1/*
2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/*
29 * @OSF_COPYRIGHT@
30 */
31/*
32 * Mach Operating System
33 * Copyright (c) 1991,1990,1989 Carnegie Mellon University
34 * All Rights Reserved.
35 *
36 * Permission to use, copy, modify and distribute this software and its
37 * documentation is hereby granted, provided that both the copyright
38 * notice and this permission notice appear in all copies of the
39 * software, derivative works or modified versions, and any portions
40 * thereof, and that both notices appear in supporting documentation.
41 *
42 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
43 * CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
44 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
45 *
46 * Carnegie Mellon requests users of this software to return to
47 *
48 * Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
49 * School of Computer Science
50 * Carnegie Mellon University
51 * Pittsburgh PA 15213-3890
52 *
53 * any improvements or extensions that they make and grant Carnegie Mellon
54 * the rights to redistribute these changes.
55 */
56/*
57 */
58/*
59 * File: ipc/ipc_right.h
60 * Author: Rich Draves
61 * Date: 1989
62 *
63 * Declarations of functions to manipulate IPC capabilities.
64 */
65
66#ifndef _IPC_IPC_RIGHT_H_
67#define _IPC_IPC_RIGHT_H_
68
69#include <mach/boolean.h>
70#include <mach/kern_return.h>
71#include <ipc/ipc_port.h>
72#include <ipc/ipc_entry.h>
73
74#define ipc_right_lookup_two_read ipc_right_lookup_two_write
75
76extern bool service_port_defense_enabled;
77
78/* Find an entry in a space, given the name */
79extern kern_return_t ipc_right_lookup_read(
80 ipc_space_t space,
81 mach_port_name_t name,
82 ipc_entry_bits_t *bitsp,
83 ipc_object_t *objectp);
84
85/* Find an entry in a space, given the name */
86extern kern_return_t ipc_right_lookup_write(
87 ipc_space_t space,
88 mach_port_name_t name,
89 ipc_entry_t *entryp);
90
91/* Find two entries in a space, given two names */
92extern kern_return_t ipc_right_lookup_two_write(
93 ipc_space_t space,
94 mach_port_name_t name1,
95 ipc_entry_t *entryp1,
96 mach_port_name_t name2,
97 ipc_entry_t *entryp2);
98
99/* Translate (space, object) -> (name, entry) */
100extern bool ipc_right_reverse(
101 ipc_space_t space,
102 ipc_object_t object,
103 mach_port_name_t *namep,
104 ipc_entry_t *entryp);
105
106/* Make a notification request, returning the previous send-once right */
107extern kern_return_t ipc_right_request_alloc(
108 ipc_space_t space,
109 mach_port_name_t name,
110 ipc_port_request_opts_t options,
111 ipc_port_t notify,
112 ipc_port_t *previousp);
113
114/* Cancel a notification request and return the send-once right */
115extern ipc_port_t ipc_right_request_cancel(
116 ipc_space_t space,
117 ipc_port_t port,
118 mach_port_name_t name,
119 ipc_entry_t entry);
120
121#define ipc_right_request_cancel_macro(space, port, name, entry) \
122 ((entry->ie_request == IE_REQ_NONE) ? IP_NULL : \
123 ipc_right_request_cancel((space), (port), (name), (entry)))
124
125/* Check if an entry is being used */
126extern bool ipc_right_inuse(
127 ipc_entry_t entry);
128
129/* Check if the port has died */
130extern boolean_t ipc_right_check(
131 ipc_space_t space,
132 ipc_port_t port,
133 mach_port_name_t name,
134 ipc_entry_t entry,
135 ipc_object_copyin_flags_t flags);
136
137/* Clean up an entry in a dead space */
138extern void ipc_right_terminate(
139 ipc_space_t space,
140 mach_port_name_t name,
141 ipc_entry_t entry);
142
143/* Destroy an entry in a space */
144extern kern_return_t ipc_right_destroy(
145 ipc_space_t space,
146 mach_port_name_t name,
147 ipc_entry_t entry,
148 boolean_t check_guard,
149 uint64_t guard);
150
151/* Release a send/send-once/dead-name user reference */
152extern kern_return_t ipc_right_dealloc(
153 ipc_space_t space,
154 mach_port_name_t name,
155 ipc_entry_t entry);
156
157/* Modify the user-reference count for a right */
158extern kern_return_t ipc_right_delta(
159 ipc_space_t space,
160 mach_port_name_t name,
161 ipc_entry_t entry,
162 mach_port_right_t right,
163 mach_port_delta_t delta);
164
165/* Destroy a receive right; Modify ref count for send rights */
166extern kern_return_t ipc_right_destruct(
167 ipc_space_t space,
168 mach_port_name_t name,
169 ipc_entry_t entry,
170 mach_port_delta_t srdelta,
171 uint64_t guard);
172
173/* Retrieve information about a right */
174extern kern_return_t ipc_right_info(
175 ipc_space_t space,
176 mach_port_name_t name,
177 ipc_entry_t entry,
178 mach_port_type_t *typep,
179 mach_port_urefs_t *urefsp);
180
181/* Check if a subsequent ipc_right_copyin of the reply port will succeed */
182extern boolean_t ipc_right_copyin_check_reply(
183 ipc_space_t space,
184 mach_port_name_t reply_name,
185 ipc_entry_t reply_entry,
186 mach_msg_type_name_t reply_type,
187 ipc_entry_t dest_entry,
188 boolean_t *reply_port_semantics_violation);
189
190/* Copyin a capability from a space */
191extern kern_return_t ipc_right_copyin(
192 ipc_space_t space,
193 mach_port_name_t name,
194 ipc_entry_t entry,
195 mach_msg_type_name_t msgt_name,
196 ipc_object_copyin_flags_t flags,
197 ipc_object_t *objectp,
198 ipc_port_t *sorightp,
199 ipc_port_t *releasep,
200 int *assertcntp,
201 mach_port_context_t context,
202 mach_msg_guard_flags_t *guard_flags);
203
204/* Copyin a pair of dispositions from a space */
205extern kern_return_t ipc_right_copyin_two(
206 ipc_space_t space,
207 mach_port_name_t name,
208 ipc_entry_t entry,
209 mach_msg_type_name_t msgt_one,
210 mach_msg_type_name_t msgt_two,
211 ipc_object_copyin_flags_t flags_one,
212 ipc_object_copyin_flags_t flags_two,
213 ipc_object_t *objectp,
214 ipc_port_t *sorightp,
215 ipc_port_t *releasep);
216
217/* Copyout a capability to a space */
218extern kern_return_t ipc_right_copyout(
219 ipc_space_t space,
220 mach_port_name_t name,
221 ipc_entry_t entry,
222 mach_msg_type_name_t msgt_name,
223 ipc_object_copyout_flags_t flags,
224 mach_port_context_t *context,
225 mach_msg_guard_flags_t *guard_flags,
226 ipc_object_t object);
227
228#endif /* _IPC_IPC_RIGHT_H_ */
229