[apple/xnu.git] / osfmk / ipc / ipc_right.h

/*
 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/*
 * @OSF_COPYRIGHT@
 */
/*
 * Mach Operating System
 * Copyright (c) 1991,1990,1989 Carnegie Mellon University
 * All Rights Reserved.
 *
 * Permission to use, copy, modify and distribute this software and its
 * documentation is hereby granted, provided that both the copyright
 * notice and this permission notice appear in all copies of the
 * software, derivative works or modified versions, and any portions
 * thereof, and that both notices appear in supporting documentation.
 *
 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
 * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
 *
 * Carnegie Mellon requests users of this software to return to
 *
 *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
 *  School of Computer Science
 *  Carnegie Mellon University
 *  Pittsburgh PA 15213-3890
 *
 * any improvements or extensions that they make and grant Carnegie Mellon
 * the rights to redistribute these changes.
 */
/*
 */
/*
 *	File:	ipc/ipc_right.h
 *	Author:	Rich Draves
 *	Date:	1989
 *
 *	Declarations of functions to manipulate IPC capabilities.
 */

#ifndef _IPC_IPC_RIGHT_H_
#define _IPC_IPC_RIGHT_H_

#include <mach/boolean.h>
#include <mach/kern_return.h>
#include <ipc/ipc_port.h>
#include <ipc/ipc_entry.h>

#define ipc_right_lookup_read           ipc_right_lookup_write
#define ipc_right_lookup_two_read       ipc_right_lookup_two_write

typedef uint32_t ipc_right_copyin_flags_t;

#define IPC_RIGHT_COPYIN_FLAGS_NONE                   0x0
#define IPC_RIGHT_COPYIN_FLAGS_DEADOK                 0x1
#define IPC_RIGHT_COPYIN_FLAGS_ALLOW_IMMOVABLE_SEND   0x2
#define IPC_RIGHT_COPYIN_FLAGS_ALLOW_DEAD_SEND_ONCE   0x4   /* allow copyin of a send once right to a dead port with no dead name requests */

/* Find an entry in a space, given the name */
extern kern_return_t ipc_right_lookup_write(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             *entryp);

/* Find two entries in a space, given two names */
extern kern_return_t ipc_right_lookup_two_write(
	ipc_space_t             space,
	mach_port_name_t        name1,
	ipc_entry_t             *entryp1,
	mach_port_name_t        name2,
	ipc_entry_t             *entryp2);

/* Translate (space, object) -> (name, entry) */
extern boolean_t ipc_right_reverse(
	ipc_space_t             space,
	ipc_object_t            object,
	mach_port_name_t        *namep,
	ipc_entry_t             *entryp);

/* Make a notification request, returning the previous send-once right */
extern kern_return_t ipc_right_request_alloc(
	ipc_space_t             space,
	mach_port_name_t        name,
	boolean_t               immediate,
	boolean_t               send_possible,
	ipc_port_t              notify,
	ipc_port_t              *previousp);

/* Cancel a notification request and return the send-once right */
extern ipc_port_t ipc_right_request_cancel(
	ipc_space_t             space,
	ipc_port_t              port,
	mach_port_name_t        name,
	ipc_entry_t             entry);

#define ipc_right_request_cancel_macro(space, port, name, entry)                \
	         ((entry->ie_request == IE_REQ_NONE) ? IP_NULL :                \
	         ipc_right_request_cancel((space), (port), (name), (entry)))

/* Check if an entry is being used */
extern boolean_t ipc_right_inuse(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             entry);

/* Check if the port has died */
extern boolean_t ipc_right_check(
	ipc_space_t              space,
	ipc_port_t               port,
	mach_port_name_t         name,
	ipc_entry_t              entry,
	ipc_right_copyin_flags_t flags);

/* Clean up an entry in a dead space */
extern void ipc_right_terminate(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             entry);

/* Destroy an entry in a space */
extern kern_return_t ipc_right_destroy(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             entry,
	boolean_t               check_guard,
	uint64_t                guard);

/* Release a send/send-once/dead-name user reference */
extern kern_return_t ipc_right_dealloc(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             entry);

/* Modify the user-reference count for a right */
extern kern_return_t ipc_right_delta(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             entry,
	mach_port_right_t       right,
	mach_port_delta_t       delta);

/* Destroy a receive right; Modify ref count for send rights */
extern kern_return_t ipc_right_destruct(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             entry,
	mach_port_delta_t       srdelta,
	uint64_t                guard);

/* Retrieve information about a right */
extern kern_return_t ipc_right_info(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             entry,
	mach_port_type_t        *typep,
	mach_port_urefs_t       *urefsp);

