libakerror/src/error.c

#include "akerror.h"
#if defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1
#include <stdlib.h>
#include <stdarg.h>
#include <stdio.h>
#endif // AKERR_USE_STDLIB

akerr_ErrorContext __akerr_last_ditch;
akerr_ErrorContext *__akerr_last_ignored;
akerr_ErrorUnhandledErrorHandler akerr_handler_unhandled_error;
akerr_ErrorLogFunction akerr_log_method = NULL;

/*
 * Status-name registry.
 *
 * Storage is an open-addressed hash table keyed by status value. Both sizes are
 * private to this translation unit -- they are deliberately NOT in the public
 * header, because a consumer-visible table bound is exactly the ABI hazard this
 * registry replaced. Overriding them changes only this file, so a library and
 * its consumers can never disagree about the layout.
 *
 * The table is never resized or rehashed, so a pointer handed out by
 * akerr_name_for_status() stays valid for the life of the process. Entries are
 * never removed, so probing needs no tombstones.
 */
#ifndef AKERR_STATUS_NAME_SLOTS
#define AKERR_STATUS_NAME_SLOTS 4096
#endif

#ifndef AKERR_MAX_RESERVED_STATUS_RANGES
#define AKERR_MAX_RESERVED_STATUS_RANGES 64
#endif

/* Probing masks with SLOTS-1, so the slot count must be a power of two. This is
 * the C99-portable spelling of a static assertion (a negative array bound). */
typedef char akerr_assert_name_slots_pow2[
    (AKERR_STATUS_NAME_SLOTS > 0 &&
     (AKERR_STATUS_NAME_SLOTS & (AKERR_STATUS_NAME_SLOTS - 1)) == 0) ? 1 : -1];

/* Cap occupancy at 75% so linear probing always meets an empty slot. */
#define AKERR_MAX_REGISTERED_STATUS_NAMES \
    (AKERR_STATUS_NAME_SLOTS - (AKERR_STATUS_NAME_SLOTS / 4))

#define AKERR_MAX_STATUS_RANGE_OWNER_LENGTH 64

typedef struct
{
    int status;
    int used;
    char name[AKERR_MAX_ERROR_NAME_LENGTH];
} akerr_StatusName;

typedef struct
{
    int first;
    int last;
    char owner[AKERR_MAX_STATUS_RANGE_OWNER_LENGTH];
} akerr_StatusRange;

static akerr_StatusName akerr_status_names[AKERR_STATUS_NAME_SLOTS];
static int akerr_status_name_count;
static akerr_StatusRange akerr_status_ranges[AKERR_MAX_RESERVED_STATUS_RANGES];
static int akerr_status_range_count;

akerr_ErrorContext AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR];

static void akerr_copy_string(char *destination, int capacity, const char *source)
{
    if ( capacity <= 0 ) {
	return;
    }
    strncpy(destination, source, (size_t)capacity - 1);
    destination[capacity - 1] = '\0';
}

/*
 * Compare against each element address rather than testing the address range.
 * A range test also accepts pointers into the *interior* of an element, which
 * would then be treated as the head of an akerr_ErrorContext and written
 * through. Keep this an element-wise scan; it is not a missed optimization.
 */
int akerr_valid_error_address(akerr_ErrorContext *ptr)
{
    // Is this within the memory region occupied by AKERR_ARRAY_ERROR?
    if ( ptr == NULL ) {
	return 1;
    }
    for ( int i = 0; i < AKERR_MAX_ARRAY_ERROR; i++ ) {
	if ( ptr == &AKERR_ARRAY_ERROR[i] ) {
	    return 1;
	}
    }
    return 0;
}

void akerr_default_logger(const char *fmt, ...)
{
#if defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1
    va_list ap;

    va_start(ap, fmt);
    vfprintf(stderr, fmt, ap);
    va_end(ap);
#else
    return;
#endif
}

