Point AGENTS.md at the issue tracker for outstanding work

The agent instructions now say where new work goes -- an issue on the forge,
carrying status::grooming until its scope is settled -- and that TODO.md is the
record: why the handler ladder is a major-version change, why a copied
akerr_ErrorContext is a trap, why validating more inputs lowers branch coverage,
and why the mutation score is a floor.

The instruction that matters most here is about consumers. Three defects in this
library -- IGNORE() leaking a context, the un-namespaced coverage target, and the
missing akerrorConfigVersion.cmake -- were written down in libakstdlib's notes
and never here, so each was worked around once per consumer and nobody saw the
pattern. Filing upstream should cost a consumer one issue instead of one
workaround.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -37,51 +37,6 @@ jobs:
           fail_on_failure: 'true'
       - run: echo "🍏 This job's status is ${{ job.status }}."
 
-  # Builds and tests the AKERR_USE_STDLIB=OFF configuration end to end (issue
-  # #12), and separately proves that the generated header compiles under a
-  # genuinely freestanding toolchain (-nostdinc -ffreestanding, no libc at
-  # all) via tests/freestanding_fixture.c, which is never linked or run.
-  cmake_build_freestanding:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-      - name: dependencies
-        run: |
-          sudo apt-get update -y
-          sudo apt-get install -y cmake gcc
-      - name: configure, build and test (AKERR_USE_STDLIB=OFF)
-        run: |
-          cmake -S . -B build-off -DAKERR_USE_STDLIB=OFF -DAKERR_THREADS=none
-          cmake --build build-off
-          ctest --test-dir build-off --output-on-failure
-      - name: freestanding consumer fixture (compile-only, no libc)
-        run: |
-          gcc -c -std=c11 \
-              -nostdinc -ffreestanding \
-              -isystem "$(gcc -print-file-name=include)" \
-              -I build-off/generated/include \
-              -I tests \
-              tests/freestanding_fixture.c -o /tmp/freestanding_fixture.o
-      - run: echo "🍏 This job's status is ${{ job.status }}."
-
-  sanitizer:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-      - name: dependencies
-        run: |
-          sudo apt-get update -y
-          sudo apt-get install -y cmake gcc moreutils
-      - name: build with AddressSanitizer and UBSan
-        run: |
-          cmake -S . -B build/asan -DAKERR_SANITIZE=address,undefined
-          cmake --build build/asan
-      - name: test with AddressSanitizer and UBSan
-        run: ctest --test-dir build/asan --output-on-failure
-      - run: echo "🍏 This job's status is ${{ job.status }}."
-
   coverage:
     runs-on: ubuntu-latest
     steps:
@@ -112,6 +67,34 @@ jobs:
           fail_on_failure: 'false'
       - run: echo "🍏 This job's status is ${{ job.status }}."
 
+  thread_sanitizer:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y cmake gcc moreutils
+      # The thread tests assert exclusive ownership of pool slots and reserved
+      # ranges, which is checkable without tooling and runs in the job above.
+      # This is the run that proves there is no data race underneath them.
+      # libtsan arrives with gcc (libgcc-N-dev depends on it); the script
+      # disables ASLR because TSan aborts on kernels with vm.mmap_rnd_bits > 28.
+      - name: thread sanitizer
+        run: |
+          scripts/thread_test.sh build/tsan --output-junit "$(pwd)/tsan-junit.xml"
+      - name: publish thread sanitizer results
+        if: always()
+        uses: mikepenz/action-junit-report@v4
+        with:
+          report_paths: 'tsan-junit.xml'
+          annotate_only: true
+          detailed_summary: true
+          include_passed: true
+          fail_on_failure: 'true'
+      - run: echo "🍏 This job's status is ${{ job.status }}."
+
   mutation_test:
     runs-on: ubuntu-latest
     steps:

CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.10)
 # 1.0.0 replaced the consumer-sized __AKERR_ERROR_NAMES array with private
 # storage. 2.0.0 makes the library thread safe, which is a second ABI break in
-# the same places: akerr_last_ignored became thread-local storage, and
+# the same places: __akerr_last_ignored became thread-local storage, and
 # ENSURE_ERROR_READY no longer takes the pool reference that akerr_next_error()
 # now takes for it. Consumer code compiled against a 1.x header would
 # double-count every reference. Hence the major bump and the SOVERSION, so a
@@ -9,35 +9,13 @@ cmake_minimum_required(VERSION 3.10)
 # 2.0.1 fixes the unhandled-error exit code, which reported success for any
 # status whose low byte was zero. It adds akerr_exit() but breaks nothing: the
 # soname is unchanged and no existing entry point changed shape.
-# 2.0.2 fixes the AKERR_USE_STDLIB=OFF build, which did not compile at all
-# (issue #12): untangles the header's includes, defines the AKERR_RUNTIME_HEADER
-# freestanding contract, retires PATH_MAX in favor of the AKERR_MAX_ERROR_FNAME_LENGTH
-# build option (default unchanged, so this is not an ABI break), and fails the
-# configure instead of the build when AKERR_THREADS would resolve to pthread
-# under AKERR_USE_STDLIB=OFF. ENSURE_ERROR_READY's pool-exhaustion path now
-# calls akerr_exit() instead of exit(1) directly, which changes that exit code
-# from 1 to AKERR_EXIT_STATUS_UNREPRESENTABLE (125) -- a deliberate behavior
-# change, not an ABI break: no soname move, no entry point changed shape.
-project(akerror VERSION 2.0.2 LANGUAGES C)
+project(akerror VERSION 2.0.1 LANGUAGES C)
 
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 include(CTest)
 
 set(AKERR_USE_STDLIB 1 CACHE BOOL "Use the C standard library")
-set(AKERR_MAX_ERROR_FNAME_LENGTH 4096 CACHE STRING
-    "Bytes reserved for the fname/function fields of akerr_ErrorContext. Defaults to PATH_MAX on Linux/glibc, which keeps sizeof(akerr_ErrorContext) and the soname unchanged; changing it is an ABI break.")
-set(AKERR_LAST_ERRNO_VALUE_FALLBACK 133 CACHE STRING
-    "AKERR_LAST_ERRNO_VALUE to stamp when AKERR_USE_STDLIB is OFF, since the freestanding build cannot shell out to 'errno --list'. Defaults to 133 (Linux's EHWPOISON).")
-# Mandatory under AKERR_USE_STDLIB=OFF: the generated header #errors at
-# compile time if it is unset when included (see include/akerror.tmpl.h). Left
-# empty here so an explicit -DAKERR_RUNTIME_HEADER=... is honored; if still
-# empty once AKERR_USE_STDLIB=OFF is known (below), it defaults to a
-# convenience header that is merely a thin, libc-backed stand-in, so this
-# repository's own OFF build and tests work without a real freestanding
-# runtime. A genuinely freestanding consumer should override this.
-set(AKERR_RUNTIME_HEADER "" CACHE STRING
-    "Header providing exit, memset, snprintf, strcmp, strlen and strncpy, required when AKERR_USE_STDLIB is OFF")
 set(AKERR_COVERAGE 0 CACHE BOOL "Instrument the build with gcov coverage counters")
 set(AKERR_SANITIZE "" CACHE STRING
     "Sanitizers to build the library and tests with, e.g. thread or address,undefined")
@@ -73,34 +51,6 @@ else()
         "AKERR_THREADS must be auto, pthread or none, not '${AKERR_THREADS}'")
 endif()
 
