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

/*
 * Copyright (c) 2000-2004 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_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;

#if !KERNEL && !LIBSYSCALL_INTERFACE
	UserPrefix _kernelrpc_;
#endif

#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.
 *
 *	This interface is OBSOLETE and will always
 *	return KERN_NOT_SUPPORTED.
 */

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);

/*
 *	Peek at the message queue for the specified receive
 *	right and return info about the message with the
 *	sequence number matching the input.  If zero is
 *	specified as the seqno, the first message in the
 *	queue will be peeked.
 *
 *	Only the following trailer types are currently supported:
 *	     MACH_RCV_TRAILER_TYPE(MACH_MSG_TRAILER_FORMAT_0)
 *
 *		or'ed with one of these element types:
 *	     MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_NULL)
 *	     MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_SEQNO)
 *	     MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_SENDER)
 *	     MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_AUDIT)
 */
routine mach_port_peek(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		trailer_type	: mach_msg_trailer_type_t;
 inout		request_seqnop	: mach_port_seqno_t;
 out		msg_sizep	: mach_msg_size_t;
 out		msg_idp		: mach_msg_id_t;
 out		trailer_infop	: mach_msg_trailer_info_t, CountInOut);		

/*
 *	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_inspect_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.  If the port is already a member
 *	of any set(s), it is atomically removed from those sets as
 *	part of this operation.  (If after is MACH_PORT_NULL, the
 *	port is still removed from all current sets).
 */

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 msgid must be one of:
 *		MACH_NOTIFY_PORT_DESTROYED (receive rights)
 *		MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
 *		MACH_NOTIFY_SEND_POSSIBLE (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_SEND_POSSIBLE: if non-zero, will generate a	send-
 *			possible notification as soon as it is possible to send
 *			to the port. If zero, will generate a send-possible
 *			notification only after a subsequent failed send
 *			(with MACH_SEND_NOTIFY option to mach_msg call).  Can
 *			generate a dead-name notification if name is already dead
 *			or becomes dead before a send-possible notification fires.
 *		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.
 *
 * If the name is deleted before a successfully registered notification
 * is delivered, it is replaced with a port-deleted notification.
 */

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_inspect_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_inspect_t;
	out	space_info	: ipc_info_space_t;
	out	table_info	: ipc_info_name_array_t;
	out	tree_info	: ipc_info_tree_name_array_t);

/*
 *	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	dnr_total	: unsigned;	/* total size of table */
	out	dnr_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.
 *
 *	This interface is DEPRECATED in favor of the new
 *	mach_port_kernel_object64() call (see below).
 */
routine	mach_port_kernel_object(
		task		: ipc_space_inspect_t;
		name		: mach_port_name_t;
	out	object_type	: unsigned;
	out	object_addr	: unsigned);


/*
 *	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);

/*
 * Only valid for receive rights.
 * Gets the context pointer for the port.
 */

routine mach_port_get_context(
		task		: ipc_space_inspect_t;
		name		: mach_port_name_t;
#ifdef LIBSYSCALL_INTERFACE
	out context		: mach_port_context_t
#else
	out context		: mach_vm_address_t
#endif
	);

/*
 * Only valid for receive rights.
 * Sets the context pointer for the port.
 */

routine mach_port_set_context(
		task		: ipc_space_t;
		name		: mach_port_name_t;
#ifdef LIBSYSCALL_INTERFACE
		context		: mach_port_context_t
#else
		context		: mach_vm_address_t
#endif
		);

/*
 *	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_kobject(
		task		: ipc_space_inspect_t;
		name		: mach_port_name_t;
	out	object_type	: natural_t;
	out	object_addr	: mach_vm_address_t);


/*
 *	Constructs a right based on the options passed
 *	in. Also allows guarding the port as one of the
 *	options if the requested right is a receive
 *	right.
 */
