KIM Error Overview

Like most C APIs, the KIM API returns numeric error codes. These error codes may come from KIM, krb5 or GSS APIs. In most cases the caller will want to handle these error programmatically. However, in some circumstances the caller may wish to print an error string to the user.

One problem with just printing the error code to the user is that frequently the context behind the error has been lost. For example if KIM is trying to obtain credentials via referrals, it may fail partway through the process. In this case the error code will be KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN, which maps to "Client not found in Kerberos database". Unfortunately this error isn't terribly helpful because it doesn't tell the user whether they typoed their principal name or if referrals failed.

To avoid this problem, KIM maintains an explanatory string for the last error seen in each thread calling into KIM. If a caller wishes to display an error to the user, immediately after getting the error the caller should call kim_string_get_last_error_message() to obtain a copy of the descriptive error message.

Note that because this string is stored in thread-specific data, callers must call kim_string_get_last_error_message() before calling any KIM APIs or any other APIs which might call into KIM. Callers who are not going to display this error string immediately should also make a copy of it so that it is not overwritten by the next call into KIM.

See KIM Error Reference Documentation for information on specific APIs.

---