osfmk/ipc/ipc_right.h

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