/*
 * The library naming its own codes. The registry entry points raise errors like
 * everything else in the library, but akerr_init() has no caller to raise into,
 * so this is where the buck stops: log the failure and take the unhandled-error
 * path, which terminates the program.
 *
 * This is fatal on purpose. The library cannot name its own status codes only
 * if the build is misconfigured -- a name table too small to hold even the
 * library's own entries, or a reservation that did not take -- and the
 * consequence of continuing is every later stack trace in the process printing
 * "Unknown Error" for a code the library defines. That is a startup defect, and
 * it is far cheaper to see it at init than to debug it from a degraded trace.
 */
void __akerr_name_library_status(int status, const char *name)
{
    akerr_ErrorContext *errctx = akerr_register_status_name(AKERR_LIBRARY_OWNER,
							    status, name);
    if ( errctx != NULL ) {
	LOG_ERROR_WITH_MESSAGE(errctx, "** libakerror could not name its own status **");
	akerr_handler_unhandled_error(errctx);
	RELEASE_ERROR(errctx);
    }
}

/*
 * Idempotent. `inited` is set before any work so that the registry calls below
 * -- and the public registry entry points, which all call akerr_init() so that
 * a consumer reserving its range before anything else touches the library
 * cannot have that reservation wiped by a later first-use of the pool -- see
 * themselves as already initialized instead of recursing.
 */
void akerr_init()
{
    static int inited = 0;
    if ( inited == 0 ) {
	inited = 1;
	for (int i = 0; i < AKERR_MAX_ARRAY_ERROR; i++ ) {
	    memset((void *)&AKERR_ARRAY_ERROR[i], 0x00, sizeof(akerr_ErrorContext));
	    AKERR_ARRAY_ERROR[i].arrayid = i;
	    AKERR_ARRAY_ERROR[i].stacktracebufptr = (char *)&AKERR_ARRAY_ERROR[i].stacktracebuf;
	}
	__akerr_last_ignored = NULL;
	memset((void *)&__akerr_last_ditch, 0x00, sizeof(akerr_ErrorContext));
	__akerr_last_ditch.stacktracebufptr = (char *)&__akerr_last_ditch.stacktracebuf;
	if ( akerr_log_method == NULL ) {
	    akerr_log_method = &akerr_default_logger;
	}
	akerr_handler_unhandled_error = &akerr_default_handler_unhandled_error;
	memset((void *)&akerr_status_names[0], 0x00, sizeof(akerr_status_names));
	memset((void *)&akerr_status_ranges[0], 0x00, sizeof(akerr_status_ranges));
	akerr_status_name_count = 0;
	akerr_status_range_count = 0;

	/* errno and AKERR_* values are the library-owned compatibility band.
	 * This must precede every registration below: naming a status is only
	 * permitted inside a reserved range. */
	akerr_ErrorContext *reserve_err =
	    akerr_reserve_status_range(0, AKERR_RESERVED_STATUS_COUNT,
				       AKERR_LIBRARY_OWNER);
	if ( reserve_err != NULL ) {
	    /* Fatal for the same reason as __akerr_name_library_status():
	     * without this band the library owns nothing, so none of the names
	     * below can register either. */
	    LOG_ERROR_WITH_MESSAGE(reserve_err,
				   "** libakerror could not reserve its own status band **");
	    akerr_handler_unhandled_error(reserve_err);
	    RELEASE_ERROR(reserve_err);
	}

	/* Every AKERR_* code gets a name; tests/err_error_names.c asserts the
	 * list is exhaustive so a new code cannot be added without one. */
	__akerr_name_library_status(AKERR_NULLPOINTER, "Null Pointer Error");
	__akerr_name_library_status(AKERR_OUTOFBOUNDS, "Out Of Bounds Error");
	__akerr_name_library_status(AKERR_API, "API Error");
	__akerr_name_library_status(AKERR_ATTRIBUTE, "Attribute Error");
	__akerr_name_library_status(AKERR_TYPE, "Type Error");
	__akerr_name_library_status(AKERR_KEY, "Key Error");
	__akerr_name_library_status(AKERR_INDEX, "Index Error");
	__akerr_name_library_status(AKERR_FORMAT, "Format Error");
	__akerr_name_library_status(AKERR_IO, "Input Output Error");
	__akerr_name_library_status(AKERR_VALUE, "Value Error");
	__akerr_name_library_status(AKERR_RELATIONSHIP, "Relationship Error");
	__akerr_name_library_status(AKERR_EOF, "End Of File");
	__akerr_name_library_status(AKERR_CIRCULAR_REFERENCE, "Circular Reference Error");
	__akerr_name_library_status(AKERR_ITERATOR_BREAK, "Iterator Break");
	__akerr_name_library_status(AKERR_NOT_IMPLEMENTED, "Not Implemented");
	__akerr_name_library_status(AKERR_BADEXC, "Invalid akerr_ErrorContext");
	__akerr_name_library_status(AKERR_STATUS_RANGE_OVERLAP, "Status Range Overlap");
	__akerr_name_library_status(AKERR_STATUS_RANGE_FULL, "Status Range Table Full");
	__akerr_name_library_status(AKERR_STATUS_RANGE_INVALID, "Invalid Status Range");
	__akerr_name_library_status(AKERR_STATUS_NAME_UNRESERVED, "Unreserved Status Name");
	__akerr_name_library_status(AKERR_STATUS_NAME_FOREIGN, "Foreign Status Name");
	__akerr_name_library_status(AKERR_STATUS_NAME_FULL, "Status Name Registry Full");
	__akerr_name_library_status(AKERR_STATUS_NAME_INVALID, "Invalid Status Name");
#if (defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1) || (!defined(AKERR_USE_STDLIB))
	akerr_init_errno();
#endif
    }
}

