Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

20

Mach Functions

C-Thread Functions

This section contains a summary of the C-thread functions, which are described in detail in the NeXTSTEP Operating System Software manual. To use the C-thread functions, include in your source files the header file mach/cthreads.h:

#include <mach/cthreads.h>

Basic C-Thread Functions Control a thread

	cthread_t	cthread_fork(any_t (*function)(), any_t arg)
	any_t	cthread_join(cthread_t t)
	void	cthread_detach(cthread_t t)
	void	cthread_yield()
	kern_return_t	cthread_abort(cthread_t t)
	void	cthread_exit(any_t result)

Get access to a thread

	cthread_t	cthread_self()
	thread_t	cthread_thread(cthread_t t)

Associate a string with a thread

	char *	cthread_name(cthread_t t)
	void	cthread_set_name(cthread_t t, char *name)

Associate data with a thread

	any_t	cthread_data(cthread_t t)
	void	cthread_set_data(cthread_t t, any_t data)

Change the priority of a thread

	kern_return_t	cthread_max_priority(cthread_t t, processor_set_t processor_set, int max_priority)
	kern_return_t	cthread_priority(cthread_t t, int priority, boolean_t set_max)

Get or set the UNIXTMerror number of this thread

	int	cthread_errno()
	void	cthread_set_errno_self(int error)

Get or set the maximum number of threads in this task

	int	cthread_limit()
	void	cthread_set_limit(int limit)
	int	cthread_count()

Mutex Functions Control a mutex

	mutex_t	mutex_alloc()
	void	mutex_init(struct mutex *m)
	void	mutex_clear(struct mutex *m)
	void	mutex_free(mutex_t m)

Associate a string with a mutex

	char *	mutex_name(mutex_t m)
	void	mutex_set_name(mutex_t m, char *name)

Synchronize a mutex

	void	mutex_lock(mutex_t m)
	int	mutex_try_lock(mutex_t m)
	void	mutex_unlock(mutex_t m)

Condition Functions Control a condition variable

	condition_t	condition_alloc()
	void	condition_init(struct condition *c)
	void	condition_clear(struct condition *c)
	void	condition_free(condition_t c)

Associate a string with a condition variable

	char *	condition_name(condition_t c)
	void	condition_set_name(condition_t c, char *name)

Synchronize a condition variable

	void	condition_broadcast(condition_t c)
	void	condition_signal(condition_t c)
	void	condition_wait(condition_t c, mutex_t m)

Mach Kernel Functions

The Mach kernel is introduced in the Operating System Software manual.  This section contains a summary of the Mach kernel functions, which are described in detail in Operating System Software. To use the Mach kernel functions, include in your source files the header file mach/mach.h:

#include <mach/mach.h>

To use the Mach message functions, also include in your source files the header file mach/message.h:

#include <mach/mach.h>
#include <mach/message.h>

To use the Mach error string functions, include the header file mach/error.h, in addition to mach/mach.h:

#include <mach/mach.h>
#include <mach/error.h>

Task Functions Control a task:

	kern_return_t	task_create(task_t parent_task, boolean_t inherit_memory, task_t *child_task)
	kern_return_t	task_suspend(task_t target_task)
	kern_return_t	task_resume(task_t target_task)
	kern_return_t	task_terminate(task_t target_task)

Access a task or its threads:

	kern_return_t	task_threads(task_t target_task, thread_array_t *thread_list, unsigned int *thread_count)
	kern_return_t	task_info(task_t target_task, int flavor, task_info_t task_info, unsigned int *task_info_count)

Access a task's special ports:

	kern_return_t	task_get_special_port(task_t task, int which_port, port_t *special_port)
	kern_return_t	task_set_special_port(task_t task, int which_port, port_t special_port)
	port_t	task_notify()
	task_t	task_self()

Translate between Mach task and UNIX process ID:

	kern_return_t	task_by_unix_pid(task_t task, int pid, task_t *result_task)
	kern_return_t	unix_pid(task_t target_task, int *pid)

Set a task's scheduling priority:

kern_return_t

task_priority(task_t task, int priority, boolean_t change_threads)

Multiprocessor functions (not useful on single-processor systems):

	kern_return_t	task_assign(task_t task, processor_set_t new_processor_set, boolean_t assign_threads)
	kern_return_t	task_assign_default(task_t task, boolean_t assign_threads)
	kern_return_t	task_get_assignment(task_t task, processor_set_t *processor_set)

Thread Functions Control a thread:

	kern_return_t	thread_create(task_t parent_task, thread_t *child_thread)
	kern_return_t	thread_suspend(thread_t target_thread)
	kern_return_t	thread_resume(thread_t target_thread)
	kern_return_t	thread_terminate(thread_t target_thread)
	kern_return_t	thread_abort(thread_t target_thread)

