I recently posted a rather lengthy explanation of Carbon's operating-system-error-code-based error-handling mechanism to Student-Dev, and thought those Cocoa programmers here who need to use Carbon calls for some things might be interested in this bit of explanation:

There's OSErr and OSStatus. What's the difference?

OSErr and OSStatus are effectively the same data type. OSErr is the older of the two, and has been around since the early days (I've been using it since System 6, but it probably was around since 1.0 or so). An OSErr is a short int (2 bytes), and when Apple realized they'd be running out of error numbers (there are some reserved numbers in the OSErr range), they introduced OSStatus (sometime during the System 8 or 9 days), which is a long int (4 bytes) and should suffice for a while.

What values can an OSStatus contain, and where can I find them?

Most of the values for OSErr and OSStatus are defined in the MacErrors.h header. If, for you, this header simply includes CoreServices/CoreServices.h, you caught the MacErrors.h file in FlatCarbon. The one in FlatCarbon is simply for backwards compatibility. So, make sure you look for the header in /System/Library/Frameworks

FlatCarbon ?!

In the old (pre-OS X) days, you'd explicitly include MacErrors.h. Since MacOS X we have umbrella headers in each framework that allow you to include one header and get all headers in that Framework. FlatCarbon is a hack to allow older code to be compiled without having to replace all those includes.

If you find a FlatCarbon header, you can fairly easily find the right header by just looking what framework it includes and digging in that framework's headers and sub-frameworks. For example, FlatCarbon's MacErrors.h header includes CoreServices, so check out /System/Library/Frameworks/CoreServices.framework's umbrella header CoreServices.h in its Headers subfolder. It includes (among others) CarbonCore, so take a look at that framework. It's a sub-framework of CoreServices, meaning you'll find it in CoreServices' Frameworks subfolder. And, surprise, surprise, you'll find the real MacErrors.h in CarbonCore's Headers folder. It contains oodles of constants defining many possible values for OSStatus and OSErr.

Help! MacErrors.h doesn't list my error?!

Some Carbon APIs also define some additional error constants in their own headers. So, you might get error codes not listed in MacErrors.h, in which case you'll want to look up the header for the API call that returned that particular error and look there for a constant that names and explains that error code.

If you can't find it there, there are some other ways to find the errors. For example, some CoreAudio developer didn't understand that error codes are supposed to be numbers, and actually used a FourCharCode for some errors. So, if you get an insanely high or low number, try viewing it as four characters (also called an 'OSType') and search for that.

Also, IOKit has some errors that are actually assembled from bit fields and flags, in which case you'd best write a little app that dumps the numeric equivalents of IOKit's error constants and compare those to your error number.

Oh, and BTW: The constant noErr (which evaluates to zero) indicates success.