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

4

Mach Functions

This chapter gives detailed descriptions of the C functions provided by the NeXT Mach operating system.  It also describes some macros that behave like functions.  For this chapter, the functions and macros are divided into five groups:

		C-thread functions--Use these to implement multiple threads in an application.
		Mach kernel functions--Use these to get access to the Mach operating system.
		Bootstrap Server functions--Use these to set up communication between the task that provides a local service and the tasks that use the service.
		Network Name Server functions--Use these to set up communication between tasks that might not be on the same machine.
		Kernel-server loader functions--Use these to load and unload loadable kernel servers, to add and delete servers to and from the kernel-server loader, and to get information about servers.

Within each section, functions are subgrouped with other functions that perform related tasks.  These subgroups are described in alphabetical order by the name of the first function listed in the subgroup.  Functions within subgroups are also listed alphabetically, with a pointer to the subgroup description. For convenience, these functions are summarized in the NEXTSTEP Programming Interface Summary.  The summary lists functions by the same subgroups used in this chapter and combines several related subgroups under a heading such as "Basic C-Thread Functions" or "Task Functions."  For each function, the summary shows the calling sequence.

C-Thread Functions

These functions provide a C language interface to the low-level, language-independent primitives for manipulating threads of control. In a multithreaded application, you should use the C-thread functions whenever possible, rather than Mach kernel functions.  If you need to call a Mach kernel function that requires a thread_t argument, you can find the Mach thread that corresponds to a particular C thread by calling cthread_thread(). condition_alloc(), mutex_alloc()

SUMMARY Create a condition or mutex object SYNOPSIS #import <mach/cthreads.h>

condition_t condition_alloc(void) mutex_t mutex_alloc(void)

DESCRIPTION The macros condition_alloc() and mutex_alloc() provide dynamic allocation of condition and mutex objects.  When you're finished using these objects, you can deallocate them using condition_free() and mutex_free(). EXAMPLE my_condition = condition_alloc();

my_mutex = mutex_alloc();

SEE ALSO condition_init(), mutex_init(), condition_free(), mutex_free()

condition_broadcast()

SUMMARY Broadcast a condition SYNOPSIS #import <mach/cthreads.h>

void condition_broadcast(condition_t c)

DESCRIPTION The macro condition_broadcast() wakes up all threads that are waiting (with condition_wait()) for the condition c.  This macro is similar to condition_signal(), except that condition_signal() doesn't wake up every waiting thread. EXAMPLE any_t listen(any_t arg)

{
mutex_lock(my_mutex);
while(!data)
condition_wait(my_condition, my_mutex);
/* . . . */
mutex_unlock(my_mutex);

mutex_lock(printing);
printf("Condition has been met\n");
mutex_unlock(printing);
}

main()
{
my_condition = condition_alloc();
my_mutex = mutex_alloc();
printing = mutex_alloc();

cthread_detach(cthread_fork((cthread_fn_t)listen, (any_t)0));

mutex_lock(my_mutex);
data = 1;
mutex_unlock(my_mutex);
condition_broadcast(my_condition);
/* . . . */
}

SEE ALSO condition_signal(), condition_wait()

condition_clear(), mutex_clear()

SUMMARY Clear a condition or mutex object SYNOPSIS #import <mach/cthreads.h>

void condition_clear(struct condition *c) void mutex_clear(struct mutex *m)

DESCRIPTION You must call one of these macros before freeing an object of type struct condition or struct mutex.  See the discussion of condition_init() and mutex_init() for information on why you might want to use these types instead of condition_t and mutex_t. EXAMPLE struct mystruct {

my_data_t     data;
struct mutex  m;
};
struct mystruct  *mydata;
mydata = (struct mystruct *)malloc(sizeof (struct mystruct));

mutex_init(&mydata->m);
/* . . . */
mutex_lock(&mydata->m);
/* Do something to mydata that only one thread can do. */
mutex_unlock(&mydata->m);
/* . . . */
mutex_clear(&mydata->m);
free(mydata);

SEE ALSO condition_init(), mutex_init(), condition_free(), mutex_free()

condition_free(), mutex_free()

SUMMARY Deallocate a condition or mutex object SYNOPSIS #import <mach/cthreads.h>

void condition_free(condition_t c) void mutex_free(mutex_t m)

DESCRIPTION The macros condition_free() and mutex_free() let you deallocate condition and mutex objects that were allocated dynamically. Before deallocating such an object, you must guarantee that no other thread will reference it.  In particular, a thread blocked in mutex_lock() or condition_wait() should be viewed as referencing the object continually; freeing the object out from under such a thread is erroneous, and can result in bugs that are extremely difficult to track down. SEE ALSO condition_alloc(), mutex_alloc(), condition_clear(), mutex_clear()

condition_init(), mutex_init()

SUMMARY Initialize a condition variable or mutex SYNOPSIS #import <mach/cthreads.h>

void condition_init(struct condition *c) void mutex_init(struct mutex *m)

DESCRIPTION The macros condition_init() and mutex_init() initialize an object of the struct condition or struct mutex referent type, so that its address can be used wherever an object of type condition_t or mutex_t is expected.  Initialization of the referent type is most often used when you have included the referent type itself (rather than a pointer) in a larger structure, for more efficient storage allocation.

For instance, a data structure might contain a component of type struct mutex to allow each instance of that structure to be locked independently.  During initialization of the instance, you would call mutex_init() on the struct mutex component.  The alternative of using a mutex_t component and initializing it using mutex_alloc() would be less efficient. If you're going to free a condition or mutex object of type struct condition or struct mutex, you should first clear it using condition_clear() or mutex_clear().

EXAMPLE struct mystruct {

my_data_t     data;
struct mutex  m;
};
struct mystruct  *mydata;
mydata = (struct mystruct *)malloc(sizeof (struct mystruct));

mutex_init(&mydata->m);
/* . . . */
mutex_lock(&mydata->m);
/* Do something to mydata that only one thread can do. */
mutex_unlock(&mydata->m);
/* . . . */
mutex_clear(&mydata->m);
free(mydata);

SEE ALSO condition_alloc(), mutex_alloc(), condition_clear(), mutex_clear()

condition_name(), condition_set_name(), mutex_name(), mutex_set_name()

SUMMARY Associate a string with a condition or mutex variable SYNOPSIS #import <mach/cthreads.h>

char *condition_name(condition_t c) void condition_set_name(condition_t c, char *name) char *mutex_name(mutex_t m) void mutex_set_name(mutex_t m, char *name)

DESCRIPTION These macros let you associate a name with a condition or a mutex object.  The name is used when trace information is displayed.  You can also use this name for your own application-dependent purposes. EXAMPLE /* Do something if this is a "TYPE 1" condition. */

if (strcmp(condition_name(c), "TYPE 1") == 0)
/* Do something. */;

condition_signal()

SUMMARY Signal a condition SYNOPSIS #import <mach/cthreads.h>

void condition_signal(condition_t c)

DESCRIPTION The macro condition_signal() should be called when one thread needs to indicate that the condition represented by the condition variable is now true.  If any other threads are waiting (using condition_wait()), at least one of them will be awakened. If no threads are waiting, nothing happens.  The macro condition_broadcast() is similar to this one, except that it wakes up all threads that are waiting. EXAMPLE any_t listen(any_t arg)

{
mutex_lock(my_mutex);
while(!data)
condition_wait(my_condition, my_mutex);
/* . . . */
mutex_unlock(my_mutex);

mutex_lock(printing);
printf("Condition has been met\n");
mutex_unlock(printing);
}

main()
{
my_condition = condition_alloc();
my_mutex = mutex_alloc();
printing = mutex_alloc();

cthread_detach(cthread_fork((cthread_fn_t)listen, (any_t)0));

mutex_lock(my_mutex);
data = 1;
mutex_unlock(my_mutex);
condition_signal(my_condition);
/* . . . */
}

SEE ALSO condition_broadcast(), condition_wait()

condition_wait()

SUMMARY Wait on a condition SYNOPSIS #import <mach/cthreads.h>

void condition_wait(condition_t c, mutex_t m)

DESCRIPTION The function condition_wait() unlocks the mutex it takes as a argument, suspends the calling thread until the specified condition is likely to be true, and locks the mutex again when the thread resumes.  There's no guarantee that the condition will be true when the thread resumes, so this function should always be used as follows:

mutex_t m;
condition_t c;

mutex_lock(m);
/* . . . */
while    (/* condition isn't true */)
condition_wait(c, m);
/* . . . */
mutex_unlock(m);

SEE ALSO condition_broadcast(), condition_signal()

cthread_abort()

SUMMARY Interrupt a C thread SYNOPSIS #import <mach/cthreads.h>

kern_return_t cthread_abort(cthread_t t)

DESCRIPTION This function provides the functionality of thread_abort() to C threads.  The cthread_abort() function interrupts system calls; it's usually used along with thread_suspend(), which stops a thread from executing any more user code.  Calling cthread_abort() on a thread that isn't suspended is risky, since it's 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.

See thread_abort() for a full description of the use of this function. cthread_count()

SUMMARY Get the number of threads in this task SYNOPSIS #import <mach/cthreads.h>

int cthread_count()

DESCRIPTION This function returns the number of threads that exist in the current task.  You can use this function to help make sure that your task doesn't create too many threads (over 200 or so).  See cthread_set_limit() for information on restricting the number of threads in a task. EXAMPLE printf("C thread count should be 1, is %d\n", cthread_count());

cthread_detach(cthread_fork((cthread_fn_t)listen, (any_t)0));
printf("C thread count should be 2, is %d\n", cthread_count());

SEE ALSO cthread_limit(), cthread_set_limit()

cthread_data(), cthread_set_data()

SUMMARY Associate data with a thread SYNOPSIS #import <mach/cthreads.h>

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

DESCRIPTION The macros cthread_data() and cthread_set_data() let you associate arbitrary data with a thread, providing a simple form of thread-specific "global" variable.  More elaborate mechanisms, such as per-thread property lists or hash tables, can then be built with these macros. EXAMPLE int listen(any_t arg)

{
mutex_lock(printing);
printf("This thread's data is: %d\n",
(int)cthread_data(cthread_self()));
mutex_unlock(printing);
/* . . . */
}

main()
{
cthread_t lthread;

printing = mutex_alloc();

lthread = cthread_fork((cthread_fn_t)listen, (any_t)0);
cthread_set_data(lthread, (any_t)100);
cthread_detach(lthread);
/* . . . */
}

