[apple/xnu.git] / osfmk / mach / mach_port.defs

/*
 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
 * 
 * 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. 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_LICENSE_HEADER_END@
 */
/*
 * @OSF_FREE_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:	mach/mach_port.defs
 *	Author:	Rich Draves
 *
 *	Exported kernel calls.
 */

subsystem
#if	KERNEL_SERVER
	  KernelServer
#endif	/* KERNEL_SERVER */
	  mach_port 3200;

#include <mach/std_types.defs>
#include <mach/mach_types.defs>
#include <mach_debug/mach_debug_types.defs>

/*
 *	Returns the set of port and port set names
 *	to which the target task has access, along with
 *	the type (set or port) for each name.
 */

routine mach_port_names(
		task		: ipc_space_t;
	out	names		: mach_port_name_array_t;
	out	types		: mach_port_type_array_t);

/*
 *	Returns the type (set or port) for the port name
 *	within the target task.  Also indicates whether
 *	there is a dead-name request for the name.
 */

routine mach_port_type(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	ptype		: mach_port_type_t);

/*
 *	Changes the name by which a port (or port set) is known to
 *	the target task.  The new name can't be in use.  The
 *	old name becomes available for recycling.
 */

routine mach_port_rename(
		task		: ipc_space_t;
		old_name	: mach_port_name_t;
		new_name	: mach_port_name_t);

/*
 *	Allocates the specified kind of object, with the given name.
 *	The right must be one of
 *		MACH_PORT_RIGHT_RECEIVE
 *		MACH_PORT_RIGHT_PORT_SET
 *		MACH_PORT_RIGHT_DEAD_NAME
 *	New port sets are empty.  New ports don't have any
 *	send/send-once rights or queued messages.  The make-send
 *	count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.
 *	New sets, ports, and dead names have one user reference.
 */

routine mach_port_allocate_name(
		task		: ipc_space_t;
		right		: mach_port_right_t;
		name		: mach_port_name_t);

/*
 *	Allocates the specified kind of object.
 *	The right must be one of
 *		MACH_PORT_RIGHT_RECEIVE
 *		MACH_PORT_RIGHT_PORT_SET
 *		MACH_PORT_RIGHT_DEAD_NAME
 *	Like port_allocate_name, but the kernel picks a name.
 *	It can use any name not associated with a right.
 */

routine mach_port_allocate(
		task		: ipc_space_t;
		right		: mach_port_right_t;
	out	name		: mach_port_name_t);

/*
 *	Destroys all rights associated with the name and makes it
 *	available for recycling immediately.  The name can be a
 *	port (possibly with multiple user refs), a port set, or
 *	a dead name (again, with multiple user refs).
 */

routine mach_port_destroy(
		task		: ipc_space_t;
		name		: mach_port_name_t);

/*
 *	Releases one send/send-once/dead-name user ref.
 *	Just like mach_port_mod_refs -1, but deduces the
 *	correct type of right.  This allows a user task
 *	to release a ref for a port without worrying
 *	about whether the port has died or not.
 */

routine mach_port_deallocate(
		task		: ipc_space_t;
		name		: mach_port_name_t);

/*
 *	A port set always has one user ref.
 *	A send-once right always has one user ref.
 *	A dead name always has one or more user refs.
 *	A send right always has one or more user refs.
 *	A receive right always has one user ref.
 *	The right must be one of
 *		MACH_PORT_RIGHT_RECEIVE
 *		MACH_PORT_RIGHT_PORT_SET
 *		MACH_PORT_RIGHT_DEAD_NAME
 *		MACH_PORT_RIGHT_SEND
 *		MACH_PORT_RIGHT_SEND_ONCE
 */

routine mach_port_get_refs(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		right		: mach_port_right_t;
	out	refs		: mach_port_urefs_t);

/*
 *	The delta is a signed change to the task's
 *	user ref count for the right.  Only dead names
 *	and send rights can have a positive delta.
 *	The resulting user ref count can't be negative.
 *	If it is zero, the right is deallocated.
 *	If the name isn't a composite right, it becomes
 *	available for recycling.  The right must be one of
 *		MACH_PORT_RIGHT_RECEIVE
 *		MACH_PORT_RIGHT_PORT_SET
 *		MACH_PORT_RIGHT_DEAD_NAME
 *		MACH_PORT_RIGHT_SEND
 *		MACH_PORT_RIGHT_SEND_ONCE
 */