routine mach_port_construct(
		task		: ipc_space_t;
		options		: mach_port_options_ptr_t;
#ifdef LIBSYSCALL_INTERFACE
		context		: mach_port_context_t;
#else
		context		: uint64_t;
#endif
	out	name		: mach_port_name_t);

/*
 *	Destroys a mach port using the guard provided
 *	for guarded ports. Also reduces the user ref
 *	count for send rights as specified by srdelta.
 */
routine mach_port_destruct(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		srdelta		: mach_port_delta_t;
#ifdef LIBSYSCALL_INTERFACE
		guard		: mach_port_context_t
#else
		guard		: uint64_t
#endif		
		);

/*
 *	Guard an already existing port. Allows guarding
 *	receive rights only. Uses the context field in the
 *	port structure to store the guard.
 */
routine mach_port_guard(
		task		: ipc_space_t;
		name		: mach_port_name_t;
#ifdef LIBSYSCALL_INTERFACE
		guard		: mach_port_context_t;
#else
		guard		: uint64_t;
#endif	
		strict		: boolean_t);

/*
 *	Unguard a port guarded previously. For unguarded ports
 *	or incorrect guards passed in it raises an exception
 *	indicating guarding misbehavior.
 */
routine mach_port_unguard(
		task		: ipc_space_t;
		name		: mach_port_name_t;
#ifdef LIBSYSCALL_INTERFACE
		guard		: mach_port_context_t
#else
		guard		: uint64_t
#endif	
		);

/*
 *	Returns basic information about an IPC space.
 *      This call is only valid on MACH_IPC_DEBUG kernels.
 *      Otherwise, KERN_FAILURE is returned.
 */
routine mach_port_space_basic_info(
		task		: ipc_space_inspect_t;
	out	basic_info	: ipc_info_space_basic_t);

#if KERNEL || !LIBSYSCALL_INTERFACE
/*
 *	Returns sync ipc turnstile link status
 *	for special reply ports.
 */
routine mach_port_special_reply_port_reset_link(
		task            : ipc_space_t;
		name            : mach_port_name_t;
	out	srp_lost_link	: boolean_t);
#else
skip;
#endif
/* vim: set ft=c : */
Commit	Line	Data
1c79356b	1	/*
91447636	2	* Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b	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.
8f6c56a5	14	*
2d21ac55 A	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
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.
8f6c56a5	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	27	*/
	28	/*
	29	* @OSF_FREE_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: mach/mach_port.defs
	60	* Author: Rich Draves
	61	*
	62	* Exported kernel calls.
	63	*/
	64
	65	subsystem
	66	#if KERNEL_SERVER
	67	KernelServer
55e303ae	68	#endif /* KERNEL_SERVER */
1c79356b A	69	mach_port 3200;
1c79356b A	70
316670eb A	71	#if !KERNEL && !LIBSYSCALL_INTERFACE
	72	UserPrefix _kernelrpc_;
	73	#endif
	74
