Mac Developer Library

Developer

Foundation Framework Reference NSException Class Reference

Options
Deployment Target:

On This Page
Language:

NSException

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.

NSException is used to implement exception handling and contains information about an exception. An exception is a special condition that interrupts the normal flow of program execution. Each application can interrupt the program for different reasons. For example, one application might interpret saving a file in a directory that is write-protected as an exception. In this sense, the exception is equivalent to an error. Another application might interpret the user’s key-press (for example, Control-C) as an exception: an indication that a long-running process should be aborted.

  • Creates and returns an exception object .

    Declaration

    Objective-C

    + (NSException *)exceptionWithName:(NSString *)name reason:(NSString *)reason userInfo:(NSDictionary *)userInfo

    Parameters

    name

    The name of the exception.

    reason

    A human-readable message string summarizing the reason for the exception.

    userInfo

    A dictionary containing user-defined information relating to the exception

    Return Value

    The created NSException object or nil if the object couldn't be created.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

  • A convenience method that creates and raises an exception.

    Declaration

    Objective-C

    + (void)raise:(NSString *)name format:(NSString *)format,, ...

    Parameters

    name

    The name of the exception.

    format,

    A human-readable message string (that is, the exception reason) with conversion specifications for the variable arguments that follow.

    ...

    Variable information to be inserted into the formatted exception reason (in the manner of printf).

    Discussion

    The user-defined information is nil for the generated exception object.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

  • Creates and raises an exception with the specified name, reason, and arguments.

    Declaration

    Swift

    class func raise(_ name: String, format format: String, arguments argList: CVaListPointer)

    Objective-C

    + (void)raise:(NSString *)name format:(NSString *)format arguments:(va_list)argList

    Parameters

    name

    The name of the exception.

    format

    A human-readable message string (that is, the exception reason) with conversion specifications for the variable arguments in argList.

    argList

    Variable information to be inserted into the formatted exception reason (in the manner of vprintf).

    Discussion

    The user-defined dictionary of the generated object is nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns a newly allocated exception object.

    Declaration

    Swift

    init(name name: String, reason reason: String?, userInfo userInfo: [NSObject : AnyObject]?)

    Objective-C

    - (instancetype)initWithName:(NSString *)name reason:(NSString *)reason userInfo:(NSDictionary *)userInfo

    Parameters

    name

    The name of the exception.

    reason

    A human-readable message string summarizing the reason for the exception.

    userInfo

    A dictionary containing user-defined information relating to the exception

    Return Value

    The created NSException object or nil if the object couldn't be created.

    Discussion

    This is the designated initializer.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Raises the receiver, causing program flow to jump to the local exception handler.

    Declaration

    Swift

    func raise()

    Objective-C

    - (void)raise

    Discussion

    When there are no exception handlers in the exception handler stack, unless the exception is raised during the posting of a notification, this method calls the uncaught exception handler, in which last-minute logging can be performed. The program then terminates, regardless of the actions taken by the uncaught exception handler.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The call return addresses related to a raised exception. (read-only)

    Declaration

    Swift

    var callStackReturnAddresses: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *callStackReturnAddresses

    Discussion

    An array of NSNumber objects encapsulating NSUInteger values. Each value is a call frame return address. The array of stack frames starts at the point at which the exception was first raised, with the first items being the most recent stack frames.

    NSException subclasses posing as the NSException class or subclasses or other API elements that interfere with the exception-raising mechanism may not get this information.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • An array containing the current call stack symbols. (read-only)

    Declaration

    Swift

    var callStackSymbols: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *callStackSymbols

    Discussion

    An array of strings describing the call stack backtrace at the moment the exception was first raised. The format of each string is determined by the backtrace_symbols() API

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.