routine mach_port_mod_refs(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		right		: mach_port_right_t;
		delta		: mach_port_delta_t);

skip;

/*
 *	Only valid for receive rights.
 *	Sets the make-send count for the port.
 */
routine mach_port_set_mscount(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		mscount		: mach_port_mscount_t);

/*
 *	Only valid for port sets.  Returns a list of
 *	the members.
 */

routine mach_port_get_set_status(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	members		: mach_port_name_array_t);

/*
 *	Puts the member port (the task must have receive rights)
 *	into the after port set.  (Or removes it from any port set
 *	if after is MACH_PORT_NULL.)  If the port is already in
 *	a set, does an atomic move.
 */

routine mach_port_move_member(
		task		: ipc_space_t;
		member		: mach_port_name_t;
		after		: mach_port_name_t);

/*
 *	Requests a notification from the kernel.  The request
 *	must supply the send-once right which is used for
 *	the notification.  If a send-once right was previously
 *	registered, it is returned.  The msg_id must be one of
 *		MACH_NOTIFY_PORT_DESTROYED (receive rights)
 *		MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
 *		MACH_NOTIFY_NO_SENDERS (receive rights)
 *
 *	The sync value specifies whether a notification should
 *	get sent immediately, if appropriate.  The exact meaning
 *	depends on the notification:
 *		MACH_NOTIFY_PORT_DESTROYED: must be zero.
 *		MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,
 *			and the notification gets sent immediately.
 *			If zero, then name can't be dead.
 *		MACH_NOTIFY_NO_SENDERS: the notification gets sent
 *			immediately if the current mscount is greater
 *			than or equal to the sync value and there are no
 *			extant send rights.
 */

routine mach_port_request_notification(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		msgid		: mach_msg_id_t;
		sync		: mach_port_mscount_t;
		notify		: mach_port_send_once_t;
	out	previous	: mach_port_move_send_once_t);

/*
 *	Inserts the specified rights into the target task,
 *	using the specified name.  If inserting send/receive
 *	rights and the task already has send/receive rights
 *	for the port, then the names must agree.  In any case,
 *	the task gains a user ref for the port.
 */

routine mach_port_insert_right(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		poly		: mach_port_poly_t);

/*
 *	Returns the specified right for the named port
 *	in the target task, extracting that right from
 *	the target task.  The target task loses a user
 *	ref and the name may be available for recycling.
 *	msgt_name must be one of
 *		MACH_MSG_TYPE_MOVE_RECEIVE
 *		MACH_MSG_TYPE_COPY_SEND
 *		MACH_MSG_TYPE_MAKE_SEND
 *		MACH_MSG_TYPE_MOVE_SEND
 *		MACH_MSG_TYPE_MAKE_SEND_ONCE
 *		MACH_MSG_TYPE_MOVE_SEND_ONCE
 */

routine mach_port_extract_right(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		msgt_name	: mach_msg_type_name_t;
	out	poly		: mach_port_poly_t);

/*
 *	Only valid for receive rights.
 *	Sets the sequence number for the port.
 */

routine mach_port_set_seqno(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		seqno		: mach_port_seqno_t);

/*
 *      Returns information about a port.
 */

routine mach_port_get_attributes(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		flavor		: mach_port_flavor_t;
	out	port_info_out	: mach_port_info_t, CountInOut);

/*
 *      Set attributes of a port
 */

routine mach_port_set_attributes(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		flavor		: mach_port_flavor_t;
		port_info	: mach_port_info_t);


/*
 *	Allocates the specified kind of object, qos version.
 *	The right must be
 *		MACH_PORT_RIGHT_RECEIVE
 *	Like port_allocate_name, but the kernel picks a name.
 *	It can use any name not associated with a right.
 */

routine mach_port_allocate_qos(
		task		: ipc_space_t;
		right		: mach_port_right_t;
	inout	qos		: mach_port_qos_t;
	out	name		: mach_port_name_t);


/*
 *	Generic interface to allocation various kinds of ports.
 *	Should never be called directly by users (at least not
 *	unless they are exceedingly masochistic).
 */

routine mach_port_allocate_full(
		task		: ipc_space_t;
		right		: mach_port_right_t;
		proto		: mach_port_t;
	inout	qos		: mach_port_qos_t;
	inout	name		: mach_port_name_t);