Get information about a thread:

	kern_return_t	thread_info(thread_t target_thread, int flavor, thread_info_t thread_info,
		unsigned int *thread_info_count)

Access a thread's state:

	kern_return_t	thread_get_state(thread_t target_thread, int flavor, thread_state_data_t old_state, unsigned int *old_state_count)
	kern_return_t	thread_set_state(thread_t target_thread, int flavor, thread_state_data_t new_state, unsigned int new_state_count)

Access a thread's special ports:

	kern_return_t	thread_get_special_port(thread_t thread, int which_port, port_t *special_port)
	kern_return_t	thread_set_special_port(thread_t thread, int which_port, port_t special_port)
	port_t	thread_reply()
	thread_t	thread_self()

Affect the scheduling policy or priority of a thread:

	kern_return_t	thread_policy(thread_t thread, int policy, int data)
	kern_return_t	thread_priority(thread_t thread, int priority, boolean_t set_max)
	kern_return_t	thread_max_priority(thread_t thread, processor_set_t processor_set, int priority)
	kern_return_t	thread_switch(thread_t new_thread, int option, int time)

Multiprocessor functions (not useful on single-processor systems):

	kern_return_t	thread_assign(thread_t thread, processor_set_t new_processor_set)
	kern_return_t	thread_assign_default(thread_t thread)
	kern_return_t	thread_get_assignment(thread_t thread, processor_set_t *processor_set)

Port Functions Control a port:

	kern_return_t	port_allocate(task_t task, port_name_t *port_name)
	kern_return_t	port_deallocate(task_t task, port_name_t port_name)
	kern_return_t	port_rename(task_t task, port_name_t old_name, port_name_t new_name)
	kern_return_t	port_set_backlog(task_t task, port_name_t port_name, int backlog)

Give a task rights to a port:

	kern_return_t	port_insert_receive(task_t task, port_t my_port, port_name_t its_name)
	kern_return_t	port_insert_send(task_t task, port_t my_port, port_name_t its_name)

Remove a task's rights to a port:

	kern_return_t	port_extract_receive(task_t task, port_name_t its_name, port_t *its_port)
	kern_return_t	port_extract_send(task_t task, port_name_t its_name, port_t *its_port)

Get information about a port:

	kern_return_t	port_status(task_t task, port_name_t port_name, port_set_name_t *port_set_name, int *num_msgs, int *backlog, boolean_t *owner, boolean_t *receiver)
	kern_return_t	port_type(task_t task, port_name_t port_name, port_type_t *port_type)

Get information about a task's port name space:

kern_return_t

port_names(task_t task, port_name_array_t *port_names, unsigned int *port_names_count, port_type_array_t *port_types, unsigned int *port_types_count)

Control a port set:

	kern_return_t	port_set_allocate(task_t task, port_set_name_t *set_name)
	kern_return_t	port_set_backup(task_t task, port_name_t port_name, port_t backup, port_t *previous)
	kern_return_t	port_set_deallocate(task_t task, port_set_name_t set_name)

Access or modify a port set:

	kern_return_t	port_set_add(task_t task, port_set_name_t set_name, port_name_t port_name)
	kern_return_t	port_set_remove(task_t task, port_name_t port_name)
	kern_return_t	port_set_status(task_t task, port_set_name_t set_name, port_name_array_t *members, unsigned int *members_count)

Message Functions Send or receive a message:

	msg_return_t	msg_send(msg_header_t *header, msg_option_t option, msg_timeout_t timeout)
	msg_return_t	msg_receive(msg_header_t *header, msg_option_t option, msg_timeout_t timeout)
	msg_return_t	msg_rpc(msg_header_t *header, msg_option_t option, msg_size_t rcv_size, msg_timeout_t send_timeout, msg_timeout_t rcv_timeout)

Virtual Memory Functions Control virtual memory:

	kern_return_t	vm_allocate(vm_task_t target_task, vm_address_t *address, vm_size_t size, boolean_t anywhere)
	kern_return_t	vm_deallocate(vm_task_t target_task, vm_address_t address, vm_size_t size)
	kern_return_t	vm_protect(vm_task_t target_task, vm_address_t address, vm_size_t size, boolean_t set_maximum, vm_prot_t new_protection)
	kern_return_t	vm_inherit(vm_task_t target_task, vm_address_t address, vm_size_t size, vm_inherit_t new_inheritance)
	kern_return_t	vm_deactivate(vm_task_t target_task, vm_address_t address, vm_size_t size, int when)
	kern_return_t	vm_set_policy(vm_task_t target_task, vm_address_t address, vm_size_t size, int policy)