SEE ALSO cthread_name(), cthread_set_name()

cthread_detach()

SUMMARY Detach a thread SYNOPSIS #import <mach/cthreads.h>

void cthread_detach(cthread_t t)

DESCRIPTION The function cthread_detach() is used to indicate that cthread_join() will never be called on the given thread.  This is usually known at the time the thread is forked, so the most efficient usage is the following:

cthread_detach(cthread_fork(function, argument)); A thread may, however, be detached at any time after it's forked, as long as no other attempt is made to join it or detach it.

EXAMPLE cthread_detach(cthread_fork((cthread_fn_t)listen, (any_t)reply_port)); SEE ALSO cthread_fork(), cthread_join()

cthread_errno()

SUMMARY Get a thread's errno value SYNOPSIS #import <mach/cthreads.h>

int cthread_errno(void)

DESCRIPTION Use the cthread_errno() function to get the errno value for the current thread.  In the UNIX operating system, errno is a process-wide global variable that's set to an error number when a UNIX system call fails.  However, because Mach has multiple threads per process, Mach keeps errno information on a per-thread basis as well as in errno.

Like the value of errno, the value returned by cthread_errno() is valid only if the last UNIX system call returned 1.  Errno values are defined in the header file bsd/sys/errno.h.

EXAMPLE int ret;

ret = chown(FILEPATH, newOwner, newGroup);
if (ret == -1) {
if (cthread_errno() == ENAMETOOLONG)
/* . . . */
}

SEE ALSO cthread_set_errno(), intro(2) UNIX manual page

cthread_exit()

SUMMARY Exit a thread SYNOPSIS #import <mach/cthreads.h>

void cthread_exit(any_t result)

DESCRIPTION The function cthread_exit() terminates the calling thread.  The result is passed to the thread that joins the caller, or is discarded if the caller is detached.

An implicit cthread_exit() occurs when the top-level function of a thread returns, but it may also be called explicitly.

EXAMPLE cthread_exit(0); SEE ALSO cthread_detach(), cthread_fork(), cthread_join()

cthread_fork()

SUMMARY Fork a thread SYNOPSIS #import <mach/cthreads.h>

cthread_t cthread_fork(any_t (*function)(), any_t arg)

DESCRIPTION The function cthread_fork() takes two arguments:  a function for the new thread to execute, and an argument to this function. The cthread_fork() function creates a new thread of control in which the specified function is executed concurrently with the caller's thread.  This is the sole means of creating new threads.

The any_t type represents a pointer to any C type.  The cthread_t type is an integer-size handle that uniquely identifies a thread of control.  Values of type cthread_t will be referred to as thread identifiers.  Arguments larger than a pointer must be passed by reference.  Similarly, multiple arguments must be simulated by passing a pointer to a structure containing several components.  The call to cthread_fork() returns a thread identifier that can be passed to cthread_join() or cthread_detach(). Every thread must be either joined or detached exactly once.

EXAMPLE cthread_detach(cthread_fork((cthread_fn_t)listen, (any_t)reply_port)); SEE ALSO cthread_detach(), cthread_exit(), cthread_join()

cthread_join()

SUMMARY Join threads SYNOPSIS #import <mach/cthreads.h>

any_t cthread_join(cthread_t t)

DESCRIPTION The function cthread_join() suspends the caller until the specified thread t terminates.  The caller receives either the result of t's top-level function or the argument with which t explicitly called cthread_exit().

Attempting to join one's own thread results in deadlock.

EXAMPLE cthread_t t;

t = cthread_fork((any_t (*)())listen, (any_t)reply_port);
/* . . . (Do some work, perhaps forking other threads.) */
result = cthread_join(t);  /* Wait for the thread to finish executing. */
/* . . . (Continue doing work) */

SEE ALSO cthread_detach(), cthread_exit(), cthread_fork()

cthread_limit(), cthread_set_limit()

SUMMARY Get or set the maximum number of threads in this task SYNOPSIS #import <mach/cthreads.h>

int cthread_limit(void) void cthread_set_limit(int limit)

ARGUMENTS limit:  The new maximum number of C threads per task.  Specify zero if you want no limit. DESCRIPTION These functions can help you to avoid creating too many threads.  The danger in creating a large number of threads is that the kernel might run out of resources and panic.  Usually, a task should avoid creating more than about 200 threads.

Use cthread_set_limit() to set a limit on the number of threads in the current task.  When the limit is reached, new C threads will appear to fork successfully.  However, they will have no associated Mach thread, so they won't do anything. Use cthread_limit() to find out how many threads can exist in the current task.  If the returned value is zero (the default), then no limit is currently being enforced. Important:  Use cthread_count() to determine when your task is approaching the maximum number of threads.

EXAMPLE cthread_set_limit(LIMIT);

/* . . . */

/* Fork if we haven't reached the limit. */
if ( (LIMIT == 0) || (LIMIT > cthread_count()) )
cthread_detach(cthread_fork((any_t (*)())a_thread,(any_t)0));

cthread_name(), cthread_set_name()

SUMMARY Associate a string with a thread SYNOPSIS #import <mach/cthreads.h>

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

DESCRIPTION The functions cthread_name() and cthread_set_name() let you associate an arbitrary name with a thread.  The name is used when trace information is displayed.  The name may also be used for application-specific diagnostics. EXAMPLE int listen(any_t arg)

{
mutex_lock(printing);
printf("This thread's name is: %s\n",
cthread_name(cthread_self()));
mutex_unlock(printing);
/* . . . */
}

main()
{
cthread_t lthread;

printing = mutex_alloc();

lthread = cthread_fork((cthread_fn_t)listen, (any_t)0);
cthread_set_name(lthread, "lthread");
cthread_detach(lthread);
/* . . . */
}

SEE ALSO cthread_data(), cthread_set_data()

cthread_priority(), cthread_max_priority()

SUMMARY Set the scheduling priority for a C thread SYNOPSIS #import <mach/cthreads.h>

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

ARGUMENTS t:  The C thread whose priority is to be changed.

priority:  The new priority to change it to. set_max:  Also set t's maximum priority if true. processor_set:  The privileged port for the processor set to which thread is currently assigned. max_priority:  The new maximum priority.

DESCRIPTION These functions give C threads the functionality of thread_priority() and thread_max_priority().  See those functions for more details than are provided here.

The cthread_priority() function changes the base priority and (optionally) the maximum priority of t.  If the new base priority is higher than the scheduled priority of the currently executing thread, this thread might be preempted.  The maximum priority of the thread is also set if set_max is true.  This call fails if priority is greater than the current maximum priority of the thread.  As a result, cthread_priority() can lower--but never raise--the value of a thread's maximum priority. The cthread_max_priority() function changes the maximum priority of the thread.  Because it requires the privileged port for the processor set, this call can reset the maximum priority to any legal value.  If the new maximum priority is less than the thread's base priority, then the thread's base priority is set to the new maximum priority.

EXAMPLE /* Get the privileged port for the default processor set. */

error=processor_set_default(host_self(), &default_set);
if (error!=KERN_SUCCESS) {
mach_error("Error calling processor_set_default()", error);
exit(1);
}

error=host_processor_set_priv(host_priv_self(), default_set,
&default_set_priv);
if (error!=KERN_SUCCESS) {
mach_error("Call to host_processor_set_priv() failed", error);
exit(1);
}

/* Set the max priority. */
error=cthread_max_priority(cthread_self(), default_set_priv,
priority);
if (error!=KERN_SUCCESS)
mach_error("Call to cthread_max_priority() failed",error);

/* Set the thread's priority. */
error=cthread_priority(cthread_self(), priority, FALSE);
if (error!=KERN_SUCCESS)
mach_error("Call to cthread_priority() failed",error);

RETURN KERN_SUCCESS:  Operation completed successfully

KERN_INVALID_ARGUMENT:  cthread is not a C thread, processor_set is not a privileged port for a processor set, or priority is out of range (not in 0-31). KERN_FAILURE:  The requested operation would violate the thread's maximum priority (only for cthread_priority()) or the thread is not assigned to the processor set whose privileged port was presented.

SEE ALSO thread_priority(), thread_max_priority(), thread_policy(), task_priority(), processor_set_priority()

cthread_self()

SUMMARY Return the caller's C-thread identifier SYNOPSIS #import <mach/cthreads.h>

cthread_t cthread_self(void)

DESCRIPTION The function cthread_self() returns the caller's own C-thread identifier, which is the same value that was returned by cthread_fork() to the creator of the thread.  The C-thread identifier uniquely identifies the thread, and hence may be used as a key in data structures that associate user data with individual threads.  Since thread identifiers may be reused by the underlying implementation, you should be careful to clean up such associations when threads exit. EXAMPLE printf("This thread's name is: %s\n",

cthread_name(cthread_self()));
mutex_unlock(printing);

SEE ALSO cthread_fork(), cthread_thread(), thread_self()

cthread_set_errno_self()

SUMMARY Set the current thread's errno value SYNOPSIS #import <mach/cthreads.h>

void cthread_set_errno_self(int error)

DESCRIPTION Use this function to set the errno value for the current thread to error.  In the UNIX operating system, errno is a process-wide global variable that's set to an error number when a UNIX system call fails.  However, because Mach has multiple threads per process, Mach keeps errno information on a per-thread basis as well as in errno.  This function has no effect on the value of errno.

The current thread's errno value can be obtained by calling cthread_errno().  Errno values are defined in the header file bsd/sys/errno.h.

EXAMPLE cthread_set_errno_self(EPERM); SEE ALSO cthread_errno(), intro(2) UNIX manual page

cthread_thread()

SUMMARY Return the caller's Mach thread identifier SYNOPSIS #import <mach/cthreads.h>

thread_t cthread_thread(cthread_t t)

DESCRIPTION The macro cthread_thread() returns the Mach thread that corresponds to the specified C thread t. EXAMPLE /* Save the cthread and thread values for the forked thread. */

l_cthread = cthread_fork((cthread_fn_t)listen, (any_t)0);
cthread_detach(l_cthread);
l_realthread = cthread_thread(l_cthread);

SEE ALSO cthread_fork(), cthread_self()

cthread_yield()

SUMMARY Yield the processor to other threads SYNOPSIS #import <mach/cthreads.h>

void cthread_yield(void)

