MIG routines

routine doubleagent_lookup_xattr(in server: mach_port_t, in file_port: mach_port_move_send_t, in file_size: int64_t, in name: xattrname, out err: int, out value_offset: uint64_t, out value_length: uint64_t)

routine doubleagent_allocate_xattr

routine doubleagent_allocate_xattr(in server: mach_port_t, in file_port: mach_port_move_send_t, in file_size: int64_t, in name: xattrname, in size: uint64_t, in options: uint32_t, out err: int, out value_offset: uint64_t)

routine doubleagent_list_xattrs

routine doubleagent_list_xattrs(in server: mach_port_t, in file_port: mach_port_move_send_t, in file_size: int64_t, out err: int, out result: listxattrs_result_t)

routine doubleagent_remove_xattr

routine doubleagent_remove_xattr(in server: mach_port_t, in file_port: mach_port_move_send_t, in file_size: int64_t, in name: xattrname, out err: int, out is_empty: boolean_t)

exc (mach/exc.defs, 3 routines)

routine exception_raise

#include <mach/exc.h>

routine exception_raise(in exception_port: mach_port_t, in thread: mach_port_t, in task: mach_port_t, in exception: exception_type_t, in code: exception_data_t)

GNU Mach reference · 7.1.8 Exceptions · © FSF, GFDL

kern_return_t exception_raise(mach_port_t exception_port, mach_port_t thread, mach_port_t task, integer_t exception, integer_t code, integer_t subcode)

XXX Fixme

routine exception_raise_state

#include <mach/exc.h>

routine exception_raise_state(in exception_port: mach_port_t, in exception: exception_type_t, in code: exception_data_t, inout flavor: int, in old_state: thread_state_t, out new_state: thread_state_t)

routine exception_raise_state_identity

#include <mach/exc.h>

routine exception_raise_state_identity(in exception_port: mach_port_t, in thread: mach_port_t, in task: mach_port_t, in exception: exception_type_t, in code: exception_data_t, inout flavor: int, in old_state: thread_state_t, out new_state: thread_state_t)

host_notify_reply (mach/host_notify_reply.defs, 2 routines)

simpleroutine host_calendar_changed

no C stub in SDK (server-side / callback)

simpleroutine host_calendar_changed(in notify_port: mach_port_move_send_once_t)

simpleroutine host_calendar_set

no C stub in SDK (server-side / callback)

simpleroutine host_calendar_set(in notify_port: mach_port_move_send_once_t)

host_priv (mach/host_priv.defs, 23 routines)

routine host_get_boot_info

Get boot configuration information from kernel.