Access or modify the contents of virtual memory:

	kern_return_t	vm_copy(vm_task_t target_task, vm_address_t source_address, vm_size_t size, vm_address_t dest_address)
	kern_return_t	vm_read(vm_task_t target_task, vm_address_t address, vm_size_t size, pointer_t *data, unsigned int *data_count)
	kern_return_t	vm_write(vm_task_t target_task, vm_address_t address, pointer_t data, unsigned int data_count)
	kern_return_t	map_fd(int fd, vm_offset_t offset, vm_offset_t *address, boolean_t find_space, vm_size_t size)

Get information about virtual memory:

	kern_return_t	vm_region(vm_task_t target_task, vm_address_t *address, vm_size_t *size, vm_prot_t *protection, vm_prot_t *max_protection, vm_inherit_t *inheritance, boolean_t *shared, port_t *object_name, vm_offset_t *offset)
	kern_return_t	vm_statistics(vm_task_t target_task, vm_statistics_data_t *vm_stats)

Host Functions Get this host's port:

	host_t	host_self()
	host_priv_t	host_priv_self()

Get information about a host:

	kern_return_t	host_info(host_t host, int flavor, host_info_t host_info, unsigned int *host_info_count)
	kern_return_t	host_kernel_version(host_t host, kernel_version_t version)

Get the name or privileged port of a processor set:

	kern_return_t	host_processor_set_priv(host_priv_t host_priv, processor_set_t processor_set_name, processor_set_t *processor_set)
	kern_return_t	host_processor_sets(host_t host, processor_set_name_array_t *processor_set_list, unsigned int *processor_set_count)

Get the ports of all processors on a host:

kern_return_t

host_processors(host_priv_t host_priv, processor_array_t *processor_list, unsigned int *processor_count)

Processor Functions Get information about a processor:

kern_return_t

processor_info(processor_t processor, int flavor, host_t *host, processor_info_t processor_info, unsigned int *processor_info_count)

Get the name of the default processor set:

kern_return_t

processor_set_default(host_t host, processor_set_t *default_set)

Change the allowed scheduling policies of a processor set:

	kern_return_t	processor_set_policy_enable(processor_set_t processor_set, int policy)
	kern_return_t	processor_set_policy_disable(processor_set_t processor_set, int policy, boolean_t change_threads)

Get information about a processor set:

	kern_return_t	processor_set_info(processor_set_t processor_set, int flavor, host_t *host, processor_set_info_t processor_set_info, unsigned int *processor_set_info_count)
	kern_return_t	processor_set_tasks(processor_set_t processor_set, task_array_t *task_list, unsigned int *task_count)
	kern_return_t	processor_set_threads(processor_set_t processor_set, thread_array_t *thread_list, unsigned int *thread_count)

Multiprocessor functions (not useful on single-processor systems):

	kern_return_t	processor_assign(processor_t processor, processor_set_t new_processor_set, boolean_t wait)
	kern_return_t	processor_control(processor_t processor, processor_info_t info, long *count)
	kern_return_t	processor_exit(processor_t processor)
	kern_return_t	processor_get_assignment(processor_t processor, processor_set_t *processor_set)
	kern_return_t	processor_start(processor_t processor)
	kern_return_t	processor_set_create(host_t host, port_t *new_set, port_t *new_name)
	kern_return_t	processor_set_destroy(processor_set_t processor_set)
	kern_return_t	processor_set_max_priority(processor_set_t processor_set, int max_priority, boolean_t change_threads)

Exception Functions Raise or handle exceptions:

	kern_return_t	exception_raise(port_t exception_port, port_t clear_port, port_t thread, port_t task, int exception, int code, int subcode)
	void	mach_NeXT_exception(char *string, int exception, int code, int subcode)
	char *	mach_NeXT_exception_string(int exception, int code, int subcode)
	boolean_t	exc_server(msg_header_t *in, msg_header_t *out)

Error String Functions Display or get a Mach error string:

	void	mach_error(char *string, kern_return_t errno)
	char *	mach_error_string(kern_return_t errno)

Network Name Server Functions

This section summarizes the Mach Network Name Server functions, which are not part of the Mach kernel.  For more information see the Operating System Software manual.  To use the Network Name Server functions, include in your source files the header files mach/mach.h and servers/netname.h:

#include <mach/mach.h>
#include <servers/netname.h>

Check a name into or out of the local name space:

	kern_return_t	netname_check_in(port_t server_port, netname_name_t port_name, port_t signature, port_t port_id)
	kern_return_t	netname_check_out(port_t server_port, netname_name_t port_name, port_t signature)

Look up a name on a specific host:

kern_return_t

