Mac Developer Library

Developer

ExceptionHandling Framework Reference NSExceptionHandler Class Reference

Options
Deployment Target:

On This Page
Language:

NSExceptionHandler

Inheritance


Conforms To


Import Statement


Swift

import ExceptionHandling

Objective-C

@import ExceptionHandling;

Availability


OS X v10.0

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.

The defaults command-line system also allows you to set values corresponding to the enum constants used to configure the exception handler; see Controlling a Program’s Response to Exceptions for details.

  • Returns the singleton NSExceptionHandler instance.

    Declaration

    Swift

    class func defaultExceptionHandler() -> NSExceptionHandler!

    Objective-C

    + (NSExceptionHandler *)defaultExceptionHandler

    Import Statement

    Objective-C

    @import ExceptionHandling;

    Swift

    import ExceptionHandling

    Availability

    Available in OS X v10.0 and later.

  • Returns a bit mask representing the types of exceptions monitored by the receiver and its handling and logging behavior.

    Declaration

    Swift

    func exceptionHandlingMask() -> Int

    Objective-C

    - (NSUInteger)exceptionHandlingMask

    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.

    Import Statement

    Objective-C

    @import ExceptionHandling;

    Swift

    import ExceptionHandling

    Availability

    Available in OS X v10.0 and later.

  • Returns a bit mask representing the types of exceptions that will halt execution for debugging.

    Declaration

    Swift

    func exceptionHangingMask() -> Int

    Objective-C

    - (NSUInteger)exceptionHangingMask

    Return Value

    A bit mask composed of one or more constants specifying the types of exceptions that will halt execution for debugging. See System Hang Constants for information about the constants.

    Import Statement

    Objective-C

    @import ExceptionHandling;

    Swift

    import ExceptionHandling

    Availability

    Available in OS X v10.0 and later.

  • Sets the bit mask of constants specifying the types of exceptions monitored by the receiver and its handling and logging behavior.

    Declaration

    Swift

    func setExceptionHandlingMask(_ aMask: Int)

    Objective-C

    - (void)setExceptionHandlingMask:(NSUInteger)aMask

    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.

    Import Statement

    Objective-C

    @import ExceptionHandling;

    Swift

    import ExceptionHandling

    Availability

    Available in OS X v10.0 and later.

  • Sets the bit mask of constants specifying the types of exceptions that will halt execution for debugging.

    Declaration

    Swift

    func setExceptionHangingMask(_ aMask: Int)

    Objective-C

    - (void)setExceptionHangingMask:(NSUInteger)aMask

    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

    Objective-C

    @import ExceptionHandling;

    Swift

    import ExceptionHandling

    Availability

    Available in OS X v10.0 and later.

  • Returns the delegate of the NSExceptionHandler object.

    Declaration

    Swift

    func delegate() -> AnyObject!

    Objective-C

    - (id)delegate

    Import Statement

    Objective-C

    @import ExceptionHandling;

    Swift

    import ExceptionHandling

    Availability

    Available in OS X v10.0 and later.

  • Sets the delegate of the NSExceptionHandler object.

    Declaration

    Swift

    func setDelegate(_ anObject: AnyObject!)

    Objective-C

    - (void)setDelegate:(id)anObject

    Parameters

    anObject

    The object to receive the delegation messages described in Logging and handling exceptions

    Import Statement

    Objective-C

    @import ExceptionHandling;

    Swift

    import ExceptionHandling

    Availability

    Available in OS X v10.0 and later.

  • 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.

    Declaration

    Swift

    var NSLogUncaughtExceptionMask: Int { get } var NSHandleUncaughtExceptionMask: Int { get } var NSLogUncaughtSystemExceptionMask: Int { get } var NSHandleUncaughtSystemExceptionMask: Int { get } var NSLogUncaughtRuntimeErrorMask: Int { get } var NSHandleUncaughtRuntimeErrorMask: Int { get } var NSLogTopLevelExceptionMask: Int { get } var NSHandleTopLevelExceptionMask: Int { get } var NSLogOtherExceptionMask: Int { get } var NSHandleOtherExceptionMask: Int { get }

    Objective-C

    enum { NSLogUncaughtExceptionMask = 1 << 0, NSHandleUncaughtExceptionMask = 1 << 1, NSLogUncaughtSystemExceptionMask = 1 << 2, NSHandleUncaughtSystemExceptionMask = 1 << 3, NSLogUncaughtRuntimeErrorMask = 1 << 4, NSHandleUncaughtRuntimeErrorMask = 1 << 5, NSLogTopLevelExceptionMask = 1 << 6, NSHandleTopLevelExceptionMask = 1 << 7, NSLogOtherExceptionMask = 1 << 8, NSHandleOtherExceptionMask = 1 << 9 };

    Constants

    • NSLogUncaughtExceptionMask

      NSLogUncaughtExceptionMask

      The exception handler logs uncaught exceptions.

      Available in OS X v10.0 and later.

    • NSHandleUncaughtExceptionMask

      NSHandleUncaughtExceptionMask

      The exception handler handles uncaught exceptions by terminating the thread in which they occur.

      Available in OS X v10.0 and later.

    • NSLogUncaughtSystemExceptionMask

      NSLogUncaughtSystemExceptionMask

      The exception handler logs uncaught system exceptions.

      Available in OS X v10.0 and later.

    • NSHandleUncaughtSystemExceptionMask

      NSHandleUncaughtSystemExceptionMask

      The exception handler handles uncaught system exceptions by converting them to NSException objects containing a stack trace.

      Available in OS X v10.0 and later.

    • NSLogUncaughtRuntimeErrorMask

      NSLogUncaughtRuntimeErrorMask

      The exception handler logs uncaught runtime errors.

      Available in OS X v10.0 and later.

    • NSHandleUncaughtRuntimeErrorMask

      NSHandleUncaughtRuntimeErrorMask

      The exception handler handles uncaught runtime errors by converting them to NSException objects containing a stack trace.

      Available in OS X v10.0 and later.

    • NSLogTopLevelExceptionMask

      NSLogTopLevelExceptionMask

      The exception handler logs exceptions that would be caught by the top-level handler.

      Available in OS X v10.0 and later.

    • NSHandleTopLevelExceptionMask

      NSHandleTopLevelExceptionMask

      The exception handler handles exceptions caught by the top-level handler by converting them to NSException objects containing a stack trace.

      Available in OS X v10.0 and later.

    • NSLogOtherExceptionMask

      NSLogOtherExceptionMask

      The exception handler logs exceptions caught by handlers lower than the top-level handler.

      Available in OS X v10.0 and later.

    • NSHandleOtherExceptionMask

      NSHandleOtherExceptionMask

      The exception handler handles exceptions caught by handlers lower than the top-level handler by converting them to NSException objects containing a stack trace.

      Available in OS X v10.0 and later.

    Discussion

    When exception-handling domains are nested, NSLogTopLevelExceptionMask and NSHandleTopLevelExceptionMask deal 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.

  • Use one or more of the following constants in the parameter of setExceptionHangingMask: to specify the types of exceptions that cause the exception to halt execution so a debugger can be attached.

    Declaration

    Swift

    var NSHangOnUncaughtExceptionMask: Int { get } var NSHangOnUncaughtSystemExceptionMask: Int { get } var NSHangOnUncaughtRuntimeErrorMask: Int { get } var NSHangOnTopLevelExceptionMask: Int { get } var NSHangOnOtherExceptionMask: Int { get }

    Objective-C

    enum { NSHangOnUncaughtExceptionMask = 1 << 0, NSHangOnUncaughtSystemExceptionMask = 1 << 1, NSHangOnUncaughtRuntimeErrorMask = 1 << 2, NSHangOnTopLevelExceptionMask = 1 << 3, NSHangOnOtherExceptionMask = 1 << 4 };

    Constants

    • NSHangOnUncaughtExceptionMask

      NSHangOnUncaughtExceptionMask

      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.

  • The following #define constants are conveniences for specifying complete sets of exception-handling enum constants.

    Declaration

    Objective-C

    NSHangOnEveryExceptionMask NSLogAndHandleEveryExceptionMask

    Constants

    • NSHangOnEveryExceptionMask

      NSHangOnEveryExceptionMask

      Combines via bitwise-OR all the constants listed in System Hang Constants.

      Available in OS X v10.0 and later.

    • NSLogAndHandleEveryExceptionMask

      NSLogAndHandleEveryExceptionMask

      Combines via bitwise-OR all the constants listed in Logging and Handling Constants.

      Available in OS X v10.0 and later.

  • 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.

    Declaration

    Swift

    let NSUncaughtSystemExceptionException: String let NSUncaughtRuntimeErrorException: String let NSStackTraceKey: String

    Objective-C

    EXCEPTIONHANDLING_EXPORT NSString *NSUncaughtSystemExceptionException; EXCEPTIONHANDLING_EXPORT NSString *NSUncaughtRuntimeErrorException; EXCEPTIONHANDLING_EXPORT NSString *NSStackTraceKey;

    Constants

    • NSUncaughtSystemExceptionException

      NSUncaughtSystemExceptionException

      Identifies an uncaught system exception.

      Available in OS X v10.0 and later.

    • NSUncaughtRuntimeErrorException

      NSUncaughtRuntimeErrorException

      Identifies an Objective-C runtime error.

      Available in OS X v10.0 and later.

    • NSStackTraceKey

      NSStackTraceKey

      The key for fetching the stack trace (an NSString object) in the userInfo dictionary of the NSException object passed into one of the delegate methods described in Logging and handling exceptions.

      Available in OS X v10.0 and later.