/* Check if a subsequent ipc_right_copyin of the reply port will succeed */
extern boolean_t ipc_right_copyin_check_reply(
	ipc_space_t              space,
	mach_port_name_t         reply_name,
	ipc_entry_t              reply_entry,
	mach_msg_type_name_t     reply_type);

/* Copyin a capability from a space */
extern kern_return_t ipc_right_copyin(
	ipc_space_t               space,
	mach_port_name_t          name,
	ipc_entry_t               entry,
	mach_msg_type_name_t      msgt_name,
	ipc_right_copyin_flags_t  flags,
	ipc_object_t              *objectp,
	ipc_port_t                *sorightp,
	ipc_port_t                *releasep,
	int                       *assertcntp,
	mach_port_context_t       context,
	mach_msg_guard_flags_t    *guard_flags);

/* Copyin a pair of dispositions from a space */
extern kern_return_t ipc_right_copyin_two(
	ipc_space_t               space,
	mach_port_name_t          name,
	ipc_entry_t               entry,
	mach_msg_type_name_t      msgt_one,
	mach_msg_type_name_t      msgt_two,
	ipc_object_t              *objectp,
	ipc_port_t                *sorightp,
	ipc_port_t                *releasep);

/* Copyout a capability to a space */
extern kern_return_t ipc_right_copyout(
	ipc_space_t             space,
	mach_port_name_t        name,
	ipc_entry_t             entry,
	mach_msg_type_name_t    msgt_name,
	mach_port_context_t     *context,
	mach_msg_guard_flags_t  *guard_flags,
	ipc_object_t            object);

#endif  /* _IPC_IPC_RIGHT_H_ */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
0a7de745	5	*
2d21ac55 A	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.
0a7de745	14	*
2d21ac55 A	15	* Please obtain a copy of the License at
2d21ac55 A	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
0a7de745	17	*
2d21ac55 A	18	* The Original Code and all software distributed under the License are
2d21ac55 A	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	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.
0a7de745	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	27	*/
	28	/*
	29	* @OSF_COPYRIGHT@
	30	*/
0a7de745	31	/*
1c79356b A	32	* Mach Operating System
	33	* Copyright (c) 1991,1990,1989 Carnegie Mellon University
	34	* All Rights Reserved.
0a7de745	35	*
1c79356b A	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.
0a7de745	41	*
1c79356b A	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.
0a7de745	45	*
1c79356b	46	* Carnegie Mellon requests users of this software to return to
0a7de745	47	*
1c79356b A	48	* Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
	49	* School of Computer Science
	50	* Carnegie Mellon University
	51	* Pittsburgh PA 15213-3890
0a7de745	52	*
1c79356b A	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
0a7de745 A	66	#ifndef _IPC_IPC_RIGHT_H_
0a7de745 A	67	#define _IPC_IPC_RIGHT_H_
1c79356b A	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
0a7de745 A	74	#define ipc_right_lookup_read ipc_right_lookup_write
	75	#define ipc_right_lookup_two_read ipc_right_lookup_two_write
	76
	77	typedef uint32_t ipc_right_copyin_flags_t;
	78
	79	#define IPC_RIGHT_COPYIN_FLAGS_NONE 0x0
	80	#define IPC_RIGHT_COPYIN_FLAGS_DEADOK 0x1
cb323159	81	#define IPC_RIGHT_COPYIN_FLAGS_ALLOW_IMMOVABLE_SEND 0x2
0a7de745	82	#define IPC_RIGHT_COPYIN_FLAGS_ALLOW_DEAD_SEND_ONCE 0x4 /* allow copyin of a send once right to a dead port with no dead name requests */
1c79356b A	83
	84	/* Find an entry in a space, given the name */
	85	extern kern_return_t ipc_right_lookup_write(
0a7de745 A	86	ipc_space_t space,
	87	mach_port_name_t name,
	88	ipc_entry_t *entryp);
1c79356b A	89
	90	/* Find two entries in a space, given two names */
	91	extern kern_return_t ipc_right_lookup_two_write(
0a7de745 A	92	ipc_space_t space,
	93	mach_port_name_t name1,
	94	ipc_entry_t *entryp1,
	95	mach_port_name_t name2,
	96	ipc_entry_t *entryp2);
1c79356b A	97
	98	/* Translate (space, object) -> (name, entry) */
	99	extern boolean_t ipc_right_reverse(
0a7de745 A	100	ipc_space_t space,
	101	ipc_object_t object,
	102	mach_port_name_t *namep,
	103	ipc_entry_t *entryp);