DESCRIPTION The function cthread_yield() is a hint to the scheduler, suggesting that this would be a convenient point to schedule another thread to run on the current processor. EXAMPLE int i, n;

/* n is set previously */
for (i = 0; i < n; i += 1)
cthread_yield();

SEE ALSO cthread_priority(), thread_switch()

mutex_lock()

SUMMARY Lock a mutex variable SYNOPSIS #import <mach/cthreads.h>

void mutex_lock(mutex_t m)

DESCRIPTION The macro mutex_lock() attempts to lock the mutex m and blocks until it succeeds.  If several threads attempt to lock the same mutex concurrently, one will succeed, and the others will block until m is unlocked.  A deadlock occurs if a thread attempts to lock a mutex it has already locked. EXAMPLE /* Only one thread at a time should call printf. */

mutex_lock(printing);
printf("Condition has been met\n");
mutex_unlock(printing);

SEE ALSO mutex_try_lock(), mutex_unlock()

mutex_try_lock()

SUMMARY Try to lock a mutex variable SYNOPSIS #import <mach/cthreads.h>

int mutex_try_lock(mutex_t m)

DESCRIPTION The function mutex_try_lock() attempts to lock the mutex m, like mutex_lock(), and returns true if it succeeds.  If m is already locked, however, mutex_try_lock() immediately returns false rather than blocking.  For example, a busy-waiting version of mutex_lock() could be written using mutex_try_lock():

void mutex_lock(mutex_t m)
{
for (;;)
if (mutex_try_lock(m))
return;
}

SEE ALSO mutex_lock(), mutex_unlock()

mutex_unlock()

SUMMARY Unlock a mutex variable SYNOPSIS #import <mach/cthreads.h>

void mutex_unlock(mutex_t m)

DESCRIPTION The function mutex_unlock() unlocks m, giving other threads a chance to lock it. EXAMPLE /* Only one thread at a time should call printf. */

mutex_lock(printing);
printf("Condition has been met\n");
mutex_unlock(printing);

SEE ALSO mutex_lock(), mutex_try_lock()

Mach Kernel Functions

exc_server()

SUMMARY Dispatch a message received on an exception port SYNOPSIS #import <mach/mach.h>

#import <mach/exception.h>

boolean_t exc_server(msg_header_t *in, msg_header_t *out)

ARGUMENTS in:  A message that was received on the exception port.  This message structure should be at least 64 bytes long.

out:  An empty message to be filled by exc_server() and then sent.  This message buffer should be at least 32 bytes long.

DESCRIPTION This function calls the appropriate exception handler.  You should call this function after you've received a message on an exception port that you set up previously.  Usually, this function is used along with a user-defined exception handler, which must have the following protocol:

kern_return_t catch_exception_raise(port_t exception_port, port_t thread, port_t task, int exception, int code, int subcode)

To receive a message on an exception port, you must first create a new port and make it the task or thread exception port.  (You can't use the default task exception port because you can't get receive rights for it.)  Before calling msg_receive(), you must set the local_port field of the header to the appropriate exception port and the msg_size field to the size of the structure for the incoming message. If it accepted the incoming message, exc_server() returns true; otherwise it returns false. You should keep a global value that indicates whether your exception handler successfully handled the exception.  If it couldn't, then you should forward the exception message to the old exception port.

EXAMPLE typedef struct {

port_t old_exc_port;
port_t clear_port;
port_t exc_port;
} ports_t;

volatile boolean_t  pass_on = FALSE;
mutex_t             printing;

/* Listen on the exception port. */
any_t exc_thread(ports_t *port_p)
{
kern_return_t   r;
char           *msg_data[2][64];
msg_header_t   *imsg = (msg_header_t *)msg_data[0],
*omsg = (msg_header_t *)msg_data[1];

/* Wait for exceptions. */
while (1) {
imsg->msg_size = 64;
imsg->msg_local_port = port_p->exc_port;
r = msg_receive(imsg, MSG_OPTION_NONE, 0);

if (r==RCV_SUCCESS) {
/* Give the message to the Mach exception server. */
if (exc_server(imsg, omsg)) {
/* Send the reply message that exc_serv gave us. */
r = msg_send(omsg, MSG_OPTION_NONE, 0);
if (r != SEND_SUCCESS) {
mach_error("msg_send", r);
exit(1);
}
}
else { /* exc_server refused to handle imsg. */
mutex_lock(printing);
printf("exc_server didn't like the message\n");
mutex_unlock(printing);
exit(2);
}
}
else { /* msg_receive() returned an error. */
mach_error("msg_receive", r);
exit(3);
}

/* Pass the message to old exception handler, if necessary. */
if (pass_on == TRUE) {
imsg->msg_remote_port = port_p->old_exc_port;
imsg->msg_local_port = port_p->clear_port;
r = msg_send(imsg, MSG_OPTION_NONE, 0);
if (r != SEND_SUCCESS) {
mach_error("msg_send to old_exc_port", r);
exit(4);
}
}
}
}

/*
* catch_exception_raise() is called by exc_server().  The only
* exception it can handle is EXC_SOFTWARE.
*/
kern_return_t catch_exception_raise(port_t exception_port,
port_t thread, port_t task, int exception, int code, int subcode)
{
if ((exception == EXC_SOFTWARE) && (code == 0x20000)) {
/* Handle the exception so that the program can continue. */
mutex_lock(printing);
printf("Handling the exception\n");
mutex_unlock(printing);
return KERN_SUCCESS;
}
else { /* Pass the exception on to the old port. */
pass_on = TRUE;
mach_NeXT_exception("Forwarding exception", exception,
code, subcode);
return KERN_FAILURE;  /* Couldn't handle this exception. */
}
}

main()
{
int             i;
kern_return_t   r;
ports_t         ports;

printing = mutex_alloc();

/* Save the old exception port for this task. */
r = task_get_exception_port(task_self(), &(ports.old_exc_port));
if (r != KERN_SUCCESS) {
mach_error("task_get_exception_port", r);
exit(1);
}

/* Create a new exception port for this task. */
r = port_allocate(task_self(), &(ports.exc_port));
if (r != KERN_SUCCESS) {
mach_error("port_allocate 0", r);
exit(1);
}
r = task_set_exception_port(task_self(), (ports.exc_port));
if (r != KERN_SUCCESS) {
mach_error("task_set_exception_port", r);
exit(1);
}

/* Fork the thread that listens to the exception port. */
cthread_detach(cthread_fork((cthread_fn_t)exc_thread,
(any_t)&ports));
/* Raise the exception. */
ports.clear_port = thread_self();
r = exception_raise(ports.exc_port, thread_reply(),
ports.clear_port, task_self(), EXC_SOFTWARE, 0x20000, 6);

if (r != KERN_SUCCESS)
mach_error("catch_exception_raise didn't handle exception",
r);
else {
mutex_lock(printing);
printf("Successfully called exception_raise\n");
mutex_unlock(printing);
}
}

SEE ALSO exception_raise(), mach_NeXT_exception()

exception_raise()

SUMMARY Cause an exception to occur SYNOPSIS #import <mach/mach.h>

#import <mach/exception.h>

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)