void akerr_default_handler_unhandled_error(akerr_ErrorContext *errctx)
{
  if ( errctx == NULL ) {
    exit(1);
  }
  exit(errctx->status);
}

akerr_ErrorContext *akerr_next_error()
{
    for (int i = 0; i < AKERR_MAX_ARRAY_ERROR; i++ ) {
	if ( AKERR_ARRAY_ERROR[i].refcount == 0 ) {
	    return &AKERR_ARRAY_ERROR[i];
	}
    }
    return (akerr_ErrorContext *)NULL;
}

akerr_ErrorContext *akerr_release_error(akerr_ErrorContext *err)
{
    int oldid = 0;
    if ( err == NULL ) {
	akerr_ErrorContext *errctx = &__akerr_last_ditch;
	FAIL_RETURN(errctx, AKERR_NULLPOINTER, "akerr_release_error got NULL context pointer");
    }
    if ( err->refcount > 0 ) {
      err->refcount -= 1;
    }
    if ( err->refcount == 0 ) {
	oldid = err->arrayid;
	memset(err, 0x00, sizeof(akerr_ErrorContext));
	err->stacktracebufptr = (char *)&err->stacktracebuf;
	err->arrayid = oldid;
	return NULL;
    }
    return err;
}


/*
 * Scatter the status across the table. Status values are typically dense runs
 * (errno 1..N, then a library's block at its base), which linear probing on the
 * raw value would pile into one cluster, so mix the bits first.
 */
static unsigned akerr_status_hash(int status)
{
    unsigned h = (unsigned)status;

    h ^= h >> 16;
    h *= 0x85ebca6bu;
    h ^= h >> 13;
    h *= 0xc2b2ae35u;
    h ^= h >> 16;
    return h & (unsigned)(AKERR_STATUS_NAME_SLOTS - 1);
}

/*
 * Find the slot holding `status`. With create != 0, claim a free slot for it if
 * it is not present yet. Returns NULL when the status is absent and either no
 * slot was requested or the registry is full.
 *
 * The `& (AKERR_STATUS_NAME_SLOTS - 1)` below is load-bearing and fails
 * silently: off by one in either direction and the probe indexes past
 * akerr_status_names, writing into whatever BSS follows rather than crashing.
 * A test that only counts how many names registered before the table filled
 * cannot see that -- a probe sequence collapsed to two slots still registers
 * "some" names. Any change to the probe sequence, the occupancy cap, or the
 * power-of-two assumption needs a test that reads every entry back by its own
 * distinct value; tests/err_maxval.c does.
 */
