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

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

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:

#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

if (UNIT_FAILED(UNIT_Procedure_Init(&procedure, context, "main"))) {
    if (UNIT_GetErrorCode(context) == UNIT_ERROR_OS_FAILURE) {
        perror("Error whilst initializing UNIT procedure");
        return 1;
    }
}

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

if (UNIT_FAILED(UNIT_Procedure_Init(&procedure, context, "main"))) {
   const char *error = UNIT_GetErrorMessage(context);
   fprintf(stderr, "Error whilst initializing UNIT procedure: %s\n", error);
   return 1;
}

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

if (UNIT_FAILED(UNIT_Procedure_Init(&procedure, context, "main"))) {
    UNIT_ErrorCode code = UNIT_GetErrorCode(context);
    const char *name = UNIT_ErrorCode_ToString(code);
    fprintf(stderr, "UNIT failed with error code %d (%s)\n", code, name);
    return 1;
}

void UNIT_PrintError(const UNIT_Context *context, FILE *stream)

Print out a formatted error message containing the error code and the error message 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

if (UNIT_FAILED(UNIT_Procedure_Init(&procedure, context, "main"))) {
    UNIT_PrintError(context, stderr);
    return 1;
}