---

NSException Class Reference

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 keypress (for example, Control-C) as an exception: an indication that a long-running process should be aborted.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

Tasks

Creating and Raising an NSException Object

• + exceptionWithName:reason:userInfo:
• + raise:format:
• + raise:format:arguments:
• – initWithName:reason:userInfo:
• – raise

Querying an NSException Object

• – name
• – reason
• – userInfo

Getting Exception Stack Frames

• – callStackReturnAddresses

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 Mac OS X v10.0 and later.

See Also

• – initWithName:reason:userInfo:
• – name
• – reason
• – userInfo

Related Sample Code

• Core Data HTML Store
• CoreRecipes

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 Mac OS X v10.0 and later.

See Also

• + raise:format:arguments:
• – raise

Related Sample Code

• EnhancedAudioBurn
• QTSSConnectionMonitor
• QTSSInspector
• Sketch-112
• TemperatureTester

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 Mac OS X v10.0 and later.

See Also

• + raise:format:
• – raise

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 Mac OS X v10.5 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 Mac OS X v10.0 and later.

See Also

• + exceptionWithName:reason:userInfo:

Declared In

NSException.h

name

Returns an NSString object used to uniquely identify the receiver.

- (NSString *)name

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + exceptionWithName:reason:userInfo:
• – initWithName:reason:userInfo:

Declared In

NSException.h

raise

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

- (void)raise

Discussion

All other methods that raise an exception invoke this method, so set a breakpoint here if you are debugging exceptions. 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 Mac OS X v10.0 and later.

See Also

• + raise:format:
• + raise:format:arguments:

Related Sample Code

• Core Data HTML Store

Declared In

NSException.h

reason

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

- (NSString *)reason

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + exceptionWithName:reason:userInfo:
• – initWithName:reason:userInfo:

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 Mac OS X v10.0 and later.

See Also

• + exceptionWithName:reason:userInfo:
• – initWithName:reason:userInfo:

Declared In

NSException.h

Constants

The string constants for exceptions are listed and described in the "Constants" chapter.

---