/*
 *	Pre-expand task port name space.
 */
routine task_set_port_space(
		task		: ipc_space_t;
		table_entries	: int);


/*
 *	Returns the exact number of extant send rights
 *	for the given receive right.
 *      This call is only valid on MACH_IPC_DEBUG kernels.
 *      Otherwise, KERN_FAILURE is returned.
 */
routine	mach_port_get_srights(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	srights		: mach_port_rights_t);


/*
 *	Returns information about an IPC space.
 *      This call is only valid on MACH_IPC_DEBUG kernels.
 *      Otherwise, KERN_FAILURE is returned.
 */
routine mach_port_space_info(
		task		: ipc_space_t;
	out	info		: ipc_info_space_t;
	out	table_info	: ipc_info_name_array_t,
					Dealloc;
	out	tree_info	: ipc_info_tree_name_array_t,
					Dealloc);

/*
 *	Returns information about the dead-name requests
 *	registered with the named receive right.
 *      This call is only valid on MACH_IPC_DEBUG kernels.
 *      Otherwise, KERN_FAILURE is returned.
 */
routine mach_port_dnrequest_info(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	total		: unsigned;	/* total size of table */
	out	used		: unsigned);	/* amount used */

/*
 *	Return the type and address of the kernel object
 *	that the given send/receive right represents.
 *      This call is only valid on MACH_IPC_DEBUG kernels.
 *      Otherwise, KERN_FAILURE is returned.
 */
routine	mach_port_kernel_object(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	object_type	: unsigned;
	out	object_addr	: vm_offset_t);


/*
 *	Inserts the specified rights into the portset identified
 *	by the <task, pset> pair.  The results of passing in the
 *	Poly argument via the supplied disposition must yield a
 *	receive right.
 *
 *	If the <task,pset> pair does not represent a valid portset
 *	KERN_INVALID_RIGHT is returned.
 *	
 *	If the passed in name argument does not represent a receive
 *	right, KERN_INVALID_CAPABILITY will be returned.
 *
 *	If the port represented by the receive right is already in
 *	the portset, KERN_ALREADY_IN_SET is returned.
 */
routine mach_port_insert_member(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		pset		: mach_port_name_t);

/*
 *	Extracts the specified right from the named portset
 *	in the target task.  
 *	the target task.  The target task loses a user
 *	ref and the name may be available for recycling.
 *	msgt_name must be one of
 *		MACH_MSG_TYPE_MOVE_RECEIVE
 *		MACH_MSG_TYPE_COPY_SEND
 *		MACH_MSG_TYPE_MAKE_SEND
 *		MACH_MSG_TYPE_MOVE_SEND
 *		MACH_MSG_TYPE_MAKE_SEND_ONCE
 *		MACH_MSG_TYPE_MOVE_SEND_ONCE
 */

routine mach_port_extract_member(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		pset		: mach_port_name_t);
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
43866e37	6	* Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
1c79356b	7	*
43866e37 A	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
1c79356b A	17	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1c79356b A	18	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
43866e37 A	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.
1c79356b A	22	*
	23	* @APPLE_LICENSE_HEADER_END@
	24	*/
	25	/*
	26	* @OSF_FREE_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: mach/mach_port.defs
	57	* Author: Rich Draves
	58	*
	59	* Exported kernel calls.
	60	*/
	61
	62	subsystem
	63	#if KERNEL_SERVER
	64	KernelServer