netname_look_up(port_t server_port, netname_name_t host_name, netname_name_t port_name, port_t *port_id)

Bootstrap Server Functions

This section contains a summary of the Bootstrap Server functions, which are described in detail in the Operating System Software manual. To use a Bootstrap Server function, include in your source files the header files mach/mach.h and servers/bootstrap.h:

#include <mach/mach.h>
#include <servers/bootstrap.h>

Look up a service:

	kern_return_t	bootstrap_look_up(port_t bootstrap_port, name_t service_name, port_t *service_port)
	kern_return_t	bootstrap_look_up_array(port_t bootstrap_port, name_array_t service_names, unsigned int service_names_count, port_array_t *service_port, unsigned int *service_ports_count, boolean_t *all_services_known)

Find out whether a service is active:

kern_return_t

bootstrap_status(port_t bootstrap_port, name_t service_name, boolean_t *service_active®)

Get information about all known services:

kern_return_t

bootstrap_info(port_t bootstrap_port, name_array_t *service_names, unsigned int *service_names_count, name_array_t *server_names, unsigned int *server_names_count, bool_array_t *service_active, unsigned int *service_active_count)

Check in a service:

	kern_return_t	bootstrap_check_in(port_t bootstrap_port, name_t service_name, port_all_t *service_port)
	kern_return_t	bootstrap_create_service(port_t bootstrap_port, name_t service_name, port_t *service_port)
	kern_return_t	bootstrap_register(port_t bootstrap_port, name_t service_name, port_t service_port)

Create a new bootstrap port:

kern_return_t

bootstrap_subset(port_t bootstrap_port, port_t requestor_port, port_t *subset_port)

Kernel-Server Loader Functions

This section contains a summary of the kernel-server loader functions, which are described in detail in the Operating System Software manual.  Use these functions in a user-level program to communicate with the kernel-server loader, which controls all loadable kernel servers. To use these functions, include in your source files the header files mach/mach.h and kernserv/kern_loader_types.h.  Most functions also require that you include the header file kernserv/kern_loader.h; the error functions require that you include the header file kernserv/kern_loader_error.h.  Two other header files may be necessary:  kernserv/kern_loader_reply_handler.h and kernserv/kern_loader_reply.h. To use these functions, you must compile with the kernload library.  For example:

cc myprog.c -lkernload

Get a port to use in other kernel-server loader functions:

	kern_return_t	kern_loader_look_up(port_t *loader_port)
	kern_return_t	kern_loader_server_com_port(port_t loader_port, port_t task_port, server_name_t server_name, port_t *server_com_port)

Get or display an error string:

	void	kern_loader_error(const char *string, kern_return_t errno)
	const char *	kern_loader_error_string(kern_return_t errno)

Affect the runnability of a loadable kernel server:

	kern_return_t	kern_loader_add_server(port_t loader_port, port_t task_port, server_reloc_t server_reloc)
	kern_return_t	kern_loader_delete_server(port_t loader_port, port_t task_port, server_name_t server_name)
	kern_return_t	kern_loader_load_server(port_t loader_port, server_name_t server_name)
	kern_return_t	kern_loader_unload_server(port_t loader_port, port_t task_port, server_name_t server_name)

Get information from or about a loaded kernel server:

	kern_return_t	kern_loader_get_log(port_t loader_port, port_t server_com_port, port_t reply_port)
	kern_return_t	kern_loader_log_level(port_t loader_port, port_t server_com_port, int log_level)
	kern_return_t	kern_loader_server_info(port_t loader_port, port_t task_port, server_name_t server_name, server_state_t *server_state, vm_address_t *load_address, vm_size_t *load_size, server_reloc_t relocatable, server_reloc_t loadable, port_name_array_t *port_list, unsigned int *port_list_count, port_name_string_array_t *port_names, unsigned int *port_names_count, boolean_array_t *advertised, unsigned int *advertised_count)
	kern_return_t	kern_loader_server_task_port(port_t loader_port, port_t kernel_port, server_name_t server_name, port_t *server_task_port)

Get general information from the kernel-server loader:

	kern_return_t	kern_loader_server_list(port_t loader_port, server_name_array_t *server_names, unsigned int *server_names_count)
	kern_return_t	kern_loader_status_port(port_t loader_port, port_t listen_port)

Request or handle an asynchronous message from the kernel-server loader:

	kern_return_t	kern_loader_ping(port_t loader_port, port_t ping_port, int id)
	kern_return_t	kern_loader_reply_handler(msg_header_t *msg, kern_loader_reply_t *kern_loader_reply)

Shut down or reconfigure the kernel-server loader:

kern_return_t

kern_loader_abort(port_t loader_port, port_t priv_port, boolean_t restart)