The NSExceptionHandler class provides facilities for monitoring and debugging exceptional conditions in Objective-C programs. It works by installing a special uncaught exception handler via the NSSetUncaughtExceptionHandler function. Consequently, to use the services of NSExceptionHandler, you must not install your own custom uncaught exception handler.

To use these services, you set a bit mask in the singleton NSExceptionHandler instance and, optionally, a delegate. The constants comprising the bit mask indicate the type of exception to be monitored and the behavior of the NSExceptionHandler object (or, simply, the exception handler). The delegate is asked to approve the logging and handling of each monitored NSException object using the NSExceptionHandlerDelegate protocol.

The constants for configuring exception handler behavior can be categorized in several ways:

Uncaught exceptions versus caught exceptions—or, more accurately, exceptions that would be caught (for example, by the top-level handler)

Exception type or cause: system exceptions (such as invalid memory accesses), Objective-C runtime errors (such as messages sent to freed objects), and other exceptions

Exception handler behavior: logging the exception (including a stack trace) to the console, handling the exception, and suspending program execution so the debugger can be attached

The way the exception handler handles an exception depends on the type of exception; the exception handler converts system exceptions and runtime errors into NSException objects with a stack trace embedded in their userInfo dictionary; for all other uncaught exceptions, it terminates the thread on which they occur . The constants used to configure an NSExceptionHandler object are described in Logging and Handling Constants and System Hang Constants.

Declaration

Return Value

A bit mask composed of one or more constants specifying the types of exceptions monitored and whether they are handled or logged (or both). See Logging and Handling Constants for information about the constants.

Declaration

Parameters

aMask

A bit mask composed of one or more constants specifying the types of exceptions monitored and whether they are handled or logged (or both). You specify multiple constants by performing a bitwise-OR operation. See Logging and Handling Constants for information about the constants.

Declaration

Parameters

aMask

A bit mask composed of one or more constants specifying the types of exceptions that will halt execution for debugging. You specify multiple constants by performing a bitwise-OR operation. See System Hang Constants for information about the constants.

Import Statement

Availability

Use one or more of the following constants in the parameter of setExceptionHandlingMask: to specify the types of exceptions that the exception handler should monitor and whether it should handle or log them.

Constants

The exception handler suspends execution when it detects an uncaught exception (other than a system exception or runtime error).

Available in OS X v10.0 and later.

NSHangOnUncaughtSystemExceptionMask

NSHangOnUncaughtSystemExceptionMask

The exception handler suspends execution when it detects an uncaught system exception.

Available in OS X v10.0 and later.

NSHangOnUncaughtRuntimeErrorMask

NSHangOnUncaughtRuntimeErrorMask

The exception handler suspends execution when it detects an uncaught runtime error.

Available in OS X v10.0 and later.

NSHangOnTopLevelExceptionMask

NSHangOnTopLevelExceptionMask

The exception handler suspends execution when it detects an exception that would be handled by the top-level handler.

Available in OS X v10.0 and later.

NSHangOnOtherExceptionMask

NSHangOnOtherExceptionMask

The exception handler suspends execution when it detects an exception that would be handled by an object other than the top-level handler.

Available in OS X v10.0 and later.

Discussion

When exception-handling domains are nested, NSHangOnTopLevelExceptionMask deals with exceptions that would make it to the top two levels of exception handlers. In the main thread of a Cocoa application, the top-level handler is the global NSApplication instance.

Two of the following global string constants identify exceptions generated by the framework for Objective-C runtime errors and system exceptions such as invalid memory accesses. The other constant is used as a key to access the stack trace in the userInfo dictionary of an NSException object, when requested.