static akerr_StatusName *akerr_status_slot(int status, int create)
{
    unsigned slot = akerr_status_hash(status);

    for ( int probe = 0; probe < AKERR_STATUS_NAME_SLOTS; probe++ ) {
	akerr_StatusName *entry = &akerr_status_names[slot];

	if ( entry->used == 0 ) {
	    if ( create == 0 ||
		 akerr_status_name_count >= AKERR_MAX_REGISTERED_STATUS_NAMES ) {
		return NULL;
	    }
	    entry->used = 1;
	    entry->status = status;
	    entry->name[0] = '\0';
	    akerr_status_name_count++;
	    return entry;
	}
	if ( entry->status == status ) {
	    return entry;
	}
	slot = (slot + 1u) & (unsigned)(AKERR_STATUS_NAME_SLOTS - 1);
    }
    /* Unreachable: occupancy is capped below the slot count, so the probe above
     * always meets a free slot. Present so a future change to that cap cannot
     * turn this into a runaway loop. */
    return NULL;
}

/* The reservation covering `status`, or NULL if nobody has claimed it. */
static akerr_StatusRange *akerr_range_for_status(int status)
{
    for ( int i = 0; i < akerr_status_range_count; i++ ) {
	if ( status >= akerr_status_ranges[i].first &&
	     status <= akerr_status_ranges[i].last ) {
	    return &akerr_status_ranges[i];
	}
    }
    return NULL;
}

/*
 * Shared body of both registration entry points. A NULL owner means the caller
 * did not identify itself (the legacy two-argument akerr_name_for_status path):
 * the status must still lie inside *some* reservation, but we cannot check that
 * it is the caller's. Every refusal raises an error -- a name that silently
 * fails to register degrades into "Unknown Error" in stack traces, which is
 * exactly the kind of quiet loss this registry exists to prevent -- so the
 * message carries everything a caller needs to see in a stack trace.
 */
static akerr_ErrorContext AKERR_NOIGNORE *akerr_store_status_name(const char *owner,
								  int status,
								  const char *name)
{
    akerr_StatusRange *range;
    akerr_StatusName *entry;
    PREPARE_ERROR(errctx);

    if ( name == NULL ) {
	FAIL_RETURN(errctx, AKERR_STATUS_NAME_INVALID,
		    "Refusing to name status %d for %s: the name is NULL",
		    status, owner == NULL ? "an unnamed caller" : owner);
    }
    if ( owner != NULL && ( owner[0] == '\0' ||
	 strlen(owner) >= AKERR_MAX_STATUS_RANGE_OWNER_LENGTH ) ) {
	FAIL_RETURN(errctx, AKERR_STATUS_NAME_INVALID,
		    "Refusing to name status %d (\"%s\"): the owner string is "
		    "empty or longer than %d characters",
		    status, name, AKERR_MAX_STATUS_RANGE_OWNER_LENGTH - 1);
    }

    range = akerr_range_for_status(status);
    if ( range == NULL ) {
	FAIL_RETURN(errctx, AKERR_STATUS_NAME_UNRESERVED,
		    "Refusing to name status %d (\"%s\") for %s: no reserved "
		    "range contains it. Call akerr_reserve_status_range() first.",
		    status, name, owner == NULL ? "an unnamed caller" : owner);
    }
    if ( owner != NULL && strcmp(owner, range->owner) != 0 ) {
	FAIL_RETURN(errctx, AKERR_STATUS_NAME_FOREIGN,
		    "Refusing to name status %d (\"%s\") for %s: that status is "
		    "in range %d..%d owned by %s.",
		    status, name, owner,
		    range->first, range->last, range->owner);
    }

    entry = akerr_status_slot(status, 1);
    if ( entry == NULL ) {
	FAIL_RETURN(errctx, AKERR_STATUS_NAME_FULL,
		    "Status name registry is full (%d entries); dropping name "
		    "\"%s\" for status %d. Rebuild libakerror with a larger "
		    "AKERR_STATUS_NAME_SLOTS.",
		    AKERR_MAX_REGISTERED_STATUS_NAMES, name, status);
    }
    akerr_copy_string(entry->name, AKERR_MAX_ERROR_NAME_LENGTH, name);
    SUCCEED_RETURN(errctx);
}

