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 [email protected] 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 __BEGIN_DECLS __ASSUME_PTR_ABI_SINGLE_BEGIN 75 #pragma GCC visibility push(hidden) 76 77 #define ipc_right_lookup_two_read ipc_right_lookup_two_write 78 79 /* Find an entry in a space, given the name */ 80 extern kern_return_t ipc_right_lookup_read( 81 ipc_space_t space, 82 mach_port_name_t name, 83 ipc_entry_bits_t *bitsp, 84 ipc_object_t *objectp); 85 86 /* Find an entry in a space, given the name */ 87 extern kern_return_t ipc_right_lookup_write( 88 ipc_space_t space, 89 mach_port_name_t name, 90 ipc_entry_t *entryp); 91 92 /* Find two entries in a space, given two names */ 93 extern kern_return_t ipc_right_lookup_two_write( 94 ipc_space_t space, 95 mach_port_name_t name1, 96 ipc_entry_t *entryp1, 97 mach_port_name_t name2, 98 ipc_entry_t *entryp2); 99 100 /* Translate (space, port) -> (name, entry) */ 101 extern bool ipc_right_reverse( 102 ipc_space_t space, 103 ipc_port_t port, 104 mach_port_name_t *namep, 105 ipc_entry_t *entryp); 106 107 /* Make a notification request, returning the previous send-once right */ 108 extern kern_return_t ipc_right_request_alloc( 109 ipc_space_t space, 110 mach_port_name_t name, 111 ipc_port_request_opts_t options, 112 ipc_port_t notify, 113 mach_msg_id_t id, 114 ipc_port_t *previousp); 115 116 /* Check if an entry is being used */ 117 extern bool ipc_right_inuse( 118 ipc_entry_t entry); 119 120 /* Check if the port has died */ 121 extern bool ipc_right_check( 122 ipc_space_t space, 123 ipc_port_t port, 124 mach_port_name_t name, 125 ipc_entry_t entry, 126 ipc_copyin_op_t copyin_reason); 127 128 /* Clean up an entry in a dead space */ 129 extern void ipc_right_terminate( 130 ipc_space_t space, 131 mach_port_name_t name, 132 ipc_entry_t entry); 133 134 /* Destroy an entry in a space */ 135 extern kern_return_t ipc_right_destroy( 136 ipc_space_t space, 137 mach_port_name_t name, 138 ipc_entry_t entry); 139 140 /* Release a send/send-once/dead-name user reference */ 141 extern kern_return_t ipc_right_dealloc( 142 ipc_space_t space, 143 mach_port_name_t name, 144 ipc_entry_t entry); 145 146 /* Modify the user-reference count for a right */ 147 extern kern_return_t ipc_right_delta( 148 ipc_space_t space, 149 mach_port_name_t name, 150 ipc_entry_t entry, 151 mach_port_right_t right, 152 mach_port_delta_t delta); 153 154 /* Destroy a receive right; Modify ref count for send rights */ 155 extern kern_return_t ipc_right_destruct( 156 ipc_space_t space, 157 mach_port_name_t name, 158 ipc_entry_t entry, 159 mach_port_delta_t srdelta, 160 uint64_t guard); 161 162 /* Retrieve information about a right */ 163 extern kern_return_t ipc_right_info( 164 ipc_space_t space, 165 mach_port_name_t name, 166 ipc_entry_t entry, 167 mach_port_type_t *typep, 168 mach_port_urefs_t *urefsp); 169 170 /* Check if a subsequent ipc_right_copyin of the reply port will succeed */ 171 extern bool ipc_right_copyin_check_reply( 172 ipc_space_t space, 173 mach_port_name_t reply_name, 174 ipc_entry_t reply_entry, 175 mach_msg_type_name_t reply_type); 176 177 typedef struct { 178 ipc_port_t icc_release_port; 179 ipc_port_t icc_deleted_port; 180 } ipc_copyin_cleanup_t; 181 182 /* used if the right copied in might be a receive right */ 183 typedef struct { 184 #if IMPORTANCE_INHERITANCE 185 uint32_t icrc_assert_count; 186 #endif /* IMPORTANCE_INHERITANCE */ 187 waitq_link_list_t icrc_free_list; 188 mach_msg_guarded_port_descriptor_t *icrc_guarded_desc; 189 } ipc_copyin_rcleanup_t; 190 191 extern void ipc_right_copyin_cleanup_destroy( 192 ipc_copyin_cleanup_t *icc, 193 mach_port_name_t name); 194 195 extern void ipc_right_copyin_rcleanup_init( 196 ipc_copyin_rcleanup_t *icrc, 197 mach_msg_guarded_port_descriptor_t *gdesc); 198 199 extern void ipc_right_copyin_rcleanup_destroy( 200 ipc_copyin_rcleanup_t *icrc); 201 202 /* Copyin a capability from a space */ 203 extern kern_return_t ipc_right_copyin( 204 ipc_space_t space, 205 mach_port_name_t name, 206 mach_msg_type_name_t msgt_name, 207 ipc_object_copyin_flags_t flags, 208 ipc_copyin_op_t copyin_reason, 209 ipc_entry_t entry, 210 ipc_port_t *portp, 211 ipc_copyin_cleanup_t *icc, 212 ipc_copyin_rcleanup_t *icrc); 213 214 /* Copyout a send or send-once capability to a space */ 215 extern void ipc_right_copyout_any_send( 216 ipc_space_t space, 217 ipc_port_t port, 218 mach_msg_type_name_t msgt_name, 219 ipc_object_copyout_flags_t flags, 220 mach_port_name_t name, 221 ipc_entry_t entry); 222 223 /* Copyout a receive capability to a space */ 224 extern void ipc_right_copyout_recv_and_unlock_space( 225 ipc_space_t space, 226 ipc_port_t port, 227 ipc_object_label_t *label, 228 mach_port_name_t name, 229 ipc_entry_t entry, 230 mach_msg_guarded_port_descriptor_t *gdesc); 231 232 #pragma GCC visibility pop 233 __ASSUME_PTR_ABI_SINGLE_END __END_DECLS 234 235 #endif /* _IPC_IPC_RIGHT_H_ */ 236