1c79356b A	75	#include <mach/std_types.defs>
	76	#include <mach/mach_types.defs>
	77	#include <mach_debug/mach_debug_types.defs>
	78
	79	/*
	80	* Returns the set of port and port set names
	81	* to which the target task has access, along with
	82	* the type (set or port) for each name.
	83	*/
	84
	85	routine mach_port_names(
	86	task : ipc_space_t;
	87	out names : mach_port_name_array_t;
	88	out types : mach_port_type_array_t);
	89
	90	/*
	91	* Returns the type (set or port) for the port name
	92	* within the target task. Also indicates whether
	93	* there is a dead-name request for the name.
	94	*/
	95
	96	routine mach_port_type(
	97	task : ipc_space_t;
	98	name : mach_port_name_t;
	99	out ptype : mach_port_type_t);
	100
	101	/*
	102	* Changes the name by which a port (or port set) is known to
	103	* the target task. The new name can't be in use. The
	104	* old name becomes available for recycling.
316670eb A	105	*
	106	* This interface is OBSOLETE and will always
	107	* return KERN_NOT_SUPPORTED.
1c79356b A	108	*/
	109
	110	routine mach_port_rename(
	111	task : ipc_space_t;
	112	old_name : mach_port_name_t;
	113	new_name : mach_port_name_t);
	114
	115	/*
	116	* Allocates the specified kind of object, with the given name.
	117	* The right must be one of
	118	* MACH_PORT_RIGHT_RECEIVE
	119	* MACH_PORT_RIGHT_PORT_SET
	120	* MACH_PORT_RIGHT_DEAD_NAME
	121	* New port sets are empty. New ports don't have any
	122	* send/send-once rights or queued messages. The make-send
	123	* count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.
	124	* New sets, ports, and dead names have one user reference.
	125	*/
	126
	127	routine mach_port_allocate_name(
	128	task : ipc_space_t;
	129	right : mach_port_right_t;
	130	name : mach_port_name_t);
	131
	132	/*
	133	* Allocates the specified kind of object.
	134	* The right must be one of
	135	* MACH_PORT_RIGHT_RECEIVE
	136	* MACH_PORT_RIGHT_PORT_SET
	137	* MACH_PORT_RIGHT_DEAD_NAME
	138	* Like port_allocate_name, but the kernel picks a name.
	139	* It can use any name not associated with a right.
	140	*/
	141
	142	routine mach_port_allocate(
	143	task : ipc_space_t;
	144	right : mach_port_right_t;
	145	out name : mach_port_name_t);
	146
	147	/*
	148	* Destroys all rights associated with the name and makes it
	149	* available for recycling immediately. The name can be a
	150	* port (possibly with multiple user refs), a port set, or
	151	* a dead name (again, with multiple user refs).
	152	*/
	153
	154	routine mach_port_destroy(
	155	task : ipc_space_t;
	156	name : mach_port_name_t);
	157
	158	/*
	159	* Releases one send/send-once/dead-name user ref.
	160	* Just like mach_port_mod_refs -1, but deduces the
	161	* correct type of right. This allows a user task
	162	* to release a ref for a port without worrying
	163	* about whether the port has died or not.
	164	*/
	165
	166	routine mach_port_deallocate(
	167	task : ipc_space_t;
	168	name : mach_port_name_t);
	169
	170	/*
	171	* A port set always has one user ref.
172	* A send-once right always has one user ref.
173	* A dead name always has one or more user refs.
174	* A send right always has one or more user refs.
175	* A receive right always has one user ref.
176	* The right must be one of
177	* MACH_PORT_RIGHT_RECEIVE
178	* MACH_PORT_RIGHT_PORT_SET
179	* MACH_PORT_RIGHT_DEAD_NAME
180	* MACH_PORT_RIGHT_SEND
181	* MACH_PORT_RIGHT_SEND_ONCE
182	*/
183
184	routine mach_port_get_refs(
185	task : ipc_space_t;
186	name : mach_port_name_t;
187	right : mach_port_right_t;
188	out refs : mach_port_urefs_t);
189
190	/*
191	* The delta is a signed change to the task's
192	* user ref count for the right. Only dead names
193	* and send rights can have a positive delta.
194	* The resulting user ref count can't be negative.
195	* If it is zero, the right is deallocated.
196	* If the name isn't a composite right, it becomes
197	* available for recycling. The right must be one of
198	* MACH_PORT_RIGHT_RECEIVE
199	* MACH_PORT_RIGHT_PORT_SET
200	* MACH_PORT_RIGHT_DEAD_NAME
201	* MACH_PORT_RIGHT_SEND
202	* MACH_PORT_RIGHT_SEND_ONCE
203	*/
204
205	routine mach_port_mod_refs(
206	task : ipc_space_t;
207	name : mach_port_name_t;
208	right : mach_port_right_t;
209	delta : mach_port_delta_t);
210
39236c6e A	211	/*
	212	* Peek at the message queue for the specified receive
	213	* right and return info about the message with the
	214	* sequence number matching the input. If zero is
	215	* specified as the seqno, the first message in the
	216	* queue will be peeked.
	217	*
	218	* Only the following trailer types are currently supported:
	219	* MACH_RCV_TRAILER_TYPE(MACH_MSG_TRAILER_FORMAT_0)
	220	*
	221	* or'ed with one of these element types:
	222	* MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_NULL)
	223	* MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_SEQNO)
	224	* MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_SENDER)
	225	* MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_AUDIT)
	226	*/
	227	routine mach_port_peek(
	228	task : ipc_space_t;
	229	name : mach_port_name_t;
	230	trailer_type : mach_msg_trailer_type_t;
	231	inout request_seqnop : mach_port_seqno_t;
	232	out msg_sizep : mach_msg_size_t;
	233	out msg_idp : mach_msg_id_t;
	234	out trailer_infop : mach_msg_trailer_info_t, CountInOut);