55e303ae	65	#endif /* KERNEL_SERVER */
1c79356b A	66	mach_port 3200;
	67
	68	#include <mach/std_types.defs>
	69	#include <mach/mach_types.defs>
	70	#include <mach_debug/mach_debug_types.defs>
	71
	72	/*
	73	* Returns the set of port and port set names
	74	* to which the target task has access, along with
	75	* the type (set or port) for each name.
	76	*/
	77
	78	routine mach_port_names(
	79	task : ipc_space_t;
	80	out names : mach_port_name_array_t;
	81	out types : mach_port_type_array_t);
	82
	83	/*
	84	* Returns the type (set or port) for the port name
	85	* within the target task. Also indicates whether
	86	* there is a dead-name request for the name.
	87	*/
	88
	89	routine mach_port_type(
	90	task : ipc_space_t;
	91	name : mach_port_name_t;
	92	out ptype : mach_port_type_t);
	93
	94	/*
	95	* Changes the name by which a port (or port set) is known to
	96	* the target task. The new name can't be in use. The
	97	* old name becomes available for recycling.
	98	*/
	99
	100	routine mach_port_rename(
	101	task : ipc_space_t;
	102	old_name : mach_port_name_t;
	103	new_name : mach_port_name_t);
	104
	105	/*
	106	* Allocates the specified kind of object, with the given name.
	107	* The right must be one of
	108	* MACH_PORT_RIGHT_RECEIVE
	109	* MACH_PORT_RIGHT_PORT_SET
	110	* MACH_PORT_RIGHT_DEAD_NAME
	111	* New port sets are empty. New ports don't have any
	112	* send/send-once rights or queued messages. The make-send
	113	* count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.
	114	* New sets, ports, and dead names have one user reference.
	115	*/
	116
	117	routine mach_port_allocate_name(
	118	task : ipc_space_t;
	119	right : mach_port_right_t;
	120	name : mach_port_name_t);
	121
	122	/*
	123	* Allocates the specified kind of object.
	124	* The right must be one of
	125	* MACH_PORT_RIGHT_RECEIVE
	126	* MACH_PORT_RIGHT_PORT_SET
	127	* MACH_PORT_RIGHT_DEAD_NAME
	128	* Like port_allocate_name, but the kernel picks a name.
	129	* It can use any name not associated with a right.
130	*/
131
132	routine mach_port_allocate(
133	task : ipc_space_t;
134	right : mach_port_right_t;
135	out name : mach_port_name_t);
136
137	/*
138	* Destroys all rights associated with the name and makes it
139	* available for recycling immediately. The name can be a
140	* port (possibly with multiple user refs), a port set, or
141	* a dead name (again, with multiple user refs).
142	*/
143
144	routine mach_port_destroy(
145	task : ipc_space_t;
146	name : mach_port_name_t);
147
148	/*
149	* Releases one send/send-once/dead-name user ref.
150	* Just like mach_port_mod_refs -1, but deduces the
151	* correct type of right. This allows a user task
152	* to release a ref for a port without worrying
153	* about whether the port has died or not.
154	*/
155
156	routine mach_port_deallocate(
157	task : ipc_space_t;
158	name : mach_port_name_t);
159
160	/*
161	* A port set always has one user ref.
162	* A send-once right always has one user ref.
163	* A dead name always has one or more user refs.
164	* A send right always has one or more user refs.
165	* A receive right always has one user ref.
166	* The right must be one of
167	* MACH_PORT_RIGHT_RECEIVE
168	* MACH_PORT_RIGHT_PORT_SET
169	* MACH_PORT_RIGHT_DEAD_NAME
170	* MACH_PORT_RIGHT_SEND
171	* MACH_PORT_RIGHT_SEND_ONCE
172	*/
173
174	routine mach_port_get_refs(
175	task : ipc_space_t;
176	name : mach_port_name_t;
177	right : mach_port_right_t;
178	out refs : mach_port_urefs_t);
179
180	/*
181	* The delta is a signed change to the task's
182	* user ref count for the right. Only dead names
183	* and send rights can have a positive delta.
184	* The resulting user ref count can't be negative.
185	* If it is zero, the right is deallocated.
186	* If the name isn't a composite right, it becomes
187	* available for recycling. The right must be one of
188	* MACH_PORT_RIGHT_RECEIVE
189	* MACH_PORT_RIGHT_PORT_SET
190	* MACH_PORT_RIGHT_DEAD_NAME
191	* MACH_PORT_RIGHT_SEND
192	* MACH_PORT_RIGHT_SEND_ONCE
193	*/
194
195	routine mach_port_mod_refs(
196	task : ipc_space_t;
197	name : mach_port_name_t;
198	right : mach_port_right_t;
199	delta : mach_port_delta_t);
200
9bccf70c	201	skip;
1c79356b A	202
	203	/*
	204	* Only valid for receive rights.
	205	* Sets the make-send count for the port.
	206	*/
	207	routine mach_port_set_mscount(
	208	task : ipc_space_t;
	209	name : mach_port_name_t;
	210	mscount : mach_port_mscount_t);
	211
	212	/*
	213	* Only valid for port sets. Returns a list of
	214	* the members.
	215	*/
	216
	217	routine mach_port_get_set_status(
	218	task : ipc_space_t;
	219	name : mach_port_name_t;
	220	out members : mach_port_name_array_t);
	221
	222	/*
	223	* Puts the member port (the task must have receive rights)
	224	* into the after port set. (Or removes it from any port set
	225	* if after is MACH_PORT_NULL.) If the port is already in
	226	* a set, does an atomic move.
	227	*/
	228
	229	routine mach_port_move_member(
	230	task : ipc_space_t;
	231	member : mach_port_name_t;
	232	after : mach_port_name_t);
	233
	234	/*
	235	* Requests a notification from the kernel. The request
	236	* must supply the send-once right which is used for
	237	* the notification. If a send-once right was previously
	238	* registered, it is returned. The msg_id must be one of
	239	* MACH_NOTIFY_PORT_DESTROYED (receive rights)
	240	* MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
	241	* MACH_NOTIFY_NO_SENDERS (receive rights)
	242	*
	243	* The sync value specifies whether a notification should
	244	* get sent immediately, if appropriate. The exact meaning
	245	* depends on the notification:
	246	* MACH_NOTIFY_PORT_DESTROYED: must be zero.
	247	* MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,
	248	* and the notification gets sent immediately.
	249	* If zero, then name can't be dead.
	250	* MACH_NOTIFY_NO_SENDERS: the notification gets sent
	251	* immediately if the current mscount is greater
	252	* than or equal to the sync value and there are no
	253	* extant send rights.
	254	*/
	255
	256	routine mach_port_request_notification(
	257	task : ipc_space_t;
	258	name : mach_port_name_t;
	259	msgid : mach_msg_id_t;
	260	sync : mach_port_mscount_t;
	261	notify : mach_port_send_once_t;
0b4e3aa0	262	out previous : mach_port_move_send_once_t);
1c79356b A	263
	264	/*
	265	* Inserts the specified rights into the target task,
	266	* using the specified name. If inserting send/receive
	267	* rights and the task already has send/receive rights
	268	* for the port, then the names must agree. In any case,
	269	* the task gains a user ref for the port.
	270	*/
	271
	272	routine mach_port_insert_right(
	273	task : ipc_space_t;
	274	name : mach_port_name_t;
	275	poly : mach_port_poly_t);
	276
	277	/*
	278	* Returns the specified right for the named port
	279	* in the target task, extracting that right from
	280	* the target task. The target task loses a user
	281	* ref and the name may be available for recycling.
	282	* msgt_name must be one of
	283	* MACH_MSG_TYPE_MOVE_RECEIVE
	284	* MACH_MSG_TYPE_COPY_SEND
	285	* MACH_MSG_TYPE_MAKE_SEND
	286	* MACH_MSG_TYPE_MOVE_SEND
	287	* MACH_MSG_TYPE_MAKE_SEND_ONCE
	288	* MACH_MSG_TYPE_MOVE_SEND_ONCE
	289	*/
	290
	291	routine mach_port_extract_right(
	292	task : ipc_space_t;
	293	name : mach_port_name_t;
	294	msgt_name : mach_msg_type_name_t;
	295	out poly : mach_port_poly_t);
	296
	297	/*
	298	* Only valid for receive rights.
	299	* Sets the sequence number for the port.
	300	*/
	301
	302	routine mach_port_set_seqno(
	303	task : ipc_space_t;
	304	name : mach_port_name_t;
	305	seqno : mach_port_seqno_t);
	306
	307	/*
	308	* Returns information about a port.
	309	*/
	310
	311	routine mach_port_get_attributes(
	312	task : ipc_space_t;
	313	name : mach_port_name_t;
	314	flavor : mach_port_flavor_t;
	315	out port_info_out : mach_port_info_t, CountInOut);
	316
	317	/*
	318	* Set attributes of a port
	319	*/
	320
	321	routine mach_port_set_attributes(
	322	task : ipc_space_t;
	323	name : mach_port_name_t;
	324	flavor : mach_port_flavor_t;
	325	port_info : mach_port_info_t);
	326
