Up

# NSAssertionHandler class reference

### Authors

Adam Fedor (`fedor@boulder.colorado.edu`)

Version: 37003

Date: 2013-08-22 16:44:54 +0100 (Thu, 22 Aug 2013)

Copyright: (C) 1995, 1996 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSAssertionHandler class
2. Software documentation for the NSException class

# Software documentation for the NSAssertionHandler class

## NSAssertionHandler : NSObject

> Declared in:
>   Foundation/NSException.h

Availability: OpenStep

NSAssertionHandler objects are used to raise exceptions on behalf of macros implementing assertions.
Each thread has its own assertion handler instance.

The macros work together with the assertion handler object to produce meaningful exception messages containing the name of the source file, the position within that file, and the name of the ObjC method or C function in which the assertion failed.

An NSAssertionHandler instance is created on demand for each thread and is stored in the thread's dictionary under the key NSAssertionHandler. A custom NSAssertionHandler can be used by adding it to the thread dictionary under this key.

The assertion macros are: NSAssert() , NSCAssert() , NSAssert1() , NSCAssert1() , NSAssert2() , NSCAssert2() , NSAssert3() , NSCAssert3() , NSAssert4() , NSCAssert4() , NSAssert5() , NSCAssert5() , NSParameterAssert() , NSCParameterAssert()

Method summary

- +currentHandler
- -handleFailureInFunction:file:lineNumber:description:,...
- -handleFailureInMethod:object:file:lineNumber:description:,...

### currentHandler

+ (NSAssertionHandler*) currentHandler;
Availability: OpenStep
Returns the assertion handler object for the current thread.
If none exists, creates one and returns it.

### handleFailureInFunction: file: lineNumber: description: ,...

- (void) handleFailureInFunction: (NSString*)functionName file: (NSString*)fileName lineNumber: (NSInteger)line description: (NSString*)format,...;
Availability: OpenStep
Handles an assertion failure by using NSLogv() to print an error message built from the supplied arguments, and then raising an NSInternalInconsistencyException

### handleFailureInMethod: object: file: lineNumber: description: ,...

- (void) handleFailureInMethod: (SEL)aSelector object: (id)object file: (NSString*)fileName lineNumber: (NSInteger)line description: (NSString*)format,...;
Availability: OpenStep
Handles an assertion failure by using NSLogv() to print an error message built from the supplied arguments, and then raising an NSInternalInconsistencyException

# Software documentation for the NSException class

## NSException : NSObject

> Declared in:
>   Foundation/NSException.h

> Conforms to:
>   NSCoding
>   NSCopying

Availability: OpenStep

The `NSException` class helps manage errors in a program. It provides a mechanism for lower-level methods to provide information about problems to higher-level methods, which more often than not, have a better ability to decide what to do about the problems.

Exceptions are typically handled by enclosing a sensitive section of code inside the macros `NS_DURING` and `NS_HANDLER`, and then handling any problems after this, up to the `NS_ENDHANDLER` macro:

       NS_DURING
        code that might cause an exception
       NS_HANDLER
        code that deals with the exception. If this code cannot deal with
        it, you can re-raise the exception like this
        [localException raise]
        so the next higher level of code can handle it
       NS_ENDHANDLER

The local variable `localException` is the name of the exception object you can use in the `NS_HANDLER` section. The easiest way to cause an exception is using the +raise:format:,... method.

If there is no NS_HANDLER... NS_ENDHANDLER block enclosing (directly or indirectly) code where an exception is raised, then control passes to the uncaught exception handler function and the program is then terminated.
The uncaught exception handler is set using NSSetUncaughtExceptionHandler() and if not set, defaults to a function which will simply print an error message before the program terminates.

Method summary

- +exceptionWithName:reason:userInfo:
- +raise:format:,...
- +raise:format:arguments:
- -callStackReturnAddresses
- -callStackSymbols
- -initWithName:reason:userInfo:
- -name
- -raise
- -reason
- -userInfo

### exceptionWithName: reason: userInfo:

+ (NSException*) exceptionWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo;
Availability: OpenStep
Create an an exception object with a name , reason and a dictionary userInfo which can be used to provide additional information or access to objects needed to handle the exception. After the exception is created you must -raise it.

### raise: format: ,...

+ (void) raise: (NSString*)name format: (NSString*)format,...;
Availability: OpenStep
Creates an exception with a name and a reason using the format string and any additional arguments. The exception is then raised using the -raise method.

### raise: format: arguments:

+ (void) raise: (NSString*)name format: (NSString*)format arguments: (va_list)argList;
Availability: OpenStep
Creates an exception with a name and a reason string using the format string and additional arguments specified as a variable argument list argList. The exception is then raised using the -raise method.

### callStackReturnAddresses

- (NSArray*) callStackReturnAddresses;
Availability: MacOS-X 10.5.0, Base 1.15.1
Returns an array of the call stack return addresses at the point when the exception was raised. Re-raising the exception does not change this value.

### callStackSymbols

- (NSArray*) callStackSymbols;
Availability: MacOS-X 10.6.0, Base 1.19.3
Returns an array of the symbolic names of the call stack return addresses. Note that, on some platforms, symbols are only exported in position-independent code and so these may only return numeric addresses for code in static libraries or the main application.

### initWithName: reason: userInfo:

- (id) initWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo;
Availability: OpenStep
This is a designated initialiser for the class.
Initializes a newly allocated NSException object with a name, reason and a dictionary userInfo.

### name

- (NSString*) name;
Availability: OpenStep
Returns the name of the exception.

### raise

- (void) raise;
Availability: OpenStep
Raises the exception. All code following the raise will not be executed and program control will be transfered to the closest calling method which encapsulates the exception code in an NS_DURING macro.
If the exception was not caught in a macro, the currently set uncaught exception handler is called to perform final logging and the program is then terminated.
If the uncaught exception handler fails to terminate the program, then the default behavior is to terminate the program as soon as the uncaught exception handler function returns.
NB. all other exception raising methods call this one, so if you want to set a breakpoint when debugging, set it in this method.

### reason

- (NSString*) reason;
Availability: OpenStep
Returns the exception reason.

### userInfo

- (NSDictionary*) userInfo;
Availability: OpenStep
Returns the exception userInfo dictionary.

Up