ARGUMENTS exception_port:  The exception port of the affected thread.  (If the thread doesn't have its own exception port, then this should be the exception port of the task.)

clear_port:  The port to which a reply message should be sent from the exception handler.  If you don't care to see the reply, you can use thread_reply(). thread:  The thread in which the exception condition occurred.  If the exception isn't thread-specific, then specify THREAD_NULL. task:  The task in which the exception condition occurred. exception:  The type of exception that occurred; for example, EXC_SOFTWARE.  Values for this variable are defined in the header file mach/exception.h. code:  The exception code.  The meaning of this code depends on the value of exception. subcode:  The exception subcode.  The meaning of this subcode depends on the values of exception and code.

DESCRIPTION This function causes an exception message to be sent to exception_port, which results in a call to the exception handler. Usually this function is used along with a user-defined exception handler.  (See exc_server() and mach_NeXT_exception() for more information on user-defined exception handlers.)

You can obtain exception_port by calling thread_get_exception_port() or (if no thread exception port exists or the exception affects the whole task) task_get_exception_port(). If you're defining your own type of exception, you must have exception equal to EXC_SOFTWARE and code equal to or greater than 0x20000.

EXAMPLE /* Raise the exception. */

r = exception_raise(ports.exc_port, thread_reply(), thread_self(),
task_self(), EXC_SOFTWARE, 0x20000, 6);
if (r != KERN_SUCCESS)
mach_error("catch_exception_raise didn't handle exception", r);
else {
/* Use mutex so only one thread at a time can call printf. */
mutex_lock(printing);
printf("Successfully called exception_raise\n");
mutex_unlock(printing);
}

RETURN KERN_SUCCESS:  The call succeeded.

KERN_FAILURE:  The exception handler didn't successfully deal with the exception. KERN_INVALID_ARGUMENT:  One of the arguments wasn't valid.

SEE ALSO exc_server(), mach_NeXT_exception(), task_get_exception_port(), thread_get_exception_port()

host_info()

SUMMARY Get information about a host SYNOPSIS #import <mach/mach.h>

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

ARGUMENTS host:  The host for which information is to be obtained.

flavor:  The type of statistics to be returned.  Currently HOST_BASIC_INFO, HOST_PROCESSOR_SLOTS, and HOST_SCHED_INFO are implemented. host_info:  Returns statistics about host. host_info_count:  The number of integers in the info structure; returns the number of integers that Mach tried to fill the info structure with.  For HOST_BASIC_INFO, you should set host_info_count to HOST_BASIC_INFO_COUNT.  For HOST_PROCESSOR_SLOTS, you should set it to the maximum number of CPUs (returned by HOST_BASIC_INFO).  For HOST_SCHED_INFO, set it to HOST_SCHED_INFO_COUNT.

DESCRIPTION Returns the selected information array for a host, as specified by flavor.  The host_info argument is an array of integers that's supplied by the caller and returned filled with specified information.  The host_info_count argument is supplied by the caller as the maximum number of integers in host_info (which can be larger than the space required for the information).  On return, it contains the actual number of integers in host_info.

Warning:  This replaces the old host_info() call.  It isn't backwards compatible. Basic information is defined by HOST_BASIC_INFO.  Its size is defined by HOST_BASIC_INFO_COUNT.  Possible values of the cpu_type and cpu_subtype fields are defined in the header file mach/machine.h, which is included in mach/mach.h.

struct host_basic_info {
int           max_cpus;     /* maximum possible cpus for
* which kernel is configured */
int           avail_cpus;   /* number of cpus now available */
vm_size_t     memory_size;  /* size of memory in bytes */
cpu_type_t    cpu_type;     /* cpu type */
cpu_subtype_t cpu_subtype;  /* cpu subtype */
};
typedef struct host_basic_info *host_basic_info_t;

Processor slots of the active (available) processors are defined by HOST_PROCESSOR_SLOTS.  The size of this information should be obtained from the max_cpus field of the structure returned by HOST_BASIC_INFO.  HOST_PROCESSOR_SLOTS returns an array of integers, each of which is the slot number of a CPU. Additional information of interest to schedulers is defined by HOST_SCHED_INFO.  The size of this information is defined by HOST_SCHED_INFO_COUNT.

struct host_sched_info {
int  min_timeout;  /* minimum timeout in milliseconds */
int  min_quantum;  /* minimum quantum in milliseconds */
};

typedef struct host_sched_info *host_sched_info_t

EXAMPLE An example of using HOST_BASIC_INFO:

kern_return_t           ret;
struct host_basic_info  basic_info;
unsigned int            count=HOST_BASIC_INFO_COUNT;

ret=host_info(host_self(), HOST_BASIC_INFO,
(host_info_t)&basic_info, &count);
if (ret != KERN_SUCCESS)
mach_error("host_info() call failed", ret);
else printf("This system has %d bytes of RAM.\n",
basic_info.memory_size);

An example of using HOST_PROCESSOR_SLOTS (you also need to include the HOST_BASIC_INFO code above so you can get max_cpus):

host_info_t  slots;
unsigned int cpu_count, i;

cpu_count=basic_info.max_cpus;
slots=(host_info_t)malloc(cpu_count*sizeof(int));
ret=host_info(host_self(), HOST_PROCESSOR_SLOTS, slots,
&cpu_count);
if (ret!=KERN_SUCCESS)
mach_error("PROCESSOR host_info() call failed", ret);
else for (i=0; i<cpu_count; i++)
printf("CPU %d is in slot %d.\n", i, *slots++);

An example of using HOST_SCHED_INFO:

kern_return_t           ret;
struct host_sched_info  sched_info;
unsigned int            sched_count=HOST_SCHED_INFO_COUNT;

ret=host_info(host_self(), HOST_SCHED_INFO,
(host_info_t)&sched_info, &sched_count);
if (ret != KERN_SUCCESS)
mach_error("SCHED host_info() call failed", ret);
else
printf("The minimum quantum is %d milliseconds.\n",
sched_info.min_quantum);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  host is not a host, flavor is not recognized, or (for HOST_PROCESSOR_SLOTS) *count is less than max_cpus. KERN_FAILURE:  *count is less than HOST_BASIC_INFO_COUNT (when flavor is HOST_BASIC_INFO) or HOST_SCHED_INFO_COUNT (for HOST_SCHED_INFO). MIG_ARRAY_TOO_LARGE:  Returned info array is too large for host_info.  The host_info argument is filled as much as possible, and host_info_count is set to the number of elements that would be returned if there were enough room.

SEE ALSO host_kernel_version(), host_processors(), processor_info()

host_kernel_version()

SUMMARY Get kernel version information SYNOPSIS #import <mach/mach.h>

kern_return_t host_kernel_version(host_t host, kernel_version_t version)

ARGUMENTS host:  The host for which information is being requested.

version:  Returns a character string describing the kernel version executing on host.

DESCRIPTION This function returns the version string compiled into host's kernel at the time it was built.  If you don't use the kernel_version_t declaration, then you should allocate KERNEL_VERSION_MAX bytes for the version string. EXAMPLE kern_return_t       ret;

kernel_version_t    string;

ret=host_kernel_version(host_self(), string);
if (ret != KERN_SUCCESS)
mach_error("host_kernel_version() call failed", ret);
else
printf("Version string:  %s\n", string);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  host was not a host. KERN_INVALID_ADDRESS:  version points to inaccessible memory.

SEE ALSO host_info(), host_processors(), processor_info()

host_processor_set_priv()

SUMMARY Get the privileged port of a processor set SYNOPSIS #import <mach/mach.h>

kern_return_t host_processor_set_priv(host_priv_t host_priv, processor_set_t processor_set_name, processor_set_t *processor_set)

ARGUMENTS host_priv:  The privileged host port for the desired host.

processor_set_name:  The name port of the processor set. processor_set:  Returns the privileged port of the processor set.

DESCRIPTION This function returns send rights to the privileged port for the specified processor set.  This port is used in calls that can affect other threads or tasks.  For example, processor_set_tasks() requires the privileged port because it returns the port of every task on the system. EXAMPLE kern_return_t    error;

processor_set_t  processor_set;
processor_set_t  default_set;

error=processor_set_default(host_self(), &default_set);
if (error != KERN_SUCCESS)
mach_error("Call to processor_set_default failed", error);

error=host_processor_set_priv(host_priv_self(), default_set,
&processor_set);
if (error != KERN_SUCCESS)
mach_error("Call to host_processor_set_priv failed; make sure
you're superuser", error);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  host_priv was not a privileged host port, or processor_set_name didn't name a valid processor set. host_processor_sets()

SUMMARY Get the name ports of all processor sets on a host SYNOPSIS #import <mach/mach.h>

kern_return_t host_processor_sets(host_t host, processor_set_name_array_t *processor_set_list, unsigned int *processor_set_count)

ARGUMENTS host:  The host port for the desired host.

processor_set_list:  Returns an array of processor sets currently existing on host; no particular ordering is guaranteed. processor_set_ count:  Returns the number of processor sets in the processor_set_list.

DESCRIPTION This function returns send rights to the name port for each processor set currently assigned to host.  The host_processor_set_priv() function can be used to obtain the privileged ports from these if desired.  The processor_set_list argument is an array that is created as a result of this call.  You should call vm_deallocate() on this array when the data is no longer needed.

Note:  In single-processor systems, you can get the same information by calling processor_set_default().

EXAMPLE kern_return_t               ret;

processor_set_name_array_t  list;
unsigned int                count;

ret=host_processor_sets(host_self(), &list, &count);
if (ret!=KERN_SUCCESS)
mach_error("error calling host_processor_sets", ret);
else {
/* . . . */
ret=vm_deallocate(task_self(), (vm_address_t)list,
sizeof(list)*count);
if (ret!=KERN_SUCCESS)
mach_error("error calling vm_deallocate", ret);
}

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  host is not a host.

SEE ALSO host_processor_set_priv(), processor_set_create(), processor_set_tasks(), processor_set_threads(), processor_set_default()

host_processors()

SUMMARY Get the processor ports for a host SYNOPSIS #import <mach/mach.h>

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

ARGUMENTS host_priv:  Privileged host port for the desired host.

processor_list:  Returns the processors existing on host_priv; no particular ordering is guaranteed. processor_count:  Returns the number of processors in processor_list.

DESCRIPTION host_processors() gets send rights to the processor port for each processor existing on host_priv.  The processor_list argument is an array that is created as a result of this call.  The caller may wish to call vm_deallocate() on this array when the data is no longer needed. EXAMPLE kern_return_t      error;

processor_array_t  list;
unsigned int       count;

error=host_processors(host_priv_self(), &list, &count);
if (error!=KERN_SUCCESS){
mach_error("error calling host_processors", error);
exit(1);
}
/* . . . */
vm_deallocate(task_self(), (vm_address_t)list, sizeof(list)*count);
if (error!=KERN_SUCCESS)
mach_error("Trouble freeing list", error);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  host_priv is not a privileged host port.

SEE ALSO processor_info(), processor_start(), processor_exit(), processor_control()

host_self(), host_priv_self()

SUMMARY Get the host port for this host SYNOPSIS #import <mach/mach.h>

host_t host_self(void) host_priv_t host_priv_self(void)

DESCRIPTION The host_self() function returns send rights to the host port for the host on which the call is executed.  This port can be used only to obtain information about the host, not to control the host.

The host_priv_self() function returns send rights to the privileged host port for the host on which the call is executed.  This port is used to control physical resources on that host and is only available to privileged tasks.  PORT_NULL is returned if the invoker is not the UNIX superuser.

EXAMPLE /* Get the privileged port for the default processor set. */

error=processor_set_default(host_self(), &default_set);
if (error!=KERN_SUCCESS) {
mach_error("Error calling processor_set_default()", error);
exit(1);
}

error=host_processor_set_priv(host_priv_self(), default_set,
&default_set_priv);
if (error!=KERN_SUCCESS) {
mach_error("Call to host_processor_set_priv() failed", error);
exit(1);
}

SEE ALSO host_processors(), host_info(), host_kernel_version()

mach_error(), mach_error_string()

SUMMARY Display or get a Mach error string SYNOPSIS #import <mach/mach.h>

#import <mach/mach_error.h>

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

ARGUMENTS string:  The string you want displayed before the Mach error string.

error:  The error value for which you want an error string.

DESCRIPTION The function mach_error() displays a message on stderr.  The message contains the string specified by string, the string returned by mach_error_string(), and the actual error value (error).  Since mach_error() isn't thread-safe, you might want to protect it with a mutex if you call it in a multiple-thread task.

The function mach_error_string() returns the string associated with error. Note that because the error value specified by error is of type kern_return_t, these functions work only with Mach functions.

EXAMPLE mutex_t        printing;

main()
{
kern_return_t  error;
port_t         result;

printing = mutex_alloc();

/* . . . */
if ((error=port_allocate(task_self(), &result)) != KERN_SUCCESS) {
mutex_lock(printing);
mach_error("Error calling port_allocate", error);
mutex_unlock(printing);
exit(1);
}
/* . . . */
}

mach_NeXT_exception(), mach_NeXT_exception_string()

SUMMARY Display or get a Mach exception string SYNOPSIS #import <mach/mach.h>

void mach_NeXT_exception(char *string, int exception, int code, int subcode) char *mach_NeXT_exception_string(int exception, int code, int subcode)

ARGUMENTS string:  The string you want displayed before the Mach exception string.

exception:  The exception value for which you want a string. code:  The exception code.  How this is used depends on the value of exception. subcode:  The exception subcode.  How this is used depends on the value of exception.

DESCRIPTION The function mach_NeXT_exception() displays a message on stderr.  The message contains the string specified by string, then the string returned by mach_NeXT_exception_string(), and then the values of exception, code, and subcode.  Since mach_NeXT_exception() isn't thread-safe, you might want to protect it with a mutex if you call it in a multiple-thread task.

The function mach_NeXT_exception_string() returns the string associated with exception, code, and subcode.

EXAMPLE /*

* catch_exception_raise() is called by exc_server().  The only
* exception it can handle is EXC_SOFTWARE.
*/
kern_return_t catch_exception_raise(port_t exception_port,
port_t thread, port_t task, int exception, int code, int subcode)
{
if ((exception == EXC_SOFTWARE) && (code == 0x20000)) {
/* Handle the exception so that the program can continue. */
mutex_lock(printing);
printf("Handling the exception\n");
mutex_unlock(printing);
return KERN_SUCCESS;
}
else { /* Pass the exception on to the old port. */
pass_on = TRUE;
mach_NeXT_exception("Forwarding exception", exception,
code, subcode);
return KERN_FAILURE;  /* Couldn't handle this exception. */
}
}

SEE ALSO exception_raise(), exc_server()

map_fd()

SUMMARY Map a file into virtual memory SYNOPSIS #import <mach/mach.h>

kern_return_t map_fd(int fd, vm_offset_t offset, vm_offset_t *address, boolean_t find_space, vm_size_t size)

ARGUMENTS fd:  An open UNIX file descriptor for the file that's to be mapped.

offset:  The byte offset within the file, at which mapping is to begin. address:  A pointer to an address in the calling process at which the mapped file should start.  This address, unlike the offset, must be page-aligned. find_space:  If true, the kernel will select an unused address range at which to map the file and return its value in address. size:  The number of bytes to be mapped.

DESCRIPTION The function map_fd() is a UNIX extension that's technically not part of Mach.  This function causes size bytes of data starting at offset in the file specified by fd to be mapped into the virtual memory at the address specified by address.  If find_space is true, the input value of address can be null, and the kernel will find an unused piece of virtual memory to use.  (You should free this space with vm_deallocate() when you no longer need it.)  If you provide a value for address, it must be page-aligned and at least size bytes long.  The sum of offset and size must not exceed the length of the file.

Memory mapping doesn't cause I/O to take place.  When specific pages are first referenced, they cause page faults that bring in the data.  The mapped memory is copy-on-write.  Modified data is returned to the file only by a write() call.

EXAMPLE kern_return_t r;

int           fd;
char         *memfile, *filename = "/tmp/myfile";

/* Open the file. */
fd = open(filename, O_RDONLY);

/* Map part of it into memory. */
r = map_fd(fd, (vm_offset_t)0, &(vm_offset_t)memfile, TRUE,
(vm_size_t)5);
if (r != KERN_SUCCESS)
mach_error("Error calling map_fd()", r);
else
printf("Second character in %s is:  %c\n", filename, memfile[1]);

RETURN KERN_SUCCESS:  The data was mapped successfully.

KERN_INVALID_ADDRESS:  address wasn't valid. KERN_INVALID_ARGUMENT:  An invalid argument was passed. msg_receive()

SUMMARY Receive a message SYNOPSIS #import <mach/mach.h>

#import <mach/message.h>

msg_return_t msg_receive(msg_header_t *header, msg_option_t option, msg_timeout_t timeout)

ARGUMENTS header:  The address of a buffer in which the message is to be received.  Two fields of the message header must be set before the call is made:  msg_local_port must be set to the value of the port from which the message is to be received, and msg_size must be set to the maximum size of the message that may be received.  This maximum size must be less than or equal to the size of the buffer.

option:  The failure conditions under which msg_receive() should terminate.  The value of this argument is a combination (using the bitwise OR operator) of the following options.  Unless one of these values is explicitly specified, msg_receive() does not return until a message has been received.

RCV_TIMEOUT:  Specifies that msg_receive() should return when the specified timeout elapses if a message has not arrived by that time; if not specified, the timeout will be ignored (that is, it will be infinite). RCV_INTERRUPT:  Specifies that msg_receive() should return when a software interrupt occurs in this thread. RCV_LARGE:  Specifies that msg_receive() should return without dequeuing a message if the next message in the queue is larger than header.msg_size.  (Normally, a message that is too large is dequeued and lost.)  You can use this option to dynamically determine how large your message buffer must be.

Use MSG_OPTION_NONE to specify that none of the above options is desired. timeout:  If RCV_TIMEOUT is specified in option, then timeout is the maximum time in milliseconds to wait for a message before giving up.

DESCRIPTION The function msg_receive() retrieves the next message from the port or port set specified in the msg_local_port field of header.  If a port is specified, the port must not be a member of a port set.

If a port set is specified, then msg_receive() will retrieve messages sent to any of the set's member ports.  Mach sets the msg_local_port field to the specific port on which the message was found.  It's not an error for the port set to have no members, or for members to be added and removed from a port set while a msg_receive() on the port set is in progress. The message consists of its header, followed by a variable amount of data; the message header supplied to msg_receive() must specify (in msg_size) the maximum size of the message that can be received into the buffer provided. If no messages are present on the port(s) in question, msg_receive() will wait until a message arrives, or until one of the specified termination conditions is met (see the description of the option argument for this function). If the message is successfully received, then msg_receive() sets the msg_size field of the header to the size of the received message.  If the RCV_LARGE option was set and msg_receive() returned RCV_TOO_LARGE, then the msg_size field is set to the size of the message that was too large. If the received message contains out-of-line data (that is, data for which the msg_type_inline attribute was specified as false), the data will be returned in a newly allocated region of memory; the message body will contain a pointer to that new region. You should deallocate this memory when the data is no longer needed.  See the vm_allocate() call for a description of the state of newly allocated memory. See Chapter 2, "Using Mach Messages," for information on setting up messages and on writing Mach servers.

EXAMPLE msg_header_t   *imsg, header;

/* Wait for messages. */
while (1) {
/* Set up the message structure. */
header.msg_size = sizeof header;
header.msg_local_port = receive_port;

/* Get the next message on the queue. */
r = msg_receive(&header, RCV_LARGE, 0);

/* If the message is too big ... */
if (r==RCV_TOO_LARGE) {
/* ... allocate a structure for it ... */
imsg = (msg_header_t *)malloc(header.msg_size);
/* ... initialize the structure ... */
imsg->msg_size = header.msg_size;
imsg->msg_local_port = receive_port;
/* ... and get the message. */
r = msg_receive(imsg, MSG_OPTION_NONE, 0);
}

if (r==RCV_SUCCESS) {
/* Handle the message. */
}
else { /* msg_receive() returned an error. */
mach_error("msg_receive", r);
exit(3);
}
}

RETURN RCV_SUCCESS:  The message has been received.

RCV_INVALID_MEMORY:  The message specified was not writable by the calling task. RCV_INVALID_PORT:  An attempt was made to receive on a port to which the calling task does not have the proper access, or which was deallocated (see port_deallocate()) while waiting for a message. RCV_TOO_LARGE:  The message header and body combined are larger than the size specified by msg_size.  Unless the RCV_LARGE option was set, the message has been dequeued and lost.  If the RCV_LARGE option was specified, then Mach sets msg_size to the size of the message that was too large and leaves the message at the head of the queue. RCV_NOT_ENOUGH_MEMORY:  The message to be received contains more out-of-line data than can be allocated in the receiving task. RCV_TIMED_OUT:  The message was not received after timeout milliseconds. RCV_INTERRUPTED:  A software interrupt occurred and the RCV_INTERRUPT option was specified. RCV_PORT_CHANGE:  The port specified was added to a port set during the duration of the msg_receive() call. msg_rpc()

SUMMARY Send and receive a message SYNOPSIS #import <mach/mach.h>

#import <mach/message.h>

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)

ARGUMENTS header:  Address of a message buffer that will be used for both msg_send() and msg_receive().  This buffer contains a message header followed by the data for the message to be sent.  The msg_remote_port field specifies the port to which the message is to be sent.  The msg_local_port field specifies the port on which a message is then to be received; if this port is the special value PORT_DEFAULT, it gets replaced by the value PORT_NULL for the purposes of the msg_send() operation.

option:  A union of the option arguments for the send and receive (see msg_send() and msg_receive()). rcv_size:  The maximum size allowed for the received message; this must be less than or equal to the size of the message buffer. The msg_size field in the header specifies the size of the message to be sent. send_timeout, rcv_timeout:  The timeout values to be applied to the component operations.  These are used only if the option SEND_TIMEOUT or RCV_TIMEOUT is specified.

DESCRIPTION The function msg_rpc() is a hybrid call that performs a msg_send() followed by a msg_receive(), using the same message buffer.  Because of the order of the send and receive, this function is appropriate for clients of Mach servers.  However, the msg_rpc() call to a Mach server is usually performed by MiG-generated code, not by handwritten code.

See Chapter 2, "Using Mach Messages," for information on setting up messages and on writing Mach servers.

RETURN RPC_SUCCESS:  The message was successfully sent and a reply was received.

Other possible values are the same as those for msg_send() and msg_receive(); any error during the msg_send() portion will terminate the call. msg_send()

SUMMARY Send a message SYNOPSIS #import <mach/mach.h>

#import <mach/message.h>

msg_return_t msg_send(msg_header_t *header, msg_option_t option, msg_timeout_t timeout)

ARGUMENTS header:  The address of the message to be sent.  A message consists of a fixed-size header followed by a variable number of data descriptors and data items.  See the header file mach/message.h for a definition of the message structure.

option:  The failure conditions under which msg_send() should terminate.  The value of this argument is a combination (using the bitwise OR operator) of the following options.  Unless one of these values is explicitly specified, msg_send() does not return until the message is successfully queued for the intended receiver.

SEND_TIMEOUT:  Specifies that the msg_send() request should terminate after the timeout period has elapsed, even if the kernel has been unable to queue the message. SEND_NOTIFY:  Allows the sender to send exactly one message without being suspended even if the destination port is full.  When that message can be posted to the receiving port queue, this task receives a message that notifies it that another message can be sent.  If the sender tries to send a second message with this option to the same port before the first notification arrives, the result is an error.  If both SEND_NOTIFY and SEND_TIMEOUT are specified, msg_send() will wait until the specified timeout has elapsed before invoking the SEND_NOTIFY option. SEND_INTERRUPT:  Specifies that msg_send() should return if a software interrupt occurs in this thread.

Use MSG_OPTION_NONE to specify that none of the above options is wanted. timeout:  If the destination port is full and the SEND_TIMEOUT option has been specified, this value specifies the maximum wait time (in milliseconds).

DESCRIPTION The function msg_send() transmits a message from the current task to the port specified in the message header field.  The message consists of its header, followed by a variable number of data descriptors and data items.

If the msg_local_port field isn't set to PORT_NULL, send rights to that port will be passed to the receiver of this message.  The receiver task can use that port to send a reply to this message. If the SEND_NOTIFY option is used and this call returns a SEND_WILL_NOTIFY code, you can expect to receive a notify message from the kernel.  This message will be either a NOTIFY_MSG_ACCEPTED or a NOTIFY_PORT_DELETED message, depending on what happened to the queued message.  The notify_port field in these messages is the port to which the original message was sent.  The formats for these messages are defined in the header file sys/notify.h. See Chapter 2, "Using Mach Messages," for information on setting up messages and on writing Mach servers.

EXAMPLE /* From the handwritten part of a Mach server... */

while (TRUE)
{
/* Receive a request from a client. */
msg.head.msg_local_port = port;
msg.head.msg_size = sizeof(struct message);
ret = msg_receive(&msg.head, MSG_OPTION_NONE, 0);
if (ret != RCV_SUCCESS) /* ignore errors */;

/* Feed the request into the server. */
(void)add_server(&msg, &reply);

/* Send a reply to the client. */
reply.head.msg_local_port = port;
ret = msg_send(&reply.head, MSG_OPTION_NONE, 0);
if (ret != SEND_SUCCESS) /* ignore errors */;
}

RETURN SEND_SUCCESS:  The message has been queued for the destination port.

SEND_INVALID_MEMORY:  The message header or body was not readable by the calling task, or the message body specified out-of-line data that was not readable. SEND_INVALID_PORT:  The message refers either to a port for which the current task does not have access, or to which access was explicitly removed from the current task (see port_deallocate()) while waiting for the message to be posted, or a msg_type_name field in the message specifies rights that the name doesn't denote in the task (for example, specifying MSG_TYPE_SEND and supplying a port set name). SEND_TIMED_OUT:  The message was not sent since the destination port was still full after timeout milliseconds. SEND_WILL_NOTIFY:  The destination port was full but the SEND_NOTIFY option was specified.  A notification message will be sent when the message can be posted. SEND_NOTIFY_IN_PROGRESS:  The SEND_NOTIFY option was specified but a notification request is already outstanding for this thread and given destination port. port_allocate()

SUMMARY Create a port SYNOPSIS #import <mach/mach.h>

kern_return_t port_allocate(task_t task, port_name_t *port_name)

ARGUMENTS task:  The task in which the new port is created (for example, use task_self() to specify the caller's task).

port_name:  Returns the name used by task for the new port.

DESCRIPTION The function port_allocate() causes a port to be created for the specified task; the resulting port is returned in port_name.  The target task initially has both send and receive rights to the port.  The new port isn't a member of any port set. EXAMPLE port_t         myport;

kern_return_t  error;

if ((error=port_allocate(task_self(), &myport)) != KERN_SUCCESS) {
mach_error("port_allocate failed", error);
exit(1);
}

RETURN KERN_SUCCESS:  A port has been allocated.

KERN_INVALID_ARGUMENT:  task was invalid. KERN_RESOURCE_SHORTAGE:  No more port slots are available for this task.

SEE ALSO port_deallocate()

port_deallocate()

SUMMARY Deallocate a port SYNOPSIS #import <mach/mach.h>

kern_return_t port_deallocate(task_t task, port_name_t port_name)

ARGUMENTS task:  The task that wants to relinquish rights to the port (for example, use task_self() to specify the caller's task).

port_name: The name that task uses for the port to be deallocated.

DESCRIPTION The function port_deallocate() requests that the target task's access to a port be relinquished.

If task has receive rights for the port and the port doesn't have a backup port, these things happen:

		The port is destroyed.
		All other tasks with send access to the port are notified of its destruction.
		If the port is a member of a port set, it's removed from the port set.

If task has receive rights for the port and the port does have a backup port, then the following things happen:

		If the port is a member of a port set, it's removed from the port set.
		Send and receive rights for the port are sent to the backup port in a notification message (see port_set_backup()).

EXAMPLE port_t         my_port;

kern_return_t  error;

/* . . . */

error=port_deallocate(task_self(), my_port);
if (error != KERN_SUCCESS) {
mach_error("port_deallocate failed", error);
exit(1);
}

RETURN KERN_SUCCESS:  The port has been deallocated.

KERN_INVALID_ARGUMENT:  task was invalid or port_name doesn't name a valid port.

SEE ALSO port_allocate()

port_extract_receive(), port_extract_send()

SUMMARY Remove access rights to a port and return them to the caller SYNOPSIS #import <mach/mach.h>

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)

ARGUMENTS task:  The task whose rights the caller takes.

its_name:  The name by which task knows the port. its_port:  Returns the receive or send rights.

DESCRIPTION The functions port_extract_receive() and port_extract_send() remove the port access rights that task has for a port and return the rights to the caller.  This leaves task with no rights for the port.

The port_extract_send() function extracts send rights; task can't have receive rights for the named port.  The port_extract_receive() function extracts receive rights.

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  task was invalid or its_name doesn't name a port for which task has the required rights.

SEE ALSO port_insert_send(), port_insert_receive()

port_insert_receive(), port_insert_send()

SUMMARY Give a task rights with a specific name SYNOPSIS #import <mach/mach.h>

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)

ARGUMENTS task:  The task getting the new rights.

my_port:  Rights supplied by the caller. its_name:  The name by which task will know the new rights.

DESCRIPTION The functions port_insert_receive() and port_insert_send() give a task rights with a specific name.  If task already has rights named its_name, or has some other name for my_port, the operation will fail.  The its_name argument can't be a predefined port, such as PORT_NULL.

The port_insert_send() function inserts send rights, and port_insert_receive() inserts receive rights.

RETURN KERN_SUCCESS:  The call succeeded.

KERN_NAME_EXISTS:  task already has a right named its_name. KERN_FAILURE:  task already has rights to my_port. KERN_INVALID_ARGUMENT:  task was invalid or its_name was an invalid name.

SEE ALSO port_extract_send(), port_extract_receive()

port_names()

SUMMARY Get information about the port name space of a task SYNOPSIS #import <mach/mach.h>

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)

