How do you convert an iPhone OSStatus code to something useful?

Question

I am getting more than a little sick of this iPhone SDK and its documentation...

I am calling AudioConverterNew

in the documentation under Returns: it says \

Answer 1

No. Not completely.

Some OSStatus are four-character-codes, so you can use (extracted from iPhone SDK's sample code "CAXException.h")

static char *FormatError(char *str, OSStatus error)
{
    // see if it appears to be a 4-char-code
    *(UInt32 *)(str + 1) = CFSwapInt32HostToBig(error);
    if (isprint(str[1]) && isprint(str[2]) && isprint(str[3]) && isprint(str[4])) {
        str[0] = str[5] = '\'';
        str[6] = '\0';
    } else {
        // no, format it as an integer
        sprintf(str, "%d", (int)error);
    }
    return str;
}

(See iOS/C: Convert "integer" into four character string for some more ways to convert fourcc into string, including Swift)

NSError's NSOSStatusErrorDomain is able to decode some OS errors. See @tomk's answer.

If you don't need to decode the number in program for the user, you may use the macerror script to manually find out the meaning, as mentioned in @lros's answer. The list of OSStatus supported can be found from its source code in /System/Library/Perl/Extras/5.18/Mac/Errors.pm.

There is also an online service http://osstatus.com/ collecting errors from all public frameworks. They are still not really complete e.g. the mapping to -12792 mentioned in the comment is missing. Probably it is a code from a private framework.