-# Normalize the stdlib option. CMake cache booleans may be spelled ON/OFF,
-# TRUE/FALSE, 1/0, YES/NO and more; pasting AKERR_USE_STDLIB straight into a
-# preprocessor definition (as this used to) left non-numeric spellings such as
-# -DAKERR_USE_STDLIB=ON expanding to "#if ON == 1", where ON reads as an
-# undefined identifier -- silently 0. Reduce it to a plain 1 or 0 once, here.
-if(AKERR_USE_STDLIB)
-    set(AKERR_USE_STDLIB_DEFINE 1)
-else()
-    set(AKERR_USE_STDLIB_DEFINE 0)
-    if(AKERR_RUNTIME_HEADER STREQUAL "")
-        set(AKERR_RUNTIME_HEADER "${CMAKE_CURRENT_SOURCE_DIR}/cmake/akerr_default_runtime.h")
-    endif()
-endif()
-
-# A freestanding build cannot be thread safe through pthreads: src/lock.h's
-# pthread backend calls into libc (pthread_mutex_init, abort) unconditionally,
-# and the freestanding runtime contract (AKERR_RUNTIME_HEADER) does not cover
-# it. Fail the configure rather than produce a library that silently links
-# libc anyway.
-if(NOT AKERR_USE_STDLIB AND AKERR_THREAD_SAFE)
-    message(FATAL_ERROR
-        "AKERR_USE_STDLIB=OFF is incompatible with a pthread threading "
-        "backend: libakerror serializes its global state with a recursive "
-        "pthread mutex, and pthreads pull in the C standard library. "
-        "Configure with -DAKERR_THREADS=none to build a freestanding "
-        "library instead.")
-endif()
-
 # Size of the private status-name hash table. Must be a power of two; usable
 # capacity is 75% of it (src/error.c asserts both). The host's errno list
 # consumes part of that at akerr_init() time, so the remainder is what all
@@ -157,19 +107,6 @@ if(AKERR_SANITIZE AND NOT CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
         "AKERR_SANITIZE requires GCC or Clang, not ${CMAKE_C_COMPILER_ID}")
 endif()
 