ARGUMENTS task:  The task whose port name space is queried.

port_names:  Returns the names of the ports and port sets in the port name space of task, in no particular order. port_names_count:  Returns the number of names returned. port_types:  Returns the type of each corresponding name.  This indicates what kind of rights the task holds for the port, or whether the name refers to a port set.  The type is one of the following:  PORT_TYPE_SEND (send rights only), PORT_TYPE_RECEIVE_OWN (send and receive rights), PORT_TYPE_SET (the port is a port set). port_types_count:  Returns the same value as port_names_count.

DESCRIPTION The function port_names() returns information about the port name space of task.  It returns the port and port set names that are currently valid for task.  For each name, it also returns what type of rights task holds.

The port_names and port_types arguments are arrays that are automatically allocated when the reply message is received.  You should use vm_deallocate() on them when the data is no longer needed.

EXAMPLE kern_return_t      error;

port_name_array_t  names;
unsigned int       names_count, types_count;
port_type_array_t  types;

error=port_names(task_self(), &names, &names_count, &types,
&types_count);
if (error != KERN_SUCCESS) {
mach_error("port_rename returned value of ", error);
exit(1);
}
/* . . . */
error=vm_deallocate(task_self(), (vm_address_t)names,
sizeof(names)*names_count);
if (error != KERN_SUCCESS)
mach_error("Trouble freeing names", error);