1c79356b	104
6d2010ae A	105	/* Make a notification request, returning the previous send-once right */
6d2010ae A	106	extern kern_return_t ipc_right_request_alloc(
0a7de745 A	107	ipc_space_t space,
	108	mach_port_name_t name,
	109	boolean_t immediate,
	110	boolean_t send_possible,
	111	ipc_port_t notify,
	112	ipc_port_t *previousp);
1c79356b	113
6d2010ae A	114	/* Cancel a notification request and return the send-once right */
6d2010ae A	115	extern ipc_port_t ipc_right_request_cancel(
0a7de745 A	116	ipc_space_t space,
	117	ipc_port_t port,
	118	mach_port_name_t name,
	119	ipc_entry_t entry);
1c79356b	120
0a7de745 A	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)))
1c79356b A	124
	125	/* Check if an entry is being used */
	126	extern boolean_t ipc_right_inuse(
0a7de745 A	127	ipc_space_t space,
	128	mach_port_name_t name,
	129	ipc_entry_t entry);
1c79356b A	130
	131	/* Check if the port has died */
	132	extern boolean_t ipc_right_check(
0a7de745 A	133	ipc_space_t space,
	134	ipc_port_t port,
	135	mach_port_name_t name,
	136	ipc_entry_t entry,
	137	ipc_right_copyin_flags_t flags);
1c79356b A	138
1c79356b A	139	/* Clean up an entry in a dead space */
316670eb	140	extern void ipc_right_terminate(
0a7de745 A	141	ipc_space_t space,
	142	mach_port_name_t name,
	143	ipc_entry_t entry);
1c79356b A	144
	145	/* Destroy an entry in a space */
	146	extern kern_return_t ipc_right_destroy(
0a7de745 A	147	ipc_space_t space,
	148	mach_port_name_t name,
	149	ipc_entry_t entry,
	150	boolean_t check_guard,
	151	uint64_t guard);
1c79356b A	152
	153	/* Release a send/send-once/dead-name user reference */
	154	extern kern_return_t ipc_right_dealloc(
0a7de745 A	155	ipc_space_t space,
	156	mach_port_name_t name,
	157	ipc_entry_t entry);
1c79356b A	158
	159	/* Modify the user-reference count for a right */
	160	extern kern_return_t ipc_right_delta(
0a7de745 A	161	ipc_space_t space,
	162	mach_port_name_t name,
	163	ipc_entry_t entry,
	164	mach_port_right_t right,
	165	mach_port_delta_t delta);
1c79356b	166
39236c6e A	167	/* Destroy a receive right; Modify ref count for send rights */
39236c6e A	168	extern kern_return_t ipc_right_destruct(
0a7de745 A	169	ipc_space_t space,
	170	mach_port_name_t name,
	171	ipc_entry_t entry,
	172	mach_port_delta_t srdelta,
	173	uint64_t guard);
39236c6e	174
1c79356b A	175	/* Retrieve information about a right */
1c79356b A	176	extern kern_return_t ipc_right_info(
0a7de745 A	177	ipc_space_t space,
	178	mach_port_name_t name,
	179	ipc_entry_t entry,
	180	mach_port_type_t *typep,
	181	mach_port_urefs_t *urefsp);
1c79356b	182
cb323159 A	183	/* Check if a subsequent ipc_right_copyin of the reply port will succeed */
	184	extern boolean_t ipc_right_copyin_check_reply(
	185	ipc_space_t space,
	186	mach_port_name_t reply_name,
	187	ipc_entry_t reply_entry,
	188	mach_msg_type_name_t reply_type);
1c79356b A	189
	190	/* Copyin a capability from a space */
	191	extern kern_return_t ipc_right_copyin(
cb323159 A	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_right_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);
1c79356b	203
fe8ab488	204	/* Copyin a pair of dispositions from a space */
1c79356b	205	extern kern_return_t ipc_right_copyin_two(
cb323159 A	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_t *objectp,
	212	ipc_port_t *sorightp,
	213	ipc_port_t *releasep);
1c79356b A	214
	215	/* Copyout a capability to a space */
	216	extern kern_return_t ipc_right_copyout(
0a7de745 A	217	ipc_space_t space,
	218	mach_port_name_t name,
	219	ipc_entry_t entry,
	220	mach_msg_type_name_t msgt_name,
cb323159 A	221	mach_port_context_t *context,
cb323159 A	222	mach_msg_guard_flags_t *guard_flags,
0a7de745	223	ipc_object_t object);
1c79356b	224
0a7de745	225	#endif /* _IPC_IPC_RIGHT_H_ */