Errors

struct UNIT_Status

The type indicating success or failure from a function call.

int8_t _status

The actual status value. This is 0 for success and -1 for failure. In general, you should never access this field manually, and thus why it is prefixed with _. However, it may be necessary to access this field if calling UNIT from somewhere where C macros are not accessible (and thus UNIT_FAILED cannot be used), such as from an FFI.

UNIT_FAILED(expr)

Check if a UNIT_Status returned by a function indicates failure. This is almost always used in if statements or in assertions.

Example
1 if (UNIT_FAILED(UNIT_Context_Init(/* ... */))) {
2     /* Handle failure somehow. */
3     return -1;
4 }

Looking for a UNIT_OK macro?

UNIT does not provide a macro for checking if UNIT_Status indicates success. For this pattern, simply negate the result of UNIT_FAILED:

C
#define OK(expr) (!UNIT_FAILED(expr))
enum UNIT_ErrorCode
enumerator UNIT_ERROR_NONE

No error is set.

enumerator UNIT_ERROR_NO_MEMORY

A memory allocation failed.

enumerator UNIT_ERROR_INVALID_USAGE

An API was misused by the caller. The error message will contain more information about what.

enumerator UNIT_ERROR_OS_FAILURE

A call to an operating system API failed. This implies that the C errno is set.

enumerator UNIT_ERROR_UNSUPPORTED_PLATFORM

An operation is not available on this platform.

UNIT_ErrorCode UNIT_GetErrorCode(const UNIT_Context *context)

Get the current error code.

Parameters:

  • context – The context holding the error state.

Returns:

The error code.

Example
1if (UNIT_FAILED(UNIT_Procedure_Init(context, /* ... */))) {
2    if (UNIT_GetErrorCode(context) == UNIT_ERROR_OS_FAILURE) {
3        perror("Error whilst initializing UNIT procedure");
4        return 1;
5    }
6}
const char *UNIT_GetErrorMessage(const UNIT_Context *context)

Return the error message that is currently active on the context. If there isn’t any error set, then this returns NULL.

Parameters:

  • context – The context holding the error state.

Returns:

A string holding the error message. The caller is not responsible for managing the memory of this string.

Example
1if (UNIT_FAILED(UNIT_Procedure_Init(context, /* ... */))) {
2   const char *error = UNIT_GetErrorMessage(context);
3   fprintf(stderr, "Error whilst initializing UNIT procedure: %s\n", error);
4   return 1;
5}
const char *UNIT_ErrorCode_ToString(UNIT_ErrorCode code)

Get the name of the given error code, with the UNIT_ERROR prefix stripped out (so passing UNIT_ERROR_NO_MEMORY, for example, will return the string "NO_MEMORY").

This function will never return NULL, but passing an invalid error code will result in the process crashing.

Example
1if (UNIT_FAILED(UNIT_Procedure_Init(context, /* ... */))) {
2    UNIT_ErrorCode code = UNIT_GetErrorCode();
3    const char *name = UNIT_ErrorCode_ToString(code);
4    fprintf(stderr, "UNIT failed with error code %d (%s)\n", code, name);
5    return 1;
6}
void UNIT_PrintError(const UNIT_Context *context, FILE *stream)

Print out a formatted error message containing the error code and the error messaage to a stream. If no error is set, nothing is written to the stream.

Parameters:

  • context – The context holding the error state.

  • stream – The stream to write the error message to. This is usually stderr.

Example
1if (UNIT_FAILED(UNIT_Procedure_Init(context, /* ... */))) {
2    UNIT_PrintError(context, stderr);
3    return 1;
4}