error=vm_deallocate(task_self(), (vm_address_t)types,
sizeof(names)*types_count);
if (error != KERN_SUCCESS)
mach_error("Trouble freeing types", error);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  task was invalid.

SEE ALSO port_type(), port_status(), port_set_status()

port_rename()

SUMMARY Change the name by which a port or port set is known to a task SYNOPSIS #import <mach/mach.h>

kern_return_t port_rename(task_t task, port_name_t old_name, port_name_t new_name)

ARGUMENTS task:  The task whose port name space is changed.

old_name:  The current name of the port or port set. new_name:  The new name for the port or port set.

DESCRIPTION The function port_rename() changes the name by which a port or port set is known to task.  The port name specified in new_name must not already be in use, and it can't be a predefined port, such as PORT_NULL.  Currently, a name is a small integer.

One way to guarantee that a name isn't already in use is to deallocate a port and then use its name as new_name.  Another way is to check all the existing names, using port_names(), before you call port_rename().  If you choose another naming scheme, you should be prepared to try another name if port_rename() returns a KERN_NAME_EXISTS error.

EXAMPLE #define MY_PORT  (port_name_t)99

port_name_t       my_port;
kern_return_t     error;

error=port_allocate(task_self(),&my_port);
if (error != KERN_SUCCESS) {
mach_error("port_allocate failed", error);
exit(1);
}

error=port_rename(task_self(), my_port, MY_PORT);
if (error == KERN_NAME_EXISTS)
/* try again with a different name */;
else if (error != KERN_SUCCESS) {
mach_error("port_rename failed", error);
exit(1);
}

RETURN KERN_SUCCESS:  The call succeeded.

KERN_NAME_EXISTS:  task already has a port or port set named new_name. KERN_INVALID_ARGUMENT:  task was invalid, or task didn't know any ports or port sets named old_name, or new_name was an invalid name.

SEE ALSO port_names()

port_set_add()

SUMMARY Move the named port into the named port set SYNOPSIS #import <mach/mach.h>

kern_return_t port_set_add(task_t task, port_set_name_t set_name, port_name_t port_name)

ARGUMENTS task:  The task that has receive rights for the port set and port.

set_name:  task's name for the port set. port_name:  task's name for the port.

DESCRIPTION The function port_set_add() moves the named port into the named port set.  The task must have receive rights for the port.  If the port is already a member of another port set, it's removed from that set first. EXAMPLE kern_return_t    error;

port_set_name_t  set_name;
port_t           my_port;

