Apple introduced NSError in Mac OS X 10.3 as a way of returning richer error results from methods. Consider reading the contents of a file into an NSData object:
+ (id) dataWithContentsOfFile: (NSString *) path;
If something goes wrong, you get nil back, and there’s not much you can do to figure out what went wrong. The updated version of this method looks like this:
+ (id) dataWithContentsOfFile: (NSString *) path options: (NSDataReadingOptions) readOptionsMask error: (NSError **) errorPtr;
Notice the NSError that is passed in. The method wants a pointer to a pointer. The method will fill in this pointer if the method failed. The return value of errorPtr is undefined if the method succeeded. Therefore, you should never use the value ...