routine host_get_boot_info(in host_priv: host_priv_t, out boot_info: kernel_boot_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return operator boot information.

The host_get_boot_info function returns the boot-time information string supplied by the operator when priv_host was initialized. The constant KERNEL_BOOT_INFO_MAX (in \*L \*O) should be used to dimension storage for the returned string.

routine host_reboot

Reboot this host. Only available to privileged users.

routine host_reboot(in host_priv: host_priv_t, in options: int)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Reboot this host.

The host_reboot function reboots the specified host.

Notes. If successful, this call will not return.

routine host_priv_statistics

Return privileged statistics from this host.

routine host_priv_statistics(in host_priv: host_priv_t, in flavor: host_flavor_t, out host_info_out: host_info_t)

routine host_default_memory_manager

Sets the default memory manager, the port to which newly-created temporary memory objects are delivered. [See (memory_object_default)memory_object_create.] Also sets the default cluster size used for pagein/pageout to this port. The old memory manager port is returned.

routine host_default_memory_manager(in host_priv: host_priv_t, inout default_manager: memory_object_default_t = MACH_MSG_TYPE_MAKE_SEND, in cluster_size: memory_object_cluster_size_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Establish the official connection between the kernel and its default pager task.

The host_default_memory_manager function establishes the default memory manager for a host. The named manager will be the target for future memory_object_create calls.

routine vm_wire

Specify that the range of the virtual address space of the target task must not cause page faults for the indicated accesses. [ To unwire the pages, specify VM_PROT_NONE. ]

routine vm_wire(in host_priv: host_priv_t, in task: vm_map_t, in address: vm_address_t, in size: vm_size_t, in desired_access: vm_prot_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Modify the target region's paging characteristics.

The vm_wire function sets the pageability privileges for a region within the specified task's address space. wired_access specifies the types of accesses to the memory region which must not suffer from (internal) faults of any kind after this call returns. A non-null wired_access value indicates that the page is to be "wired" into memory; a null value indicates "un-wiring". The kernel maintains for the region a count of the number of times the region is wired. A page is wired into physical memory if any task accessing it has a non-zero wired count for the page. The region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than size. Use host_page_size to find the current virtual page size.

Notes. This interface is machine word length specific because of the virtual address parameter.

The address is illegal or specifies a non-allocated region.

routine thread_wire

Specify that the target thread must always be able to run and to allocate memory.

routine thread_wire(in host_priv: host_priv_t, in thread: thread_act_t, in wired: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Mark the thread as privileged with respect to kernel resources.

The thread_wire function marks the thread as "wired". A "wired" thread is always eligible to be scheduled and can consume physical memory even when free memory is scarce. This property should be assigned to threads in the default page-out path. Threads not in the default page-out path should not have this property to prevent the kernel's free list of pages from being exhausted.

KERN_INVALID_ARGUMENT

thread is not a thread port..P host_priv is not the control port for the host on which thread executes.

GNU Mach reference · 7.1.4 Thread Settings · © FSF, GFDL

kern_return_t thread_wire(host_priv_t host_priv, thread_t thread, boolean_t wired)

The function thread_wire controls the VM privilege level of the thread thread. A VM-privileged thread never waits inside the kernel for memory allocation from the kernel's free list of pages or for allocation of a kernel stack. Threads that are part of the default pageout path should be VM-privileged, to prevent system deadlocks. Threads that are not part of the default pageout path should not be VM-privileged, to prevent the kernel's free list of pages from being exhausted. The functions returns KERN_SUCCESS if the call succeeded, KERN_INVALID_ARGUMENT if host_priv or thread was invalid. The thread_wire call is actually an RPC to host_priv, normally a send right for a privileged host port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

routine vm_allocate_cpm

Obsolete

routine vm_allocate_cpm(in host_priv: host_priv_t, in task: vm_map_t, inout address: vm_address_t, in size: vm_size_t, in flags: int)

routine host_processors

Get list of processors on this host.

routine host_processors(in host_priv: host_priv_t, out out_processor_list: processor_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return a list of send rights representing all processor ports.

The host_processors function returns an array of send right ports for each processor existing on host_priv.

routine host_get_clock_control

Obsolete interfaces, removed from kernel

routine host_get_clock_control(in host_priv: host_priv_t, in clock_id: clock_id_t, out clock_ctrl: clock_ctrl_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return a send right to a kernel clock's control port.

The host_get_clock_control function returns a send right to the control port for a kernel clock object. This right is used to set the clock's resolution and time.

routine kmod_create

routine kmod_create(in host_priv: host_priv_t, in info: vm_address_t, out module: kmod_t)

routine kmod_destroy

routine kmod_destroy(in host_priv: host_priv_t, in module: kmod_t)

routine kmod_control

routine kmod_control(in host_priv: host_priv_t, in module: kmod_t, in flavor: kmod_control_flavor_t, inout data: kmod_args_t)

routine host_get_special_port

Get a given special port for a given node. Special ports are defined in host_special_ports.h; examples include the master device port. There are a limited number of slots available for system servers.

routine host_get_special_port(in host_priv: host_priv_t, in node: int, in which: int, out port: mach_port_t)

routine host_set_special_port

Set a given special port for the local node. See host_get_special_port.

routine host_set_special_port(in host_priv: host_priv_t, in which: int, in port: mach_port_t)

routine host_set_exception_ports

Set an exception handler for a host on one or more exception types. These handlers are invoked for all threads on the host if there are no task or thread-specific exception handlers or those handlers returned an error.

routine host_set_exception_ports(in host_priv: host_priv_t, in exception_mask: exception_mask_t, in new_port: mach_port_t, in behavior: exception_behavior_t, in new_flavor: thread_state_flavor_t)

routine host_get_exception_ports

Lookup some of the old exception handlers for a host

routine host_get_exception_ports(in host_priv: host_priv_t, in exception_mask: exception_mask_t, out masks: exception_mask_array_t, out old_handlers: exception_handler_array_t, out old_behaviors: exception_behavior_array_t, out old_flavors: exception_flavor_array_t)

routine host_swap_exception_ports

Set an exception handler for a host on one or more exception types. At the same time, return the previously defined exception handlers for those types.

routine host_swap_exception_ports(in host_priv: host_priv_t, in exception_mask: exception_mask_t, in new_port: mach_port_t, in behavior: exception_behavior_t, in new_flavor: thread_state_flavor_t, out masks: exception_mask_array_t, out old_handlerss: exception_handler_array_t, out old_behaviors: exception_behavior_array_t, out old_flavors: exception_flavor_array_t)

routine mach_vm_wire

old host_load_symbol_table Specify that the range of the virtual address space of the target task must not cause page faults for the indicated accesses. [ To unwire the pages, specify VM_PROT_NONE. ]

routine mach_vm_wire(in host_priv: host_priv_t, in task: vm_map_t, in address: mach_vm_address_t, in size: mach_vm_size_t, in desired_access: vm_prot_t)

routine host_processor_sets

JMM - Keep all processor_set related items at the end for easy removal. List all processor sets on host.

routine host_processor_sets(in host_priv: host_priv_t, out processor_sets: processor_set_name_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return a list of send rights representing all processor set name ports.

The host_processor_sets function returns send rights for the name ports for each processor set currently existing on host.

Notes. If control ports to the processor sets are needed, use host_processor_set_priv.

routine host_processor_set_priv

Get control port for a processor set.

routine host_processor_set_priv(in host_priv: host_priv_t, in set_name: processor_set_name_t, out set: processor_set_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Translate a processor set name port into a processor set control port.

The host_processor_set_priv function returns send rights for the control port for a specified processor set currently existing on host_priv.

routine host_set_UNDServer

old get_dp_control_port Set the UserNotification daemon access port for this host. If this value is already set, the kernel will discard its reference to the previously registered port.

routine host_set_UNDServer(in host: host_priv_t, in server: UNDServerRef)

routine host_get_UNDServer

Get the UserNotification daemon access port for this host. This can then be used to communicate with that daemon, which in turn communicates with the User through whatever means available (pop-up-menus for GUI systems, text for non-GUI, etc..). Access to this port is restricted to privileged clients because it is a special purpose port intended for kernel clients. User level clients should go directly to the CFUserNotifcation services.

routine host_get_UNDServer(in host: host_priv_t, out server: UNDServerRef)

routine kext_request

#include <mach/host_security.h>

Perform an operation with a kernel extension, on the kext loading system, or request information about loaded kexts or the state of the kext loading system. Active operations (load, unload, disable/enable) require host_priv/root access. Info retrieval does not. WARNING: THIS ROUTINE IS PRIVATE TO THE KEXT-MANAGEMENT STACK AND IS SUBJECT TO CHANGE AT ANY TIME.

routine kext_request(in host_priv: host_priv_t, in user_log_flags: uint32_t, in request_data: pointer_t, out response_data: pointer_t, out log_data: pointer_t, out op_result: kern_return_t)

host_security (mach/host_security.defs, 2 routines)

routine host_security_create_task_token

Basic types Obsolete interfaces, removed from kernel.

routine host_security_create_task_token(in host_security: host_security_t, in parent_task: task_t, in sec_token: security_token_t, in audit_token: audit_token_t, in host: host_t, in ledgers: ledger_array_t, in inherit_memory: boolean_t, out child_task: task_t)

routine host_security_set_task_token

#include <mach/host_security.h>

routine host_security_set_task_token(in host_security: host_security_t, in target_task: task_t, in sec_token: security_token_t, in audit_token: audit_token_t, in host: host_t)

mach_exc (mach/mach_exc.defs, 3 routines)

routine mach_exception_raise

no C stub in SDK (server-side / callback)

routine mach_exception_raise(in exception_port: mach_port_t, in thread: mach_port_t, in task: mach_port_t, in exception: exception_type_t, in code: mach_exception_data_t)

routine mach_exception_raise_state

no C stub in SDK (server-side / callback)

routine mach_exception_raise_state(in exception_port: mach_port_t, in exception: exception_type_t, in code: mach_exception_data_t, inout flavor: int, in old_state: thread_state_t, out new_state: thread_state_t)

routine mach_exception_raise_state_identity

no C stub in SDK (server-side / callback)

routine mach_exception_raise_state_identity(in exception_port: mach_port_t, in thread: mach_port_t, in task: mach_port_t, in exception: exception_type_t, in code: mach_exception_data_t, inout flavor: int, in old_state: thread_state_t, out new_state: thread_state_t)

mach_host (mach/mach_host.defs, 25 routines)

routine host_info

Basic types References to host objects are returned by: mach_host_self() - trap Return information about this host.

routine host_info(in host: host_t, in flavor: host_flavor_t, out host_info_out: host_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return information about a host.

The host_info function returns selected information about a host, as specified by flavor.

Notes. This interface is machine word length specific because of the memory size returned by HOST_BASIC_INFO.

routine host_kernel_version

Get string describing current kernel version.

routine host_kernel_version(in host: host_t, out kernel_version: kernel_version_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return kernel version information for a host.

The host_kernel_version function returns the version string compiled into the kernel executing on host at the time it was built. This describes the version of the kernel. The constant KERNEL_VERSION_MAX (in \*L \*O) should be used to dimension storage for the returned string if the kernel_version_t declaration is not used.

routine _host_page_size

Get host page size (compatibility for running old libraries on new kernels - host_page_size() is now a library routine based on constants)

routine _host_page_size(in host: host_t, out out_page_size: vm_size_t)

routine mach_memory_object_memory_entry

Allow pagers to create named entries that point to un-mapped abstract memory object. The named entries are generally mappable and can be subsetted through the mach_make_memory_entry call

routine mach_memory_object_memory_entry(in host: host_t, in internal: boolean_t, in size: vm_size_t, in permission: vm_prot_t, in pager: memory_object_t, out entry_handle: mach_port_move_send_t)

routine host_processor_info

Get processor info for all the processors on this host. The returned data is an OOL array of processor info.

routine host_processor_info(in host: host_t, in flavor: processor_flavor_t, out out_processor_count: natural_t, out out_processor_info: processor_info_array_t)

routine host_get_io_main

Return host IO main access port

routine host_get_io_main(in host: host_t, out io_main: io_main_t)

routine host_get_clock_service

Get service port for a processor set. Available to all.

routine host_get_clock_service(in host: host_t, in clock_id: clock_id_t, out clock_serv: clock_serv_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return a send right to a kernel clock's service port.

The host_get_clock_service function returns a send right to the name port for a kernel clock object. This right is used to get the time and resolutions of the clock and to set clock alarms.

routine kmod_get_info

kernel module interface (obsolete as of SnowLeopard) see mach/kmod.h kmod_ MIG calls now return KERN_NOT_SUPPORTED on PPC/i386/x86_64.

routine kmod_get_info(in host: host_t, out modules: kmod_args_t)

routine host_virtual_physical_table_info

was host_zone_info Returns information about the global VP table. Only supported in MACH_VM_DEBUG kernels, otherwise returns KERN_FAILURE.

routine host_virtual_physical_table_info(in host: host_t, out info: hash_info_bucket_array_t)

routine processor_set_default

was disable_bluebox Get default processor set for host.

routine processor_set_default(in host: host_t, out default_set: processor_set_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return the default processor set.

The processor_set_default function returns the name port for the default processor set for the specified host. The default processor set is used by all threads, tasks and processors that are not explicitly assigned to other sets.

routine processor_set_create

OBSOLETE interfaces, removed from kernel

routine processor_set_create(in host: host_t, out new_set: processor_set_t, out new_name: processor_set_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Create a new processor set object.

The processor_set_create function creates a new processor set and returns the two ports associated with it. The port returned in new_set is the control port representing the set. It is used to perform operations such as assigning processors, tasks or threads. The port returned in new_name is the name port which identifies the set, and is used to obtain information about the set.

routine mach_memory_object_memory_entry_64

routine mach_memory_object_memory_entry_64(in host: host_t, in internal: boolean_t, in size: memory_object_size_t, in permission: vm_prot_t, in pager: memory_object_t, out entry_handle: mach_port_move_send_t)

routine host_statistics

Return statistics from this host.

routine host_statistics(in host_priv: host_t, in flavor: host_flavor_t, out host_info_out: host_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return statistics for a host.

The host_statistics function returns scheduling and virtual memory statistics concerning the host as specified by flavor.

routine host_request_notification

routine host_request_notification(in host: host_t, in notify_type: host_flavor_t, in notify_port: mach_port_make_send_once_t)

routine host_lockgroup_info

routine host_lockgroup_info(in host: host_t, out lockgroup_info: lockgroup_info_array_t)

routine host_statistics64

Return 64-bit statistics from this host.

routine host_statistics64(in host_priv: host_t, in flavor: host_flavor_t, out host_info64_out: host_info64_t)

routine mach_zone_info

Returns information about the memory allocation zones. Data returned is compatible with various caller and kernel address space sizes.

routine mach_zone_info(in host: mach_port_t, out names: mach_zone_name_array_t, out info: mach_zone_info_array_t)

routine host_create_mach_voucher

Create a new voucher by running a series of commands against <key, previous-voucher> pairs of resource attributes.

routine host_create_mach_voucher(in host: host_t, in recipes: mach_voucher_attr_raw_recipe_array_t, out voucher: ipc_voucher_t)

routine host_register_mach_voucher_attr_manager

OBSOLETE

routine host_register_mach_voucher_attr_manager(in host: host_t, in attr_manager: mach_voucher_attr_manager_t, in default_value: mach_voucher_attr_value_handle_t, out new_key: mach_voucher_attr_key_t, out new_attr_control: ipc_voucher_attr_control_t)

routine host_register_well_known_mach_voucher_attr_manager

routine host_register_well_known_mach_voucher_attr_manager(in host: host_t, in attr_manager: mach_voucher_attr_manager_t, in default_value: mach_voucher_attr_value_handle_t, in key: mach_voucher_attr_key_t, out new_attr_control: ipc_voucher_attr_control_t)

routine host_set_atm_diagnostic_flag

Update the global ATM diagnostic flag, readable from the commpage

routine host_set_atm_diagnostic_flag(in host: host_t, in diagnostic_flag: uint32_t)

routine mach_memory_info

routine mach_memory_info(in host: mach_port_t, out names: mach_zone_name_array_t, out info: mach_zone_info_array_t, out memory_info: mach_memory_info_array_t)

routine host_set_multiuser_config_flags

Update the global multiuser flags, readable from the commpage

routine host_set_multiuser_config_flags(in host_priv: host_priv_t, in multiuser_flags: uint32_t)

routine mach_zone_info_for_zone

Returns information about a specific zone. The zone name is passed in via the argument name, info returns the zone info.

routine mach_zone_info_for_zone(in host: host_priv_t, in name: mach_zone_name_t, out info: mach_zone_info_t)

routine mach_memory_info_redacted

Always returns the redacted version of the mach_memory_info output

routine mach_memory_info_redacted(in host: mach_port_t, out names: mach_zone_name_array_t, out info: mach_zone_info_array_t, out memory_info: mach_memory_info_array_t)

mach_port (mach/mach_port.defs, 43 routines)

routine mach_port_names

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(in task: ipc_space_t, out names: mach_port_name_array_t, out types: mach_port_type_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return information about a task's port name space.

The mach_port_names returns information about task 's port name space. It returns task's currently active names, which represent some port, port set, or dead name right. For each name, it also returns what type of rights task holds (the same information returned by mach_port_type). Note that when a call to mach_port_names returns, the number of entries in the two output arrays (names and types) are equal (namesCnt equals typesCnt). The fact that this interface returns two separate counts is an artifact of the Mach Interface Generator.

Notes. This interface is machine word length specific because of the port name parameter and the returned port names.

routine mach_port_type

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(in task: ipc_space_t, in name: mach_port_name_t, out ptype: mach_port_type_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return the characteristics of the target port name.

The mach_port_type function returns information about task 's rights for a specific name in its port name space. The returned ptype is a bit-mask indicating what rights task holds with this name. The bit-mask is composed of the following bits: MACH_PORT_TYPE_SEND The name denotes send rights. MACH_PORT_TYPE_RECEIVE The name denotes a receive right. MACH_PORT_TYPE_SEND_ONCE The name denotes a send-once right. MACH_PORT_TYPE_PORT_SET The name denotes a port set. MACH_PORT_TYPE_DEAD_NAME The name is a dead name. MACH_PORT_TYPE_DNREQUEST A dead-name request has been registered for the right.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME

name did not denote a right.

routine mach_port_rename

OBSOLETE interface, removed from kernel

routine mach_port_rename(in task: ipc_space_t, in old_name: mach_port_name_t, in new_name: mach_port_name_t)

routine mach_port_allocate_name

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(in task: ipc_space_t, in right: mach_port_right_t, in name: mach_port_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Create a port right with the caller-specified name.

The mach_port_allocate_name function creates a new right in the specified task, with a specified name for the new right.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_NAME_EXISTS

name was already in use for a port right.

routine mach_port_allocate

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(in task: ipc_space_t, in right: mach_port_right_t, out name: mach_port_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Create caller-specified type of port right.

The mach_port_allocate function creates a new right in the specified task. The new right's name is returned in name. Ports that are allocated via this call do not support the full set of Mach port semantics; in particular, the kernel will not provide no-more-senders notification service requests on such ports. Any attempt to request no-more-senders notification service will generate an error. Use the mach_port_allocate_full interface to allocate ports that support the full set of Mach port semantics.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_NO_SPACE

There was no room in task's IPC name space for another right.

routine mach_port_destroy

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(in task: ipc_space_t, in name: mach_port_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Deallocate all port rights associated with specified name.

The mach_port_destroy function de-allocates all rights denoted by a name. The name becomes immediately available for reuse. For most purposes, mach_port_mod_refs and mach_port_deallocate are preferable. If name denotes a port set, then all members of the port set are implicitly removed from the port set. If name denotes a receive right that is a member of a port set, the receive right is implicitly removed from the port set. Remaining messages queued to the port are destroyed and extant send and send-once rights turn into dead names. If those send and send-once rights have dead-name requests registered, then dead-name notifications are generated for them. If name denotes a send-once right, then the destruction of the send-once right produces a send-once notification for the port. If name denotes a send-once, send, and/or receive right, and it has a dead-name request registered, then a port-deleted notification is generated (as opposed to a dead-name notification).

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME

The name parameter did not denote a right.

routine mach_port_deallocate

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(in task: ipc_space_t, in name: mach_port_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Decrement the target port right's user reference count.

The mach_port_deallocate function releases a user reference for a right. It is an alternate form of mach_port_mod_refs that allows a task to release a user reference for a send or send-once right without failing if the port has died and the right is now actually a dead name. If name denotes a dead name, send right, or send-once right, then the right loses one user reference. If it only had one user reference, then the right is destroyed. If name does not denote an element in the port name space, the function returns success.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_RIGHT

The name parameter denoted an invalid right.

routine mach_port_get_refs

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(in task: ipc_space_t, in name: mach_port_name_t, in right: mach_port_right_t, out refs: mach_port_urefs_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return the current count of user references on the target port right.

The mach_port_get_refs function returns the number of user references a task has for a right. If name denotes a right, but not the type of right specified, then zero is returned. Otherwise a positive number of user references is returned. Note a name may simultaneously denote send and receive rights. The number of references for send-once rights is always one.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME

name did not denote a right.

routine mach_port_mod_refs

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(in task: ipc_space_t, in name: mach_port_name_t, in right: mach_port_right_t, in delta: mach_port_delta_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Modify the specified port right's count of user references.

The mach_port_mod_refs function requests that the number of user references a task has for a right be changed. This results in the right being destroyed, if the number of user references is changed to zero. The name parameter should denote the specified right. The number of user references for the right is changed by the amount delta, subject to the following restrictions: port sets, receive rights, and send-once rights may only have one user reference. The resulting number of user references can't be negative. If the resulting number of user references is zero, the effect is to de-allocate the right. For dead names and send rights, there is an implementation-defined maximum number of user references. If the call destroys the right, then the effect is as described for mach_port_destroy, with the exception that mach_port_destroy simultaneously destroys all the rights denoted by a name, while mach_port_mod_refs can only destroy one right. The name will be available for reuse if it only denoted the one right.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME	name did not denote a right.
KERN_INVALID_RIGHT	name denoted a right, but not the specified right.
KERN_INVALID_VALUE	The user-reference count would become negative.
KERN_UREFS_OVERFLOW	The user-reference count would overflow.

routine mach_port_peek

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(in task: ipc_space_t, in name: mach_port_name_t, in 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)

routine mach_port_set_mscount

Only valid for receive rights. Sets the make-send count for the port.

routine mach_port_set_mscount(in task: ipc_space_t, in name: mach_port_name_t, in mscount: mach_port_mscount_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Change the target port's make-send count.

The mach_port_set_mscount function changes the make-send count of task 's receive right named name. A port's make-send count specifies the number of send rights that have been generated via the port's receive right. A port's make-send count is set to zero when the port is first allocated; the count is reset to zero each time the port's receive right is transferred via a Mach message.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME	name did not denote a right.
KERN_INVALID_RIGHT	name denoted a right, but not a receive right.

routine mach_port_get_set_status

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

routine mach_port_get_set_status(in task: ipc_space_read_t, in name: mach_port_name_t, out members: mach_port_name_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return the port right names contained in the target port set.

The mach_port_get_set_status function returns the individual port right names for all port rights contained in the specified port set. The members parameter is an array that is automatically allocated when the reply message is received. Note that vm_deallocate should be used to free the array. Note that this interface, unlike others such as task_threads, returns a collection of port right names, NOT a collection of port rights themselves. In other words, this function does not insert port rights into the caller's port right name space; consequently, a call to mach_port_get_set_status does not affect the reference count of each port right within the target port set.

Notes. This interface is machine word length specific because of the port name parameter and the returned port names.

KERN_INVALID_NAME	name did not denote a right.
KERN_INVALID_RIGHT	name denoted a right, but not a port set.

routine mach_port_move_member

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(in task: ipc_space_t, in member: mach_port_name_t, in after: mach_port_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

The mach_port_move_member function moves a receive right into a port set. If the receive right is already a member of any other port sets, it is removed from those sets first. If the port set is MACH_PORT_NULL, then the receive right is not put into a port set, but removed from all its current port sets.

Notes. This interface is machine word length specific because of the port name parameter.

routine mach_port_request_notification

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(in task: ipc_space_t, in name: mach_port_name_t, in msgid: mach_msg_id_t, in sync: mach_port_mscount_t, in notify: mach_port_send_once_t, out previous: mach_port_move_send_once_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Request notification of the specified port event type.

The mach_port_request_notification function registers a request for a notification and supplies a send-once right that the notification will use. It is an atomic swap, returning the previously registered send-once right (or MACH_PORT_NULL for none). A notification request may be cancelled by providing MACH_PORT_NULL. The variant argument takes the following values: MACH_NOTIFY_PORT_DESTROYED sync must be zero. The name must specify a receive right, and the call requests a port-destroyed notification for the receive right. If the receive right were to have been destroyed, for instance by mach_port_destroy, then instead the receive right will be sent in a port-destroyed notification to the registered send-once right. MACH_NOTIFY_DEAD_NAME The call requests a dead-name notification. name specifies send, receive, or send-once rights for a port. If the port is destroyed (and the right remains, becoming a dead name), then a dead-name notification which carries the name of the right will be sent to the registered send-once right. If sync is non-zero, the name may specify a dead name, and a dead-name notification is immediately generated. Whenever a dead-name notification is generated, the user reference count of the dead name is incremented. For example, a send right with two user refs has a registered dead-name request. If the port is destroyed, the send right turns into a dead name with three user refs (instead of two), and a dead-name notification is generated. If the name is made available for reuse, perhaps because of mach_port_destroy or mach_port_mod_refs, or the name denotes a send-once right which has a message sent to it, then the registered send-once right is used to generate a port-deleted notification instead. MACH_NOTIFY_NO_SENDERS The call requests a no-senders notification. name must specify a receive right. If the receive right's make-send count is greater than or equal to the sync value, and it has no extant send rights, than an immediate no-senders notification is generated. Otherwise the notification is generated when the receive right next loses its last extant send right. In either case, any previously registered send-once right is returned. The no-senders notification carries the value the port's make-send count had when it was generated. The make-send count is incremented whenever a send right is made directly from a receive right. The make-send count is reset to zero when the receive right is carried in a message. When moving a receive right, no-senders notifications are canceled, with a send-once notification sent to indicate the cancelation.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME	name did not denote a right.
KERN_INVALID_RIGHT	name denoted an invalid right.
KERN_INVALID_CAPABILITY	notify was invalid.
KERN_UREFS_OVERFLOW	name denotes a dead name, but generating an immediate dead-name notification would overflow the name's user-reference count.

routine mach_port_insert_right

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(in task: ipc_space_t, in name: mach_port_name_t, in poly: mach_port_poly_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Insert the specified port right into the target task.

The mach_port_insert_right function inserts into task the caller's right for a port, using a specified name for the right in the target task. The specified name can't be one of the reserved values MACH_PORT_NULL or MACH_PORT_DEAD. The right can't be MACH_PORT_NULL or MACH_PORT_DEAD. The argument right_type specifies a right to be inserted and how that right should be extracted from the caller. It should be a value appropriate for mach_msg. If right_type is MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, or MACH_MSG_TYPE_COPY_SEND, then a send right is inserted. If the target already holds send or receive rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. If the target already has send rights, then those send rights gain an additional user reference. Otherwise, the target gains a send right, with a user reference count of one. If right_type is MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE, then a send-once right is inserted. The name should be unused in the target. The target gains a send-once right. If right_type is MACH_MSG_TYPE_MOVE_RECEIVE, then a receive right is inserted. If the target already holds send rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. The receive right is moved into the target task.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_NAME_EXISTS	name already denoted a right.
KERN_INVALID_CAPABILITY	right was null or dead.
KERN_UREFS_OVERFLOW	Inserting the right would overflow name 's user-reference count.
KERN_RIGHT_EXISTS	task already had rights for the port, with a different name.

routine mach_port_extract_right

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(in task: ipc_space_t, in name: mach_port_name_t, in msgt_name: mach_msg_type_name_t, out poly: mach_port_poly_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Remove the specified right from the target task and return it to the caller.

The mach_port_extract_right function extracts a port right from the target task and returns it to the caller as if the task sent the right voluntarily, using desired_type as the disposition for the right. See mach_msg. The returned value of acquired_type will be MACH_MSG_TYPE_PORT_SEND if a send right is extracted, MACH_MSG_TYPE_PORT_RECEIVE if a receive right is extracted, and MACH_MSG_TYPE_PORT_SEND_ONCE if a send-once right is extracted.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME	name did not denote a right.
KERN_INVALID_RIGHT	name denoted an invalid right.

routine mach_port_set_seqno

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

routine mach_port_set_seqno(in task: ipc_space_t, in name: mach_port_name_t, in seqno: mach_port_seqno_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Change the current value of the target port's sequence number.

The mach_port_set_seqno function changes the sequence number of task 's receive right named name. (Each port is associated with a sequence number attribute that can be used to track the order in which messages sent to the port are received. A port's sequence number is initially set to zero and is incremented each time a message is received from the port. A port's sequence number is automatically reset to zero each time the port's receive right migrates.)

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME	name did not denote a right.
KERN_INVALID_RIGHT	name denoted a right, but not a receive right.

routine mach_port_get_attributes

Returns information about a port.

routine mach_port_get_attributes(in task: ipc_space_read_t, in name: mach_port_name_t, in flavor: mach_port_flavor_t, out port_info_out: mach_port_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return information about target port as specified by the caller.

The mach_port_get_attributes function returns an information structure of type flavor.

Notes. This interface is machine word length specific because of the port name parameter in the MACH_PORT_RECEIVE_STATUS structure return.

KERN_INVALID_NAME	name did not denote a right.
KERN_INVALID_RIGHT	name denoted a right, but not a receive right.

routine mach_port_set_attributes

Set attributes of a port

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

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set the target port's attributes.

The mach_port_set_attributes function sets attributes of type flavor.

Notes. This interface is machine word length specific because of the port name parameter.

KERN_INVALID_NAME	name did not denote a right.
KERN_INVALID_RIGHT	name denoted a right, but not a receive right.

routine mach_port_allocate_qos

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(in task: ipc_space_t, in right: mach_port_right_t, inout qos: mach_port_qos_t, out name: mach_port_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Allocate a port with specified "quality of service."

The mach_port_allocate_qos function allocates a port with caller-specified "quality of service" characteristics with or without a caller-specified name; in other words, the caller may specify a desired name or it may let the kernel generate the name. The new port is capable of supporting full Mach port semantics (i.e no-more-senders notification can be requested on the port).

Notes. This interface is machine word length specific because of the port name parameter.

KERN_NO_SPACE	There was no room in task's IPC name space for another right.
KERN_INVALID_VALUE	The type of right specified by right is either invalid or conflicts with the requested "quality of service" as specified via qos.

routine mach_port_allocate_full

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(in task: ipc_space_t, in right: mach_port_right_t, in proto: mach_port_t, inout qos: mach_port_qos_t, inout name: mach_port_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Create a port right with full Mach port semantics.

The mach_port_allocate_full function creates a new right in the specified task. The new right's name is returned via the name parameter. The new port supports the full set of Mach port semantics (i.e. no_more_senders detection will work, if requested).

Notes. This interface is machine word length specific because of the port name parameter.

KERN_NO_SPACE

There was no room in task's IPC name space for another right.

routine task_set_port_space

Pre-expand task port name space. OBSOLETE. Do nothing and return success.

routine task_set_port_space(in task: ipc_space_t, in table_entries: int)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set the size of the target task's port name space table.

The task_set_port_space function preallocates the specified number of entries in the specified task's IPC name space.

KERN_NO_SPACE

The requested table size exceeds the maximum allowable table size.

routine mach_port_get_srights

Returns the exact number of extant send rights for the given receive right.

routine mach_port_get_srights(in task: ipc_space_t, in name: mach_port_name_t, out srights: mach_port_rights_t)

routine mach_port_space_info

Returns information about an IPC space.

routine mach_port_space_info(in space: ipc_space_read_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)

routine mach_port_dnrequest_info

Returns information about the dead-name requests registered with the named receive right.

routine mach_port_dnrequest_info(in task: ipc_space_t, in name: mach_port_name_t, out dnr_total: unsigned, out dnr_used: unsigned)

routine mach_port_kernel_object

amount used OBSOLETE interface, removed from kernel.

routine mach_port_kernel_object(in task: ipc_space_read_t, in name: mach_port_name_t, out object_type: unsigned, out object_addr: unsigned)

routine mach_port_insert_member

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(in task: ipc_space_t, in name: mach_port_name_t, in pset: mach_port_name_t)

routine mach_port_extract_member

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(in task: ipc_space_t, in name: mach_port_name_t, in pset: mach_port_name_t)

routine mach_port_get_context

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

routine mach_port_get_context(in task: ipc_space_read_t, in name: mach_port_name_t, out context: mach_vm_address_t)

routine mach_port_set_context

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

routine mach_port_set_context(in task: ipc_space_t, in name: mach_port_name_t, in context: mach_vm_address_t)

routine mach_port_kobject

Return the type and address of the kernel object that the given send/receive right represents.

routine mach_port_kobject(in task: ipc_space_read_t, in name: mach_port_name_t, out object_type: ipc_info_object_type_t, out object_addr: mach_vm_address_t)

routine mach_port_construct

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(in task: ipc_space_t, in options: mach_port_options_ptr_t, in context: uint64_t, out name: mach_port_name_t)

routine mach_port_destruct

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(in task: ipc_space_t, in name: mach_port_name_t, in srdelta: mach_port_delta_t, in guard: uint64_t)

routine mach_port_guard

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(in task: ipc_space_t, in name: mach_port_name_t, in guard: uint64_t, in strict: boolean_t)

routine mach_port_unguard

Unguard a port guarded previously. For unguarded ports or incorrect guards passed in it raises an exception indicating guarding misbehavior.

routine mach_port_unguard(in task: ipc_space_t, in name: mach_port_name_t, in guard: uint64_t)

routine mach_port_space_basic_info

#include <Kernel/mach/mach_port.h>

Returns basic information about an IPC space.

routine mach_port_space_basic_info(in task: ipc_space_inspect_t, out basic_info: ipc_info_space_basic_t)

routine mach_port_special_reply_port_reset_link

Returns sync ipc turnstile link status for special reply ports.

routine mach_port_special_reply_port_reset_link(in task: ipc_space_t, in name: mach_port_name_t, out srp_lost_link: boolean_t)

routine mach_port_guard_with_flags

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_with_flags(in task: ipc_space_t, in name: mach_port_name_t, in guard: uint64_t, in flags: uint64_t)

routine mach_port_swap_guard

Swap guard value of an existing guarded port. Works only if it is not a strict guard.

routine mach_port_swap_guard(in task: ipc_space_t, in name: mach_port_name_t, in old_guard: uint64_t, in new_guard: uint64_t)

routine mach_port_kobject_description

Return the type and address of the kernel object that the given send/receive right represents.

routine mach_port_kobject_description(in task: ipc_space_read_t, in name: mach_port_name_t, out object_type: ipc_info_object_type_t, out object_addr: mach_vm_address_t, out description: kobject_description_t)

routine mach_port_is_connection_for_service

Verifies that connection port was created for this service port and returns the filter policy id for that connection port

routine mach_port_is_connection_for_service(in task: ipc_space_t, in connection_port: mach_port_name_t, in service_port: mach_port_name_t, out filter_policy_id: uint64_t)

routine mach_port_get_service_port_info

Get information about service ports. Supported only on development/debug builds

routine mach_port_get_service_port_info(in task: ipc_space_read_t, in name: mach_port_name_t, out sp_info_out: mach_service_port_info_data_t)

routine mach_port_assert_attributes

routine mach_port_assert_attributes(in task: ipc_space_t, in name: mach_port_name_t, in flavor: mach_port_flavor_t, in info: mach_port_info_t)

mach_vm (mach/mach_vm.defs, 28 routines)

routine mach_vm_allocate

If building for Sandbox, keep NAME unchanged Allocate zero-filled memory in the address space of the target task, either at the specified address, or wherever space can be found (controlled by flags), of the specified size. The address at which the allocation actually took place is returned.

routine mach_vm_allocate(in target: vm_task_entry_t, inout address: mach_vm_address_t, in size: mach_vm_size_t, in flags: int)

routine mach_vm_deallocate

Deallocate the specified range from the virtual address space of the target virtual memory map.

routine mach_vm_deallocate(in target: vm_task_entry_t, in address: mach_vm_address_t, in size: mach_vm_size_t)

routine mach_vm_protect

Set the current or maximum protection attribute for the specified range of the virtual address space of the target virtual memory map. The current protection limits the memory access rights of threads within the map; the maximum protection limits the accesses that may be given in the current protection. Protections are specified as a set of {read, write, execute} *permissions*.

routine mach_vm_protect(in target_task: vm_task_entry_t, in address: mach_vm_address_t, in size: mach_vm_size_t, in set_maximum: boolean_t, in new_protection: vm_prot_t)

routine mach_vm_inherit

Set the inheritance attribute for the specified range of the virtual address space of the target address space. The inheritance value is one of {none, copy, share}, and specifies how the child address space should acquire this memory at the time of a task_create call.

routine mach_vm_inherit(in target_task: vm_task_entry_t, in address: mach_vm_address_t, in size: mach_vm_size_t, in new_inheritance: vm_inherit_t)

routine mach_vm_read

Returns the contents of the specified range of the virtual address space of the target task. [The range must be aligned on a virtual page boundary, and must be a multiple of pages in extent. The protection on the specified range must permit reading.]

routine mach_vm_read(in target_task: vm_map_read_t, in address: mach_vm_address_t, in size: mach_vm_size_t, out data: pointer_t)

routine mach_vm_read_list

List corrollary to vm_read, returns mapped contents of specified ranges within target address space.

routine mach_vm_read_list(in target_task: vm_map_read_t, inout data_list: mach_vm_read_entry_t, in count: natural_t)

routine mach_vm_write

Writes the contents of the specified range of the virtual address space of the target task. [The range must be aligned on a virtual page boundary, and must be a multiple of pages in extent. The protection on the specified range must permit writing.]

routine mach_vm_write(in target_task: vm_map_t, in address: mach_vm_address_t, in data: pointer_t)

routine mach_vm_copy

Copy the contents of the source range of the virtual address space of the target task to the destination range in that same address space. [Both of the ranges must be aligned on a virtual page boundary, and must be multiples of pages in extent. The protection on the source range must permit reading, and the protection on the destination range must permit writing.]

routine mach_vm_copy(in target_task: vm_map_t, in source_address: mach_vm_address_t, in size: mach_vm_size_t, in dest_address: mach_vm_address_t)

routine mach_vm_read_overwrite

Returns the contents of the specified range of the virtual address space of the target task. [There are no alignment restrictions, and the results will overwrite the area pointed to by data - which must already exist. The protection on the specified range must permit reading.]

routine mach_vm_read_overwrite(in target_task: vm_map_read_t, in address: mach_vm_address_t, in size: mach_vm_size_t, in data: mach_vm_address_t, out outsize: mach_vm_size_t)

routine mach_vm_msync

routine mach_vm_msync(in target_task: vm_map_t, in address: mach_vm_address_t, in size: mach_vm_size_t, in sync_flags: vm_sync_t)

routine mach_vm_behavior_set

Set the paging behavior attribute for the specified range of the virtual address space of the target task. The behavior value is one of {default, random, forward sequential, reverse sequential} and indicates the expected page reference pattern for the specified range.

routine mach_vm_behavior_set(in target_task: vm_map_t, in address: mach_vm_address_t, in size: mach_vm_size_t, in new_behavior: vm_behavior_t)

routine mach_vm_map

Map a user-supplie memory object into the virtual address space of the target task. If desired (anywhere is TRUE), the kernel will find a suitable address range of the specified size; else, the specific address will be allocated. The beginning address of the range will be aligned on a virtual page boundary, be at or beyond the address specified, and meet the mask requirements (bits turned on in the mask must not be turned on in the result); the size of the range, in bytes, will be rounded up to an integral number of virtual pages. The memory in the resulting range will be associated with the specified memory object, with the beginning of the memory range referring to the specified offset into the memory object. The mapping will take the current and maximum protections and the inheritance attributes specified; see the vm_protect and vm_inherit calls for a description of these attributes. If desired (copy is TRUE), the memory range will be filled with a copy of the data from the memory object; this copy will be private to this mapping in this target task. Otherwise, the memory in this mapping will be shared with other mappings of the same memory object at the same offset (in this task or in other tasks). [The Mach kernel only enforces shared memory consistency among mappings on one host with similar page alignments. The user-defined memory manager for this object is responsible for further consistency.]

routine mach_vm_map(in target_task: vm_task_entry_t, inout address: mach_vm_address_t, in size: mach_vm_size_t, in mask: mach_vm_offset_t, in flags: int, in object: mem_entry_name_port_t, in offset: memory_object_offset_t, in copy: boolean_t, in cur_protection: vm_prot_t, in max_protection: vm_prot_t, in inheritance: vm_inherit_t)

routine mach_vm_machine_attribute

Set/Get special properties of memory associated to some virtual address range, such as cachability, migrability, replicability. Machine-dependent.

routine mach_vm_machine_attribute(in target_task: vm_map_t, in address: mach_vm_address_t, in size: mach_vm_size_t, in attribute: vm_machine_attribute_t, inout value: vm_machine_attribute_val_t)

routine mach_vm_remap

Map portion of a task's address space.

routine mach_vm_remap(in target_task: vm_map_t, inout target_address: mach_vm_address_t, in size: mach_vm_size_t, in mask: mach_vm_offset_t, in flags: int, in src_task: vm_map_t, in src_address: mach_vm_address_t, in copy: boolean_t, out cur_protection: vm_prot_t, out max_protection: vm_prot_t, in inheritance: vm_inherit_t)

routine mach_vm_page_query

Give the caller information on the given location in a virtual address space. If a page is mapped return ref and dirty info.

routine mach_vm_page_query(in target_map: vm_map_read_t, in offset: mach_vm_offset_t, out disposition: integer_t, out ref_count: integer_t)

routine mach_vm_region_recurse

routine mach_vm_region_recurse(in target_task: vm_map_read_t, inout address: mach_vm_address_t, out size: mach_vm_size_t, inout nesting_depth: natural_t, out info: vm_region_recurse_info_t)

routine mach_vm_region

Returns information about the contents of the virtual address space of the target task at the specified address. The returned protection, inheritance, sharing and memory object values apply to the entire range described by the address range returned; the memory object offset corresponds to the beginning of the address range. [If the specified address is not allocated, the next highest address range is described. If no addresses beyond the one specified are allocated, the call returns KERN_NO_SPACE.]

routine mach_vm_region(in target_task: vm_map_read_t, inout address: mach_vm_address_t, out size: mach_vm_size_t, in flavor: vm_region_flavor_t, out info: vm_region_info_t, out object_name: memory_object_name_t = MACH_MSG_TYPE_MOVE_SEND ctype : mach_port_t)

routine mach_vm_purgable_control

Control behavior and investigate state of a "purgable" object in the virtual address space of the target task. A purgable object is created via a call to mach_vm_allocate() with VM_FLAGS_PURGABLE specified. See the routine implementation for a complete definition of the routine.

routine mach_vm_purgable_control(in target_task: vm_map_t, in address: mach_vm_address_t, in control: vm_purgable_t, inout state: int)

routine mach_vm_page_info

routine mach_vm_page_info(in target_task: vm_map_read_t, in address: mach_vm_address_t, in flavor: vm_page_info_flavor_t, out info: vm_page_info_t)

routine mach_vm_page_range_query

routine mach_vm_page_range_query(in target_map: vm_map_read_t, in address: mach_vm_offset_t, in size: mach_vm_size_t, in dispositions: mach_vm_address_t, inout dispositions_count: mach_vm_size_t)

routine mach_vm_remap_new

Map portion of a task's address space, {max, cur}_protection is inout.

routine mach_vm_remap_new(in target_task: vm_map_t, inout target_address: mach_vm_address_t, in size: mach_vm_size_t, in mask: mach_vm_offset_t, in flags: int, in src_task: vm_map_read_t, in src_address: mach_vm_address_t, in copy: boolean_t, inout cur_protection: vm_prot_t, inout max_protection: vm_prot_t, in inheritance: vm_inherit_t)

routine mach_vm_deferred_reclamation_buffer_allocate

Mach VM deferred reclamation subsystem

routine mach_vm_deferred_reclamation_buffer_allocate(in target_task: task_t, out address: mach_vm_address_t, out next_deadline: uint64_t, in len: uint32_t, in max_len: uint32_t)

routine mach_vm_deferred_reclamation_buffer_flush

routine mach_vm_deferred_reclamation_buffer_flush(in target_task: task_t, in num_entries_to_reclaim: uint32_t, out bytes_reclaimed: uint64_t, out next_deadline: uint64_t)

routine mach_vm_range_create

was: mach_vm_deferred_reclamation_buffer_update_reclaimable_bytes()

routine mach_vm_range_create(in target_task: vm_map_t, in flavor: mach_vm_range_flavor_t, in recipes: mach_vm_range_recipes_raw_t)

routine mach_vm_deferred_reclamation_buffer_resize

routine mach_vm_deferred_reclamation_buffer_resize(in target_task: task_t, in new_len: uint32_t, out bytes_reclaimed: uint64_t, out next_deadline: uint64_t)

routine mach_vm_update_pointers_with_remote_tags

routine mach_vm_update_pointers_with_remote_tags(in target: vm_map_t, in in_pointer_list: mach_vm_offset_list_t, out out_pointer_list: mach_vm_offset_list_t)

routine mach_vm_deferred_reclamation_buffer_query

routine mach_vm_deferred_reclamation_buffer_query(in target: task_read_t, out addr: mach_vm_address_t, out size: mach_vm_size_t)

routine mach_vm_reallocate

Relocate the pages of the source range of the specified map to a new range of the given size in bytes within the same map.

routine mach_vm_reallocate(in target_task: vm_map_t, in src: mach_vm_address_t, in src_size: mach_vm_size_t, inout dst: mach_vm_address_t, in dst_size: mach_vm_size_t, in align_mask: mach_vm_offset_t, in options: int, in flags: int)

mach_voucher (mach/mach_voucher.defs, 5 routines)

routine mach_voucher_extract_attr_content

extract just the content data for a <voucher, key> pair

routine mach_voucher_extract_attr_content(in voucher: ipc_voucher_t, in key: mach_voucher_attr_key_t, out content: mach_voucher_attr_content_t)

routine mach_voucher_extract_attr_recipe

extract a recipe to reconstitue a <voucher, key> pair item in a future voucher

routine mach_voucher_extract_attr_recipe(in voucher: ipc_voucher_t, in key: mach_voucher_attr_key_t, out recipe: mach_voucher_attr_raw_recipe_t)

routine mach_voucher_extract_all_attr_recipes

extract a recipe array to reconstitue all the key values in a future voucher

routine mach_voucher_extract_all_attr_recipes(in voucher: ipc_voucher_t, out recipes: mach_voucher_attr_raw_recipe_array_t)

routine mach_voucher_attr_command

execute a command against a given voucher attribute

routine mach_voucher_attr_command(in voucher: ipc_voucher_t, in key: mach_voucher_attr_key_t, in command: mach_voucher_attr_command_t, in in_content: mach_voucher_attr_content_t, out out_content: mach_voucher_attr_content_t)

routine mach_voucher_debug_info

#include <Kernel/mach/mach_voucher_attr_control.h>

extract a recipe array to reconstitue all the key values in a future voucher

routine mach_voucher_debug_info(in task: ipc_space_read_t, in voucher_name: mach_port_name_t, out recipes: mach_voucher_attr_raw_recipe_array_t)

mach_voucher_attr_control (mach/mach_voucher_attr_control.defs, 2 routines)

routine mach_voucher_attr_control_get_values

Obsolete Interfaces Extract the given voucher-control's value-handle from the supplied voucher

routine mach_voucher_attr_control_get_values(in control: ipc_voucher_attr_control_t, in voucher: ipc_voucher_t, out value_handles: mach_voucher_attr_value_handle_array_t)

routine mach_voucher_attr_control_create_mach_voucher

#include <Kernel/mach/mach_voucher_attr_control.h>

Create a new voucher with the control's privilege (to directly assign value-handles)

routine mach_voucher_attr_control_create_mach_voucher(in control: ipc_voucher_attr_control_t, in recipes: mach_voucher_attr_raw_recipe_array_t, out voucher: ipc_voucher_t)

memory_entry (mach/memory_entry.defs, 4 routines)

routine mach_memory_entry_purgable_control

routine mach_memory_entry_purgable_control(in mem_entry: mem_entry_name_port_t, in control: vm_purgable_t, inout state: int)

routine mach_memory_entry_access_tracking

routine mach_memory_entry_access_tracking(in mem_entry: mem_entry_name_port_t, inout access_tracking: int, out access_tracking_reads: uint32_t, out access_tracking_writes: uint32_t)

routine mach_memory_entry_ownership

routine mach_memory_entry_ownership(in mem_entry: mem_entry_name_port_t, in owner: task_t, in ledger_tag: int, in ledger_flags: int)

routine mach_memory_entry_get_page_counts

#include <Kernel/mach/memory_error_notification_server.h>

Query the residency of the physical memory backing a given memory entry. This operation is only supported on "named" memory entries created with `MAP_MEM_NAMED_CREATE`. It is unsupported on "mappings" created with `MAP_MEM_COPY` or `MAM_MEM_SHARED` - Parameters - mem_entry: The memory entry to query - resident_cnt: If non-null, the number of resident pages written out - dirty_cnt: If non-null, the number of resident, modified pages written out - swapped_cnt: If non-null, the number of evicted pages written out

routine mach_memory_entry_get_page_counts(in mem_entry: mem_entry_name_port_t, out resident_cnt: uint64_t, out dirty_cnt: uint64_t, out swapped_cnt: uint64_t)

memory_error_notification (mach/memory_error_notification.defs, 3 routines)

simpleroutine memory_error_notification

simpleroutine memory_error_notification(requestport memory_error_port: mach_port_t, in event: ecc_event_t, serveraudittoken atoken: audit_token_t)

simpleroutine mcc_memory_error_notification

#include <Kernel/mach/memory_error_notification_server.h>

simpleroutine mcc_memory_error_notification(requestport memory_error_port: mach_port_t, in event: mcc_ecc_event_t, serveraudittoken atoken: audit_token_t)

simpleroutine llc_memory_error_notification

#include <Kernel/mach/memory_error_notification_server.h>

simpleroutine llc_memory_error_notification(requestport memory_error_port: mach_port_t, in event: llc_event_t, serveraudittoken atoken: audit_token_t)

notify (mach/notify.defs, 5 routines)

simpleroutine mach_notify_port_deleted

no C stub in SDK (server-side / callback)

MACH_NOTIFY_PORT_DELETED: 0101

simpleroutine mach_notify_port_deleted(in notify: mach_port_move_send_once_t, in name: mach_port_name_t)

simpleroutine mach_notify_port_destroyed

no C stub in SDK (server-side / callback)

was NOTIFY_RECEIVE_RIGHTS: 0104 MACH_NOTIFY_PORT_DESTROYED: 0105

simpleroutine mach_notify_port_destroyed(in notify: mach_port_move_send_once_t, in rights: mach_port_move_receive_t)

simpleroutine mach_notify_no_senders

no C stub in SDK (server-side / callback)

MACH_NOTIFY_NO_SENDERS: 0106

simpleroutine mach_notify_no_senders(in notify: mach_port_move_send_once_t, in mscount: mach_port_mscount_t)

simpleroutine mach_notify_send_once

no C stub in SDK (server-side / callback)

MACH_NOTIFY_SEND_ONCE: 0107

simpleroutine mach_notify_send_once(in notify: mach_port_move_send_once_t)

simpleroutine mach_notify_dead_name

no C stub in SDK (server-side / callback)

MACH_NOTIFY_DEAD_NAME: 0110

simpleroutine mach_notify_dead_name(in notify: mach_port_move_send_once_t, in name: mach_port_name_t)

processor (mach/processor.defs, 6 routines)

routine processor_start

References to processor objects are returned by: host_processors(host_priv_t,...); Start processor.

routine processor_start(in processor: processor_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Start a processor.

The processor_start function allows privileged software to start a processor in a multi-processor that so allows it. A newly started processor is assigned to the default processor set. The interpretation of this operation is machine dependent.

Notes. This operation is machine dependent. It may do nothing.

Cautions. The ability to restart an exited processor is machine dependent.

The operation was not performed. A likely reason is that it is not supported on this processor.

routine processor_exit

Exit processor -- may not be restartable.

routine processor_exit(in processor: processor_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Exit a processor.

The processor_exit function allows privileged software to exit a processor in a multi-processor that so allows it. An exited processor is removed from the processor set to which it was assigned and ceases to be active. The interpretation of this operation is machine dependent.

Notes. This operation is machine dependent. It may do nothing.

Cautions. The ability to restart an exited processor is machine dependent.

The operation was not performed. A likely reason is that it is not supported on this processor.

routine processor_info

Return information about this processor.

routine processor_info(in processor: processor_t, in flavor: processor_flavor_t, out host: host_t, out processor_info_out: processor_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return information about a processor.

The processor_info function returns selected information for a processor, as specified by flavor.

routine processor_control

Do something machine-dependent to processor.

routine processor_control(in processor: processor_t, in processor_cmd: processor_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Perform caller-specified operation on target processor. (Protected Interface.)

The processor_control function allows privileged software to control a processor in a multi-processor that so allows it. The interpretation of cmd is machine dependent.

Notes. These operations are machine dependent. They may do nothing.

The operation was not performed. A likely reason is that it is not supported on this processor.

routine processor_assign

JMM - Keep processor_set related stuff at the end because they likely will be removed. Assign processor to processor set.

routine processor_assign(in processor: processor_t, in new_set: processor_set_t, in wait: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Assign a processor to a processor set.

The processor_assign function assigns processor to the set new_set. After the assignment is completed, the processor only executes threads that are assigned to that processor set. Any previous assignment of the processor is nullified. The master processor cannot be re-assigned. The wait argument indicates whether the caller should wait for the assignment to be completed or should return immediately. Dedicated kernel threads are used to perform processor assignment, so setting wait to FALSE allows assignment requests to be queued and performed more quickly, especially if the kernel has more than one dedicated internal thread for processor assignment. All processors take clock interrupts at all times. Redirection of other device interrupts away from processors assigned to other than the default processor set is machine dependent.

routine processor_get_assignment

Get current assignment for processor.

routine processor_get_assignment(in processor: processor_t, out assigned_set: processor_set_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Get current assignment for a processor.

The processor_get_assignment function returns the name port for the processor set to which a desired processor is currently assigned.

Processor is either shut down of off-line.

processor_set (mach/processor_set.defs, 11 routines)

routine processor_set_statistics

Return scheduling statistics for a processor set.

routine processor_set_statistics(in pset: processor_set_name_t, in flavor: processor_set_flavor_t, out info_out: processor_set_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return scheduling statistics for a processor set.

The processor_set_statistics function returns statistics for a processor set as specified by flavor.

routine processor_set_destroy

OBSOLETE interfaces, removed from kernel

routine processor_set_destroy(in set: processor_set_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Destroy the target processor set object.

The processor_set_destroy function destroys the specified processor set. Any assigned processors, tasks or threads are re-assigned to the default set. The object port (not the name port) for the processor set is required.

KERN_DEFAULT_SET

An attempt was made to destroy the default processor set.

routine processor_set_max_priority

routine processor_set_max_priority(in processor_set: processor_set_t, in max_priority: int, in change_threads: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Sets the maximum scheduling priority for a processor set.

The processor_set_max_priority function sets the maximum scheduling priority for processor_set. The maximum priority of a processor set is used only when creating new threads. A new thread's maximum priority is set to that of its assigned processor set. When assigned to a processor set, a thread's maximum priority is reduced, if necessary, to that of its new processor set; its current priority is also reduced, as needed. Changing the maximum priority of a processor set does not affect the priority of the currently assigned threads unless change_threads is TRUE. If this priority change violates the maximum priority of some threads, their maximum priorities will be reduced to match.

routine processor_set_policy_enable

routine processor_set_policy_enable(in processor_set: processor_set_t, in policy: int)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Enables a scheduling policy for a processor set.

The processor_set_policy_enable function extends the set of scheduling policies allowed for processor_set. The set of scheduling policies allowed for a processor set is the set of policies allowed to be set for threads assigned to that processor set. The current set of permitted policies can be obtained from processor_set_info.

routine processor_set_policy_disable

routine processor_set_policy_disable(in processor_set: processor_set_t, in policy: int, in change_threads: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Disables a scheduling policy for a processor set.

The processor_set_policy_disable function restricts the set of scheduling policies allowed for processor_set. The set of scheduling policies allowed for a processor set is the set of policies allowed to be set for threads assigned to that processor set. The current set of permitted policies can be obtained from processor_set_info. Timesharing may not be forbidden for any processor set. This is a compromise to reduce the complexity of the assign operation; any thread whose policy is forbidden by its target processor set has its policy reset to timesharing. Disabling a scheduling policy for a processor set has no effect on threads currently assigned to that processor set unless change_threads is TRUE, in which case their policies will be reset to timesharing.

routine processor_set_tasks

List all tasks in processor set.

routine processor_set_tasks(in processor_set: processor_set_t, out task_list: task_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return a list of pointers to all tasks currently assigned to the target processor set.

The processor_set_tasks function returns send rights to the kernel ports for each task currently assigned to processor_set.

routine processor_set_threads

OBSOLETE interfaces, removed from kernel

routine processor_set_threads(in processor_set: processor_set_t, out thread_list: thread_act_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return a list of pointers to all threads currently assigned to the target processor set.

The processor_set_threads function returns send rights to the kernel ports for each thread currently assigned to processor_set.

routine processor_set_policy_control

routine processor_set_policy_control(in pset: processor_set_t, in flavor: processor_set_flavor_t, in policy_info: processor_set_info_t, in change: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set target processor set's scheduling policy state.

The processor_set_policy_control function controls scheduling attributes governing the processor set.

routine processor_set_stack_usage

routine processor_set_stack_usage(in pset: processor_set_t, out ltotal: unsigned, out space: vm_size_t, out resident: vm_size_t, out maxusage: vm_size_t, out maxstack: vm_offset_t)

routine processor_set_info

Get information about processor set.

routine processor_set_info(in set_name: processor_set_name_t, in flavor: int, out host: host_t, out info_out: processor_set_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return processor set state according to caller-specified flavor.

The processor_set_info function returns selected information for a processor set, as specified by flavor.

Notes. A processor set has a single default scheduling policy in effect for it (as returned by PROCESSOR_SET_BASIC_INFO), so only one of the default scheduling structures has valid information. On the other hand, a processor set maintains limits for all defined scheduling policies, so all of the scheduling limit structures return valid values.

routine processor_set_tasks_with_flavor

List all tasks(/inspect/read) in processor set based on flavor.

routine processor_set_tasks_with_flavor(in processor_set: processor_set_t, in flavor: mach_task_flavor_t, out task_list: task_array_t)

task (mach/task.defs, 65 routines)

routine task_create

Sandbox builds task.defs with KERNEL_SERVER defined when generating the map of MIG routine names to message IDs. The MIG routine names need to be kept stable so as to not break Sandbox profiles. OBSOLETE interfaces, removed from kernel

routine task_create(in target_task: task_t, in ledgers: ledger_array_t, in inherit_memory: boolean_t, out child_task: task_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Create a new task.

The task_create function creates a new task from parent_task and returns the name of the new task in child_task. The child task acquires shared or copied parts of the parent's address space (see vm_inherit). The child task initially contains no threads. The child task inherits the parent's security ID. The child task receives the following "special" ports, which are created or copied for it at task creation: [task-self send right] The port by which the kernel knows the new child task and allows it to be manipulated. The child task holds a send right for this port. The port name is also returned to the calling task. [bootstrap send right] The port to which the child task can send a message requesting return of any system service ports that it needs (for example, a port to the Network Name Server or the Environment Manager). The child task inherits a send right for this port from the parent task. The task can use task_set_special_port to change this port. [host-self send right] The port by which the child task requests information about its host. The child task inherits a send right for this port from the parent task. [ledger send rights] The ports naming the ledgers from which the task draws its resources. The child task also inherits the following ports: [sample send right] The port to which PC sampling messages are to be sent. [exception send rights] Ports to which exception messages are sent. [registered send rights] Ports to system services.

Notes. The ledgers functionality mentioned above is not currently implemented.

GNU Mach reference · 7.2.1 Task Creation · © FSF, GFDL

kern_return_t task_create(task_t parent_task, boolean_t inherit_memory, task_t *child_task)

The function task_create creates a new task from parent_task; the resulting task (child_task) acquires shared or copied parts of the parent's address space (see vm_inherit). The child task initially contains no threads. If inherit_memory is set, the child task's address space is built from the parent task according to its memory inheritance values; otherwise, the child task is given an empty address space. The child task gets the three special ports created or copied for it at task creation. The TASK_KERNEL_PORT is created and send rights for it are given to the child and returned to the caller. The TASK_BOOTSTRAP_PORT and the TASK_EXCEPTION_PORT are inherited from the parent task. The new task can get send rights to these ports with the call task_get_special_port. The function returns KERN_SUCCESS if a new task has been created, KERN_INVALID_ARGUMENT if parent_task is not a valid task port and KERN_RESOURCE_SHORTAGE if some critical kernel resource is unavailable.

routine task_terminate

Destroy the target task, causing all of its threads to be destroyed, all of its IPC rights to be deallocated, and all of its address space to be deallocated.

routine task_terminate(in target_task: task_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Terminate the target task and deallocate its resources.

The task_terminate function kills task and all its threads, if any. The kernel frees all resources that are in use by the task. The kernel destroys any port for which the task holds the receive right.

GNU Mach reference · 7.2.2 Task Termination · © FSF, GFDL

kern_return_t task_terminate(task_t target_task)

The function task_terminate destroys the task specified by target_task and all its threads. All resources that are used only by this task are freed. Any port to which this task has receive and ownership rights is destroyed. The function returns KERN_SUCCESS if the task has been killed, KERN_INVALID_ARGUMENT if target_task is not a task.

routine task_threads

Returns the set of threads belonging to the target task. [Polymorphic] This routine returns thread port with the same flavor as that of the task port passed in.

routine task_threads(in target_task: task_inspect_t, out act_list: thread_act_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return the target task's list of threads.

The task_threads function returns a list of the threads within task. The calling task or thread also receives a send right to the kernel port for each listed thread.

GNU Mach reference · 7.2.3 Task Information · © FSF, GFDL

kern_return_t task_threads(task_t target_task, thread_array_t *thread_list, mach_msg_type_number_t *thread_count)

The function task_threads gets send rights to the kernel port for each thread contained in target_task. thread_list is an array that is created as a result of this call. The caller may wish to vm_deallocate this array when the data is no longer needed. The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if target_task is not a task.

routine mach_ports_register3

no C stub in SDK (server-side / callback)

Stash a handful of ports for the target task; child tasks inherit this stash at task_create time.

routine mach_ports_register3(in target_task: task_t, in port1: mach_port_t, in port2: mach_port_t, in port3: mach_port_t)

routine mach_ports_lookup3

no C stub in SDK (server-side / callback)

Retrieve the stashed ports for the target task.

routine mach_ports_lookup3(in target_task: task_t, out port1: mach_port_t, out port2: mach_port_t, out port3: mach_port_t)

routine task_info

Returns information about the target task.

routine task_info(in target_task: task_name_t, in flavor: task_flavor_t, out task_info_out: task_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return per-task information according to specified flavor.

The task_info function returns an information structure of type flavor.

Notes. At any given time, a task has one default scheduling policy assigned to it (as returned by TASK_BASIC_INFO). As such, only one of the scheduling flavors will return valid information.

KERN_INVALID_POLICY

A request was made for the default scheduling policy attributes for the task but the requested policy is not the task's default policy.

GNU Mach reference · 7.2.3 Task Information · © FSF, GFDL

kern_return_t task_info(task_t target_task, int flavor, task_info_t task_info, mach_msg_type_number_t *task_info_count)

The function task_info returns the selected information array for a task, as specified by flavor. task_info is an array of integers that is supplied by the caller, and filled with specified information. task_info_count is supplied as the maximum number of integers in task_info. On return, it contains the actual number of integers in task_info. The maximum number of integers returned by any flavor is TASK_INFO_MAX. The type of information returned is defined by flavor, which can be one of the following: TASK_BASIC_INFOThe function returns basic information about the task, as defined by task_basic_info_t. This includes the user and system time and memory consumption. The number of integers returned is TASK_BASIC_INFO_COUNT. TASK_EVENTS_INFOThe function returns information about events for the task as defined by thread_sched_info_t. This includes statistics about virtual memory and IPC events like pageouts, pageins and messages sent and received. The number of integers returned is TASK_EVENTS_INFO_COUNT. TASK_THREAD_TIMES_INFOThe function returns information about the total time for live threads as defined by task_thread_times_info_t. The number of integers returned is TASK_THREAD_TIMES_INFO_COUNT. The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if target_task is not a thread or flavor is not recognized. The function returns MIG_ARRAY_TOO_LARGE if the returned info array is too large for task_info. In this case, task_info is filled as much as possible and task_infoCnt is set to the number of elements that would have been returned if there were enough room.

routine task_set_info

Set task information.

routine task_set_info(in target_task: task_t, in flavor: task_flavor_t, in task_info_in: task_info_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set task-specific information state.

The task_set_info interface provides the caller with the means to set the target task's user_data field. This field may be used to specify arbitrarily task-specific data.

Notes. Currently, this interface is used exclusively to provide freshly colocated user tasks with the short-circuited RPC glue vector.

routine task_suspend

Increment the suspend count for the target task. No threads within a task may run when the suspend count for that task is non-zero.

routine task_suspend(in target_task: task_read_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Suspend the target task.

The task_suspend function increments the suspend count for task and stops all threads within the task. As long as the suspend count is positive, no newly-created threads can execute. The function does not return until all of the task's threads have been suspended.

Notes. To resume a suspended task and its threads, use task_resume. If the suspend count is greater than one, task_resume must be repeated that number of times.

GNU Mach reference · 7.2.4 Task Execution · © FSF, GFDL

kern_return_t task_suspend(task_t target_task)

The function task_suspend increments the task's suspend count and stops all threads in the task. As long as the suspend count is positive newly created threads will not run. This call does not return until all threads are suspended. The count may become greater than one, with the effect that it will take more than one resume call to restart the task. The function returns KERN_SUCCESS if the task has been suspended and KERN_INVALID_ARGUMENT if target_task is not a task.

routine task_resume

Decrement the suspend count for the target task, if the count is currently non-zero. If the resulting suspend count is zero, then threads within the task that also have non-zero suspend counts may execute.

routine task_resume(in target_task: task_read_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Decrement the target task's suspend count.

The task_resume function decrements the suspend count for task. If the task's suspend count goes to zero, the function resumes any suspended threads within the task. To resume a given thread, the thread's own suspend count must also be zero.

Notes. An attempt to lower the suspend count below zero is ignored.

GNU Mach reference · 7.2.4 Task Execution · © FSF, GFDL

kern_return_t task_resume(task_t target_task)

The function task_resume decrements the task's suspend count. If it becomes zero, all threads with zero suspend counts in the task are resumed. The count may not become negative. The function returns KERN_SUCCESS if the task has been resumed, KERN_FAILURE if the suspend count is already at zero and KERN_INVALID_ARGUMENT if target_task is not a task.

routine task_get_special_port

Returns the current value of the selected special port associated with the target task.

routine task_get_special_port(in task: task_inspect_t, in which_port: int, out special_port: mach_port_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return a send write to the indicated special port.

The task_get_special_port function returns a send right for a special port belonging to task. If one task has a send right for the kernel port of another task, it can use the port to perform kernel operations for the other task. Send rights for a kernel port normally are held only by the task to which the port belongs, or by the task's parent task. Using the mach_msg function, however, any task can pass a send right for its kernel port to another task.

Notes. The current implementation does not support the TASK_HOST_NAME_PORT features associated with this interface.

GNU Mach reference · 7.2.5 Task Special Ports · © FSF, GFDL

kern_return_t task_get_special_port(task_t task, int which_port, mach_port_t *special_port)

The function task_get_special_port returns send rights to one of a set of special ports for the task specified by task. The special ports associated with a task are the kernel port (TASK_KERNEL_PORT), the bootstrap port (TASK_BOOTSTRAP_PORT) and the exception port (TASK_EXCEPTION_PORT). The bootstrap port is a port to which a task may send a message requesting other system service ports. This port is not used by the kernel. The task's exception port is the port to which messages are sent by the kernel when an exception occurs and the thread causing the exception has no exception port of its own. The following macros to call task_get_special_port for a specific port are defined in mach/task_special_ports.h: task_get_exception_port and task_get_bootstrap_port. The function returns KERN_SUCCESS if the port was returned and KERN_INVALID_ARGUMENT if task is not a task or which_port is an invalid port selector.

routine task_set_special_port

Set one of the special ports associated with the target task.

routine task_set_special_port(in task: task_t, in which_port: int, in special_port: mach_port_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set the indicated special port.

The task_set_special_port function sets a special port belonging to task.

Notes. The current implementation does not support the TASK_HOST_NAME_PORT features associated with this interface.

GNU Mach reference · 7.2.5 Task Special Ports · © FSF, GFDL

kern_return_t task_set_special_port(task_t task, int which_port, mach_port_t special_port)

The function thread_set_special_port sets one of a set of special ports for the task specified by task. The special ports associated with a task are the kernel port (TASK_KERNEL_PORT), the bootstrap port (TASK_BOOTSTRAP_PORT) and the exception port (TASK_EXCEPTION_PORT). The bootstrap port is a port to which a thread may send a message requesting other system service ports. This port is not used by the kernel. The task's exception port is the port to which messages are sent by the kernel when an exception occurs and the thread causing the exception has no exception port of its own. The function returns KERN_SUCCESS if the port was set and KERN_INVALID_ARGUMENT if task is not a task or which_port is an invalid port selector.

routine thread_create

Create a new thread within the target task, returning the port representing the first thr_act in that new thread. The initial execution state of the thread is undefined.

routine thread_create(in parent_task: task_t, out child_act: thread_act_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Create a thread within a task.

The thread_create function creates a new thread within parent_task. The new thread has a suspend count of one and no processor state. The new thread holds a send right for its thread kernel port. A send right for the thread's kernel port is also returned to the calling task or thread in child_thread. The new thread's exception ports are set to MACH_PORT_NULL.

Notes. To get a new thread running, first use thread_set_state to set a processor state for the thread. Then, use thread_resume to schedule the thread for execution. Alternately, use thread_create_running.

GNU Mach reference · 7.1.1 Thread Creation · © FSF, GFDL

kern_return_t thread_create(task_t parent_task, thread_t *child_thread)

The function thread_create creates a new thread within the task specified by parent_task. The new thread has no processor state, and has a suspend count of 1. To get a new thread to run, first thread_create is called to get the new thread's identifier, (child_thread). Then thread_set_state is called to set a processor state, and finally thread_resume is called to get the thread scheduled to execute. When the thread is created send rights to its thread kernel port are given to it and returned to the caller in child_thread. The new thread's exception port is set to MACH_PORT_NULL. The function returns KERN_SUCCESS if a new thread has been created, KERN_INVALID_ARGUMENT if parent_task is not a valid task and KERN_RESOURCE_SHORTAGE if some critical kernel resource is not available.

routine thread_create_running

Create a new thread within the target task, returning the port representing that new thread. The new thread is not suspended; its initial execution state is given by flavor and new_state. Returns the port representing the new thread.

routine thread_create_running(in parent_task: task_t, in flavor: thread_state_flavor_t, in new_state: thread_state_t, out child_act: thread_act_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Optimized creation of a running thread.

The thread_create_running function creates a new thread within parent_task. The new thread has is not suspended. Its initial state is given by state. flavor specifies the type of state to set. The format of the state to set is machine specific; it is defined in \*L \*O. The new thread holds a send right for its thread kernel port. A send right for the thread's kernel port is also returned to the calling task or thread in child_thread. The new thread's exception ports are set to MACH_PORT_NULL.

Notes. This is an optimized form of the sequence: thread_create, thread_set_state and thread_resume.

routine task_set_exception_ports

Set an exception handler for a task on one or more exception types. These handlers are invoked for all threads in the task if there are no thread-specific exception handlers or those handlers returned an error.

routine task_set_exception_ports(in task: task_t, in exception_mask: exception_mask_t, in new_port: mach_port_t, in behavior: exception_behavior_t, in new_flavor: thread_state_flavor_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set target task's exception ports.

The task_set_exception_ports function sets a specified set of exception ports belonging to task. A task exception port is used when a thread specific exception port returns a non-success reply.

routine task_get_exception_ports

Lookup some of the old exception handlers for a task

routine task_get_exception_ports(in task: task_t, in exception_mask: exception_mask_t, out masks: exception_mask_array_t, out old_handlers: exception_handler_array_t, out old_behaviors: exception_behavior_array_t, out old_flavors: exception_flavor_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return send rights to the target task's exception ports.

The task_get_exception_ports function returns send rights for a specified set of exception ports belonging to task. A task exception port is used when a thread specific exception port returns a non-success reply. The call returns a set of quadruples for each unique set of in effect for the task where the exception type mask indicates for which exception types the other values apply.

routine task_swap_exception_ports

Set an exception handler for a thread on one or more exception types. At the same time, return the previously defined exception handlers for those types.

routine task_swap_exception_ports(in task: task_t, in exception_mask: exception_mask_t, in new_port: mach_port_t, in behavior: exception_behavior_t, in new_flavor: thread_state_flavor_t, out masks: exception_mask_array_t, out old_handlers: exception_handler_array_t, out old_behaviors: exception_behavior_array_t, out old_flavors: exception_flavor_array_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set target task's exception ports, returning the previous exception ports.

The task_swap_exception_ports function sets a specified set of exception ports belonging to task, returning the old set. A task exception port is used when a thread specific exception port returns a non-success reply.

routine lock_set_create

OBSOLETE interfaces, removed from kernel

routine lock_set_create(in task: task_t, out new_lock_set: lock_set_t, in n_ulocks: int, in policy: int)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Create a new lock set.

The lock_set_create function creates a new lock set representing a collection of associated locks. The lock set is associated with the specified task. A send right naming the lock set is returned to the caller.

KERN_SUCCESS	The lock set was created.
KERN_INVALID_ARGUMENT	Either the task or policy argument is invalid, or the locks argument has a value that is less than or equal to zero.
KERN_RESOURCE_SHORTAGE	The kernel could not allocate the lock set.

routine lock_set_destroy

routine lock_set_destroy(in task: task_t, in lock_set: lock_set_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Destroy a lock set and its associated locks.

The lock_set_destroy function will destroy a lock set and all of its associated locks. Threads that are blocked on locks represented by the destroyed lock set are unblocked and will receive a KERN_LOCK_SET_DESTROYED error message indicating that the lock set was destroyed. The lock_set_destroy function will only succeed if the specified task is associated with the specified lock set.

KERN_INVALID_ARGUMENT	The specified lock set or task is invalid.
KERN_INVALID_RIGHT	The specified task does not own the specified lock set.
KERN_LOCK_SET_DESTROYED	The specified lock set does not exist.
KERN_SUCCESS	The lock set was destroyed.

routine semaphore_create

Create and destroy semaphore synchronizers on a per-task basis (i.e. the task owns them).

routine semaphore_create(in task: task_t, out semaphore: semaphore_t, in policy: int, in value: int)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Create a new semaphore.

The semaphore_create function creates a new semaphore, associates the created semaphore with the specified task, and returns a send right naming the new semaphore. In order to support a robust producer/consumer communication service, Interrupt Service Routines (ISR) must be able to signal semaphores. The semaphore synchronizer service is designed to allow user-level device drivers to perform signal operations, eliminating the need for event counters. Device drivers which utilize semaphores are responsible for creating (via semaphore_create) and exporting (via device_get_status) semaphores for user level access. Device driver semaphore creation is done at device initialization time. Device drivers may support multiple semaphores.

KERN_INVALID_ARGUMENT	The task argument or the policy argument was invalid, or the initial value of the semaphore was invalid.
KERN_RESOURCE_SHORTAGE	The kernel could not allocate the semaphore.
KERN_SUCCESS	The semaphore was successfully created.

routine semaphore_destroy

routine semaphore_destroy(in task: task_t, in semaphore: semaphore_consume_ref_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Destroy a semaphore.

The semaphore_destroy function destroys a semaphore. All send rights naming the semaphore become dead names. Threads waiting on the semaphore become unblocked with the return from the semaphore_wait call indicating that the semaphore was destroyed. A call to semaphore_destroy succeeds only if the semaphore is associated with the specified task.

KERN_INVALID_ARGUMENT	Either, or both, the task or semaphore arguments were invalid.
KERN_INVALID_RIGHT	The specified task does not own the specified semaphore.
KERN_TERMINATED	The specified semaphore was previously destroyed.
KERN_SUCCESS	The semaphore was destroyed.

routine task_policy_set

Set/get policy information for a task. (Approved Mac OS X microkernel interface)

routine task_policy_set(in task: task_policy_set_t, in flavor: task_policy_flavor_t, in policy_info: task_policy_t)

routine task_policy_get

routine task_policy_get(in task: task_policy_get_t, in flavor: task_policy_flavor_t, out policy_info: task_policy_t, inout get_default: boolean_t)

routine task_sample

OBSOLETE interfaces, removed from kernel.

routine task_sample(in task: task_t, in reply: mach_port_make_send_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Sample the target task's thread program counters periodically.

The task_sample function causes the program counter (PC) of the specified sample_task (actually, all of the threads within sample_task) to be sampled periodically (whenever one of the threads happens to be running at the time of the kernel's "hardclock" interrupt). The set of PC sample values obtained are saved in buffers which are sent to the specified reply_port in receive_samples messages.

routine task_policy

routine task_policy(in task: task_t, in policy: policy_t, in base: policy_base_t, in set_limit: boolean_t, in change: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set target task's default scheduling policy state.

The task_policy function sets the default scheduling attributes for task. These attributes are used when creating new threads. Changing the default attributes for a task does not affect the attributes of the contained threads unless change_threads is TRUE. At no time will a thread ever have scheduling attributes that exceed the thread's limits.

KERN_INVALID_POLICY	The processor set does not currently enable policy.
KERN_POLICY_LIMIT	The specified scheduling attributes exceeds the thread's limits.

routine task_set_emulation

routine task_set_emulation(in target_port: task_t, in routine_entry_pt: vm_address_t, in routine_number: int)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Establish a user-level handler for a system call.

The task_set_emulation function establishes a handler within the task for a particular system call. When a thread executes a system call with this particular number, the system call will be redirected to the specified routine within the task's address space. This is expected to be an address within the transparent emulation library. These emulation handler addresses are inherited by child processes.

Notes. This interface is machine word length specific because of the virtual address parameter.

GNU Mach reference · 7.2.6 Syscall Emulation · © FSF, GFDL

kern_return_t task_set_emulation(task_t task, vm_address_t routine_entry_pt, int routine_number)

The function task_set_emulation establishes a user-level handler for the specified system call. System call emulation handlers are inherited by the children of task.

routine task_get_emulation_vector

routine task_get_emulation_vector(in task: task_t, out vector_start: int, out emulation_vector: emulation_vector_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return an array identifying the target task's user-level system call handlers.

The task_get_emulation_vector function returns the user-level syscall handler entrypoint addresses.

Notes. This interface is machine word length specific because of the virtual addresses in the emulation_vector parameter.

GNU Mach reference · 7.2.6 Syscall Emulation · © FSF, GFDL

kern_return_t task_get_emulation_vector(task_t task, int *vector_start, emulation_vector_t *emulation_vector, mach_msg_type_number_t *emulation_vector_count)

The function task_get_emulation_vector gets the user-level handler entry points for all emulated system calls.

routine task_set_emulation_vector

routine task_set_emulation_vector(in task: task_t, in vector_start: int, in emulation_vector: emulation_vector_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Establish the target task's user-level system call handlers.

The task_set_emulation_vector function establishes a handler within the task for a set of system calls. When a thread executes a system call with one of these numbers, the system call will be redirected to the corresponding routine within the task's address space. These emulation handler addresses are inherited by child processes.

Notes. This interface is machine word length specific because of the virtual addresses in the emulation_vector parameter.

GNU Mach reference · 7.2.6 Syscall Emulation · © FSF, GFDL

kern_return_t task_set_emulation_vector(task_t task, int vector_start, emulation_vector_t emulation_vector, mach_msg_type_number_t emulation_vector_count)

The function task_set_emulation_vector establishes user-level handlers for the specified system calls. Non-emulated system calls are specified with an entry of EML_ROUTINE_NULL. System call emulation handlers are inherited by the children of task.

routine task_set_ras_pc

routine task_set_ras_pc(in target_task: task_t, in basepc: vm_address_t, in boundspc: vm_address_t)

routine task_zone_info

routine task_zone_info(in target_task: task_inspect_t, out names: mach_zone_name_array_t, out info: task_zone_info_array_t)

routine task_assign

routine task_assign(in task: task_t, in new_set: processor_set_t, in assign_threads: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Assign a task to a processor set.

The task_assign function assigns task to the set processor_set. After the assignment is completed, newly created threads within this task will be assigned to this processor set. Any previous assignment of the task is nullified. If assign_threads is TRUE, existing threads within the task will also be assigned to the processor set.

routine task_assign_default

routine task_assign_default(in task: task_t, in assign_threads: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Assign a task to the default processor set.

The task_assign_default function assigns task to the default processor set. After the assignment is completed, newly created threads within this task will be assigned to this processor set. Any previous assignment of the task is nullified. If assign_threads is TRUE, existing threads within the task will also be assigned to the processor set.

Notes. This variant of task_assign exists because the control port for the default processor set is privileged, and therefore not available to most tasks.

routine task_get_assignment

routine task_get_assignment(in task: task_inspect_t, out assigned_set: processor_set_name_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Return the processor set to which a task is assigned.

The task_get_assignment function returns the name port to the processor set to which task is currently assigned. This port can only be used to obtain information about the processor set.

routine task_set_policy

KERN_INVALID_PROCESSOR_SET

routine task_set_policy(in task: task_t, in pset: processor_set_t, in policy: policy_t, in base: policy_base_t, in limit: policy_limit_t, in change: boolean_t)

CMU/MIT Mach reference · manual page · © Carnegie Mellon

Set target task's default scheduling policy state. (Protected Interface.)

The task_set_policy function sets the scheduling attributes, both base and limit, for task. policy may be any policy implemented by the processor set whether or not it is enabled.

processor_set is not the task's processor set control port.

routine task_get_state

Read the selected state which is to be installed on new threads in the task as they are created.

routine task_get_state(in task: task_read_t, in flavor: thread_state_flavor_t, out old_state: thread_state_t)

routine task_set_state

Set the selected state information to be installed on all subsequently created threads in the task.

routine task_set_state(in task: task_t, in flavor: thread_state_flavor_t, in new_state: thread_state_t)

routine task_set_phys_footprint_limit

Change the task's physical footprint limit (in MB).

routine task_set_phys_footprint_limit(in task: task_t, in new_limit: int, out old_limit: int)

routine task_suspend2

routine task_suspend2(in target_task: task_read_t, out suspend_token: task_suspension_token_t)

routine task_resume2

routine task_resume2(in suspend_token: task_suspension_token_t)

routine task_purgable_info

routine task_purgable_info(in task: task_inspect_t, out stats: task_purgable_info_t)

routine task_get_mach_voucher

routine task_get_mach_voucher(in task: task_read_t, in which: mach_voucher_selector_t, out voucher: ipc_voucher_t)

routine task_set_mach_voucher

routine task_set_mach_voucher(in task: task_t, in voucher: ipc_voucher_t)

routine task_swap_mach_voucher

routine task_swap_mach_voucher(in task: task_t, in new_voucher: ipc_voucher_t, inout old_voucher: ipc_voucher_t)

routine task_generate_corpse

routine task_generate_corpse(in task: task_read_t, out corpse_task_port: mach_port_t)

routine task_map_corpse_info

routine task_map_corpse_info(in task: task_t, in corspe_task: task_read_t, out kcd_addr_begin: vm_address_t, out kcd_size: uint32_t)

routine task_register_dyld_image_infos

routine task_register_dyld_image_infos(in task: task_t, in dyld_images: dyld_kernel_image_info_array_t)

routine task_unregister_dyld_image_infos

routine task_unregister_dyld_image_infos(in task: task_t, in dyld_images: dyld_kernel_image_info_array_t)

routine task_get_dyld_image_infos

routine task_get_dyld_image_infos(in task: task_read_t, out dyld_images: dyld_kernel_image_info_array_t)

routine task_register_dyld_shared_cache_image_info

routine task_register_dyld_shared_cache_image_info(in task: task_t, in dyld_cache_image: dyld_kernel_image_info_t, in no_cache: boolean_t, in private_cache: boolean_t)

routine task_register_dyld_set_dyld_state

routine task_register_dyld_set_dyld_state(in task: task_t, in dyld_state: uint8_t)

routine task_register_dyld_get_process_state

routine task_register_dyld_get_process_state(in task: task_t, out dyld_process_state: dyld_kernel_process_info_t)

routine task_map_corpse_info_64

routine task_map_corpse_info_64(in task: task_t, in corspe_task: task_read_t, out kcd_addr_begin: mach_vm_address_t, out kcd_size: mach_vm_size_t)

routine task_inspect

routine task_inspect(in task: task_inspect_t, in flavor: task_inspect_flavor_t, out info_out: task_inspect_info_t)

routine task_get_exc_guard_behavior

routine task_get_exc_guard_behavior(in task: task_inspect_t, out behavior: task_exc_guard_behavior_t)

routine task_set_exc_guard_behavior

#include <mach/mach_init.h>

routine task_set_exc_guard_behavior(in task: task_t, in behavior: task_exc_guard_behavior_t)

routine mach_task_is_self

routine mach_task_is_self(in task: task_name_t, out is_self: boolean_t)

routine task_dyld_process_info_notify_register

routine task_dyld_process_info_notify_register(in target_task: task_read_t, in notify: mach_port_make_send_t)

routine task_create_identity_token

routine task_create_identity_token(in task: task_t, out token: task_id_token_t)

routine task_identity_token_get_task_port

routine task_identity_token_get_task_port(in token: task_id_token_t, in flavor: task_flavor_t, out task_port: mach_port_t)

routine task_dyld_process_info_notify_deregister

routine task_dyld_process_info_notify_deregister(in target_task: task_read_t, in notify: mach_port_name_t)

routine task_get_exception_ports_info

routine task_get_exception_ports_info(in port: mach_port_t, in exception_mask: exception_mask_t, out masks: exception_mask_array_t, out old_handlers_info: exception_handler_info_array_t, out old_behaviors: exception_behavior_array_t, out old_flavors: exception_flavor_array_t)

routine task_test_sync_upcall

routine task_test_sync_upcall(in task: task_t, in port: mach_port_t)

routine task_set_corpse_forking_behavior

routine task_set_corpse_forking_behavior(in task: task_t, in behavior: task_corpse_forking_behavior_t)

routine task_test_async_upcall_propagation

routine task_test_async_upcall_propagation(in task: task_t, in port: mach_port_t, in qos: int, in iotier: int)

routine task_map_kcdata_object_64

routine task_map_kcdata_object_64(in task: task_t, in kcdata_object: kcdata_object_t, out kcd_addr_begin: mach_vm_address_t, out kcd_size: mach_vm_size_t)

routine task_register_hardened_exception_handler

#include <Kernel/mach/task_access.h>

When used in conjunction with thread_adopt_exception_handler, we call this a hardened mach exception handler, and it adds additional security guarantees to this exception port: 1. Enforces only a subset of exceptions, behaviours, and flavors may be used with this port 2. The `new_exception_port` must be created using MPO_EXCEPTION_PORT (implicitly immovable) 3. When using *STATE* behaviors of exception handling, only the PC is allowed to be set. 4. Setting the PC in an exception handler must be signed using a diversifier of signed_pc_key (if non-zero). You can pre-sign your PC state and then throw away the key to ensure that only a limited set of PC's may be used with this exception handler 5. Calling `[task,thread,host]_set_exception_ports` if you have the IPC_ONLY_ONE_EXCEPTION_PORT entitlement is disallowed, and you must use this hardened exception flow. If used with the traditional set_exception_ports functions, these security guarantees do not apply. You can only call this once per task. See tests/ipc/hardened_exceptions.c for examples.

routine task_register_hardened_exception_handler(in task: task_t, in signed_pc_key: uint32_t, in exceptions_allowed: exception_mask_t, in behaviors_allowed: exception_behavior_t, in flavors_allowed: thread_state_flavor_t, in new_exception_port: mach_port_t)

task_access (mach/task_access.defs, 3 routines)

routine check_task_access

Verify task_for_pid access for the given pid Access granted by return value (success/failure)

routine check_task_access(in task_access_port: mach_port_t, in calling_pid: int32_t, in calling_gid: uint32_t, in target_pid: int32_t, serveraudittoken caller_cred: audit_token_t)

routine find_code_signature

#include <Kernel/mach/task_access.h>

Search for a code signature for unsigned executables

routine find_code_signature(in task_access_port: mach_port_t, in new_pid: int32_t)

routine check_task_access_with_flavor

#include <Kernel/mach/task_access.h>

routine check_task_access_with_flavor(in task_access_port: mach_port_t, in calling_pid: int32_t, in calling_gid: uint32_t, in target_pid: int32_t, in flavor: mach_task_flavor_t, serveraudittoken caller_cred: audit_token_t)

telemetry_notification (mach/telemetry_notification.defs, 1 routines)

simpleroutine telemetry_notification

#include <Kernel/mach/telemetry_notification_server.h>

simpleroutine telemetry_notification(requestport telemetry_port: mach_port_t, in flags: uint32_t)

thread_act (mach/thread_act.defs, 33 routines)

routine thread_terminate

If building for Sandbox, keep NAME unchanged Destroy the target thread. JMM - For legacy reasons this consumes a reference to the target thread. This will have to change in the future because we want the interfaces to be able to be defined in more standard IDLs and transports, and most of them do not support the notion of reference ownership transfers (just sharing).

routine thread_terminate(in target_act: thread_act_consume_ref_t)

Destroy a thread.

The thread_terminate function kills target_thread.

kern_return_t thread_terminate(thread_t target_thread)

The function thread_terminate destroys the thread specified by target_thread. The function returns KERN_SUCCESS if the thread has been killed and KERN_INVALID_ARGUMENT if target_thread is not a thread.

routine act_get_state

Return the selected state information for the target thr_act. If the thr_act is currently executing, the results may be stale. [Flavor THREAD_STATE_FLAVOR_LIST provides a list of valid flavors for the target thread.]

routine act_get_state(in target_act: thread_read_t, in flavor: int, out old_state: thread_state_t)

routine act_set_state

Set the selected state information for the target thread. If the thread is currently executing, the state change may be ill-defined.

routine act_set_state(in target_act: thread_act_t, in flavor: int, in new_state: thread_state_t)

routine thread_get_state

Backward compatible old-style thread routines. These have different semantics than the new activation versions. Return the selected state information for the target thread. If the thread is currently executing, the results may be stale. [Flavor THREAD_STATE_FLAVOR_LIST provides a list of valid flavors for the target thr_act.]

routine thread_get_state(in target_act: thread_read_t, in flavor: thread_state_flavor_t, out old_state: thread_state_t)

Return the execution state for a thread.

The thread_get_state function returns the execution state (for example, the machine registers) for target_thread. flavor specifies the type of state information returned. The format of the data returned is machine specific; it is defined in \*L \*O.

kern_return_t thread_get_state(thread_t target_thread, int flavor, thread_state_t old_state, mach_msg_type_number_t *old_stateCnt)

The function thread_get_state returns the execution state (e.g. the machine registers) of target_thread as specified by flavor. The old_state is an array of integers that is provided by the caller and returned filled with the specified information. old_stateCnt is input set to the maximum number of integers in old_state and returned equal to the actual number of integers in old_state. target_thread may not be mach_thread_self(). The definition of the state structures can be found in machine/thread_status.h. The function returns KERN_SUCCESS if the state has been returned, KERN_INVALID_ARGUMENT if target_thread is not a thread or is mach_thread_self or flavor is unrecognized for this machine. The function returns MIG_ARRAY_TOO_LARGE if the returned state is too large for old_state. In this case, old_state is filled as much as possible and old_stateCnt is set to the number of elements that would have been returned if there were enough room.

routine thread_set_state

Set the selected state information for the target thread. If the thread is currently executing, the state change may be ill-defined.

routine thread_set_state(in target_act: thread_act_t, in flavor: thread_state_flavor_t, in new_state: thread_state_t)

Set the target thread's user-mode execution state.

The thread_set_state function sets the execution state (for example, the machine registers) for target_thread. flavor specifies the type of state to set. The format of the state to set is machine specific; it is defined in mach/thread_status.h.

kern_return_t thread_set_state(thread_t target_thread, int flavor, thread_state_t new_state, mach_msg_type_number_t new_state_count)

The function thread_set_state sets the execution state (e.g. the machine registers) of target_thread as specified by flavor. The new_state is an array of integers. new_state_count is the number of elements in new_state. The entire set of registers is reset. This will do unpredictable things if target_thread is not suspended. target_thread may not be mach_thread_self. The definition of the state structures can be found in machine/thread_status.h. The function returns KERN_SUCCESS if the state has been set and KERN_INVALID_ARGUMENT if target_thread is not a thread or is mach_thread_self or flavor is unrecognized for this machine.

routine thread_suspend

Increment the suspend count for the target thread. Once this call has completed, the thread will not execute any further user or meta- instructions. Once suspended, a thread may not execute again until its suspend count is zero, and the suspend count for its task is also zero.

routine thread_suspend(in target_act: thread_read_t)

Suspend a thread.

The thread_suspend function increments the suspend count for target_thread and prevents the thread from executing any more user-level instructions. In this context, a user-level instruction can be either a machine instruction executed in user mode or a system trap instruction, including a page fault. If a thread is currently executing within a system trap, the kernel code may continue to execute until it reaches the system return code or it may suspend within the kernel code. In either case, the system trap returns when the thread resumes. To resume a suspended thread, use thread_resume. If the suspend count is greater than one, thread_resume must be repeated that number of times.

Cautions. Unpredictable results may occur if a program suspends a thread and alters its user state so that its direction is changed upon resuming. Note that the thread_abort function allows a system call to be aborted only if it is progressing in a predictable way.

kern_return_t thread_suspend(thread_t target_thread)

Increments the thread's suspend count and prevents the thread from executing any more user level instructions. In this context a user level instruction is either a machine instruction executed in user mode or a system trap instruction including page faults. Thus if a thread is currently executing within a system trap the kernel code may continue to execute until it reaches the system return code or it may suspend within the kernel code. In either case, when the thread is resumed the system trap will return. This could cause unpredictable results if the user did a suspend and then altered the user state of the thread in order to change its direction upon a resume. The call thread_abort is provided to allow the user to abort any system call that is in progress in a predictable way. The suspend count may become greater than one with the effect that it will take more than one resume call to restart the thread. The function returns KERN_SUCCESS if the thread has been suspended and KERN_INVALID_ARGUMENT if target_thread is not a thread.

routine thread_resume

Decrement the suspend count for the target thread, if that count is not already zero.

routine thread_resume(in target_act: thread_read_t)

Resume a thread.

The thread_resume function decrements the suspend count for target_thread by one. The thread is resumed if its suspend count goes to zero. If the suspend count is still positive, thread_resume must be repeated until the count reaches zero.

Notes. An attempt to lower the suspend count below zero is ignored.

kern_return_t thread_resume(thread_t target_thread)

Decrements the thread's suspend count. If the count becomes zero the thread is resumed. If it is still positive, the thread is left suspended. The suspend count may not become negative. The function returns KERN_SUCCESS if the thread has been resumed, KERN_FAILURE if the suspend count is already zero and KERN_INVALID_ARGUMENT if target_thread is not a thread.

routine thread_abort

Cause any user or meta- instructions currently being executed by the target thread to be aborted. [Meta- instructions consist of the basic traps for IPC (e.g., msg_send, msg_receive) and self-identification (e.g., task_self, thread_self, thread_reply). Calls described by MiG interfaces are not meta-instructions themselves.]

routine thread_abort(in target_act: thread_act_t)

Abort a thread.

The thread_abort function aborts page faults and any message primitive calls in use by target_thread. Scheduling depressions and clock sleeps are also aborted. The call returns a code indicating that it was interrupted. The call is interrupted even if the thread (or the task containing it) is suspended. If it is suspended, the thread receives the interrupt when it resumes. If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the mach_msg library routine, which, by default, retries interrupted message calls. The basic purpose of thread_abort is to let one thread cleanly stop another thread (target_thread). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When thread_abort returns, the target thread will appear to have just returned from the kernel (if it had been in kernel mode).

Notes. By way of comparison, the thread_suspend function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The thread_get_state function returns the thread's user state, while thread_set_state allows modification of the user state. A problem occurs if a suspended thread had been executing within a system call. In this case, the thread has, not only a user state, but an associated kernel state. (The kernel state cannot be changed with thread_set_state.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory. For a thread executing within a system call, thread_abort aborts the kernel call from the thread's point of view. Specifically, it resets the kernel state so that the thread will resume execution at the system call return, with the return code value set to one of the interrupted codes. The system call itself may be completed entirely, aborted entirely or be partially completed, depending on when the abort is received. As a result, if the thread's user state has been modified by thread_set_state, it will not be altered un-predictably by any unexpected system call side effects. For example, to simulate a POSIX signal, use the following sequence of calls: thread_suspend \(emTo stop the thread. thread_abort \(emTo interrupt any system call in progress and set the return value to "interrupted". Because the thread is already stopped, it will not return to user code. thread_set_state \(emTo modify the thread's user state to simulate a procedure call to the signal handler. thread_resume \(emTo resume execution at the signal handler. If the thread's stack is set up correctly, the thread can return to the interrupted system call. Note that the code to push an extra stack frame and change the registers is highly machine dependent.

Cautions. As a rule, do not use thread_abort on a non-suspended thread. This operation is very risky because it is difficult to know which system trap, if any, is executing and whether an interrupt return will result in some useful action by the thread. thread_abort will abort any non-atomic operation (such as a multi-page memory_object_data_supply) at an arbitrary point in a non-restartable way. Such problems can be avoided by using thread_abort_safely.

KERN_EXCEPTION_PROTECTED

The thread is processing a protected exception.

kern_return_t thread_abort(thread_t target_thread)

The function thread_abort aborts the kernel primitives: mach_msg, msg_send, msg_receive and msg_rpc and page-faults, making the call return a code indicating that it was interrupted. The call is interrupted whether or not the thread (or task containing it) is currently suspended. If it is suspended, the thread receives the interrupt when it is resumed. A thread will retry an aborted page-fault if its state is not modified before it is resumed. msg_send returns SEND_INTERRUPTED; msg_receive returns RCV_INTERRUPTED; msg_rpc returns either SEND_INTERRUPTED or RCV_INTERRUPTED, depending on which half of the RPC was interrupted. The main reason for this primitive is to allow one thread to cleanly stop another thread in a manner that will allow the future execution of the target thread to be controlled in a predictable way. thread_suspend keeps the target thread from executing any further instructions at the user level, including the return from a system call. thread_get_state/thread_set_state allows the examination or modification of the user state of a target thread. However, if a suspended thread was executing within a system call, it also has associated with it a kernel state. This kernel state can not be modified by thread_set_state with the result that when the thread is resumed the system call may return changing the user state and possibly user memory. thread_abort aborts the kernel call from the target thread's point of view by resetting the kernel state so that the thread will resume execution at the system call return with the return code value set to one of the interrupted codes. The system call itself will either be entirely completed or entirely aborted, depending on the precise moment at which the abort was received. Thus if the thread's user state has been changed by thread_set_state, it will not be modified by any unexpected system call side effects. For example to simulate a Unix signal, the following sequence of calls may be used: thread_suspend: Stops the thread. thread_abort: Interrupts any system call in progress, setting the return value to `interrupted'. Since the thread is stopped, it will not return to user code. thread_set_state: Alters thread's state to simulate a procedure call to the signal handler thread_resume: Resumes execution at the signal handler. If the thread's stack has been correctly set up, the thread may return to the interrupted system call. (Of course, the code to push an extra stack frame and change the registers is VERY machine-dependent.) Calling thread_abort on a non-suspended thread is pretty risky, since it is very difficult to know exactly what system trap, if any, the thread might be executing and whether an interrupt return would cause the thread to do something useful. The function returns KERN_SUCCESS if the thread received an interrupt and KERN_INVALID_ARGUMENT if target_thread is not a thread.

routine thread_abort_safely

Cause any user or meta- instructions currently being executed by the target thread to be aborted so that they are transparently restartable. This call fails if the abort would result in a non-restartable condition. Retry is the caller's responsibility. [Meta- instructions consist of the basic traps for IPC (e.g., msg_send, msg_receive) and self-identification (e.g., task_self, thread_self, thread_reply). Calls described by MiG interfaces are not meta-instructions themselves.]

routine thread_abort_safely(in target_act: thread_act_t)

Abort a thread, restartably.

The thread_abort_safely function aborts page faults and any message primitive calls in use by target_thread. Scheduling depressions and clock sleeps are also aborted. The call returns a code indicating that it was interrupted. The call is interrupted even if the thread (or the task containing it) is suspended. If it is suspended, the thread receives the interrupt when it resumes. If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the mach_msg library routine, which, by default, retries interrupted message calls. The basic purpose of thread_abort_safely is to let one thread cleanly stop another thread (target_thread). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When thread_abort_safely returns (if successful), the target thread will appear to have just returned from the kernel (if it had been in kernel mode).

Notes. By way of comparison, the thread_suspend function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The thread_get_state function returns the thread's user state, while thread_set_state allows modification of the user state. A problem occurs if a suspended thread had been executing within a system call. In this case, the thread has, not only a user state, but an associated kernel state. (The kernel state cannot be changed with thread_set_state.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory. For a thread executing within a system call, thread_abort_safely aborts the kernel call from the thread's point of view. Specifically, it resets the kernel state so that the thread will resume execution at the system call return, with the return code value set to one of the interrupted codes. The system call itself may completed entirely, aborted entirely or be partially completed, depending on when the abort is received. As a result, if the thread's user state has been modified by thread_set_state, it will not be altered un-predictably by any unexpected system call side effects. For example, to simulate a POSIX signal, use the following sequence of calls: thread_suspend \(emTo stop the thread. thread_abort_safely \(emTo interrupt any system call in progress and set the return value to "interrupted". Because the thread is already stopped, it will not return to user code. thread_set_state \(emTo modify the thread's user state to simulate a procedure call to the signal handler. thread_resume \(emTo resume execution at the signal handler. If the thread's stack is set up correctly, the thread can return to the interrupted system call. Note that the code to push an extra stack frame and change the registers is highly machine dependent.

Cautions. As a rule, do not use thread_abort_safely on a non-suspended thread. This operation is very risky because it is difficult to know which system trap, if any, is executing and whether an interrupt return will result in some useful action by the thread. thread_abort_safely will not abort any non-atomic operation (such as a multi-page memory_object_data_supply or exception processing) but will return an error instead. The caller of this function must then allow the thread to resume and attempt to abort it later. If the thread must be aborted, even if doing so would abort any non-atomic operations, thread_abort would be used.

The thread is in the middle of a non-restartable operation.

routine thread_depress_abort

routine thread_depress_abort(in thread: thread_act_t)

Cancel thread scheduling depression.

The thread_depress_abort function cancels any scheduling depression effective for thread caused by a thread_switch call.

kern_return_t thread_depress_abort(thread_t thread)

The function thread_depress_abort cancels any priority depression for thread caused by a swtch_pri or thread_switch call. The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if thread is not a valid thread.

routine thread_get_special_port

Returns the current value of the selected special port associated with the target thread.

routine thread_get_special_port(in thr_act: thread_inspect_t, in which_port: int, out special_port: mach_port_t)

Return a send right to the caller-specified special port.

The thread_get_special_port function returns a send right for a special port belonging to thread. The thread kernel port is a port for which the kernel holds the receive right. The kernel uses this port to identify the thread. If one thread has a send right for the kernel port of another thread, it can use the port to perform kernel operations for the other thread. Send rights for a kernel port normally are held only by the thread to which the port belongs, or by the task that contains the thread. Using the mach_msg function, however, any thread can pass a send right for its kernel port to another thread.

kern_return_t thread_get_special_port(thread_t thread, int which_port, mach_port_t *special_port)

The function thread_get_special_port returns send rights to one of a set of special ports for the thread specified by thread. The possible values for which_port are THREAD_KERNEL_PORT and THREAD_EXCEPTION_PORT. A thread also has access to its task's special ports. The function returns KERN_SUCCESS if the port was returned and KERN_INVALID_ARGUMENT if thread is not a thread or which_port is an invalid port selector.

routine thread_set_special_port

Set one of the special ports associated with the target thread.

routine thread_set_special_port(in thr_act: thread_act_t, in which_port: int, in special_port: mach_port_t)

Set caller-specified special port belonging to the target thread.

The thread_set_special_port function sets a special port belonging to thread.

kern_return_t thread_set_special_port(thread_t thread, int which_port, mach_port_t special_port)

The function thread_set_special_port sets one of a set of special ports for the thread specified by thread. The possible values for which_port are THREAD_KERNEL_PORT and THREAD_EXCEPTION_PORT. A thread also has access to its task's special ports. The function returns KERN_SUCCESS if the port was set and KERN_INVALID_ARGUMENT if thread is not a thread or which_port is an invalid port selector.

routine thread_info

Returns information about the target thread.

routine thread_info(in target_act: thread_inspect_t, in flavor: thread_flavor_t, out thread_info_out: thread_info_t)

Return information about a thread.

The thread_info function returns an information structure of type flavor.

Notes. At any given time, a thread has only one scheduling policy in effect for it. Thus, only one of the scheduling information structures will be valid, that so indicated by the policy value returned by THREAD_BASIC_INFO.

kern_return_t thread_info(thread_t target_thread, int flavor, thread_info_t thread_info, mach_msg_type_number_t *thread_infoCnt)

The function thread_info returns the selected information array for a thread, as specified by flavor. thread_info is an array of integers that is supplied by the caller and returned filled with specified information. thread_infoCnt is supplied as the maximum number of integers in thread_info. On return, it contains the actual number of integers in thread_info. The maximum number of integers returned by any flavor is THREAD_INFO_MAX. The type of information returned is defined by flavor, which can be one of the following: THREAD_BASIC_INFOThe function returns basic information about the thread, as defined by thread_basic_info_t. This includes the user and system time, the run state, and scheduling priority. The number of integers returned is THREAD_BASIC_INFO_COUNT. THREAD_SCHED_INFOThe function returns information about the scheduling policy for the thread as defined by thread_sched_info_t. The number of integers returned is THREAD_SCHED_INFO_COUNT. The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if target_thread is not a thread or flavor is not recognized. The function returns MIG_ARRAY_TOO_LARGE if the returned info array is too large for thread_info. In this case, thread_info is filled as much as possible and thread_infoCnt is set to the number of elements that would have been returned if there were enough room.

routine thread_set_exception_ports

Set an exception handler for a thread on one or more exception types

routine thread_set_exception_ports(in thread: thread_act_t, in exception_mask: exception_mask_t, in new_port: mach_port_t, in behavior: exception_behavior_t, in new_flavor: thread_state_flavor_t)

Set exception ports for a thread.

The thread_set_exception_ports function sets a specified set of exception ports belonging to thread.

Notes. If the value of the EXC_MACH_SYSCALL exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception. A "protected" exception port is one which cannot be fetched and for which exception processing cannot be aborted (thread_abort).

routine thread_get_exception_ports

Lookup some of the old exception handlers for a thread

routine thread_get_exception_ports(in thread: thread_act_t, in exception_mask: exception_mask_t, out masks: exception_mask_array_t, out old_handlers: exception_handler_array_t, out old_behaviors: exception_behavior_array_t, out old_flavors: exception_flavor_array_t)

Return a send right to an exception port.

The thread_get_exception_ports function returns send rights for a specified set of exception ports belonging to thread. The call returns a set of quadruples for each unique set of in effect for the thread where the exception type mask indicates for which exception types the other values apply.

KERN_EXCEPTION_PROTECTED

One of the requested exception ports is protected and cannot be returned.

routine thread_swap_exception_ports

Set an exception handler for a thread on one or more exception types. At the same time, return the previously defined exception handlers for those types.

routine thread_swap_exception_ports(in thread: thread_act_t, in exception_mask: exception_mask_t, in new_port: mach_port_t, in behavior: exception_behavior_t, in new_flavor: thread_state_flavor_t, out masks: exception_mask_array_t, out old_handlers: exception_handler_array_t, out old_behaviors: exception_behavior_array_t, out old_flavors: exception_flavor_array_t)

Swap exception ports for a thread.

The thread_swap_exception_ports function sets a specified set of exception ports belonging to thread, returning the old set.

KERN_EXCEPTION_PROTECTED

One of the requested exception ports is protected and cannot be returned.

routine thread_policy

OBSOLETE interface.

routine thread_policy(in thr_act: thread_act_t, in policy: policy_t, in base: policy_base_t, in set_limit: boolean_t)

Set target thread's scheduling policy state.

The thread_policy function sets the scheduling policy to be applied to thread. policy must be a scheduling policy currently "enabled" for the thread's assigned processor set.

KERN_INVALID_POLICY	The processor set to which thread is currently assigned does not currently enable policy.
KERN_POLICY_LIMIT	The specified scheduling attributes exceeds the thread's limits.

kern_return_t thread_policy(thread_t thread, int policy, int data)

The function thread_policy changes the scheduling policy for thread to policy. data is policy-dependent scheduling information. There are currently two supported policies: POLICY_TIMESHARE and POLICY_FIXEDPRI defined in mach/policy.h; this file is included by mach.h. data is meaningless for timesharing, but is the quantum to be used (in milliseconds) for the fixed priority policy. To be meaningful, this quantum must be a multiple of the basic system quantum (min_quantum) which can be obtained from host_info. The system will always round up to the next multiple of the quantum. Processor sets may restrict the allowed policies, so this call will fail if the processor set to which thread is currently assigned does not permit policy. The function returns KERN_SUCCESS if the call succeeded. KERN_INVALID_ARGUMENT if thread is not a thread or policy is not a recognized policy, and KERN_FAILURE if the processor set to which thread is currently assigned does not permit policy.

routine thread_policy_set

Set/get policy information for a thread. (Approved Mac OS X microkernel interface)

routine thread_policy_set(in thread: thread_act_t, in flavor: thread_policy_flavor_t, in policy_info: thread_policy_t)

routine thread_policy_get

routine thread_policy_get(in thread: thread_inspect_t, in flavor: thread_policy_flavor_t, out policy_info: thread_policy_t, inout get_default: boolean_t)

routine thread_sample

Removed from the kernel.

routine thread_sample(in thread: thread_act_t, in reply: mach_port_make_send_t)

Perform periodic PC sampling for a thread.

The thread_sample function causes the program counter (PC) of the specified sample_thread to be sampled periodically (whenever the thread happens to be running at the time of the kernel's "hardclock" interrupt). The set of PC sample values obtained are saved in buffers which are sent to the specified reply_port in receive_samples messages.

routine etap_trace_thread

routine etap_trace_thread(in target_act: thread_act_t, in trace_status: boolean_t)

routine thread_assign

routine thread_assign(in thread: thread_act_t, in new_set: processor_set_t)

Assign a thread to a processor set.

The thread_assign function assigns thread to the set processor_set. After the assignment is completed, the thread executes only on processors that are assigned to that processor set. Any previous assignment of the thread is nullified.

routine thread_assign_default

routine thread_assign_default(in thread: thread_act_t)

Assign a thread to the default processor set.

The thread_assign_default function assigns thread to the default processor set. After the assignment is completed, the thread executes only on processors that are assigned to that processor set. Any previous assignment of the thread is nullified.

Notes. This variant of thread_assign exists because the control port for the default processor set is privileged, and therefore not available to most tasks.

routine thread_get_assignment

routine thread_get_assignment(in thread: thread_inspect_t, out assigned_set: processor_set_name_t)

Return the processor set to which a thread is assigned.

The thread_get_assignment function returns the name port to the processor set to which thread is currently assigned. This port can only be used to obtain information about the processor set.

routine thread_set_policy

KERN_INVALID_PROCESSOR_SET

OBSOLETE interface.

routine thread_set_policy(in thr_act: thread_act_t, in pset: processor_set_t, in policy: policy_t, in base: policy_base_t, in limit: policy_limit_t)

Set target thread's scheduling policy state. (Protected Interface.)

The thread_set_policy function sets the scheduling attributes, both base and limit, for thread. policy may be any policy implemented by the processor set whether or not it is enabled.

processor_set is not the thread's processor set control port.

routine thread_get_mach_voucher

routine thread_get_mach_voucher(in thr_act: thread_read_t, in which: mach_voucher_selector_t, out voucher: ipc_voucher_t)

routine thread_set_mach_voucher

routine thread_set_mach_voucher(in thr_act: thread_act_t, in voucher: ipc_voucher_t)

routine thread_swap_mach_voucher

routine thread_swap_mach_voucher(in thr_act: thread_act_t, in new_voucher: ipc_voucher_t, inout old_voucher: ipc_voucher_t)

routine thread_convert_thread_state

routine thread_convert_thread_state(in thread: thread_act_t, in direction: int, in flavor: thread_state_flavor_t, in in_state: thread_state_t, out out_state: thread_state_t)

routine thread_get_exception_ports_info

routine thread_get_exception_ports_info(in port: mach_port_t, in exception_mask: exception_mask_t, out masks: exception_mask_array_t, out old_handlers_info: exception_handler_info_array_t, out old_behaviors: exception_behavior_array_t, out old_flavors: exception_flavor_array_t)

routine thread_adopt_exception_handler

Calls thread_set_exception_ports on thread using a previously registered hardened exception handler. Only one hardened exception handler is allowed per task.

routine thread_adopt_exception_handler(in thread: thread_t, in exc_port: mach_port_t, in exc_mask: exception_mask_t, in behavior_mask: exception_behavior_t, in flavor_mask: thread_state_flavor_t)

routine thread_suspend2

New thread suspend interface that returns a suspend token

routine thread_suspend2(in target_act: thread_read_t, out suspend_token: mach_port_move_send_t)

routine thread_resume2

New thread resume interface that takes a suspend token

routine thread_resume2(in suspend_token: mach_port_move_send_t)

vm_map (mach/vm_map.defs, 27 routines)

routine mach_make_memory_entry

Allow application level processes to create named entries which correspond to mapped portions of their address space. These named entries can then be manipulated, shared with other processes in other address spaces and ultimately mapped in ohter address spaces

routine mach_make_memory_entry(in target_task: vm_map_t, inout size: vm_size_t, in offset: vm_offset_t, in permission: vm_prot_t, out object_handle: mem_entry_name_port_move_send_t, in parent_entry: mem_entry_name_port_t)

routine vm_region

If building for Sandbox, keep NAME unchanged Returns information about the contents of the virtual address space of the target task at the specified address. The returned protection, inheritance, sharing and memory object values apply to the entire range described by the address range returned; the memory object offset corresponds to the beginning of the address range. [If the specified address is not allocated, the next highest address range is described. If no addresses beyond the one specified are allocated, the call returns KERN_NO_SPACE.]

routine vm_region(in target_task: vm_map_read_t, inout address: vm_address_t, out size: vm_size_t, in flavor: vm_region_flavor_t, out info: vm_region_info_t, out object_name: memory_object_name_t = MACH_MSG_TYPE_MOVE_SEND ctype : mach_port_t)

Return description of a virtual memory region.

The vm_region function returns information on a region within the specified task's address space. The function begins looking at address and continues until it finds an allocated region. If the input address is within a region, the function uses the start of that region. The starting address for the located region is returned in address.

Notes. This interface is machine word length specific because of the virtual address parameter.

There is no region at or beyond the specified starting address.

routine vm_inherit

Set the inheritance attribute for the specified range of the virtual address space of the target task. The inheritance value is one of {none, copy, share}, and specifies how the child address space should acquire this memory at the time of a task_create call.

routine vm_inherit(in target_task: vm_task_entry_t, in address: vm_address_t, in size: vm_size_t, in new_inheritance: vm_inherit_t)

Set a VM region's inheritance attribute.

The vm_inherit function sets the inheritance attribute for a region within the specified task's address space. The inheritance attribute determines the type of access established for child tasks at task creation. Because inheritance applies to virtual pages, the specified address and size are rounded to page boundaries, as follows: the region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than size. Use host_page_size to find the current virtual page size. A parent and a child task can share the same physical memory only if the inheritance for the memory is set to VM_INHERIT_SHARE before the child task is created. Other than through the use of an external memory manager (see vm_map), this is the only way that two tasks can share memory. Note that all the threads within a task share the task's memory.

Notes. This interface is machine word length specific because of the virtual address parameter.

The address is illegal or specifies a non-allocated region.

routine vm_read

routine vm_read(in target_task: vm_map_read_t, in address: vm_address_t, in size: vm_size_t, out data: pointer_t)

Read the specified range of target task's address space.

The vm_read and vm_read_overwrite functions read a portion of a task's virtual memory (they enable tasks to read other tasks' memory). The vm_read function returns the data in a dynamically allocated array of bytes; the vm_read_overwrite function places the data into a caller-specified buffer (the data_in parameter).

Notes. This interface is machine word length specific because of the virtual address parameter.

KERN_PROTECTION_FAILURE	Specified memory is valid, but does not permit reading.
KERN_INVALID_ADDRESS	The address is illegal or specifies a non-allocated region, or there are less than size bytes of data following the address, or the region specified by the data_in parameter cannot be written to.

routine vm_read_list

List corrollary to vm_read, returns mapped contents of specified ranges within target address space.

routine vm_read_list(in target_task: vm_map_read_t, inout data_list: vm_read_entry_t, in count: natural_t)

routine vm_write

routine vm_write(in target_task: vm_map_t, in address: vm_address_t, in data: pointer_t)

Write data to the specified address in the target task's address space.

The vm_write function writes an array of data to a task's virtual memory. It allows one task to write to another task's memory. The result of vm_write is as if target_task had directly written into the set of pages. Hence, target_task must have write permission to the pages.

Notes. This interface is machine word length specific because of the virtual address parameter.

KERN_PROTECTION_FAILURE	Specified memory is valid, but does not permit writing.
KERN_INVALID_ADDRESS	The address is illegal or specifies a non-allocated region.

routine vm_copy

routine vm_copy(in target_task: vm_map_t, in source_address: vm_address_t, in size: vm_size_t, in dest_address: vm_address_t)

Copy a region of virtual memory.

The vm_copy function copies a source region to a destination region within the same task's virtual memory. It is semantically equivalent to vm_read followed by vm_write. The destination region can overlap the source region. The destination region must already be allocated. The source region must be readable, and the destination region must be writable.

Notes. This interface is machine word length specific because of the virtual address parameter.

KERN_PROTECTION_FAILURE	The source region is protected against reading, or the destination region is protected against writing.
KERN_INVALID_ADDRESS	An address is illegal or specifies a non-allocated region, or there is not enough memory following one of the addresses.

routine vm_read_overwrite

routine vm_read_overwrite(in target_task: vm_map_read_t, in address: vm_address_t, in size: vm_size_t, in data: vm_address_t, out outsize: vm_size_t)

routine vm_msync

routine vm_msync(in target_task: vm_map_t, in address: vm_address_t, in size: vm_size_t, in sync_flags: vm_sync_t)

Synchronize the specified region of virtual memory.

The vm_msync function synchronizes the contents of a memory range with its backing store image by flushing or cleaning the contents of the specified range to the range's memory manager, engaging in a synchronization protocol with the manager (memory_object_synchronize). The client does not return from this call until the memory manager responds (to the kernel) with memory_object_synchronize_completed.

Notes. This interface is machine word length specific because of the virtual address parameter.

The address is illegal or specifies a non-allocated region.

routine vm_behavior_set

routine vm_behavior_set(in target_task: vm_map_t, in address: vm_address_t, in size: vm_size_t, in new_behavior: vm_behavior_t)

Specify expected access patterns for the target VM region.

The vm_behavior_set function informs the kernel of the expected access pattern for a region of memory. The kernel uses this information to bias its prefetch and page replacement algorithms. The region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than size. Use host_page_size to find the current virtual page size.

Notes. This interface is machine word length specific because of the virtual address parameter.

The specified address is illegal or reserved.

routine vm_map

Map a user-defined memory object into the virtual address space of the target task. If desired (anywhere is TRUE), the kernel will find a suitable address range of the specified size; else, the specific address will be allocated. The beginning address of the range will be aligned on a virtual page boundary, be at or beyond the address specified, and meet the mask requirements (bits turned on in the mask must not be turned on in the result); the size of the range, in bytes, will be rounded up to an integral number of virtual pages. The memory in the resulting range will be associated with the specified memory object, with the beginning of the memory range referring to the specified offset into the memory object. The mapping will take the current and maximum protections and the inheritance attributes specified; see the vm_protect and vm_inherit calls for a description of these attributes. If desired (copy is TRUE), the memory range will be filled with a copy of the data from the memory object; this copy will be private to this mapping in this target task. Otherwise, the memory in this mapping will be shared with other mappings of the same memory object at the same offset (in this task or in other tasks). [The Mach kernel only enforces shared memory consistency among mappings on one host with similar page alignments. The user-defined memory manager for this object is responsible for further consistency.]

routine vm_map(in target_task: vm_task_entry_t, inout address: vm_address_t, in size: vm_size_t, in mask: vm_address_t, in flags: int, in object: mem_entry_name_port_t, in offset: vm_offset_t, in copy: boolean_t, in cur_protection: vm_prot_t, in max_protection: vm_prot_t, in inheritance: vm_inherit_t)

Map the specified memory object to a region of virtual memory.

The vm_map function maps a portion of the specified memory object into the virtual address space belonging to target_task. The target task can be the calling task or another task, identified by its task kernel port. The portion of the memory object mapped is determined by offset and size. The kernel maps address to the offset, so that an access to the memory starts at the offset in the object. The mask parameter specifies additional alignment restrictions on the kernel's selection of the starting address. Uses for this mask include: Forcing the memory address alignment for a mapping to be the same as the alignment within the memory object. Quickly finding the beginning of an allocated region by performing bit arithmetic on an address known to be in the region. Emulating a larger virtual page size. The cur_protection, max_protection, and inheritance parameters set the protection and inheritance attributes for the mapped object. As a rule, at least the maximum protection should be specified so that a server can make a restricted (for example, read-only) mapping in a client atomically. The current protection and inheritance parameters are provided for convenience so that the caller does not have to call vm_inherit and vm_protect separately. The same memory object can be mapped more than once and by more than one task. If an object is mapped by multiple tasks, the kernel maintains consistency for all the mappings if they use the same page alignment for offset and are on the same host. In this case, the virtual memory to which the object is mapped is shared by all the tasks. Changes made by one task in its address space are visible to all the other tasks. The call will not return until the memory object is ready for use.

Notes. vm_map allocates a region in a task's address space and maps the specified memory object to this region. vm_allocate allocates a zero-filled temporary region in a task's address space. Before a memory object can be mapped, a port naming it must be acquired from the memory manager serving it. This interface is machine word length specific because of the virtual address parameter.

Cautions. Do not attempt to map a memory object unless it has been provided by a memory manager that implements the memory object interface. If another type of port is specified, a thread that accesses the mapped virtual memory may become permanently hung or may receive a memory exception.

KERN_NO_SPACE	There is not enough space in the task's address space to allocate the new region for the memory object.
KERN_PROTECTION_FAILURE	max_protection or cur_protection exceeds that permitted by memory_object.
KERN_INVALID_OBJECT	The memory manager failed to map the memory object.

routine vm_machine_attribute

Set/Get special properties of memory associated to some virtual address range, such as cachability, migrability, replicability. Machine-dependent.

routine vm_machine_attribute(in target_task: vm_map_t, in address: vm_address_t, in size: vm_size_t, in attribute: vm_machine_attribute_t, inout value: vm_machine_attribute_val_t)

Get/set the target memory region's special attributes.

The vm_machine_attribute function gets and sets special attributes of the memory region implemented by the underlying pmap module. These attributes are properties such as cachability, migratability and replicability. The behavior of this function is machine dependent.

Notes. This interface is machine word length specific because of the virtual address parameter.

The address is illegal or specifies a non-allocated region.

routine vm_remap

Map portion of a task's address space.

routine vm_remap(in target_task: vm_map_t, inout target_address: vm_address_t, in size: vm_size_t, in mask: vm_address_t, in flags: int, in src_task: vm_map_t, in src_address: vm_address_t, in copy: boolean_t, out cur_protection: vm_prot_t, out max_protection: vm_prot_t, in inheritance: vm_inherit_t)

Map memory objects in one task's address space to that of another task's.

The vm_remap function maps the memory objects underlying a portion of the specified source_task 's virtual address space into the address space belonging to target_task. The target task can be the calling task or another task, identified by its task kernel port. The effect is as if the target task performed a vm_map call given the same memory object, maximum protection, current protection, and inheritance as the source task. However, the two tasks must reside on the same host. The kernel maps the memory objects starting at target_address, so that access to target_address is as if the source task accessed its source_address. The mask parameter specifies additional alignment restrictions on the kernel's selection of the starting address. Uses for this mask include: Forcing the memory address alignment for a mapping to be the same as the alignment within the source task. Quickly finding the beginning of an allocated region by performing bit arithmetic on an address known to be in the region. Emulating a larger virtual page size. The cur_protection and max_protection parameters return the protection attributes for the mapped memory. If all memory within the range had the same attributes, these attributes are returned; otherwise the call returns the most restrictive values for any memory in the region.

Notes. This interface is machine word length specific because of the virtual address parameter.

KERN_NO_SPACE	There is not enough space in the task's address space to allocate the new region for the memory object.
KERN_PROTECTION_FAILURE	Specified memory is valid, but the backing memory manager is not permitted by the requesting task.

routine task_wire

Require that all future virtual memory allocation allocates wired memory. Setting must_wire to FALSE disables the wired future feature.

routine task_wire(in target_task: vm_map_t, in must_wire: boolean_t)

routine vm_map_page_query

Give the caller information on the given location in a virtual address space. If a page is mapped return ref and dirty info.

routine vm_map_page_query(in target_map: vm_map_read_t, in offset: vm_offset_t, out disposition: integer_t, out ref_count: integer_t)

routine mach_vm_region_info

Returns information about a region of memory. Includes info about the chain of objects rooted at that region. Only available in MACH_VM_DEBUG compiled kernels, otherwise returns KERN_FAILURE.

routine mach_vm_region_info(in task: vm_map_read_t, in address: vm_address_t, out region: vm_info_region_t, out objects: vm_info_object_array_t)

routine vm_mapped_pages_info

routine vm_mapped_pages_info(in task: vm_map_read_t, out pages: page_address_array_t)

routine vm_region_recurse

was vm_region_object_create A recursive form of vm_region which probes submaps withint the address space.

routine vm_region_recurse(in target_task: vm_map_read_t, inout address: vm_address_t, out size: vm_size_t, inout nesting_depth: natural_t, out info: vm_region_recurse_info_t)

routine vm_region_recurse_64

The routines below are temporary, meant for transitional use as their counterparts are moved from 32 to 64 bit data path

routine vm_region_recurse_64(in target_task: vm_map_read_t, inout address: vm_address_t, out size: vm_size_t, inout nesting_depth: natural_t, out info: vm_region_recurse_info_t)

routine mach_vm_region_info_64

routine mach_vm_region_info_64(in task: vm_map_read_t, in address: vm_address_t, out region: vm_info_region_64_t, out objects: vm_info_object_array_t)

routine vm_region_64

routine vm_region_64(in target_task: vm_map_read_t, inout address: vm_address_t, out size: vm_size_t, in flavor: vm_region_flavor_t, out info: vm_region_info_t, out object_name: memory_object_name_t = MACH_MSG_TYPE_MOVE_SEND ctype : mach_port_t)

routine mach_make_memory_entry_64

routine mach_make_memory_entry_64(in target_task: vm_map_t, inout size: memory_object_size_t, in offset: memory_object_offset_t, in permission: vm_prot_t, out object_handle: mach_port_move_send_t, in parent_entry: mem_entry_name_port_t)

routine vm_map_64

routine vm_map_64(in target_task: vm_task_entry_t, inout address: vm_address_t, in size: vm_size_t, in mask: vm_address_t, in flags: int, in object: mem_entry_name_port_t, in offset: memory_object_offset_t, in copy: boolean_t, in cur_protection: vm_prot_t, in max_protection: vm_prot_t, in inheritance: vm_inherit_t)

routine vm_purgable_control

was vm_upl_unmap Control behavior and investigate state of a "purgable" object in the virtual address space of the target task. A purgable object is created via a call to vm_allocate() with VM_FLAGS_PURGABLE specified. See the routine implementation for a complete definition of the routine.

routine vm_purgable_control(in target_task: vm_map_t, in address: vm_address_t, in control: vm_purgable_t, inout state: int)

routine vm_map_exec_lockdown

routine vm_map_exec_lockdown(in target_task: vm_map_t)

routine vm_remap_new

routine vm_remap_new(in target_task: vm_map_t, inout target_address: vm_address_t, in size: vm_size_t, in mask: vm_address_t, in flags: int, in src_task: vm_map_read_t, in src_address: vm_address_t, in copy: boolean_t, inout cur_protection: vm_prot_t, inout max_protection: vm_prot_t, in inheritance: vm_inherit_t)

routine vm_reallocate