error=port_set_allocate(task_self(),&set_name);
if (error != KERN_SUCCESS) {
mach_error("port_set_allocate failed", error);
exit(1);
}

error=port_allocate(task_self(),&my_port);
if (error != KERN_SUCCESS) {
mach_error("port_allocate failed", error);
exit(1);
}

error=port_set_add(task_self(), set_name, my_port);
if (error != KERN_SUCCESS) {
mach_error("port_allocate failed", error);
exit(1);
}

RETURN KERN_SUCCESS:  The call succeeded.

KERN_NOT_RECEIVER:  task doesn't have receive rights for the port. KERN_INVALID_ARGUMENT:  task was invalid, or set_name doesn't name a valid port set, or port_name doesn't name a valid port.

SEE ALSO port_set_remove()

port_set_allocate()

SUMMARY Create a port set SYNOPSIS #import <mach/mach.h>

kern_return_t port_set_allocate(task_t task, port_set_name_t *set_name)

ARGUMENTS task:  The task in which the new port set is created.

set_name:  Returns task's name for the new port set.

DESCRIPTION The function port_set_allocate() causes a port set to be created for the specified task; the resulting set's name is returned in set_name.  The new port set is empty. EXAMPLE kern_return_t    error;

port_set_name_t  set_name;

error=port_set_allocate(task_self(),&set_name);
if (error != KERN_SUCCESS) {
mach_error("port_set_allocate failed", error);
exit(1);
}

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  task was invalid. KERN_RESOURCE_SHORTAGE:  The kernel ran out of memory.

SEE ALSO port_set_deallocate(), port_set_add()

port_set_backlog()

SUMMARY Set the size of the port queue SYNOPSIS #import <mach/mach.h>

kern_return_t port_set_backlog(task_t task, port_name_t port_name, int backlog)

ARGUMENTS task:  The task that has receive rights for the named port (for example, use task_self() to specify the caller's task).

port_name:  task's name for the port. backlog:  The new backlog to be set.

DESCRIPTION The function port_set_backlog() changes the backlog value on the specified port (the port's backlog value is the number of unreceived messages that are allowed in its message queue before the kernel will refuse to accept any more sends to that port).

The task specified by task must have receive rights for the named port. The maximum backlog value is the constant PORT_BACKLOG_MAX.  You can get a port's current backlog value by calling port_status().

EXAMPLE #define MY_BACKLOG  10

kern_return_t   error;
port_t          my_port;

error=port_allocate(task_self(),&my_port);
if (error != KERN_SUCCESS) {
mach_error("port_allocate failed", error);
exit(1);
}

error=port_set_backlog(task_self(), my_port, MY_BACKLOG);
if (error!=KERN_SUCCESS)
mach_error("Call to port_set_backlog failed", error);

RETURN KERN_SUCCESS:  The backlog value has been changed.

KERN_NOT_RECEIVER:  task doesn't have receive rights for the port. KERN_INVALID_ARGUMENT:  task was invalid, or port_name doesn't name a valid port, or the desired backlog wasn't greater than 0, or the desired backlog was greater than PORT_BACKLOG_MAX.

SEE ALSO msg_send(), port_status()

port_set_backup()

SUMMARY Set the backup port for a port SYNOPSIS #import <mach/mach.h>

kern_return_t port_set_backup(task_t task, port_name_t port_name, port_t backup, port_t *previous)

ARGUMENTS task:  The task that has receive rights for the named port (for example, use task_self() to specify the caller's task).

port_name:  task's name for the port right. backup:  The new backup port.  If you want to disable the current backup port without setting a new one, set this to PORT_NULL. previous:  Returns the previous backup port.

DESCRIPTION Use this function to keep a port alive despite its being deallocated by its receiver.  If the call to port_set_backup() is successful, then whenever port_name is deallocated by its receiver, backup will receive a notification message with receive and send rights for port_name.  As far as task is concerned, the port will be deleted; however, as far as senders to the port are concerned, the port will continue to exist.

To let a port die naturally after its backup port has been set, call port_set_backup() on it with backup set to PORT_NULL.

EXAMPLE kern_return_t    error;

port_t           my_port, backup_port, previous_port;

error=port_allocate(task_self(),&my_port);
if (error != KERN_SUCCESS) {
mach_error("port_allocate failed", error);
exit(1);
}

error=port_allocate(task_self(),&backup_port);
if (error != KERN_SUCCESS) {
mach_error("port_allocate failed", error);
exit(1);
}

error=port_set_backup(task_self(), my_port, backup_port,
&previous_port);
if (error!=KERN_SUCCESS)
mach_error("Call to port_set_backlog failed", error);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  task was invalid, or port_name doesn't name a valid port. KERN_NOT_RECEIVER:  task doesn't have receive rights for port_name. port_set_deallocate()

SUMMARY Destroy a port set SYNOPSIS #import <mach/mach.h>

kern_return_t port_set_deallocate(task_t task, port_set_name_t set_name)

ARGUMENTS task:  The task that has receive rights for the port set to be destroyed.

set_name:  task's name for the doomed port set.

DESCRIPTION The function port_set_deallocate() requests that the port set of task be destroyed.  If the port set isn't empty, any members are first removed. EXAMPLE kern_return_t   error;

port_set_name_t set_name;

error=port_set_deallocate(task_self(),set_name);
if (error != KERN_SUCCESS) {
mach_error("port_set_deallocate failed", error);
exit(1);
}

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  task was invalid or set_name doesn't name a valid port set.

SEE ALSO port_set_allocate()

port_set_remove()

SUMMARY Remove the named port from a port set SYNOPSIS #import <mach/mach.h>

kern_return_t port_set_remove(task_t task, port_name_t port_name)

ARGUMENTS task:  The task that has receive rights for the port and port set.

port_name:  task's name for the receive rights to be removed.

DESCRIPTION The function port_set_remove() removes the named port from a port set.  The task must have receive rights for the port, and the port must be a member of a port set. EXAMPLE error=port_set_remove(task_self(), my_port);

if (error != KERN_SUCCESS) {
mach_error("port_set_remove failed", error);
exit(1);
}

RETURN KERN_SUCCESS:  The call succeeded.

KERN_NOT_RECEIVER:  task doesn't have receive rights for the port. KERN_NOT_IN_SET:  The port isn't a member of a set. KERN_INVALID_ARGUMENT:  task was invalid or port_name doesn't name a valid port.

SEE ALSO port_set_add()

port_set_status()

SUMMARY Get the members of a port set SYNOPSIS #import <mach/mach.h>

kern_return_t port_set_status(task_t task, port_set_name_t set_name, port_name_array_t *members, unsigned int *members_count)

ARGUMENTS task:  The task whose port set is queried.

set_name:  task's name for the port set. members:  Returns task's names for the members of its port set. members_count:  Returns the number of port names in members.

DESCRIPTION The function port_set_status() returns a list of the ports in a port set.  The members argument is an array that's automatically allocated when the reply message is received.  You should use vm_deallocate() on it when the data is no longer needed. EXAMPLE error=port_set_status(task_self(), set_name, &members,

&members_count);
if (error != KERN_SUCCESS) {
mach_error("port_set_status failed", error);
exit(1);
}

/* . . . */
error=vm_deallocate(task_self(), (vm_address_t)members,
sizeof(members)*members_count);
if (error != KERN_SUCCESS)
mach_error("Trouble freeing members", error);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  task was invalid or set_name doesn't name a valid port set.

SEE ALSO port_status()

port_status()

SUMMARY Examine a port's current status SYNOPSIS #import <mach/mach.h>

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)

ARGUMENTS task:  The task that has receive rights for the port in question (for example, use task_self() to specify the caller's task).

port_name:  task's name for the port right. port_set_name:  Returns task's name for the port set that the named port belongs to, or PORT_NULL if it isn't in a set. num_msgs:  Returns the number of messages queued on this port.  If task isn't the port's receiver, the number of messages will be returned as negative. backlog:  Returns the number of messages that can be queued to this port without causing the sender to block. owner:  Returns the same value as receiver, since ownership rights and receive rights aren't separable. receiver:  Returns true if task has receive rights to port_name; otherwise, returns false.

DESCRIPTION The function port_status() returns the current port status associated with port_name. EXAMPLE error=port_status(task_self(), my_port, &port_set_name, &num_msgs,

&backlog, &owner, &receiver);
if (error!=KERN_SUCCESS)
mach_error("Call to port_status failed", error);

RETURN KERN_SUCCESS:  The data has been retrieved.

KERN_INVALID_ARGUMENT:  task was invalid or port_name doesn't name a valid port.

SEE ALSO port_set_backlog(), port_set_status()

port_type()

SUMMARY Determine the access rights of a task for a specific port name SYNOPSIS #import <mach/mach.h>

kern_return_t port_type(task_t task, port_name_t port_name, port_type_t *port_type)

ARGUMENTS task:  The task whose port name space is queried.

port_name:  The name being queried. port_type:  Returns a value that indicates what kind of rights the task holds for the port, or whether the name refers to a port set. This value is one of the following:  PORT_TYPE_SEND (send rights only), PORT_TYPE_RECEIVE_OWN (send and receive rights), PORT_TYPE_SET (the port is a port set).

DESCRIPTION The function port_type() returns information about task's rights for a specific name in its port name space. EXAMPLE error=port_type(task_self(), port, &type);

if (error != KERN_SUCCESS)
mach_error("Couldn't get type of port", error);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  task was invalid or task didn't have any rights named port_name.

SEE ALSO port_names(), port_status(), port_set_status()

processor_assign(), processor_control(), processor_exit(), processor_get_assignment(), processor_start()

SUMMARY Control a processor SYNOPSIS #import <mach/mach.h>

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)

DESCRIPTION processor_assign() changes the processor set to which processor is assigned.  processor_control() returns information about processor.  processor_exit() shuts down processor.  processor_get_assignment() returns the processor set to which processor is assigned.  processor_start() starts up processor.

Note:  These functions are useful only on multiprocessor systems. processor_info()

SUMMARY Get information about a processor SYNOPSIS #import <mach/mach.h>

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

ARGUMENTS processor:  The processor for which information is to be obtained.

flavor:  The type of information that is wanted.  Currently only PROCESSOR_BASIC_INFO is implemented. host:  Returns the non-privileged host port for the host on which the processor resides. processor_info:  Returns information about the processor specified by processor. processor_info_count:  Size of the info structure.  Should be PROCESSOR_BASIC_INFO_COUNT when flavor is PROCESSOR_BASIC_INFO.

DESCRIPTION Returns the selected information array for a processor, as specified by flavor.  The processor_info argument is an array of integers that is supplied by the caller and filled with specified information.  The processor_info_count argument is supplied as the maximum number of integers in processor_info.  On return, it contains the actual number of integers in processor_info.

Basic information is defined by PROCESSOR_BASIC_INFO.  The size of this information is defined by PROCESSOR_BASIC_INFO_COUNT.  The data structures used by PROCESSOR_BASIC_INFO are defined in the header file mach/processor_info.h.  Possible values of the cpu_type and cpu_subtype fields are defined in the header file mach/machine.h.

typedef int *processor_info_t;  /* variable length array of int */

/* one interpretation of info is */
struct processor_basic_info {
cpu_type_t     cpu_type;    /* cpu type */
cpu_subtype_t  cpu_subtype; /* cpu subtype */
boolean_t      running;     /* is processor running? */
int            slot_num;    /* slot number */
boolean_t      is_master;   /* is this the master processor */
};

typedef struct processor_basic_info *processor_basic_info_t;

EXAMPLE kern_return_t                  error;

host_t                         host;
unsigned int                   list_size, info_count;
struct processor_basic_info    info;
processor_array_t              list;

/* Get the processor port. */
error=host_processors(host_priv_self(), &list, &list_size);
if ((error!=KERN_SUCCESS) || (list_size < 1)){
mach_error("Error calling host_processors (are you root?)",
error);
exit(1);
}

/* Get information about the processor. */
info_count=PROCESSOR_BASIC_INFO_COUNT;
error=processor_info(list[0], PROCESSOR_BASIC_INFO, &host,
(processor_info_t)&info, &info_count);
if (error != KERN_SUCCESS)
mach_error("Error calling processor_info", error);

/* Now that we're done with the processor port, free it. */
vm_deallocate(task_self(), (vm_address_t)list,
sizeof(list)*list_size);
if (error!=KERN_SUCCESS)
mach_error("Trouble freeing list", error);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  processor isn't a known processor. MIG_ARRAY_TOO_LARGE:  Returned info array is too large for processor_info.  The processor_info argument is filled as much as possible, and processor_info_count is set to the number of elements that would be returned if there were enough room. KERN_FAILURE:  flavor isn't recognized or processor_info_count is too small.

SEE ALSO processor_start(), processor_exit(), processor_control(), host_processors()

processor_set_create()

SUMMARY Create a new processor set SYNOPSIS #import <mach/mach.h>

kern_return_t processor_set_create(host_t host, port_t *new_set, port_t *new_name)

DESCRIPTION This function creates a new processor set on host.

Note:  This function is useful only on multiprocessor systems. processor_set_default()

SUMMARY Get the port of the default processor set SYNOPSIS #import <mach/mach.h>

kern_return_t processor_set_default(host_t host, processor_set_t *default_set)

ARGUMENTS host:  The host whose default processor set is requested.

default_set:  Returns the name (nonprivileged) port for the default processor set.

DESCRIPTION The default processor set is used by all threads, tasks, and processors that aren't explicitly assigned to other sets.  This function returns a port that can be used to obtain information about this set (for example, how many threads are assigned to it).  This port isn't privileged and thus can't be used to perform operations on that set; call host_processor_set_priv() after processor_set_default() to get the privileged port. EXAMPLE error=processor_set_default(host_self(), &default_set);

if (error!=KERN_SUCCESS){
mach_error("Error calling processor_set_default", error);
exit(1);
}

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  host is not a host.

SEE ALSO processor_set_info(), task_assign(), thread_assign()

processor_set_destroy()

SUMMARY Delete a processor set SYNOPSIS #import <mach/mach.h>

kern_return_t processor_set_destroy(processor_set_t processor_set)

DESCRIPTION This function destroys processor_set, reassigning all of its tasks, threads, and processors to the default processor set.

Note:  This function is useful only on multiprocessor systems. processor_set_info()

SUMMARY Get information about a processor set SYNOPSIS #import <mach/mach.h>

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)