1c79356b A	235
	236	/*
	237	* Only valid for receive rights.
	238	* Sets the make-send count for the port.
	239	*/
	240	routine mach_port_set_mscount(
	241	task : ipc_space_t;
	242	name : mach_port_name_t;
	243	mscount : mach_port_mscount_t);
	244
	245	/*
	246	* Only valid for port sets. Returns a list of
	247	* the members.
	248	*/
	249
	250	routine mach_port_get_set_status(
813fb2f6	251	task : ipc_space_inspect_t;
1c79356b A	252	name : mach_port_name_t;
	253	out members : mach_port_name_array_t);
	254
	255	/*
	256	* Puts the member port (the task must have receive rights)
2d21ac55 A	257	* into the after port set. If the port is already a member
	258	* of any set(s), it is atomically removed from those sets as
	259	* part of this operation. (If after is MACH_PORT_NULL, the
	260	* port is still removed from all current sets).
1c79356b A	261	*/
	262
	263	routine mach_port_move_member(
	264	task : ipc_space_t;
	265	member : mach_port_name_t;
	266	after : mach_port_name_t);
	267
	268	/*
	269	* Requests a notification from the kernel. The request
	270	* must supply the send-once right which is used for
	271	* the notification. If a send-once right was previously
6d2010ae	272	* registered, it is returned. The msgid must be one of:
1c79356b A	273	* MACH_NOTIFY_PORT_DESTROYED (receive rights)
1c79356b A	274	* MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
6d2010ae	275	* MACH_NOTIFY_SEND_POSSIBLE (send/receive/send-once rights)
1c79356b A	276	* MACH_NOTIFY_NO_SENDERS (receive rights)
	277	*
	278	* The sync value specifies whether a notification should
	279	* get sent immediately, if appropriate. The exact meaning
	280	* depends on the notification:
	281	* MACH_NOTIFY_PORT_DESTROYED: must be zero.
	282	* MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,
	283	* and the notification gets sent immediately.
	284	* If zero, then name can't be dead.
6d2010ae A	285	* MACH_NOTIFY_SEND_POSSIBLE: if non-zero, will generate a send-
	286	* possible notification as soon as it is possible to send
	287	* to the port. If zero, will generate a send-possible
	288	* notification only after a subsequent failed send
	289	* (with MACH_SEND_NOTIFY option to mach_msg call). Can
	290	* generate a dead-name notification if name is already dead
	291	* or becomes dead before a send-possible notification fires.
1c79356b A	292	* MACH_NOTIFY_NO_SENDERS: the notification gets sent
	293	* immediately if the current mscount is greater
	294	* than or equal to the sync value and there are no
	295	* extant send rights.
6d2010ae A	296	*
	297	* If the name is deleted before a successfully registered notification
	298	* is delivered, it is replaced with a port-deleted notification.
1c79356b A	299	*/
	300
	301	routine mach_port_request_notification(
	302	task : ipc_space_t;
	303	name : mach_port_name_t;
	304	msgid : mach_msg_id_t;
	305	sync : mach_port_mscount_t;
	306	notify : mach_port_send_once_t;
0b4e3aa0	307	out previous : mach_port_move_send_once_t);
1c79356b A	308
	309	/*
	310	* Inserts the specified rights into the target task,
	311	* using the specified name. If inserting send/receive
	312	* rights and the task already has send/receive rights
	313	* for the port, then the names must agree. In any case,
	314	* the task gains a user ref for the port.
	315	*/
	316
	317	routine mach_port_insert_right(
	318	task : ipc_space_t;
	319	name : mach_port_name_t;
	320	poly : mach_port_poly_t);
	321
	322	/*
	323	* Returns the specified right for the named port
	324	* in the target task, extracting that right from
	325	* the target task. The target task loses a user
	326	* ref and the name may be available for recycling.
	327	* msgt_name must be one of
	328	* MACH_MSG_TYPE_MOVE_RECEIVE
	329	* MACH_MSG_TYPE_COPY_SEND
	330	* MACH_MSG_TYPE_MAKE_SEND
	331	* MACH_MSG_TYPE_MOVE_SEND
	332	* MACH_MSG_TYPE_MAKE_SEND_ONCE
	333	* MACH_MSG_TYPE_MOVE_SEND_ONCE
	334	*/
	335
	336	routine mach_port_extract_right(
	337	task : ipc_space_t;
	338	name : mach_port_name_t;
	339	msgt_name : mach_msg_type_name_t;
	340	out poly : mach_port_poly_t);
	341
	342	/*
	343	* Only valid for receive rights.
	344	* Sets the sequence number for the port.
	345	*/
	346
	347	routine mach_port_set_seqno(
	348	task : ipc_space_t;
	349	name : mach_port_name_t;
	350	seqno : mach_port_seqno_t);
	351
	352	/*
	353	* Returns information about a port.
	354	*/
	355
	356	routine mach_port_get_attributes(
813fb2f6	357	task : ipc_space_inspect_t;
1c79356b A	358	name : mach_port_name_t;
	359	flavor : mach_port_flavor_t;
	360	out port_info_out : mach_port_info_t, CountInOut);
	361
	362	/*
	363	* Set attributes of a port
	364	*/
	365
	366	routine mach_port_set_attributes(
	367	task : ipc_space_t;
	368	name : mach_port_name_t;
	369	flavor : mach_port_flavor_t;
	370	port_info : mach_port_info_t);
	371
	372
	373	/*
	374	* Allocates the specified kind of object, qos version.
	375	* The right must be
	376	* MACH_PORT_RIGHT_RECEIVE
	377	* Like port_allocate_name, but the kernel picks a name.
	378	* It can use any name not associated with a right.
	379	*/
	380
	381	routine mach_port_allocate_qos(
	382	task : ipc_space_t;
	383	right : mach_port_right_t;
	384	inout qos : mach_port_qos_t;
	385	out name : mach_port_name_t);
	386
