Mac Developer Library

Developer

ExceptionHandling Framework Reference NSExceptionHandler Class Reference

Options
Deployment Target:

On This Page
Language:

NSExceptionHandler

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

Inheritance


Conforms To


Import Statement


import ExceptionHandling @import ExceptionHandling;

Availability


OS X v10.0
  • Returns the singleton NSExceptionHandler instance.

    Declaration

    Swift

    class func defaultExceptionHandler() -> NSExceptionHandler!

    Objective-C

    + (NSExceptionHandler *)defaultExceptionHandler

    Import Statement

    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

    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

    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

    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

    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

    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 in NSExceptionHandlerDelegate Informal Protocol Reference

    Import Statement

    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.

    Import Statement

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

    Import Statement

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

    Import Statement

  • 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

    var NSUncaughtSystemExceptionException: NSString! var NSUncaughtRuntimeErrorException: NSString! var NSStackTraceKey: NSString!

    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 in NSExceptionHandlerDelegate Informal Protocol Reference.

      Available in OS X v10.0 and later.

    Import Statement