ARGUMENTS processor_set:  The processor set for which information is to be obtained.

flavor:  The type of information that is wanted.  Should be PROCESSOR_SET_BASIC_INFO or PROCESSOR_SET_SCHED_INFO. host:  Returns the nonprivileged host port for the host on which the processor set resides. processor_set_info:  Returns information about the processor set specified by processor_set. processor_set_info_count:  Size of the info structure.  Should be PROCESSOR_SET_BASIC_INFO_COUNT when flavor is PROCESSOR_SET_BASIC_INFO, and PROCESSOR_SET_SCHED_INFO_COUNT when flavor is PROCESSOR_SET_SCHED_INFO.

DESCRIPTION Returns the selected information array for a processor set, as specified by flavor.  The processor_set_info argument is an array of integers that is supplied by the caller, and filled with specified information.  The processor_set_info_count argument is supplied as the maximum number of integers in processor_set_info.  On return, it contains the actual number of integers in processor_set_info.

Basic information is defined by PROCESSOR_SET_BASIC_INFO.  The size of this information is defined by PROCESSOR_SET_BASIC_INFO_COUNT.  The load_average and mach_factor fields are scaled by the constant LOAD_SCALE (that is, the integer value returned is the load average or Mach factor multiplied by LOAD_SCALE). The Mach factor, like the UNIX load average, is a measurement of how busy the system is.  Unlike the load average, higher Mach factors mean that the system is less busy.  The Mach factor tells you how much of a CPU you have available for running an application.  For example, on a single-processor system with one job running, the Mach factor is 0.5; this means if another job starts running it will get half of the CPU.  (Two jobs will be running, each getting half the CPU.)  On a single-processor system, the Mach factor is between zero and one.  On a multiprocessor system, the Mach factor can go over one.  For example, a three-processor system with one job running has a Mach factor of 2.0, since two processors are available to new jobs.

struct processor_set_basic_info {
int  processor_count;   /* number of processors */
int  task_count;        /* number of tasks */
int  thread_count;      /* number of threads */
int  load_average;      /* scaled load average */
int  mach_factor;       /* scaled mach factor */
};
typedef struct processor_set_basic_info *processor_set_basic_info_t;

Scheduling information is defined by PROCESSOR_SET_SCHED_INFO.  The size of this information is given by PROCESSOR_SET_SCHED_INFO_COUNT.

struct processor_set_sched_info {
int  policies;          /* allowed policies */
int  max_priority;      /* max priority for new threads */
};
typedef struct processor_set_sched_info *processor_set_sched_info_t;

EXAMPLE kern_return_t                    error;

host_t                           host;
unsigned int                     info_count;
struct processor_set_basic_info  info;
processor_set_t                  default_set;

error=processor_set_default(host_self(), &default_set);
if (error!=KERN_SUCCESS){
mach_error("Error calling processor_set_default", error);
exit(1);
}

info_count=PROCESSOR_SET_BASIC_INFO_COUNT;
error=processor_set_info(default_set, PROCESSOR_SET_BASIC_INFO,
&host, (processor_set_info_t)&info, &info_count);
if (error != KERN_SUCCESS)
mach_error("Error calling processor_set_info", error);

printf("The UNIX load average is %f\n",
(float)info.load_average/LOAD_SCALE);
printf("The Mach factor is %f\n", (float)info.mach_factor/LOAD_SCALE);

RETURN KERN_SUCCESS:  The call succeeded.

KERN_INVALID_ARGUMENT:  processor_set is not a processor set, or flavor is not recognized. KERN_FAILURE:  processor_set_info_count is less than what it should be. MIG_ARRAY_TOO_LARGE:  Returned info array is too large for processor_set_info.

SEE ALSO processor_set_create(), processor_set_default(), processor_assign(), task_assign(), thread_assign()

processor_set_max_priority()

SUMMARY Set the maximum priority permitted on a processor set SYNOPSIS #import <mach/mach.h>

kern_return_t processor_set_max_priority(processor_set_t processor_set, int max_priority, boolean_t change_threads)

DESCRIPTION This function affects only newly created or newly assigned threads unless you specify change_threads as true.

Note:  This function is useful only on multiprocessor systems. processor_set_policy_enable(), processor_set_policy_disable()

SUMMARY Enable or disable a scheduling policy on a processor set SYNOPSIS #import <mach/mach.h>

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)

ARGUMENTS processor_set:  The processor set whose allowed policies are to be changed.  This must be the privileged processor set port, which is returned by host_processor_set_priv().

policy:  The policy to enable or disable.  Currently, the only valid policies are POLICY_TIMESHARE, POLICY_INTERACTIVE, and POLICY_FIXEDPRI.  You can't disable timesharing. change_threads:  Specify true if you want to reset to timesharing the policies of any threads with the newly disallowed policy. Otherwise, specify false.

DESCRIPTION Processor sets may restrict the scheduling policies to be used for threads assigned to them.  These two calls provide the mechanism for designating permitted and forbidden policies.  The current set of permitted policies can be obtained from processor_set_info().  Timesharing can't be forbidden by any processor set.  This is a compromise to reduce the complexity of the assign operation; any thread whose policy is forbidden by the target processor set has its policy reset to timesharing.  If the change_threads argument to processor_set_policy_disable() is true, threads currently assigned to this processor set and using the newly disabled policy will have their policy reset to timesharing.

Warning:  Don't use POLICY_FIXEDPRI unless you're familiar with the consequences of fixed-priority scheduling.  Using fixed-priority scheduling in a process can keep other processes from getting any CPU time.  If processes that are essential to the functioning of the system don't get CPU time, you might have to reboot your system to make it work normally.

EXAMPLE kern_return_t    error;

processor_set_t  default_set, default_set_priv;

error=processor_set_default(host_self(), &default_set);
if (error!=KERN_SUCCESS) {
mach_error("Error calling processor_set_default()", error);
exit(1);
}

error=host_processor_set_priv(host_priv_self(), default_set,
&default_set_priv);
if (error != KERN_SUCCESS) {
mach_error("Call to host_processor_set_priv() failed", error);
exit(1);
}

error=processor_set_policy_enable(default_set_priv, POLICY_FIXEDPRI);
if (error != KERN_SUCCESS)
mach_error("Error calling processor_set_policy_enable", error);

RETURN KERN_SUCCESS:  Operation completed successfully.