9bccf70c	387
1c79356b A	388	/*
	389	* Generic interface to allocation various kinds of ports.
	390	* Should never be called directly by users (at least not
	391	* unless they are exceedingly masochistic).
	392	*/
	393
	394	routine mach_port_allocate_full(
	395	task : ipc_space_t;
	396	right : mach_port_right_t;
9bccf70c	397	proto : mach_port_t;
1c79356b A	398	inout qos : mach_port_qos_t;
	399	inout name : mach_port_name_t);
	400
	401
	402	/*
	403	* Pre-expand task port name space.
	404	*/
	405	routine task_set_port_space(
	406	task : ipc_space_t;
	407	table_entries : int);
	408
	409
	410	/*
	411	* Returns the exact number of extant send rights
	412	* for the given receive right.
	413	* This call is only valid on MACH_IPC_DEBUG kernels.
	414	* Otherwise, KERN_FAILURE is returned.
	415	*/
	416	routine mach_port_get_srights(
	417	task : ipc_space_t;
	418	name : mach_port_name_t;
	419	out srights : mach_port_rights_t);
	420
	421
	422	/*
	423	* Returns information about an IPC space.
	424	* This call is only valid on MACH_IPC_DEBUG kernels.
	425	* Otherwise, KERN_FAILURE is returned.
	426	*/
	427	routine mach_port_space_info(
813fb2f6	428	task : ipc_space_inspect_t;
91447636	429	out space_info : ipc_info_space_t;
2d21ac55 A	430	out table_info : ipc_info_name_array_t;
2d21ac55 A	431	out tree_info : ipc_info_tree_name_array_t);
1c79356b A	432
	433	/*
	434	* Returns information about the dead-name requests
	435	* registered with the named receive right.
	436	* This call is only valid on MACH_IPC_DEBUG kernels.
	437	* Otherwise, KERN_FAILURE is returned.
	438	*/
	439	routine mach_port_dnrequest_info(
	440	task : ipc_space_t;
	441	name : mach_port_name_t;
91447636 A	442	out dnr_total : unsigned; /* total size of table */
91447636 A	443	out dnr_used : unsigned); /* amount used */
1c79356b A	444
	445	/*
	446	* Return the type and address of the kernel object
	447	* that the given send/receive right represents.
	448	* This call is only valid on MACH_IPC_DEBUG kernels.
	449	* Otherwise, KERN_FAILURE is returned.
b0d623f7 A	450	*
	451	* This interface is DEPRECATED in favor of the new
	452	* mach_port_kernel_object64() call (see below).
1c79356b A	453	*/
1c79356b A	454	routine mach_port_kernel_object(
813fb2f6	455	task : ipc_space_inspect_t;
1c79356b A	456	name : mach_port_name_t;
1c79356b A	457	out object_type : unsigned;
b0d623f7	458	out object_addr : unsigned);
1c79356b A	459
	460
	461	/*
	462	* Inserts the specified rights into the portset identified
	463	* by the <task, pset> pair. The results of passing in the
	464	* Poly argument via the supplied disposition must yield a
	465	* receive right.
	466	*
	467	* If the <task,pset> pair does not represent a valid portset
	468	* KERN_INVALID_RIGHT is returned.
	469	*
	470	* If the passed in name argument does not represent a receive
	471	* right, KERN_INVALID_CAPABILITY will be returned.
	472	*
	473	* If the port represented by the receive right is already in
	474	* the portset, KERN_ALREADY_IN_SET is returned.
	475	*/
	476	routine mach_port_insert_member(
	477	task : ipc_space_t;
	478	name : mach_port_name_t;
	479	pset : mach_port_name_t);
	480
	481	/*
	482	* Extracts the specified right from the named portset
	483	* in the target task.
	484	* the target task. The target task loses a user
	485	* ref and the name may be available for recycling.
	486	* msgt_name must be one of
	487	* MACH_MSG_TYPE_MOVE_RECEIVE
	488	* MACH_MSG_TYPE_COPY_SEND
	489	* MACH_MSG_TYPE_MAKE_SEND
	490	* MACH_MSG_TYPE_MOVE_SEND
	491	* MACH_MSG_TYPE_MAKE_SEND_ONCE
	492	* MACH_MSG_TYPE_MOVE_SEND_ONCE
	493	*/
	494
	495	routine mach_port_extract_member(
	496	task : ipc_space_t;
	497	name : mach_port_name_t;
	498	pset : mach_port_name_t);
	499
