NSException Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
NSException.h
Related sample code

Overview

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.

Adopted Protocols

NSCoding
NSCopying

Tasks

Creating and Raising an NSException Object

Querying an NSException Object

Getting Exception Stack Frames

Class Methods

exceptionWithName:reason:userInfo:

Creates and returns an exception object .

+ (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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSException.h

raise:format:

A convenience method that creates and raises an exception.

+ (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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSException.h

raise:format:arguments:

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

+ (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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSException.h

Instance Methods

callStackReturnAddresses

Returns the call return addresses related to a raised exception.

- (NSArray *)callStackReturnAddresses
Return Value

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.

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSException.h

callStackSymbols

Returns an array containing the current call symbols.

- (NSArray *)callStackSymbols
Return Value

An array containing the current call stack symbols.

Discussion

This method returns an array of strings describing the call stack backtrace at the moment the exception was first raised. The format of each string is non-negotiable and is determined by the backtrace_symbols() API

Availability
  • Available in iOS 4.0 and later.
Declared In
NSException.h

initWithName:reason:userInfo:

Initializes and returns a newly allocated exception object.

- (id)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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSException.h

name

Returns an NSString object used to uniquely identify the receiver.

- (NSString *)name
Availability
  • Available in iOS 2.0 and later.
Declared In
NSException.h

raise

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

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSException.h

reason

Returns an NSString object containing a “human-readable” reason for the receiver.

- (NSString *)reason
Availability
  • Available in iOS 2.0 and later.
Declared In
NSException.h

userInfo

Returns an NSDictionary object containing application-specific data pertaining to the receiver.

- (NSDictionary *)userInfo
Discussion

Returns nil if no application-specific data exists. As an example, if a method’s return value caused the exception to be raised, the return value might be available to the exception handler through this method.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSException.h