Skip to content

dterr

Error capture, chaining, and structured propagation.

This group of functions provides error capture and propagation for C modules. It is designed to construct explicit error chains with source location and messages. The implementation does explicit ownership and disposal over implicit global state.

Mini-guide

  • Construct error nodes explicitly by calling dterr_new, which formats a message into heap memory.
  • Propagate failures through wrappers by appending or nesting errors.
  • Use the provided macros to short-circuit control flow which jump to a cleanup:.
  • Iterate error chains with dterr_each.
  • Dispose entire error chains with dterr_dispose.

Example

dterr_t* dterr = NULL;

DTERR_ASSERT_NOT_NULL(some_ptr);

dterr = dterr_new(DTERR_FAIL, DTERR_LOC, NULL, "operation failed");

cleanup:
if (dterr != NULL)
{
    dterr_each(dterr, some_callback, NULL);
    dterr_dispose(dterr);
}

Data structures

dterr_t

Represents a single error node with optional causal linkage.

Members:

int32_t error_code Primary error classification code.
int32_t line_number Source line where the error was created.
const char* source_file Source file of origin with static storage duration.
const char* source_function Function name of origin with static storage duration.
dterr_t* inner_err Optional inner error representing the causal predecessor.
char* message Heap-allocated message owned by this node.
void (*dispose)(struct dterr_t* self) Virtual destructor for the node.

Macros

DTERR_ASSERT_NOT_NULL

DTERR_ASSERT_NOT_NULL(ARG)

Checks a required argument and creates an error node before jumping to cleanup.

DTERR_C

DTERR_C(call)

Wraps a call and converts a returned error into a chained error node before cleanup.

DTERR_ERRNO_C

DTERR_ERRNO_C(call)

Wraps an errno-style call and creates an error node on nonzero return.

DTERR_NEGERROR_C

DTERR_NEGERROR_C(call)

Wraps a call returning negative error codes and creates an error node on failure.

DTERR_POSERROR_C

Wraps a call returning positive error codes and creates an error node on failure.

Functions

dterr_append

Appends an error chain to another by transferring ownership.

Params:

dterr_t* self Destination error node that receives the appended chain.
dterr_t* that Source error node whose chain is transferred.

Return: void No return value.

dterr_dispose

Disposes an error chain and releases all owned resources.

Params:

dterr_t* self Error node to dispose.

Return: void No return value.

dterr_each

Invokes a callback for each error node in causal order.

Params:

dterr_t* self Error chain to iterate.
dterr_each_callback_t callback Callback invoked for each node.
void* context Caller-provided context passed to the callback.

Return: void No return value.

dterr_new

Creates a new error node with formatted message text.

Params:

int32_t error_code Primary error classification code.
int32_t line_number Source line where the error was created.
const char* source_file Source file of origin.
const char* source_function Function name of origin.
dterr_t* inner_err Optional inner error representing the cause.
const char* format Format string for the message.
... Variadic arguments for the format string.

Return: dterr_t* Newly created error node or NULL on construction failure.