b0d623f7 A	500	/*
	501	* Only valid for receive rights.
	502	* Gets the context pointer for the port.
	503	*/
	504
	505	routine mach_port_get_context(
813fb2f6	506	task : ipc_space_inspect_t;
b0d623f7	507	name : mach_port_name_t;
316670eb A	508	#ifdef LIBSYSCALL_INTERFACE
	509	out context : mach_port_context_t
	510	#else
	511	out context : mach_vm_address_t
	512	#endif
	513	);
b0d623f7 A	514
	515	/*
	516	* Only valid for receive rights.
	517	* Sets the context pointer for the port.
	518	*/
	519
	520	routine mach_port_set_context(
	521	task : ipc_space_t;
	522	name : mach_port_name_t;
316670eb A	523	#ifdef LIBSYSCALL_INTERFACE
	524	context : mach_port_context_t
	525	#else
	526	context : mach_vm_address_t
	527	#endif
	528	);
b0d623f7 A	529
	530	/*
	531	* Return the type and address of the kernel object
	532	* that the given send/receive right represents.
	533	* This call is only valid on MACH_IPC_DEBUG kernels.
	534	* Otherwise, KERN_FAILURE is returned.
	535	*/
	536	routine mach_port_kobject(
813fb2f6	537	task : ipc_space_inspect_t;
b0d623f7 A	538	name : mach_port_name_t;
	539	out object_type : natural_t;
	540	out object_addr : mach_vm_address_t);
	541
	542