-if(AKERR_SANITIZE STREQUAL "thread" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
-    # ThreadSanitizer reserves a fixed, very large virtual-address range. Linux
-    # ASLR can put a loader mapping inside it before the runtime starts, which
-    # makes every test fail with "unexpected memory mapping" before main().
-    # Run the instrumented tests under the normal util-linux ASLR wrapper.
-    find_program(AKERR_SETARCH_EXECUTABLE setarch)
-    if(NOT AKERR_SETARCH_EXECUTABLE)
-        message(FATAL_ERROR
-            "AKERR_SANITIZE=thread on Linux requires setarch (util-linux) to "
-            "start tests with ASLR disabled.")
-    endif()
-endif()
-
 function(akerr_instrument_for_sanitizers _target)
     if(AKERR_SANITIZE)
         target_compile_options(${_target} PRIVATE
@@ -204,36 +141,14 @@ add_custom_command(
           ${CMAKE_CURRENT_SOURCE_DIR}
           ${GENERATED_DIR}
           ${AKERR_THREAD_SAFE}
-          ${AKERR_USE_STDLIB_DEFINE}
-          ${AKERR_LAST_ERRNO_VALUE_FALLBACK}
-          ${AKERR_MAX_ERROR_FNAME_LENGTH}
   DEPENDS ${SCRIPT} ${INFILE} ${GENERATED_THREAD_STAMP}
   VERBATIM
 )
 
-# More than one library target consumes the generated sources below. Route
-# them through one explicit prerequisite so parallel Make builds cannot invoke
-# the same generator twice and interleave writes to errno.c.
-add_custom_target(akerror_generated
-  DEPENDS ${GENERATED_ERRNO_C} ${GENERATED_AKERROR_H}
-)
-
-# The generated errno table is produced by shelling out to `errno --list`
-# (moreutils) and #include <errno.h>, neither of which is freestanding-safe.
-# It is also useless there: akerr_init_errno() is only ever called under
-# AKERR_USE_STDLIB (see src/error.c), so a freestanding build does not compile
-# or link it into the library at all.
-if(AKERR_USE_STDLIB)
-    set(AKERR_ERRNO_SOURCES ${GENERATED_ERRNO_C})
-else()
-    set(AKERR_ERRNO_SOURCES)
-endif()
-
 add_library(akerror SHARED
   src/error.c
-  ${AKERR_ERRNO_SOURCES}
+  ${GENERATED_ERRNO_C}
 )
-add_dependencies(akerror akerror_generated)
 
 target_include_directories(akerror PUBLIC
   $<BUILD_INTERFACE:${GENERATED_DIR}/include>
@@ -253,25 +168,12 @@ else()
     set(AKERR_THREADS_DEFINE AKERR_THREADS_NONE=1)
 endif()
 
-# PUBLIC and unconditional: the generated header #errors at compile time if
-# AKERR_USE_STDLIB is OFF and this is not defined, and that check runs for any
-# translation unit that includes the header -- the library's own sources as
-# much as a consumer's. Harmless (and unused) when AKERR_USE_STDLIB is ON.
-if(NOT AKERR_USE_STDLIB)
-    set(AKERR_RUNTIME_HEADER_DEFINE "AKERR_RUNTIME_HEADER=\"${AKERR_RUNTIME_HEADER}\"")
-else()
-    set(AKERR_RUNTIME_HEADER_DEFINE "")
-endif()
-
 target_compile_definitions(akerror
-    PUBLIC AKERR_USE_STDLIB=${AKERR_USE_STDLIB_DEFINE}
+    PUBLIC AKERR_USE_STDLIB=${AKERR_USE_STDLIB}
     PRIVATE AKERR_STATUS_NAME_SLOTS=${AKERR_STATUS_NAME_SLOTS}
     PRIVATE AKERR_MAX_RESERVED_STATUS_RANGES=${AKERR_MAX_RESERVED_STATUS_RANGES}
     PRIVATE ${AKERR_THREADS_DEFINE}
 )
-if(AKERR_RUNTIME_HEADER_DEFINE)
-    target_compile_definitions(akerror PUBLIC ${AKERR_RUNTIME_HEADER_DEFINE})
-endif()
 
 if(AKERR_THREAD_SAFE)
     target_link_libraries(akerror PRIVATE Threads::Threads)
@@ -285,35 +187,6 @@ set_target_properties(akerror PROPERTIES
 akerr_instrument_for_coverage(akerror)
 akerr_instrument_for_sanitizers(akerror)
 
-# akerr_init() must terminate if it cannot reserve the library-owned status
-# band. The production table sizes are deliberately PRIVATE, so exercise that
-# otherwise unreachable startup failure with a second library target whose
-# private registries cannot accept even the first reservation. Keeping this a
-# distinct target is the test: no compile definition leaks into consumers or
-# weakens the production library.
-add_library(akerror_init_failure SHARED
-  src/error.c
-  ${AKERR_ERRNO_SOURCES}
-)
-add_dependencies(akerror_init_failure akerror_generated)
-target_include_directories(akerror_init_failure PUBLIC
-  ${GENERATED_DIR}/include
-)
-target_compile_definitions(akerror_init_failure
-  PUBLIC AKERR_USE_STDLIB=${AKERR_USE_STDLIB_DEFINE}
-  PRIVATE AKERR_STATUS_NAME_SLOTS=8
-  PRIVATE AKERR_MAX_RESERVED_STATUS_RANGES=0
-  PRIVATE ${AKERR_THREADS_DEFINE}
-)
-if(AKERR_RUNTIME_HEADER_DEFINE)
-    target_compile_definitions(akerror_init_failure PUBLIC ${AKERR_RUNTIME_HEADER_DEFINE})
-endif()
-if(AKERR_THREAD_SAFE)
-    target_link_libraries(akerror_init_failure PRIVATE Threads::Threads)
-endif()
-akerr_instrument_for_coverage(akerror_init_failure)
-akerr_instrument_for_sanitizers(akerror_init_failure)
-
 # Each test is one source file in tests/ built into test_<name> and registered
 # as CTest <name>. Tests expected to abort (unhandled error / contract
 # violation) go in AKERR_WILL_FAIL_TESTS; all others must exit 0.
@@ -341,7 +214,6 @@ set(AKERR_TESTS
     err_registry_init_order
     err_status_exception
     err_copy_string
-    err_init_reservation_fatal
     err_library_status_fatal
     err_refcount_double_fail
     err_stacktrace_bounds
@@ -369,29 +241,18 @@ endif()
 set(AKERR_WILL_FAIL_TESTS
     err_trace
     err_improper_closure
-    err_init_reservation_fatal
     err_library_status_fatal
 )
 
 foreach(_test IN LISTS AKERR_TESTS)
     add_executable(test_${_test} tests/${_test}.c)
     target_include_directories(test_${_test} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/tests)
-    if(_test STREQUAL "err_init_reservation_fatal")
-        target_link_libraries(test_${_test} PRIVATE akerror_init_failure)
-    else()
     target_link_libraries(test_${_test} PRIVATE akerror)
-    endif()
     if(AKERR_THREAD_SAFE)
         target_link_libraries(test_${_test} PRIVATE Threads::Threads)
     endif()
     akerr_instrument_for_sanitizers(test_${_test})
-    if(AKERR_SANITIZE STREQUAL "thread" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
-        add_test(NAME ${_test}
-                 COMMAND ${AKERR_SETARCH_EXECUTABLE} ${CMAKE_SYSTEM_PROCESSOR}
-                         -R $<TARGET_FILE:test_${_test}>)
-    else()
     add_test(NAME ${_test} COMMAND test_${_test})
-    endif()
     # A sanitizer report is a test failure. Without halt_on_error the runtime
     # prints and continues, which leaves a race to be noticed in the log by
     # somebody reading it -- and under a race storm the reporting itself is slow
@@ -402,14 +263,6 @@ foreach(_test IN LISTS AKERR_TESTS)
     endif()
 endforeach()
 
-# HANDLE_GROUP deliberately enters the next case label. Keep that public macro
-# compiling with the warning enabled, so a future macro edit cannot restore the
-# warning for consumers which adopt -Wextra.
-if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
-    target_compile_options(test_err_handle_group PRIVATE
-                           -Werror=implicit-fallthrough)
-endif()
-
 set_tests_properties(
     ${AKERR_WILL_FAIL_TESTS}
     PROPERTIES WILL_FAIL TRUE
@@ -425,14 +278,7 @@ if(Python3_FOUND)
     # The script configures and drives its own instrumented build tree (under
     # ${CMAKE_BINARY_DIR}/coverage) so this build's binaries and its coverage
     # counters can never be stale or half-instrumented. Reports via gcov.
-    # Keep the convenient generic name at the top level, but namespace it when
-    # embedded so a parent project can provide its own coverage target.
-    if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
-        set(AKERR_COVERAGE_TARGET coverage)
-    else()
-        set(AKERR_COVERAGE_TARGET akerror_coverage)
-    endif()
-    add_custom_target(${AKERR_COVERAGE_TARGET}
+    add_custom_target(coverage
         COMMAND ${Python3_EXECUTABLE}
                 ${CMAKE_CURRENT_SOURCE_DIR}/scripts/coverage.py
                 --source-root ${CMAKE_CURRENT_SOURCE_DIR}
@@ -464,6 +310,7 @@ if(Python3_FOUND)
     )
 endif()
 
+set(main_lib_dest "lib/my_library-${MY_LIBRARY_VERSION}")
 install(TARGETS akerror
   EXPORT akerrorTargets
   ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
@@ -487,17 +334,8 @@ configure_package_config_file(
     INSTALL_DESTINATION ${akerror_install_cmakedir}
 )
 
-# The SOVERSION is the project major version, so packages with the same major
-# are ABI-compatible and a different major must be rejected.
-write_basic_package_version_file(
-    "${CMAKE_CURRENT_BINARY_DIR}/akerrorConfigVersion.cmake"
-    VERSION ${PROJECT_VERSION}
-    COMPATIBILITY SameMajorVersion
-)
-
 install(FILES
     "${CMAKE_CURRENT_BINARY_DIR}/akerrorConfig.cmake"
-    "${CMAKE_CURRENT_BINARY_DIR}/akerrorConfigVersion.cmake"
     DESTINATION ${akerror_install_cmakedir}
 )
 

README.md

@@ -170,7 +170,7 @@ 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](docs/exit-status.md). No ABI break.
 
-2.0.0 makes the library thread safe. That is an ABI break — `akerr_last_ignored`
+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.

UPGRADING.md

@@ -1,38 +1,3 @@
-# Bug fix: the AKERR_USE_STDLIB=OFF build, and a pool-exhaustion exit code (2.0.2)
-
-`-DAKERR_USE_STDLIB=OFF` did not compile at all ([issue #12](https://source.starfort.tech/andrew/libakerror/issues/12)):
-`bool`, `PATH_MAX` and `NULL` were used unconditionally in the public header
-but only included under the stdlib branch, and the CMake option itself was
-pasted straight into a preprocessor definition, so a boolean spelling like
-`ON` silently evaluated to 0 in `#if AKERR_USE_STDLIB == 1`. Both are fixed:
-`<stdbool.h>` and `<stddef.h>` are now included unconditionally (they are
-freestanding-safe), and the CMake option is normalized to a plain `1`/`0`
-before being stamped into the header.
-
-`AKERR_USE_STDLIB=OFF` now has a mandatory, explicit contract:
-`AKERR_RUNTIME_HEADER` must name a header providing `exit`, `memset`,
-`snprintf`, `strcmp`, `strlen` and `strncpy` — the header `#error`s at compile
-time naming those six symbols if it is unset. `AKERR_THREADS` must resolve to
-`none`; the configure now fails outright (not a warning) if it would resolve
-to `pthread`, since the pthread backend calls into libc. See
-[docs/building.md](docs/building.md#dependencies).
-
-`PATH_MAX`, used to size the `fname`/`function` fields of `akerr_ErrorContext`,
-is retired in favor of a new `AKERR_MAX_ERROR_FNAME_LENGTH` build option. Its
-default (4096) matches `PATH_MAX` on Linux/glibc, so `sizeof(akerr_ErrorContext)`
-and the soname are unchanged unless you deliberately override it — **no ABI
-break**.
-
-**Behavior change, not an ABI break:** `ENSURE_ERROR_READY`'s pool-exhaustion
-path — reached when every slot in `AKERR_ARRAY_ERROR` is checked out and
-something still tries to raise — used to call `exit(1)` directly. It now calls
-`akerr_exit(AKERR_EXIT_STATUS_UNREPRESENTABLE)`, the same terminal path every
-other exit out of the library's status space goes through, so **the exit code
-for that case changes from 1 to 125**. If you were checking `$?` for exactly
-`1` to detect pool exhaustion specifically, check for 125 instead (and note
-125 is shared with every other status an exit code cannot carry — see the note
-on `AKERR_EXIT_STATUS_UNREPRESENTABLE` in the header).
-
 # Bug fix: unhandled-error exit status (2.0.1)
 
 An unhandled error could kill the process and still report success.
@@ -87,7 +52,7 @@ accident.
 
 What moved at the ABI:
 
-* `akerr_last_ignored` is thread-local storage. An ignored error is a fact
+* `__akerr_last_ignored` is thread-local storage. An ignored error is a fact
   about the thread that ignored it, and one shared slot had two threads
   overwriting each other's. The `IGNORE` macro expands at *your* call site, so
   your objects reference the symbol under whichever storage model your header
@@ -167,11 +132,6 @@ One recursive lock covers both the pool and the registry, so error
 correctness there is worth more than throughput, but a program that raises
 errors in a hot loop will feel it.
 
-Releasing the last reference to a context remains serialized under that same
-pool lock, but it now resets only the handled/status/reported state, the string
-heads, and the stack-trace cursor. It no longer wipes the whole context buffer,
-so release is a fixed handful of stores rather than a tens-of-kilobytes write.
-
 The per-thread last-ditch context is a whole `akerr_ErrorContext` (tens of
 kilobytes) in thread-local storage, allocated per thread on first use of the
 library from that thread.

cmake/akerr_default_runtime.h

@@ -1,22 +0,0 @@
-#ifndef AKERR_DEFAULT_RUNTIME_H_
-#define AKERR_DEFAULT_RUNTIME_H_
-
-/*
- * Convenience default for AKERR_RUNTIME_HEADER, used when libakerror is
- * configured -DAKERR_USE_STDLIB=OFF without also setting
- * -DAKERR_RUNTIME_HEADER. It re-exposes the six symbols the freestanding
- * build needs (exit, memset, snprintf, strcmp, strlen, strncpy) from the
- * host's own C library, so building and testing the OFF configuration on an
- * ordinary hosted machine does not require standing up a real freestanding
- * runtime first.
- *
- * A genuinely freestanding consumer -- the whole point of
- * AKERR_USE_STDLIB=OFF -- supplies their own header providing those six
- * symbols and overrides the AKERR_RUNTIME_HEADER cache variable; this file is
- * not meant for that use.
- */
-#include <stdlib.h>
-#include <string.h>
-#include <stdio.h>
-
-#endif /* AKERR_DEFAULT_RUNTIME_H_ */

docs/building.md

@@ -9,22 +9,13 @@ either of those.
 
 | Option | Default | What it does |
 | ------ | ------- | ------------ |
-| `AKERR_THREADS` | `auto` | Threading backend: `auto`, `pthread`, or `none`. `auto` takes POSIX threads and **fails the configure** if it cannot find them. See [Building single threaded](thread-safety.md#building-single-threaded). **Must be `none` when `AKERR_USE_STDLIB` is `OFF`** — the pthread backend calls into libc, and the configure fails otherwise. |
+| `AKERR_THREADS` | `auto` | Threading backend: `auto`, `pthread`, or `none`. `auto` takes POSIX threads and **fails the configure** if it cannot find them. See [Building single threaded](thread-safety.md#building-single-threaded). |
 | `AKERR_USE_STDLIB` | `ON` | Link against the C standard library. See [Dependencies](#dependencies) for what you must supply instead when this is `OFF`. |
-| `AKERR_RUNTIME_HEADER` | *(empty)* | **Mandatory when `AKERR_USE_STDLIB` is `OFF`.** Header providing `exit`, `memset`, `snprintf`, `strcmp`, `strlen` and `strncpy`; the generated header `#error`s at compile time if it is unset. Defaults to a thin, libc-backed convenience header (`cmake/akerr_default_runtime.h`) so this repository's own `OFF` build and test suite work without a real freestanding runtime — a genuinely freestanding consumer should override it with their own header. |
-| `AKERR_MAX_ERROR_FNAME_LENGTH` | `4096` | Bytes reserved for the `fname`/`function` fields of `akerr_ErrorContext`. Defaults to `PATH_MAX` on Linux/glibc, which keeps `sizeof(akerr_ErrorContext)` and the soname unchanged; changing it is an ABI break. |
-| `AKERR_LAST_ERRNO_VALUE_FALLBACK` | `133` | `AKERR_LAST_ERRNO_VALUE` to stamp when `AKERR_USE_STDLIB` is `OFF`, since that configuration cannot shell out to `errno --list`. Defaults to 133 (Linux's `EHWPOISON`). |
 | `AKERR_STATUS_NAME_SLOTS` | `4096` | Slots in the status-name table; 75% of it is usable. |
 | `AKERR_MAX_RESERVED_STATUS_RANGES` | `64` | How many status ranges may be reserved in one process. |
 | `AKERR_SANITIZE` | *(empty)* | Sanitizer list applied to the library and the tests, e.g. `thread` or `address,undefined`. |
 | `AKERR_COVERAGE` | `OFF` | Instrument the library with gcov counters. |
 
-**Behavior change (2.0.2):** pool exhaustion inside `ENSURE_ERROR_READY` (every
-context-producing macro goes through it) used to call `exit(1)` directly. It
-now calls `akerr_exit(AKERR_EXIT_STATUS_UNREPRESENTABLE)`, so a process that
-runs out of pool slots exits **125** instead of **1**. See
-[UPGRADING.md](../UPGRADING.md).
-
 The two capacity options are applied `PRIVATE`: the tables live entirely in
 `src/error.c`, so raising them never changes anything a consumer can see. See
 [UPGRADING.md](../UPGRADING.md) for what happens when you exhaust them.
@@ -33,59 +24,38 @@ The two capacity options are applied `PRIVATE`: the tables live entirely in
 
 The build process relies upon `scripts/generrno.sh` which performs the following:
 
-1. When `AKERR_USE_STDLIB` is `ON`: executes `errno --list` and gathers up the
-   output. When it is `OFF`, this is skipped entirely (`errno --list` needs
-   moreutils and `<errno.h>`, neither freestanding-safe) and
-   `AKERR_LAST_ERRNO_VALUE` is taken from the `AKERR_LAST_ERRNO_VALUE_FALLBACK`
-   cache variable instead.
-1. Templates `include/akerror.tmpl.h` into `include/akerror.h` to set
-   `AKERR_LAST_ERRNO_VALUE`, `AKERR_THREAD_SAFE`, and
-   `AKERR_MAX_ERROR_FNAME_LENGTH`.
-2. Generates `src/errno.c`, which contains a function called by `akerr_init`
-   that initializes all of the status names for the previously defined values
-   of `errno`. Under `AKERR_USE_STDLIB=OFF` this file is a stub, and CMake does
-   not compile it into the library at all — `akerr_init_errno()` is never
-   called in that configuration.
+1. Executes `errno --list` and gathers up the output
+1. Templates `include/akerror.tmpl.h` into `include/akerror.h` to set the `AKERR_LAST_ERRNO_VALUE` equal to the highest integer defined by `errno`
+2. Generates `src/errno.c` which contains a function called by `akerr_init` which initializes all of the status names for the previously defined values of `errno`.
 
-Neither generated output is meant to be edited. Change the template or the generator.
+Neither output is meant to be edited. Change the template or the generator.
 
 ## Dependencies
 
 This library depends upon `stdlib`, and upon POSIX threads unless it is built
-with `-DAKERR_THREADS=none` (see [Thread safety](thread-safety.md)). If you
-don't want to link against stdlib, build with `-DAKERR_USE_STDLIB=OFF` (which
-requires `-DAKERR_THREADS=none` — see the options table above) and supply a
-header, via the `AKERR_RUNTIME_HEADER` cache variable, that provides:
+with `-DAKERR_THREADS=none` (see [Thread safety](thread-safety.md)). If you don't want to link against stdlib, you must modify the library code to include headers and link against a library that provides the following:
 
 - `memset` function
 - `strncpy` function
 - `strlen` function
 - `strcmp` function
-- `snprintf` function
+- `sprintf` function
 - `exit` function
 - `bool` type
 - `NULL` type
-- `size_t` type
 - `INT_MAX` constant
-
-`<stdbool.h>` and `<stddef.h>` — which give you `bool`/`NULL`/`size_t` — are
-included unconditionally by the public header regardless of
-`AKERR_USE_STDLIB`, since both are freestanding-safe. `AKERR_RUNTIME_HEADER` is
-mandatory in this configuration: the generated header `#error`s at compile
-time if it is unset.
+- `PATH_MAX` constant
 
 ... then you can compile it thusly:
 
 ```
-cmake -S . -B build -DAKERR_USE_STDLIB=OFF -DAKERR_THREADS=none \
-    -DAKERR_RUNTIME_HEADER=/path/to/your/runtime.h
+cmake -S . -B build -DAKERR_USE_STDLIB=OFF
 cmake --build build
 cmake --install build
 ```
 
-If you omit `-DAKERR_RUNTIME_HEADER`, the build falls back to a convenience
-header backed by the host's own libc (see the options table above), so the
-`OFF` configuration still builds and its test suite still runs on an ordinary
-hosted machine — useful for exercising the freestanding code paths without a
-real freestanding runtime, but not what an actually freestanding consumer
-wants. Supply your own header to get the real thing.
+**Known defect:** that configuration does not currently compile. `bool`,
+`PATH_MAX` and `NULL` are used unconditionally but only included under the
+stdlib branch, so the header's includes need untangling before
+`-DAKERR_USE_STDLIB=OFF` builds. The list above still states what a replacement
+must provide. See [TODO.md](../TODO.md).

docs/thread-safety.md

@@ -14,12 +14,9 @@ What that covers:
   against each other and against lookups. Two threads reserving the same range
   cannot both win — exactly one gets `NULL` and the other gets
   `AKERR_STATUS_RANGE_OVERLAP` naming the winner.
-* **Per-thread state.** `IGNORE` copies the swallowed context into its
-  thread-local `akerr_last_ignored` snapshot before releasing the pool slot.
-  The snapshot remains valid until that thread ignores another error, so a
-  later pool checkout cannot overwrite it. The snapshot and the last-ditch
-  context used to report `akerr_release_error(NULL)` are thread-local, so
-  concurrent calls cannot overwrite each other's state.
+* **Per-thread state.** The context behind `IGNORE` (`__akerr_last_ignored`) and
+  the last-ditch context used to report `akerr_release_error(NULL)` are
+  thread-local, so one thread's ignored error is never another's.
 * **Handing a context from one thread to another.** A context is not thread
   state — it lives in `AKERR_ARRAY_ERROR`, which is process-global — so it
   outlives the thread that raised it. The reference count is the only field the

include/akerror.tmpl.h

@@ -1,42 +1,12 @@
 #ifndef _AKERR_H_
 #define _AKERR_H_
 
-/*
- * A consumer compiling this header directly (not through the CMake package,
- * which always stamps a numeric AKERR_USE_STDLIB=0/1 -- see CMakeLists.txt)
- * gets the hosted default.
- */
-#ifndef AKERR_USE_STDLIB
-#define AKERR_USE_STDLIB 1
-#endif
-
-/*
- * <stdbool.h> and <stddef.h> are freestanding-safe (C99/C11 4p6): they define
- * only bool/true/false and NULL/size_t, nothing that requires an operating
- * system underneath. Include them unconditionally so both configurations get
- * those types. Everything that actually talks to a hosted environment --
- * stdlib.h, string.h, stdio.h -- stays behind AKERR_USE_STDLIB.
- */
-#include <stdbool.h>
-#include <stddef.h>
-
-#if AKERR_USE_STDLIB
+#if (defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1) || (!defined(AKERR_USE_STDLIB))
 #include <stdlib.h>
+#include <stdbool.h>
 #include <string.h>
 #include <stdio.h>
-#else
-/*
- * Freestanding runtime contract. AKERR_USE_STDLIB=OFF still needs exit,
- * memset, snprintf, strcmp, strlen and strncpy (see the FAIL/ENSURE_ERROR_READY
- * macros and src/error.c below) -- this library does not implement its own
- * copies of them. Define AKERR_RUNTIME_HEADER to a header that provides all
- * six before including this one.
- */
-#ifdef AKERR_RUNTIME_HEADER
-#include AKERR_RUNTIME_HEADER
-#else
-#error "AKERR_USE_STDLIB is OFF: define AKERR_RUNTIME_HEADER to a header providing exit, memset, snprintf, strcmp, strlen and strncpy"
-#endif
+#include <limits.h>
 #endif
 
 /*
@@ -45,7 +15,7 @@
  * scripts/generrno.sh stamps this value in at build time from the AKERR_THREADS
  * build option, the same way it stamps AKERR_LAST_ERRNO_VALUE. It is generated
  * rather than defined by the consumer on purpose: whether the library
- * serializes its global state and whether akerr_last_ignored is a
+ * serializes its global state and whether __akerr_last_ignored is a
  * thread-local are the same decision, and a consumer that disagreed with the
  * library about it would link against a differently shaped symbol.
  *
@@ -82,15 +52,7 @@
 #define AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH              12384
 
 #define AKERR_MAX_ERROR_NAME_LENGTH                        64
-/*
- * scripts/generrno.sh stamps this in from the AKERR_MAX_ERROR_FNAME_LENGTH
- * CMake cache variable, the same way it stamps AKERR_THREAD_SAFE and
- * AKERR_LAST_ERRNO_VALUE. It used to be PATH_MAX, which is not available in a
- * freestanding build; the default here (4096) matches PATH_MAX on Linux/glibc
- * so sizeof(akerr_ErrorContext) and the soname are unchanged unless you
- * deliberately override it.
- */
-#define AKERR_MAX_ERROR_FNAME_LENGTH                       4096
+#define AKERR_MAX_ERROR_FNAME_LENGTH                       PATH_MAX
 #define AKERR_MAX_ERROR_FUNCTION_LENGTH                    128
 #define AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH              (AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH + AKERR_MAX_ERROR_NAME_LENGTH + AKERR_MAX_ERROR_FNAME_LENGTH + AKERR_MAX_ERROR_FUNCTION_LENGTH + 16)
 
@@ -211,12 +173,11 @@ extern akerr_ErrorContext AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR];
 extern akerr_ErrorUnhandledErrorHandler akerr_handler_unhandled_error;
 extern akerr_ErrorLogFunction akerr_log_method;
 /*
- * IGNORE()'s public per-thread snapshot. IGNORE() copies the swallowed error here
- * before releasing its pool context, so this remains a useful debugging aid
- * after the pool slot is reused. The snapshot is read-only and is replaced by
- * the next ignored error. Thread local only when AKERR_THREAD_SAFE is 1.
+ * The error IGNORE() last swallowed, per thread: an ignored error is a fact
+ * about the thread that ignored it, and one shared slot would have two threads
+ * overwriting each other's. Thread local only when AKERR_THREAD_SAFE is 1.
  */
-static AKERR_THREAD_LOCAL akerr_ErrorContext akerr_last_ignored;
+extern AKERR_THREAD_LOCAL akerr_ErrorContext *__akerr_last_ignored;
 
 /*
  * Drop one reference, returning NULL once the last one is gone so the caller can
@@ -334,7 +295,7 @@ akerr_ErrorContext AKERR_NOIGNORE *__akerr_copy_string(char *destination, int ca
 	__err_context = akerr_next_error();				\
 	if ( __err_context == NULL ) {					\
 	    akerr_log_method("%s:%s:%d: Unable to pull an error context from the array!", __FILE__, (char *)__func__, __LINE__); \
-	    akerr_exit(AKERR_EXIT_STATUS_UNREPRESENTABLE);		\
+	    exit(1);							\
 	}								\
     }
 
@@ -430,18 +391,6 @@ akerr_ErrorContext AKERR_NOIGNORE *__akerr_copy_string(char *destination, int ca
  * Defines for the ATTEMPT/CATCH/CLEANUP/PROCESS/HANDLE/FINISH process
  */
 
-/*
- * HANDLE_GROUP deliberately enters the next case label. GCC and clang both
- * understand this spelling in the C modes supported by libakerror. Other
- * compilers keep the established control flow without receiving an attribute
- * they do not implement.
- */
-#if defined(__GNUC__) || defined(__clang__)
-#define AKERR_FALLTHROUGH __attribute__((fallthrough));
-#else
-#define AKERR_FALLTHROUGH
-#endif
-
 #define ATTEMPT					\
     switch ( 0 ) {				\
     case 0:					\
@@ -473,20 +422,10 @@ akerr_ErrorContext AKERR_NOIGNORE *__akerr_copy_string(char *destination, int ca
     FINISH_LOGIC(__err_context, true);
 
 #define IGNORE(__stmt)							\
-    do {								\
-	akerr_ErrorContext *__akerr_ignored = __stmt;				\
-	if ( __akerr_ignored != NULL ) {				\
-	    memcpy(&akerr_last_ignored, __akerr_ignored,	\
-		   sizeof(akerr_last_ignored));			\
-	    akerr_last_ignored.stacktracebufptr =		\
-		(char *)&akerr_last_ignored.stacktracebuf;	\
-	    akerr_ErrorContext *__akerr_ignored_snapshot =	\
-		&akerr_last_ignored;					\
-	    LOG_ERROR_WITH_MESSAGE(__akerr_ignored_snapshot,	\
-				   "** IGNORED ERROR **");		\
-	    RELEASE_ERROR(__akerr_ignored);				\
-	}								\
-    } while ( 0 )
+    __akerr_last_ignored = __stmt;					\
+    if ( __akerr_last_ignored != NULL ) {				\
+	LOG_ERROR_WITH_MESSAGE(__akerr_last_ignored, "** IGNORED ERROR **"); \
+    }
 
 #define CLEANUP					\
     }; 
@@ -504,7 +443,6 @@ akerr_ErrorContext AKERR_NOIGNORE *__akerr_copy_string(char *destination, int ca
     __err_context->handled = true;
 
 #define HANDLE_GROUP(__err_context, __err_status)			\
-    AKERR_FALLTHROUGH					\
     case __err_status:							\
     __err_context->stacktracebufptr = (char *)&__err_context->stacktracebuf; \
     __err_context->handled = true;

scripts/generrno.sh

@@ -7,39 +7,18 @@ outdir=$2
 # with the library about whether it locks and whether its per-thread state is
 # thread local. Defaults to 1 for a hand-run of this script.
 thread_safe=${3:-1}
-# 1 for a normal (libc-linked) build, 0 for -DAKERR_USE_STDLIB=OFF. The
-# freestanding build cannot shell out to `errno --list` (moreutils) or
-# #include <errno.h>, so it skips the errno scrape entirely and stamps
-# AKERR_LAST_ERRNO_VALUE from a fixed fallback instead. Defaults to 1 for a
-# hand-run of this script.
-use_stdlib=${4:-1}
-# AKERR_LAST_ERRNO_VALUE to stamp when use_stdlib is 0. Defaults to 133
-# (Linux's EHWPOISON) so the reserved band assertion in akerror.tmpl.h still
-# holds.
-last_errno_fallback=${5:-133}
-# Bytes reserved for the fname/function fields of akerr_ErrorContext. Defaults
-# to 4096 (PATH_MAX on Linux/glibc) so sizeof(akerr_ErrorContext) and the
-# soname stay unchanged from before this became a build option.
-max_error_fname_length=${6:-4096}
 
 if [ "${thread_safe}" != "0" ] && [ "${thread_safe}" != "1" ]; then
     echo "$0: thread-safe argument must be 0 or 1, got '${thread_safe}'" >&2
     exit 1
 fi
 
-if [ "${use_stdlib}" != "0" ] && [ "${use_stdlib}" != "1" ]; then
-    echo "$0: use-stdlib argument must be 0 or 1, got '${use_stdlib}'" >&2
-    exit 1
-fi
-
 mkdir -p ${outdir}/src
 mkdir -p ${outdir}/include
 rm -f ${outdir}/src/errno.c
-
-if [ "${use_stdlib}" = "1" ]; then
-    echo "#include <akerror.h>" >> ${outdir}/src/errno.c
-    echo "#include <errno.h>" >> ${outdir}/src/errno.c
-    cat >> ${outdir}/src/errno.c <<'EOF'
+echo "#include <akerror.h>" >> ${outdir}/src/errno.c
+echo "#include <errno.h>" >> ${outdir}/src/errno.c
+cat >> ${outdir}/src/errno.c <<'EOF'
 
 /*
  * These names belong to the library's own reserved band, and this runs from
@@ -50,25 +29,15 @@ if [ "${use_stdlib}" = "1" ]; then
  * control flow no test can reach.
  */
 EOF
-    echo "void akerr_init_errno(void) {" >> ${outdir}/src/errno.c
-    maxval=$(errno --list | cut -d ' ' -f 2 | sort -g | tail -n 1)
-    errno --list | while read LINE; do
+echo "void akerr_init_errno(void) {" >> ${outdir}/src/errno.c
+maxval=$(errno --list | cut -d ' ' -f 2 | sort -g | tail -n 1)
+errno --list | while read LINE; do
     define=$(echo "$LINE" | cut -d ' ' -f 1);
     value=$(echo "$LINE" | cut -d ' ' -f 2);
     desc=$(echo "$LINE" | cut -d ' ' -f 3-);
     echo "	__akerr_name_library_status(${define}, \"${desc}\");" >> ${outdir}/src/errno.c ;
-    done;
-    echo "}" >> ${outdir}/src/errno.c
-else
-    # Freestanding: no `errno --list` shellout (requires moreutils and
-    # <errno.h>, neither freestanding-safe), and no errno.c at all -- CMake
-    # does not compile it into the library under AKERR_USE_STDLIB=OFF. Still
-    # write a stub so the OUTPUT this rule promises always exists.
-    echo "/* AKERR_USE_STDLIB=OFF: no errno table generated. */" >> ${outdir}/src/errno.c
-    maxval=${last_errno_fallback}
-fi
-
+done;
+echo "}" >> ${outdir}/src/errno.c
 sed -e "s/#define AKERR_LAST_ERRNO_VALUE .*/#define AKERR_LAST_ERRNO_VALUE      ${maxval}/" \
     -e "s/#define AKERR_THREAD_SAFE .*/#define AKERR_THREAD_SAFE           ${thread_safe}/" \
-    -e "s/#define AKERR_MAX_ERROR_FNAME_LENGTH .*/#define AKERR_MAX_ERROR_FNAME_LENGTH                       ${max_error_fname_length}/" \
     ${srcdir}/include/akerror.tmpl.h > ${outdir}/include/akerror.h

scripts/mutation_test.py

@@ -25,8 +25,6 @@ Usage:
     --work DIR          scratch dir for the mutated copy (default: a temp dir)
     --timeout SECONDS   per-suite ctest timeout (default: 120)
     --threshold PCT     exit non-zero if mutation score < PCT (default: 0 = off)
-    --cmake-arg ARG     pass an additional argument to the mutant CMake configure;
-                        repeat for multiple arguments (e.g. -DAKERR_SANITIZE=thread)
     --list              only list the mutants that would be run, then exit
     --keep              keep the scratch working copy on exit (for debugging)
     -j N                (reserved) currently runs sequentially
@@ -201,11 +199,10 @@ def generate_mutants(root, rel_target):
 # --------------------------------------------------------------------------- #
 
 class Runner:
-    def __init__(self, work, timeout, cmake_args):
+    def __init__(self, work, timeout):
         self.work = work
         self.build = os.path.join(work, "build")
         self.timeout = timeout
-        self.cmake_args = cmake_args
 
     def _run(self, cmd, timeout=None):
         return subprocess.run(
@@ -214,8 +211,7 @@ class Runner:
         )
 
     def configure(self):
-        r = self._run(["cmake", "-S", ".", "-B", "build", *self.cmake_args],
-                      timeout=self.timeout)
+        r = self._run(["cmake", "-S", ".", "-B", "build"], timeout=self.timeout)
         return r.returncode == 0, r.stdout
 
     def build_and_test(self):
@@ -311,8 +307,6 @@ def main():
     ap.add_argument("--work", default=None)
     ap.add_argument("--timeout", type=int, default=120)
     ap.add_argument("--threshold", type=float, default=0.0)
-    ap.add_argument("--cmake-arg", action="append", default=[],
-                    help="pass an argument to the mutant CMake configure; repeatable")
     ap.add_argument("--junit", default=None,
                     help="write a JUnit XML report to this path")
     ap.add_argument("--max-mutants", type=int, default=0,
@@ -360,7 +354,7 @@ def main():
     print(f"\nCopying sources to scratch dir: {work}")
     copy_tree(root, work)
 
-    runner = Runner(work, args.timeout, args.cmake_arg)
+    runner = Runner(work, args.timeout)
 
     print("Configuring baseline ...")
     ok, out = runner.configure()

src/error.c

@@ -1,10 +1,6 @@
 #include "akerror.h"
 #include "lock.h"
-/* INT_MAX (used below in akerr_reserve_status_range_locked) only, not in the
- * public header: <limits.h> is freestanding-safe, but nothing else in this
- * file's freestanding build needs it, so it stays out of the shared header. */
-#include <limits.h>
-#if AKERR_USE_STDLIB
+#if defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1
 #include <stdlib.h>
 #include <stdarg.h>
 #include <stdio.h>
@@ -24,10 +20,10 @@
  * It is not small (an akerr_ErrorContext is tens of kilobytes), but the storage
  * is allocated per thread only when that thread first touches the library's
  * thread-local block, and the alternative is a shared buffer that two threads
- * can be writing at once. The per-thread IGNORE() snapshot lives in the public
- * template header because the macro copies into it at the call site.
+ * can be writing at once.
  */
 static AKERR_THREAD_LOCAL akerr_ErrorContext __akerr_last_ditch;
+AKERR_THREAD_LOCAL akerr_ErrorContext *__akerr_last_ignored;
 akerr_ErrorUnhandledErrorHandler akerr_handler_unhandled_error;
 akerr_ErrorLogFunction akerr_log_method = NULL;
 
@@ -92,10 +88,7 @@ typedef struct
 
 static akerr_StatusName akerr_status_names[AKERR_STATUS_NAME_SLOTS];
 static int akerr_status_name_count;
-/* C has no portable zero-length arrays. Keep one unused physical slot when a
- * test build sets the logical capacity to zero to drive init's fatal path. */
-static akerr_StatusRange akerr_status_ranges[
-    AKERR_MAX_RESERVED_STATUS_RANGES > 0 ? AKERR_MAX_RESERVED_STATUS_RANGES : 1];
+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];
@@ -158,7 +151,7 @@ int akerr_valid_error_address(akerr_ErrorContext *ptr)
 
 void akerr_default_logger(const char *fmt, ...)
 {
-#if AKERR_USE_STDLIB
+#if defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1
     va_list ap;
 
     va_start(ap, fmt);
@@ -240,6 +233,7 @@ static void akerr_init_state(void)
 	AKERR_ARRAY_ERROR[i].arrayid = i;
 	AKERR_ARRAY_ERROR[i].stacktracebufptr = (char *)&AKERR_ARRAY_ERROR[i].stacktracebuf;
     }
+    __akerr_last_ignored = NULL;
     (void)akerr_last_ditch_context();
     if ( akerr_log_method == NULL ) {
 	akerr_log_method = &akerr_default_logger;
@@ -289,7 +283,7 @@ static void akerr_init_state(void)
     __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 AKERR_USE_STDLIB
+#if (defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1) || (!defined(AKERR_USE_STDLIB))
     akerr_init_errno();
 #endif
 
@@ -383,10 +377,10 @@ akerr_ErrorContext *akerr_next_error()
 }
 
 /*
- * The reset returns the slot to the pool, so it and the decrement that triggers
+ * The wipe returns the slot to the pool, so it and the decrement that triggers
  * it are one operation under the lock. Otherwise a thread that saw the count
  * reach zero could be handed the slot by akerr_next_error() and start writing
- * its error into it while the releasing thread was still resetting it.
+ * its error into it while the releasing thread was still memsetting it.
  */
 akerr_ErrorContext *akerr_release_error(akerr_ErrorContext *err)
 {
@@ -404,13 +398,7 @@ akerr_ErrorContext *akerr_release_error(akerr_ErrorContext *err)
     }
     if ( err->refcount == 0 ) {
 	oldid = err->arrayid;
-	err->handled = false;
-	err->status = 0;
-	err->reported = false;
-	err->message[0] = '\0';
-	err->fname[0] = '\0';
-	err->function[0] = '\0';
-	err->stacktracebuf[0] = '\0';
+	memset(err, 0x00, sizeof(akerr_ErrorContext));
 	err->stacktracebufptr = (char *)&err->stacktracebuf;
 	err->arrayid = oldid;
 	remaining = NULL;
@@ -676,7 +664,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *akerr_reserve_status_range_locked(int
 			"must not overflow int)",
 			count, first_status, owner == NULL ? "(null)" : owner,
 			AKERR_MAX_STATUS_RANGE_OWNER_LENGTH);
-    last_status = first_status + (count - 1);
+    last_status = first_status + count - 1;
 
     for ( int i = 0; i < akerr_status_range_count; i++ ) {
 	if ( first_status <= akerr_status_ranges[i].last &&

src/lock.h

@@ -33,12 +33,10 @@
 
 /*
  * PTHREAD_MUTEX_RECURSIVE is XSI, so glibc hides it under a strict -std=c99
- * without _XOPEN_SOURCE. No feature-test macro is defined here: this file is
- * only ever compiled with AKERR_THREADS_PTHREAD, which CMake now refuses to
- * pair with AKERR_USE_STDLIB=OFF (see the AKERR_THREADS/AKERR_USE_STDLIB
- * check in CMakeLists.txt), so whatever default feature-test macros the host
- * libc uses when building the rest of the (hosted) library apply here too.
- * Build with -D_XOPEN_SOURCE=700 if you need strict C99.
+ * without _XOPEN_SOURCE. No feature-test macro is defined here, because the
+ * public header already needs the same one for PATH_MAX: a build strict enough
+ * to lose one has already lost the other. Build with -D_XOPEN_SOURCE=700 if you
+ * need strict C99.
  */
 #if defined(AKERR_THREADS_PTHREAD) && AKERR_THREADS_PTHREAD == 1
 

tests/MUTATION.md

@@ -32,9 +32,6 @@ scripts/mutation_test.py --target src/error.c --list
 
 # Gate CI: exit non-zero if the score drops below 90%
 scripts/mutation_test.py --threshold 90
-
-# Check concurrency mutants under ThreadSanitizer
-scripts/mutation_test.py --cmake-arg=-DAKERR_SANITIZE=thread
 ```
 
 Via CMake (configures a build first if needed):
@@ -43,10 +40,8 @@ Via CMake (configures a build first if needed):
 cmake --build build --target mutation
 ```
 
-Useful flags: `--cmake-arg ARG` (pass a CMake configure argument to every
-mutant build; repeat it for multiple arguments), `--timeout SECONDS` (per-suite
-build+test cap; a mutant that hangs is counted as killed), `--keep` (retain the
-scratch copy for debugging),
+Useful flags: `--timeout SECONDS` (per-suite build+test cap; a mutant that
+hangs is counted as killed), `--keep` (retain the scratch copy for debugging),
 `--work DIR` (use a specific scratch directory), `--junit FILE` (write a JUnit
 XML report — surviving mutants appear as failing test cases).
 
@@ -112,7 +107,7 @@ The remaining survivors are dominated by:
 
 * **Equivalent mutants** in `akerr_init`: deleting the `memset`/`NULL` setup of
   file-scope statics (`AKERR_ARRAY_ERROR`, `__akerr_last_ditch`,
-  `akerr_last_ignored`) changes nothing, because C already zero-initializes
+  `__akerr_last_ignored`) changes nothing, because C already zero-initializes
   objects with static storage duration. `int oldid = 0;` → `1` is likewise
   dead: it is overwritten before use, and so is clearing `akerr_initializing`
   at the end of initialization — nothing reads that flag once the once-routine

tests/err_errno.c

@@ -26,13 +26,7 @@ int main(void)
     char *nm = akerr_name_for_status(EACCES, NULL);
     AKERR_CHECK(nm != NULL);
     AKERR_CHECK(nm[0] != '\0');
-#if AKERR_USE_STDLIB
-    /* akerr_init_errno() -- the only thing that registers a name for a host
-     * errno -- is not called when AKERR_USE_STDLIB is OFF (see
-     * akerr_init_state() in src/error.c), so EACCES deliberately reads back
-     * as "Unknown Error" in that configuration. */
     AKERR_CHECK(strcmp(nm, "Unknown Error") != 0);
-#endif
 
     AKERR_CHECK(strcmp(akerr_name_for_status(1000000, NULL),
 		       "Unknown Error") == 0);

tests/err_ignore.c

@@ -1,8 +1,11 @@
 #include "akerror.h"
 #include "err_capture.h"
-#include <string.h>
 
-/* IGNORE snapshots and logs an error, releases its pool slot, then continues. */
+/*
+ * IGNORE deliberately swallows an error: it records the context in
+ * __akerr_last_ignored, logs it with an "IGNORED ERROR" marker, and lets
+ * execution continue.
+ */
 
 akerr_ErrorContext *boom(void)
 {
@@ -18,19 +21,11 @@ int main(void)
     PREPARE_ERROR(e);
     (void)e;
 
-    /* More failures than the pool has slots must remain safe: a leaking
-     * IGNORE used to exhaust the pool and terminate the process here. The
-     * copied snapshot must also survive the slot being reused on the next
-     * iteration. */
-    for ( int i = 0; i < AKERR_MAX_ARRAY_ERROR + 1; i++ ) {
     IGNORE(boom());
-	AKERR_CHECK(akerr_last_ignored.status == AKERR_VALUE);
-	AKERR_CHECK(strcmp(akerr_last_ignored.message,
-			  "this error is ignored on purpose") == 0);
-	AKERR_CHECK(akerr_slots_in_use() == 0);
-    }
     reached_after_ignore = 1;
 
+    AKERR_CHECK(__akerr_last_ignored != NULL);
+    AKERR_CHECK(__akerr_last_ignored->status == AKERR_VALUE);
     AKERR_CHECK(reached_after_ignore == 1);
     AKERR_CHECK_CONTAINS("IGNORED ERROR");
     AKERR_CHECK_CONTAINS("this error is ignored on purpose");

tests/err_init_reservation_fatal.c

@@ -1,20 +0,0 @@
-#include "akerror.h"
-
-#include <stdio.h>
-
-/*
- * This executable links to akerror_init_failure, a test-only library target
- * with no status-range slots. The first reservation in akerr_init() must be
- * terminal: continuing would leave every library status unowned and make all
- * subsequent name registrations invalid.
- *
- * CTest marks this WILL_FAIL. Reaching the message and returning zero means
- * initialization swallowed its own reservation failure.
- */
-int main(void)
-{
-    akerr_init();
-
-    fprintf(stderr, "err_init_reservation_fatal: akerr_init did not terminate\n");
-    return 0;
-}

tests/err_release_clears.c

@@ -1,32 +1,24 @@
 #include "akerror.h"
 #include "err_capture.h"
+#include <string.h>
 
 /*
- * Releasing an error context back to the pool must reset the state that affects
- * the next caller. In particular, a handled error must not make a fresh error
- * look handled when its slot is recycled.
+ * Releasing an error context back to the pool must wipe it, so the next caller
+ * that checks it out never sees stale status/message/stacktrace from a previous
+ * error. Mutation testing showed the clearing memset in akerr_release_error
+ * could be deleted without any test noticing.
  */
 
-static int unhandled_calls = 0;
-static int unhandled_status = 0;
-
-static void test_unhandled_handler(akerr_ErrorContext *errctx)
-{
-    unhandled_calls++;
-    unhandled_status = (errctx != NULL) ? errctx->status : 0;
-}
-
 akerr_ErrorContext *boom(void)
 {
     PREPARE_ERROR(e);
-    FAIL_RETURN(e, AKERR_VALUE, "first error is handled");
+    FAIL_RETURN(e, AKERR_VALUE, "stale dirty message that must not survive");
 }
 
 int main(void)
 {
     akerr_capture_install();
     akerr_init();
-    akerr_handler_unhandled_error = &test_unhandled_handler;
 
     /* Raise and fully handle an error; FINISH_NORETURN releases it to the pool. */
     PREPARE_ERROR(e);
@@ -40,31 +32,13 @@ int main(void)
 
     AKERR_CHECK(e == NULL);
 
-    /* A fresh error in the recycled slot must not inherit handled=true. */
-    PREPARE_ERROR(fresh);
-    ATTEMPT {
-	CATCH(fresh, boom());
-    } CLEANUP {
-    } PROCESS(fresh) {
-    } FINISH_NORETURN(fresh);
-
-    AKERR_CHECK(unhandled_calls == 1);
-    AKERR_CHECK(unhandled_status == AKERR_VALUE);
-    AKERR_CHECK(fresh == NULL);
-
-    /* The next context handed out is the same slot, with recycle state reset. */
+    /* The next context handed out is the slot we just released: it must be clean. */
     akerr_ErrorContext *slot = akerr_next_error();
     AKERR_CHECK(slot != NULL);
-    AKERR_CHECK(slot->handled == false);
     AKERR_CHECK(slot->status == 0);
-    AKERR_CHECK(slot->reported == false);
     AKERR_CHECK(slot->message[0] == '\0');
-    AKERR_CHECK(slot->fname[0] == '\0');
-    AKERR_CHECK(slot->function[0] == '\0');
     AKERR_CHECK(slot->stacktracebuf[0] == '\0');
-    AKERR_CHECK(slot->stacktracebufptr == (char *)&slot->stacktracebuf);
-    RELEASE_ERROR(slot);
-    AKERR_CHECK(akerr_slots_in_use() == 0);
+    AKERR_CHECK(strstr(slot->message, "stale dirty message") == NULL);
 
     fprintf(stderr, "err_release_clears ok\n");
     return 0;

tests/err_threads_pool.c

@@ -100,21 +100,17 @@ static void *pool_body(void *raw)
 	one_checkout(arg);
     }
 
-    /* IGNORE's snapshot is thread-local while logging and remains valid after
-     * release. Concurrent ignored errors must all return their pool slots. */
+    /* An ignored error is a fact about the thread that ignored it: each thread
+     * must see its own, not the last one any thread swallowed. */
     IGNORE(ignorable(arg));
-    AKERR_TCHECK(arg, akerr_last_ignored.status == AKERR_IO);
-    AKERR_TCHECK(arg, strcmp(akerr_last_ignored.message, expected) == 0);
-
-    /* Reuse a slot after IGNORE and prove that the copied snapshot did not
-     * become an alias for the newly acquired context. */
-    akerr_ErrorContext *reused = akerr_next_error();
-    AKERR_TCHECK(arg, reused != NULL);
-    if ( reused != NULL ) {
-	RELEASE_ERROR(reused);
+    AKERR_TCHECK(arg, __akerr_last_ignored != NULL);
+    if ( __akerr_last_ignored != NULL ) {
+	AKERR_TCHECK(arg, __akerr_last_ignored->status == AKERR_IO);
+	AKERR_TCHECK(arg, strcmp(__akerr_last_ignored->message, expected) == 0);
     }
-    AKERR_TCHECK(arg, akerr_last_ignored.status == AKERR_IO);
-    AKERR_TCHECK(arg, strcmp(akerr_last_ignored.message, expected) == 0);
+    /* IGNORE keeps the reference by design; hand it back so the pool is empty
+     * at the end of the test. */
+    RELEASE_ERROR(__akerr_last_ignored);
 
     return NULL;
 }

tests/freestanding_fixture.c

@@ -1,14 +0,0 @@
-/*
- * Compile-only proof that a genuinely freestanding consumer (-nostdinc
- * -ffreestanding, no libc) can include the generated header under
- * AKERR_USE_STDLIB=OFF. Never linked or run -- see .gitea/workflows/ci.yaml.
- */
-#define AKERR_USE_STDLIB 0
-#define AKERR_RUNTIME_HEADER "freestanding_fixture_runtime.h"
-#include "akerror.h"
-
-akerr_ErrorContext *akerr_freestanding_fixture_example(void)
-{
-    PREPARE_ERROR(e);
-    FAIL_RETURN(e, AKERR_VALUE, "freestanding fixture example error");
-}

tests/freestanding_fixture_runtime.h

@@ -1,19 +0,0 @@
-#ifndef AKERR_FIXTURE_RUNTIME_H_
-#define AKERR_FIXTURE_RUNTIME_H_
-
-/*
- * A minimal AKERR_RUNTIME_HEADER for tests/freestanding_fixture.c: just
- * enough declarations (no definitions -- this fixture is compiled, never
- * linked) to prove that -DAKERR_USE_STDLIB=OFF's public header needs nothing
- * from a hosted environment beyond these six symbols and the freestanding-safe
- * <stddef.h>/<stdbool.h>. size_t comes from <stddef.h>, already included by
- * akerror.h before this header is pulled in.
- */
-void exit(int status);
-void *memset(void *s, int c, size_t n);
-int snprintf(char *str, size_t size, const char *format, ...);
-int strcmp(const char *a, const char *b);
-size_t strlen(const char *s);
-char *strncpy(char *dest, const char *src, size_t n);
-
-#endif /* AKERR_FIXTURE_RUNTIME_H_ */