libakerror/docs/exit-status.md

Exit status

Never call exit() with an akerr status. Call akerr_exit().

void akerr_exit(int status);

This applies everywhere you are leaving the process on account of a status, not just in an unhandled-error handler: a CLI's top-level HANDLE block, an initialization routine that cannot continue, a main() that ends by reporting the status it finished with. One function owns the mapping so that a given status produces the same exit code no matter which of your exits it left by.

The mapping exists because a process exit status is one byte wide. exit() accepts an int and the kernel keeps the low 8 bits of it — _exit(), _Exit(), quick_exit() and the raw exit_group syscall all behave identically, and even waitid(), whose si_status is a full int, sees the truncated value because the truncation happened before the parent looked. There is no wider exit() to reach for.

That leaves 0 through 255 as the only statuses an exit code can carry, and consumer statuses start at AKERR_FIRST_CONSUMER_STATUS (256) — so no consumer status can be an exit code:

status                  exit code
0                       0                                     (success)
1 .. 255                the status
negative, or > 255      AKERR_EXIT_STATUS_UNREPRESENTABLE (125)

Passing the low byte instead would have made status 256 exit 0 and report success to the shell, and status 300 exit 44 — an unrelated error's code. 125 is the conventional "the tool itself failed" status; 126, 127 and 128+n already belong to the shell.

Status 0 exits 0, because 0 is this library's success status. That is not a hole in the rule that an unhandled error never exits 0: PROCESS opens with case 0, which marks a zero status handled, so a successful context cannot reach FINISH_NORETURN's call to the handler at all.

Above 255, the exit code tells you the process died of an error, not which one. 125 is inside the library's reserved band and so is also some host's errno, and every status above 255 collapses onto it. The stack trace is what identifies the error — it is printed before the handler runs, carrying the status at full width along with its registered name.

Replacing the handler

After the trace is printed, FINISH_NORETURN calls akerr_handler_unhandled_error. The default implementation, akerr_default_handler_unhandled_error(), hands errctx->status to akerr_exit() (a NULL context exits 1). Replace it if you need something else to happen first — a core dump, a crash reporter, a flush — and finish by calling akerr_exit() so the exit code still means what it means everywhere else:

static void mylib_handler(akerr_ErrorContext *e)
{
    mylib_flush_telemetry();
    if ( e == NULL ) {
	akerr_exit(AKERR_API);
    }
    akerr_exit(e->status);
}

akerr_handler_unhandled_error = &mylib_handler;

akerr_exit() is declared AKERR_NORETURN, so the compiler knows a handler ending in one of those calls is complete rather than falling off the end.

Set the handler once, before you start any threads. tests/err_custom_handler.c installs one that does not exit at all, which is how the test suite asserts on unhandled errors without dying.