Up

# NSError class documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Copyright: (C) 2004,2006 Free Software Foundation, Inc.

# Software documentation for the NSError class

## NSError : NSObject

> Declared in:
>   Foundation/NSError.h

> Conforms to:
>   NSCopying
>   NSCoding

Availability: MacOS-X 10.3.0
Error information class.
NSError instances are used to pass information about runtime errors from lower levels to higher levels of the program.
These should be used instead of exceptions where an error is caused by external factors (such as a resource file not being present) rather than a programming error (where NSException should be used).
Method summary

- +errorWithDomain:code:userInfo:
- -code
- -domain
- -initWithDomain:code:userInfo:
- -localizedDescription
- -localizedFailureReason
- -localizedRecoveryOptions
- -localizedRecoverySuggestion
- -recoveryAttempter
- -userInfo

### errorWithDomain: code: userInfo:

+ (id) errorWithDomain: (NSErrorDomain)aDomain code: (NSInteger)aCode userInfo: (NSDictionary*)aDictionary;
Availability: MacOS-X 10.3.0
Creates and returns an autoreleased NSError instance by calling -initWithDomain:code:userInfo:

### code

- (NSInteger) code;
Availability: MacOS-X 10.3.0
Return the error code... which is not globally unique, just unique for a particular domain.

### domain

- (NSErrorDomain) domain;
Availability: MacOS-X 10.3.0
Return the domain for this instance.

### initWithDomain: code: userInfo:

- (id) initWithDomain: (NSErrorDomain)aDomain code: (NSInteger)aCode userInfo: (NSDictionary*)aDictionary;
Availability: MacOS-X 10.3.0
This is a designated initialiser for the class.
Initialises the receiver using the supplied domain, code, and info.
The domain must be non-nil.

### localizedDescription

- (NSString*) localizedDescription;
Availability: MacOS-X 10.3.0
Return a human readable description for the error.
The default implementation uses the value from the user info dictionary if it is available, otherwise it generates a generic one from domain and code.

### localizedFailureReason

- (NSString*) localizedFailureReason;
Availability: MacOS-X 10.4.0
Return a human readable explanation of the reason for the error (if known). This should normally be a more discursive explanation then the short one provided by the -localizedDescription method.
The default implementation uses the value from the user info dictionary if it is available, otherwise it returns `nil` .

### localizedRecoveryOptions

- (NSArray*) localizedRecoveryOptions;
Availability: MacOS-X 10.4.0
Returns an array of strings to be used as titles of buttons in an alert panel when offering the user optionbs to try to recover from the error.
The default implementation uses the value from the user info dictionary if it is available, otherwise it returns `nil`.

### localizedRecoverySuggestion

- (NSString*) localizedRecoverySuggestion;
Availability: MacOS-X 10.4.0
Returns a string used as the secondary text in an alert panel, suggesting how the user might select an option to attempt to recover from the error.
The default implementation uses the value from the user info dictionary if it is available, otherwise it returns `nil`.

### recoveryAttempter

- (id) recoveryAttempter;
Availability: MacOS-X 10.4.0
Not yet useful in GNUstep.
The default implementation uses the value from the user info dictionary if it is available, otherwise it returns `nil`.

### userInfo

- (NSDictionary*) userInfo;
Availability: MacOS-X 10.3.0
Return the user info for this instance (or `nil` if none is set)
The `NSLocalizedDescriptionKey` should locate a human readable description in the dictionary.
The `NSUnderlyingErrorKey` key should locate an `NSError` instance if an error is available describing any underlying problem.

Up