Summary

This library provides a TRY/CATCH style exception handling mechanism for C.

Why?

There is nothing wrong with C as it is. This library does not claim to fix some problem with C.

Instead, this library implements a pragmatic and stylistic choice to assist the programmer in better handling errors in their programs. Vanilla C provides everything you need to do this out of the box, but this library makes it easier to avoid pointing certain guns at your foot, and when you do, it provides better context with those errors to help you more quickly recover.

Why? Because some programmers prefer to have the power of C with just a little bit of help in managing their errors.

This library has 6 guiding principles:

• Manually checking every possible return code for every possible meaning of that return code is tedious and prone to miss unpredicted failure cases
• Functions should return rich descriptive error contexts, not values
• Uncaught errors should cause program termination with a stacktrace
• Dynamic memory allocation is the source of many errors and should be avoided if possible
• Manipulating the call stack directly is error prone and dangerous
• Declaring, capturing, and reacting to errors should be intuitive and no more difficult than managing return codes

Documentation

Document	What it answers
docs/architecture.md	What an error context is, how one travels up the call stack, and what the macros build
docs/usage.md	The macro reference: ATTEMPT/CLEANUP/PROCESS/FINISH, CATCH, FAIL_*, PASS, HANDLE, SUCCEED_RETURN
docs/status-codes.md	Defining your own status codes, and reserving a range so two libraries cannot collide
docs/uncaught-errors.md	AKERR_NOIGNORE, what a stack trace looks like, and how to read one
docs/exit-status.md	Why you call akerr_exit() and never exit(), and how to replace the unhandled-error handler
docs/thread-safety.md	What thread safety here covers, what it does not, and how to hand an error to another thread
docs/building.md	Configure options, the generated header, and building without stdlib
UPGRADING.md	What changed in 1.0.0, 2.0.0 and 2.0.1, and how to migrate
TODO.md	The reasoning behind decisions and measurements. Outstanding work is in the issue tracker.

Installation

cmake -S . -B build
cmake --build build
cmake --install build

The library depends on stdlib and on POSIX threads. Both are optional at the cost of some functionality — see docs/building.md for -DAKERR_USE_STDLIB=OFF and docs/thread-safety.md for -DAKERR_THREADS=none.

Setting up your project

Include it

#include <akerror.h>

Link the library directly, or

cc -lakerror

Using pkg-config, or

pkg-config akerror --cflags
pkg-config akerror --ldflags

Using cmake:

find_package(akerror REQUIRED)
pkg_check_modules(akerror REQUIRED akerror)
target_link_libraries(YOUR_TARGET PRIVATE akerror::akerror)

Using this project as a submodule with cmake:

add_subdirectory(deps/libakerror EXCLUDE_FROM_ALL)

target_link_libraries(YOUR_PROJECT PRIVATE akerror::akerror)

Quickstart

A function that can fail returns an akerr_ErrorContext * instead of a value, and moves its real output to a pointer parameter. AKERR_NOIGNORE makes the compiler complain if a caller throws that return away.

#include <akerror.h>
#include <stdio.h>

/* Fails with a message; the caller finds out what and where. */
static akerr_ErrorContext AKERR_NOIGNORE *open_config(const char *path, FILE **dest)
{
    PREPARE_ERROR(errctx);

    FAIL_ZERO_RETURN(errctx, (path != NULL), AKERR_NULLPOINTER,
		     "no config path was given");

    *dest = fopen(path, "r");
    FAIL_ZERO_RETURN(errctx, (*dest != NULL), AKERR_IO,
		     "could not open %s", path);

    SUCCEED_RETURN(errctx);
}

int main(int argc, char **argv)
{
    FILE *config = NULL;

    PREPARE_ERROR(errctx);
    ATTEMPT {
	FAIL_ZERO_BREAK(errctx, (argc == 2), AKERR_VALUE,
			"usage: %s <config>", argv[0]);
	CATCH(errctx, open_config(argv[1], &config));
	/* ... read the config ... */
    } CLEANUP {
	/* Runs whether or not anything failed. */
	if ( config != NULL ) {
	    fclose(config);
	}
    } PROCESS(errctx) {
    } HANDLE(errctx, AKERR_VALUE) {
	/* A usage error is ours to handle, so handle it and carry on. */
    } FINISH_NORETURN(errctx);

    return 0;
}

ATTEMPT is where work that can fail goes. CLEANUP always runs. PROCESS opens the handler section, and each HANDLE claims one status. Anything no HANDLE claims is still an error when it reaches FINISH: inside a function, FINISH(errctx, true) returns it to your caller; at the top, as above, FINISH_NORETURN(errctx) prints the stack trace and ends the process. You do not need to call akerr_init() — every entry point does it for you.

Three things worth knowing before you write much more than that:

• The full macro reference, including PASS for errors you cannot do anything about, and HANDLE_GROUP for several statuses that fail the same way.
• Never use CATCH or a FAIL_*_BREAK macro inside a loop. They leave the ATTEMPT with a C break, which only escapes the innermost loop. This is the first thing that bites people.
• Never call exit() with a status. Call akerr_exit(). An exit status is a byte and every consumer status starts at 256, so exit() truncates status 256 to 0 and reports success.

Thread safety

The library is thread safe as built by default: every entry point may be called from any thread at any time, and an error context may be handed from one thread to another and released there. There is one recursive lock covering the pool and the registry, so error construction is serialized — a program that raises errors on its hot path will feel it. See docs/thread-safety.md for what that covers, what it cannot, and the handoff pattern.

Upgrading

2.0.1 fixes an unhandled error killing the process and still reporting success: the exit code was the status truncated to a byte, and every consumer status starts at 256. Use akerr_exit() instead of exit() — see docs/exit-status.md. No ABI break.

2.0.0 makes the library thread safe. That is an ABI break — __akerr_last_ignored became thread-local storage and the pool now takes its own reference — so everything built against a 1.x header must be rebuilt. 1.0.0 replaced the consumer-sized status-name array with a private, ownership-enforced registry. See UPGRADING.md for all three, what was removed, how to migrate, the capacity limits and how to raise them, and the thread-safety rules.