327
328	/*
329	* Allocates the specified kind of object, qos version.
330	* The right must be
331	* MACH_PORT_RIGHT_RECEIVE
332	* Like port_allocate_name, but the kernel picks a name.
333	* It can use any name not associated with a right.
334	*/
335
336	routine mach_port_allocate_qos(
337	task : ipc_space_t;
338	right : mach_port_right_t;
339	inout qos : mach_port_qos_t;
340	out name : mach_port_name_t);
341
9bccf70c	342
1c79356b A	343	/*
	344	* Generic interface to allocation various kinds of ports.
	345	* Should never be called directly by users (at least not
	346	* unless they are exceedingly masochistic).
	347	*/
	348
	349	routine mach_port_allocate_full(
	350	task : ipc_space_t;
	351	right : mach_port_right_t;
9bccf70c	352	proto : mach_port_t;
1c79356b A	353	inout qos : mach_port_qos_t;
	354	inout name : mach_port_name_t);
	355
	356
	357	/*
	358	* Pre-expand task port name space.
	359	*/
	360	routine task_set_port_space(
	361	task : ipc_space_t;
	362	table_entries : int);
	363
	364
	365	/*
	366	* Returns the exact number of extant send rights
	367	* for the given receive right.
	368	* This call is only valid on MACH_IPC_DEBUG kernels.
	369	* Otherwise, KERN_FAILURE is returned.
	370	*/
	371	routine mach_port_get_srights(
	372	task : ipc_space_t;
	373	name : mach_port_name_t;
	374	out srights : mach_port_rights_t);
	375
	376
	377	/*
	378	* Returns information about an IPC space.
	379	* This call is only valid on MACH_IPC_DEBUG kernels.
	380	* Otherwise, KERN_FAILURE is returned.
	381	*/
	382	routine mach_port_space_info(
	383	task : ipc_space_t;
	384	out info : ipc_info_space_t;
	385	out table_info : ipc_info_name_array_t,
	386	Dealloc;
	387	out tree_info : ipc_info_tree_name_array_t,
	388	Dealloc);
	389
	390	/*
	391	* Returns information about the dead-name requests
	392	* registered with the named receive right.
	393	* This call is only valid on MACH_IPC_DEBUG kernels.
	394	* Otherwise, KERN_FAILURE is returned.
	395	*/
	396	routine mach_port_dnrequest_info(
	397	task : ipc_space_t;
	398	name : mach_port_name_t;
	399	out total : unsigned; /* total size of table */
	400	out used : unsigned); /* amount used */
	401
	402	/*
	403	* Return the type and address of the kernel object
	404	* that the given send/receive right represents.
	405	* This call is only valid on MACH_IPC_DEBUG kernels.
	406	* Otherwise, KERN_FAILURE is returned.
	407	*/
	408	routine mach_port_kernel_object(
	409	task : ipc_space_t;
	410	name : mach_port_name_t;
	411	out object_type : unsigned;
	412	out object_addr : vm_offset_t);
	413
	414
	415	/*
	416	* Inserts the specified rights into the portset identified
417	* by the <task, pset> pair. The results of passing in the
418	* Poly argument via the supplied disposition must yield a
419	* receive right.
420	*
421	* If the <task,pset> pair does not represent a valid portset
422	* KERN_INVALID_RIGHT is returned.
423	*
424	* If the passed in name argument does not represent a receive
425	* right, KERN_INVALID_CAPABILITY will be returned.
426	*
427	* If the port represented by the receive right is already in
428	* the portset, KERN_ALREADY_IN_SET is returned.
429	*/
430	routine mach_port_insert_member(
431	task : ipc_space_t;
432	name : mach_port_name_t;
433	pset : mach_port_name_t);
434
435	/*
436	* Extracts the specified right from the named portset
437	* in the target task.
438	* the target task. The target task loses a user
439	* ref and the name may be available for recycling.
440	* msgt_name must be one of
441	* MACH_MSG_TYPE_MOVE_RECEIVE
442	* MACH_MSG_TYPE_COPY_SEND
443	* MACH_MSG_TYPE_MAKE_SEND
444	* MACH_MSG_TYPE_MOVE_SEND
445	* MACH_MSG_TYPE_MAKE_SEND_ONCE
446	* MACH_MSG_TYPE_MOVE_SEND_ONCE
447	*/
448
449	routine mach_port_extract_member(
450	task : ipc_space_t;
451	name : mach_port_name_t;
452	pset : mach_port_name_t);
453