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 |
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
Tasks
Creating and Raising an NSException Object
-
+ exceptionWithName:reason:userInfo: -
+ raise:format: -
+ raise:format:arguments: -
– initWithName:reason:userInfo: -
– raise
Querying an NSException Object
Getting Exception Stack Frames
Class Methods
exceptionWithName:reason:userInfo:
Creates and returns an exception object .
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.hraise:format:
A convenience method that creates and raises an exception.
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.
See Also
Declared In
NSException.hraise:format:arguments:
Creates and raises an exception with the specified name, reason, and arguments.
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.
See Also
Declared In
NSException.hInstance Methods
callStackReturnAddresses
Returns the call return addresses related to a raised exception.
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.hcallStackSymbols
Returns an array containing the current call symbols.
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.hinitWithName:reason:userInfo:
Initializes and returns a newly allocated exception object.
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.
See Also
Declared In
NSException.hname
Returns an NSString object used to uniquely identify the receiver.
Availability
- Available in iOS 2.0 and later.
Declared In
NSException.hraise
Raises the receiver, causing program flow to jump to the local exception handler.
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 iOS 2.0 and later.
See Also
Declared In
NSException.hreason
Returns an NSString object containing a “human-readable” reason for the receiver.
Availability
- Available in iOS 2.0 and later.
Declared In
NSException.huserInfo
Returns an NSDictionary object containing application-specific data pertaining to the receiver.
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© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-08-28)