39236c6e A	543	/*
	544	* Constructs a right based on the options passed
	545	* in. Also allows guarding the port as one of the
	546	* options if the requested right is a receive
	547	* right.
	548	*/
	549	routine mach_port_construct(
	550	task : ipc_space_t;
	551	options : mach_port_options_ptr_t;
	552	#ifdef LIBSYSCALL_INTERFACE
	553	context : mach_port_context_t;
	554	#else
	555	context : uint64_t;
	556	#endif
	557	out name : mach_port_name_t);
	558
	559	/*
	560	* Destroys a mach port using the guard provided
	561	* for guarded ports. Also reduces the user ref
	562	* count for send rights as specified by srdelta.
	563	*/
	564	routine mach_port_destruct(
	565	task : ipc_space_t;
	566	name : mach_port_name_t;
	567	srdelta : mach_port_delta_t;
	568	#ifdef LIBSYSCALL_INTERFACE
	569	guard : mach_port_context_t
	570	#else
	571	guard : uint64_t
	572	#endif
	573	);
	574
	575	/*
	576	* Guard an already existing port. Allows guarding
	577	* receive rights only. Uses the context field in the
	578	* port structure to store the guard.
	579	*/
	580	routine mach_port_guard(
	581	task : ipc_space_t;
	582	name : mach_port_name_t;
	583	#ifdef LIBSYSCALL_INTERFACE
	584	guard : mach_port_context_t;
	585	#else
	586	guard : uint64_t;
	587	#endif
	588	strict : boolean_t);
	589
	590	/*
	591	* Unguard a port guarded previously. For unguarded ports
	592	* or incorrect guards passed in it raises an exception
	593	* indicating guarding misbehavior.
	594	*/
	595	routine mach_port_unguard(
	596	task : ipc_space_t;
	597	name : mach_port_name_t;
	598	#ifdef LIBSYSCALL_INTERFACE
	599	guard : mach_port_context_t
	600	#else
	601	guard : uint64_t
	602	#endif
	603	);
	604
fe8ab488 A	605	/*
	606	* Returns basic information about an IPC space.
	607	* This call is only valid on MACH_IPC_DEBUG kernels.
	608	* Otherwise, KERN_FAILURE is returned.
	609	*/
	610	routine mach_port_space_basic_info(
813fb2f6	611	task : ipc_space_inspect_t;
fe8ab488 A	612	out basic_info : ipc_info_space_basic_t);
fe8ab488 A	613
d9a64523 A	614	#if KERNEL \|\| !LIBSYSCALL_INTERFACE
	615	/*
	616	* Returns sync ipc turnstile link status
	617	* for special reply ports.
	618	*/
	619	routine mach_port_special_reply_port_reset_link(
	620	task : ipc_space_t;
	621	name : mach_port_name_t;
	622	out srp_lost_link : boolean_t);
	623	#else
	624	skip;
	625	#endif
2d21ac55	626	/* vim: set ft=c : */