/* Register a name for a status inside a range the caller reserved. */
akerr_ErrorContext *akerr_register_status_name(const char *owner, int status, const char *name)
{
    PREPARE_ERROR(errctx);

    FAIL_ZERO_RETURN(errctx, (owner != NULL), AKERR_STATUS_NAME_INVALID,
		     "Refusing to name status %d: the owner string is NULL. "
		     "Pass the same owner you reserved the range with.",
		     status);
    PASS(errctx, akerr_store_status_name(owner, status, name));
    SUCCEED_RETURN(errctx);
}

/*
 * Return or set a name. Status magnitude is unrelated to storage size.
 *
 * The set path is the legacy two-argument form and cannot hand an error back to
 * its caller (it returns a name), so a refusal is logged here and released.
 * akerr_register_status_name() is the form that raises.
 */
char *akerr_name_for_status(int status, char *name)
{
    akerr_StatusName *entry;

    akerr_init();
    if ( name != NULL ) {
	akerr_ErrorContext *errctx = akerr_store_status_name(NULL, status, name);
	if ( errctx != NULL ) {
	    LOG_ERROR_WITH_MESSAGE(errctx, "** REFUSED STATUS NAME **");
	    RELEASE_ERROR(errctx);
	    return "Unknown Error";
	}
    }
    entry = akerr_status_slot(status, 0);
    if ( entry == NULL ) {
	return "Unknown Error";
    }
    return entry->name;
}

/* Reserve an inclusive status interval and reject collisions. */
akerr_ErrorContext *akerr_reserve_status_range(int first_status, int count, const char *owner)
{
    int last_status;
    PREPARE_ERROR(errctx);

    if ( count <= 0 || owner == NULL || owner[0] == '\0' ||
	 strlen(owner) >= AKERR_MAX_STATUS_RANGE_OWNER_LENGTH ||
	 first_status > INT_MAX - (count - 1) ) {
	FAIL_RETURN(errctx, AKERR_STATUS_RANGE_INVALID,
		    "Invalid status range reservation: %d status values from "
		    "%d for %s (count must be positive, the owner string "
		    "non-empty and shorter than %d characters, and the range "
		    "must not overflow int)",
		    count, first_status, owner == NULL ? "(null)" : owner,
		    AKERR_MAX_STATUS_RANGE_OWNER_LENGTH);
    }
    last_status = first_status + count - 1;

    for ( int i = 0; i < akerr_status_range_count; i++ ) {
	if ( first_status <= akerr_status_ranges[i].last &&
	     last_status >= akerr_status_ranges[i].first ) {
	    if ( first_status == akerr_status_ranges[i].first &&
		 last_status == akerr_status_ranges[i].last &&
		 strcmp(owner, akerr_status_ranges[i].owner) == 0 ) {
		SUCCEED_RETURN(errctx);
	    }
	    FAIL_RETURN(errctx, AKERR_STATUS_RANGE_OVERLAP,
			"Status range %d..%d requested by %s overlaps %d..%d "
			"owned by %s",
			first_status, last_status, owner,
			akerr_status_ranges[i].first,
			akerr_status_ranges[i].last,
			akerr_status_ranges[i].owner);
	}
    }
    if ( akerr_status_range_count == AKERR_MAX_RESERVED_STATUS_RANGES ) {
	FAIL_RETURN(errctx, AKERR_STATUS_RANGE_FULL,
		    "Status range table is full (%d ranges); refusing %d..%d "
		    "for %s.",
		    AKERR_MAX_RESERVED_STATUS_RANGES,
		    first_status, last_status, owner);
    }

    akerr_status_ranges[akerr_status_range_count].first = first_status;
    akerr_status_ranges[akerr_status_range_count].last = last_status;
    akerr_copy_string(akerr_status_ranges[akerr_status_range_count].owner,
		      AKERR_MAX_STATUS_RANGE_OWNER_LENGTH, owner);
    akerr_status_range_count++;
    SUCCEED_RETURN(errctx);
}