catch_exception_raise


Server Interface - Handles the occurrence of an exception within a thread.

SYNOPSIS

kern_return_t   catch_exception_raise
                (mach_port_t                          exception_port,
                 mach_port_t                                  thread,
                 mach_port_t                                    task,
                 exception_type_t                          exception,
                 exception_data_t                               code,
                 mach_msg_type_number_t                   code_count);

catch_exception_raise_state expanded form:

kern_return_t   catch_exception_raise_state
                (mach_port_t                          exception_port,
                 exception_type_t                          exception,
                 exception_data_t                               code,
                 mach_msg_type_number_t                   code_count,
                 int *                                        flavor,
                 thread_state_t                             in_state,
                 mach_msg_type_number_t               in_state_count,
                 thread_state_t                            out_state,
                 mach_msg_type_number_t *            out_state_count);

catch_exception_raise_state_identity expanded form:

kern_return_t   catch_exception_raise_state_identity
                (mach_port_t                          exception_port,
                 mach_port_t                                  thread,
                 mach_port_t                                    task,
                 exception_type_t                          exception,
                 exception_data_t                               code,
                 mach_msg_type_number_t                   code_count,
                 int *                                        flavor,
                 thread_state_t                             in_state,
                 mach_msg_type_number_t               in_state_count,
                 thread_state_t                            out_state,
                 mach_msg_type_number_t *            out_state_count);

PARAMETERS

exception_port
[in exception (receive) right] The port to which the exception notification was sent.

thread
[in thread-self send right] The thread self port for the thread taking the exception.

task
[in task-self send right] The task self port for the task containing the thread taking the exception.

exception
[in scalar] The type of the exception. The machine independent values raised by all implementations are:

EXC_BAD_ACCESS
Could not access memory. subcode contains the bad memory address.

EXC_BAD_INSTRUCTION
Instruction failed. Illegal or undefined instruction or operand.

EXC_ARITHMETIC
Arithmetic exception; exact nature of exception is in subcode field.

EXC_EMULATION
Emulation instruction. Emulation support instruction encountered. Details in subcode field.

EXC_SOFTWARE
Software generated exception; exact exception is in subcode field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000 - 0x1FFFF reserved for OS emulation.

EXC_BREAKPOINT
Trace, breakpoint, etc. Details in subcode field.

EXC_SYSCALL
System call requested. Details in subcode field.

EXC_MACH_SYSCALL
System call with a number in the Mach call range requested. Details in subcode field.
code
[in scalar] A machine dependent array indicating a particular instance of exception.

code_count
[in scalar] The size of the buffer (in natural-sized units).

flavor
[pointer to in/out scalar] On input, the type of state included as selected when the exception port was set. On output, the type of state being returned.

in_state
[pointer to in structure] State information of the thread at the time of the exception.

in_state_count
[in scalar] The size of the in state buffer (in natural-sized units).

out_state
[out structure] The state the thread will have if continued from the point of the exception. The maximum size of this array is THREAD_STATE_MAX.

out_state_count
[pointer to out scalar] The size of the out state buffer (in natural-sized units).

DESCRIPTION

A catch_exception_raise function is called by exc_server as the result of a kernel message indicating that an exception occurred within a thread. The exception_port parameter specifies the port named via a previous call to thread_set_exception_ports or task_set_exception_ports as the port that responds when the thread takes an exception.

The alternate message forms (the format being selected when the exception port was set) allow for selected thread state to be included.

NOTES

When an exception occurs in a thread, the thread sends an exception message to its exception port, blocking in the kernel waiting for the receipt of a reply. It is assumed that some task is listening (most likely with mach_msg_server) to this port, using the exc_server function to decode the messages and then call the linked in catch_exception_raise. It is the job of catch_exception_raise to handle the exception and decide the course of action for thread.

If the thread should continue from the point of exception, catch_exception_raise would return KERN_SUCCESS. This causes a reply message to be sent to the kernel, which will allow the thread to continue from the point of the exception. If some other action should be taken by thread, the following actions should be performed by catch_exception_raise:

thread_suspend
This keeps the thread from proceeding after the next step.

thread_abort
This aborts the message receive operation currently blocking the thread.

thread_set_state
(if using the catch_exception_raise form). Set the thread's state so that it continues doing something else.

thread_resume
Let the thread start running from its new state.
Returning a value other than KERN_SUCCESS insures that no reply message will be sent. sent. (Actually, the kernel uses a send once right to send the exception message, which thread_abort destroys, so replying to the message is harmless.) The thread can always be destroyed with thread_terminate.

A thread can have two exception ports active for it: its thread type specific exception port and the task type specific exception port. The kernel will try sending an exception message to both ports looking for a reply message with a return value of KERN_SUCCESS. The kernel tries the thread specific port first, then the task specific port. If the return value from the first exception message the kernel sends has a return value of KERN_SUCCESS, the thread continues (with a possibly modified state). If the return value is not KERN_SUCCESS, the kernel tries the second port. If that return value is KERN_SUCCESS, the thread continues; otherwise, the thread is terminated.

To get the effect of a non-success return value, the server interface should return MIG_DESTROY_REQUEST. This causes exc_server and mach_msg_server to destroy the kernel's request (as opposed to sending a reply with a KERN_SUCCESS value).

RETURN VALUES

A return value of KERN_SUCCESS indicates that the thread is to continue from the point of exception. A return value of MIG_NO_REPLY indicates that the exception was handled directly and the thread was restarted or terminated by the exception handler. A return value of MIG_DESTROY_REQUEST causes the kernel to try another exception handler (or terminate the thread). Any other value will cause mach_msg_server to remove the task and thread port references.

RELATED INFORMATION

Functions: exc_server, thread_abort, task_get_exception_ports, thread_get_exception_ports, thread_get_state, thread_resume, task_set_exception_ports, thread_set_exception_ports, task_swap_exception_ports, thread_swap_exception_ports, thread_set_state, thread_suspend, thread_terminate.