1 Commits

Author SHA1 Message Date
ffe1850dd8 Working on timestamps 2026-01-17 22:49:37 -05:00
7 changed files with 80 additions and 195 deletions

View File

@@ -1,23 +0,0 @@
name: libakerror CI Build
run-name: ${{ gitea.actor }} libakerror test
on: [push]
jobs:
cmake_build:
runs-on: ubuntu-latest
steps:
- run: echo "Triggered by ${{ gitea.event_name }} from ${{ gitea.repository }}@${{ gitea.ref }}. Building on ${{ runner.os }}."
- 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 and test
run: |
mkdir installdir
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=installdir
cmake --build build
cmake --install build
cmake --build build --target test
- run: echo "🍏 This job's status is ${{ job.status }}."

View File

@@ -3,42 +3,31 @@ project(akerror LANGUAGES C)
include(GNUInstallDirs)
include(CMakePackageConfigHelpers)
include(CTest)
set(AKERR_USE_STDLIB 1 CACHE BOOL "Use the C standard library")
set(akerror_install_cmakedir "${CMAKE_INSTALL_LIBDIR}/cmake/akerror")
set(SCRIPT ${CMAKE_CURRENT_SOURCE_DIR}/scripts/generrno.sh)
set(INFILE ${CMAKE_CURRENT_SOURCE_DIR}/include/akerror.tmpl.h)
set(GENERATED_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated)
set(GENERATED_ERRNO_C ${GENERATED_DIR}/src/errno.c)
set(GENERATED_AKERROR_H ${GENERATED_DIR}/include/akerror.h)
set(SCRIPT ${CMAKE_SOURCE_DIR}/scripts/generrno.sh)
set(INFILE ${CMAKE_SOURCE_DIR}/include/akerror.tmpl.h)
set(OUTFILES ${CMAKE_SOURCE_DIR}/src/errno.c ${CMAKE_SOURCE_DIR}/include/akerror.h)
add_custom_command(
OUTPUT ${GENERATED_ERRNO_C} ${GENERATED_AKERROR_H}
COMMAND ${CMAKE_COMMAND} -E make_directory ${GENERATED_DIR}
COMMAND /usr/bin/env bash
${SCRIPT}
${CMAKE_CURRENT_SOURCE_DIR}
${GENERATED_DIR}
OUTPUT ${OUTFILES}
COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}
COMMAND /usr/bin/env bash ${SCRIPT} ${CMAKE_SOURCE_DIR}
DEPENDS ${SCRIPT} ${INFILE}
VERBATIM
)
add_library(akerror SHARED
src/error.c
${GENERATED_ERRNO_C}
)
set_source_files_properties(src/errno.c PROPERTIES GENERATED TRUE)
target_include_directories(akerror PUBLIC
$<BUILD_INTERFACE:${GENERATED_DIR}/include>
$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
)
add_custom_target(generrno DEPENDS src/errno.c)
find_package(PkgConfig REQUIRED)
add_library(akerror::akerror ALIAS akerror)
add_library(akerror STATIC
src/error.c
src/errno.c
)
add_dependencies(akerror generrno)
target_compile_definitions(akerror
PUBLIC AKERR_USE_STDLIB=${AKERR_USE_STDLIB}
@@ -47,24 +36,24 @@ target_compile_definitions(akerror
add_executable(test_err_catch tests/err_catch.c)
add_executable(test_err_cleanup tests/err_cleanup.c)
add_executable(test_err_trace tests/err_trace.c)
add_executable(test_err_improper_closure tests/err_improper_closure.c)
add_executable(test_err_unhandled tests/err_unhandled.c)
add_test(NAME err_catch COMMAND test_err_catch)
add_test(NAME err_cleanup COMMAND test_err_cleanup)
add_test(NAME err_trace COMMAND test_err_trace)
add_test(NAME err_improper_closure COMMAND test_err_improper_closure)
add_test(NAME err_unhandled COMMAND test_err_unhandled)
set_tests_properties(
err_trace
err_improper_closure
PROPERTIES WILL_FAIL TRUE
# Specify include directories for the library's headers (if applicable)
target_include_directories(akerror PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/>
)
target_link_libraries(test_err_catch PRIVATE akerror)
target_link_libraries(test_err_cleanup PRIVATE akerror)
target_link_libraries(test_err_trace PRIVATE akerror)
target_link_libraries(test_err_improper_closure PRIVATE akerror)
target_link_libraries(test_err_unhandled PRIVATE akerror)
set(main_lib_dest "lib/my_library-${MY_LIBRARY_VERSION}")
install(TARGETS akerror EXPORT akerror DESTINATION "lib/")
install(TARGETS akerror
EXPORT akerrorTargets
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
@@ -73,10 +62,13 @@ install(TARGETS akerror
INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)
install(FILES ${GENERATED_AKERROR_H} DESTINATION "include/")
install(EXPORT akerror FILE akerrorTargets.cmake DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/akerror)
install(FILES "include/akerror.h" DESTINATION "include/")
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/akerror.pc DESTINATION "lib/pkgconfig/")
install(EXPORT akerrorTargets
install(EXPORT akerror
FILE akerrorTargets.cmake
NAMESPACE akerror::
DESTINATION ${akerror_install_cmakedir}

View File

@@ -2,8 +2,6 @@
This library provides a TRY/CATCH style exception handling mechanism for C.
![build badge](https://source.starfort.tech/andrew/libakerror/actions/workflows/ci.yaml/badge.svg?branch=main)
# Why?
There is nothing wrong with C as it is. This library does not claim to fix some problem with C.
@@ -139,14 +137,6 @@ pkg_check_modules(akerror REQUIRED akerror)
target_link_libraries(YOUR_TARGET PRIVATE akerror::akerror)
```
Using this project as a submodule with cmake:
```cmake
add_subdirectory(deps/libakerror EXCLUDE_FROM_ALL)
target_link_libraries(YOUR_PROJECT PRIVATE akerror::akerror)
```
## (Optional) Configuring the logging function
@@ -232,28 +222,6 @@ ATTEMPT {
When either of these two macros are used, the `ATTEMPT` block is immediately exited, and the `CLEANUP` block begins.
# Passing errors
Sometimes you can't actually do anything about the errors that come out of a given method, but you want that error to be propagated back up the call chain, and to be properly reported. If this is your goal, you can avoid using a `ATTEMPT ... FINISH` block, and simply use the `PASS` macro.
```
PREPARE_ERROR(e);
PASS(e, some_method_that_may_fail());
SUCCEED_RETURN(e);
```
This does the same thing as this, but with less code:
```
PREPARE_ERROR(e);
ATTEMPT {
CATCH(e, some_method_that_may_fail());
} CLEANUP {
} PROCESS(e) {
} FINISH(e, true);
SUCCEED_RETURN(e);
```
# Handling errors
Inside of the `PROCESS { ... }` block, you must handle any errors that occurred during the `ATTEMPT { ... }` block. You do this with `HANDLE`, `HANDLE_GROUP`, and `HANDLE_DEFAULT`.
@@ -342,24 +310,20 @@ FAIL_NONZERO_RETURN(errctx, strcmp("not", "equal"), AKERR_VALUE, "Strings are no
# Uncaught errors
## Misbehaving methods
Any function which returns `akerr_ErrorContext *` and completes successfully MUST call `SUCCEED_RETURN(errctx)`. Failure to do this may result in an invalid `akerr_ErrorContext *` being returned, which will cause an `AKERR_BEHAVIOR` error to be triggered from your code.
## Ensuring that all error codes are captured
Any function which returns `akerr_ErrorContext *` should also be marked with `AKERROR_NOIGNORE`.
Any function which returns `akerr_ErrorContext *` should also be marked with `ERROR_NOIGNORE`.
```c
akerr_ErrorContext AKERROR_NOIGNORE *f(...);
akerr_ErrorContext ERROR_NOIGNORE *f(...);
```
This will cause a compile-time error if the return value of such a function is not used. "Used" here means assigned to a variable - it does not necessarily mean that the value is checked. However assuming that such functions are called inside of `ATTEMPT { ... }` blocks, it is safe to assume that such returns will be caught with `CATCH(...)`; therefore this error is a generally effective safeguard against careless coding where errors are not checked.
Beware that `AKERROR_NOIGNORE` is not a failsafe - it implements the `warn_unused_result` mechanic. By design users may explicitly ignore an error code from a function marked with `warn_unused_result` by explicitly casting the return to `void`.
Beware that `ERROR_NOIGNORE` is not a failsafe - it implements the `warn_unused_result` mechanic. By design users may explicitly ignore an error code from a function marked with `warn_unused_result` by explicitly casting the return to `void`.
```c
#define AKERROR_NOIGNORE __attribute__((warn_unused_result))
#define ERROR_NOIGNORE __attribute__((warn_unused_result))
```
## Stack Traces

View File

@@ -6,41 +6,33 @@
#include <stdbool.h>
#include <string.h>
#include <stdio.h>
#include <limits.h>
#endif
// FIXME: This is huge now. It used to be 1000 bytes, then I wanted to report errors
// related to filesystem paths, which made it grow beyond PATH_MAX, then I started
// reporting messages including 2 file paths (PATH_MAX * 2), so now to make the compiler warnings
// shut up, it's enormous (PATH_MAX*3).
#define AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH 12384
#define AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH 1024
#define AKERR_MAX_ERROR_NAME_LENGTH 64
#define AKERR_MAX_ERROR_FNAME_LENGTH PATH_MAX
#define AKERR_MAX_ERROR_FNAME_LENGTH 256
#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)
#define AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH 2048
#define AKERR_LAST_ERRNO_VALUE AKERR_LAST_ERRNO_VALUE_SED
#define AKERR_NULLPOINTER (AKERR_LAST_ERRNO_VALUE + 1) /** A pointer had a NULL value where such was not permissible */
#define AKERR_OUTOFBOUNDS (AKERR_LAST_ERRNO_VALUE + 2) /** Attempt to access a datastructure outside of bounds */
#define AKERR_API (AKERR_LAST_ERRNO_VALUE + 3) /** An otherwise unspecified API contract has been violated */
#define AKERR_ATTRIBUTE (AKERR_LAST_ERRNO_VALUE + 4) /** Relates to accessing of attributes on objects */
#define AKERR_TYPE (AKERR_LAST_ERRNO_VALUE + 5) /** An object had the incorrect type */
#define AKERR_KEY (AKERR_LAST_ERRNO_VALUE + 6) /** A key was either invalid for or not present in a map */
#define AKERR_INDEX (AKERR_LAST_ERRNO_VALUE + 8) /** An error occurred when attempting to index an indexable datastructure (other than out of bounds) */
#define AKERR_FORMAT (AKERR_LAST_ERRNO_VALUE + 9) /** An error occurred in the formatting of an object (usually a string) */
#define AKERR_IO (AKERR_LAST_ERRNO_VALUE + 10) /** An unspecified IO error occurred. */
#define AKERR_VALUE (AKERR_LAST_ERRNO_VALUE + 11) /** A provided value was invalid */
#define AKERR_RELATIONSHIP (AKERR_LAST_ERRNO_VALUE + 12) /** An error occurred in establishing, maintaining or severing a relationship between two objects */
#define AKERR_EOF (AKERR_LAST_ERRNO_VALUE + 13) /** The end of a stream or file has been encountered */
#define AKERR_CIRCULAR_REFERENCE (AKERR_LAST_ERRNO_VALUE + 14) /** Indicates that a circular reference has been found in a linked list */
#define AKERR_ITERATOR_BREAK (AKERR_LAST_ERRNO_VALUE + 15) /** Used to prematurely end an iteration cycle (such as when searching a graph and the desired node has been found) */
#define AKERR_NOT_IMPLEMENTED (AKERR_LAST_ERRNO_VALUE + 16) /** A method was called that is defined but not currently implemented */
#define AKERR_BADEXC (AKERR_LAST_ERRNO_VALUE + 17) /** The libakerr library was given an akerr_ErrorContext to parse that did not come from AKERR_ARRAY_ERROR (likely an uninitialized pointer) */
#define AKERR_NULLPOINTER (AKERR_LAST_ERRNO_VALUE + 1)
#define AKERR_OUTOFBOUNDS (AKERR_LAST_ERRNO_VALUE + 2)
#define AKERR_API (AKERR_LAST_ERRNO_VALUE + 3)
#define AKERR_ATTRIBUTE (AKERR_LAST_ERRNO_VALUE + 4)
#define AKERR_TYPE (AKERR_LAST_ERRNO_VALUE + 5)
#define AKERR_KEY (AKERR_LAST_ERRNO_VALUE + 6)
#define AKERR_HEAP (AKERR_LAST_ERRNO_VALUE + 7)
#define AKERR_INDEX (AKERR_LAST_ERRNO_VALUE + 8)
#define AKERR_FORMAT (AKERR_LAST_ERRNO_VALUE + 9)
#define AKERR_IO (AKERR_LAST_ERRNO_VALUE + 10)
#define AKERR_REGISTRY (AKERR_LAST_ERRNO_VALUE + 11)
#define AKERR_VALUE (AKERR_LAST_ERRNO_VALUE + 12)
#define AKERR_BEHAVIOR (AKERR_LAST_ERRNO_VALUE + 13)
#define AKERR_RELATIONSHIP (AKERR_LAST_ERRNO_VALUE + 14)
#ifndef AKERR_MAX_ERR_VALUE
#define AKERR_MAX_ERR_VALUE (AKERR_LAST_ERRNO_VALUE + 15)
#define AKERR_MAX_ERR_VALUE (AKERR_LAST_ERRNO_VALUE + 14)
#elif AKERR_MAX_ERR_VALUE < 256
#error user-defined AKERR_MAX_ERR_VALUE must be >= 256
#endif
@@ -74,6 +66,8 @@ extern akerr_ErrorContext AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR];
extern akerr_ErrorUnhandledErrorHandler akerr_handler_unhandled_error;
extern akerr_ErrorLogFunction akerr_log_method;
extern akerr_ErrorContext *__akerr_last_ignored;
extern akerr_ErrorContext *__akerr_last_prepared;
extern int __akerr_last_attempt_id;
akerr_ErrorContext AKERR_NOIGNORE *akerr_release_error(akerr_ErrorContext *ptr);
akerr_ErrorContext AKERR_NOIGNORE *akerr_next_error();
@@ -81,7 +75,6 @@ char *akerr_name_for_status(int status, char *name);
void akerr_init();
void akerr_default_handler_unhandled_error(akerr_ErrorContext *ptr);
void akerr_default_logger(const char *f, ...);
int akerr_valid_error_address(akerr_ErrorContext *ptr);
/* defined in src/errno.c which is built dynamically at build time from system errno definitions */
void akerr_init_errno(void);
@@ -184,16 +177,10 @@ void akerr_init_errno(void);
switch ( 0 ) { \
case 0: \
#define VALID(__err_context, __stmt) \
__stmt; \
if ( akerr_valid_error_address(__err_context) == 0 ) { \
__err_context = NULL; \
FAIL(__err_context, AKERR_BADEXC, "Received (akerr_ErrorContext *) from an invalid memory region. (Did the method finish without calling SUCCEED_RETURN?)"); \
}
#define DETECT(__err_context, __stmt) \
VALID(__err_context, __stmt); \
__stmt; \
if ( __err_context != NULL ) { \
__err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d: Detected error %d from array (refcount %d)\n", (char *)__FILE__, (char *)__func__, __LINE__, __err_context->arrayid, __err_context->refcount); \
if ( __err_context->status != 0 ) { \
__err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d\n", (char *)__FILE__, (char *)__func__, __LINE__); \
break; \
@@ -203,13 +190,6 @@ void akerr_init_errno(void);
#define CATCH(__err_context, __stmt) \
DETECT(__err_context, __err_context = __stmt);
#define PASS(__err_context, __stmt) \
switch ( 0 ) { \
case 0: \
DETECT(__err_context, __err_context = __stmt); \
} \
FINISH_LOGIC(__err_context, true);
#define IGNORE(__stmt) \
__akerr_last_ignored = __stmt; \
if ( __akerr_last_ignored != NULL ) { \
@@ -242,17 +222,18 @@ void akerr_init_errno(void);
__err_context->stacktracebufptr = (char *)&__err_context->stacktracebuf; \
__err_context->handled = true;
#define FINISH_LOGIC(__err_context, __pass_up) \
if ( __err_context != NULL ) { \
if ( __err_context->handled == false && __pass_up == true ) { \
return __err_context; \
} \
} \
#define FINISH(__err_context, __pass_up) \
}; \
}; \
FINISH_LOGIC(__err_context, __pass_up) \
if ( __err_context != NULL ) { \
__err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d\n", (char *)__FILE__, (char *)__func__, __LINE__); \
if ( __err_context->handled == false && __pass_up == true && __err_context->arrayid > 0 ) { \
return __err_context; \
} else if ( __err_context->handled == false ) { \
LOG_ERROR_WITH_MESSAGE(__err_context, "Unhandled Error"); \
akerr_handler_unhandled_error(__err_context); \
} \
} \
RELEASE_ERROR(__err_context);
#define FINISH_NORETURN(__err_context) \
@@ -266,4 +247,12 @@ void akerr_init_errno(void);
} \
RELEASE_ERROR(__err_context);
#define CATCH_AND_RETURN(__err_context, __stmt) \
ATTEMPT { \
CATCH(__err_context, __stmt); \
} CLEANUP { \
} PROCESS(__err_context) { \
} FINISH(__err_context, true);
#endif // _AKERR_H_

View File

@@ -1,20 +1,16 @@
#!/bin/bash
srcdir=$1
outdir=$2
mkdir -p ${outdir}/src
mkdir -p ${outdir}/include
rm -f ${outdir}/src/errno.c
echo "#include <akerror.h>" >> ${outdir}/src/errno.c
echo "#include <errno.h>" >> ${outdir}/src/errno.c
echo "void akerr_init_errno(void) {" >> ${outdir}/src/errno.c
rm -f ${srcdir}/src/errno.c
echo "#include <akerror.h>" >> ${srcdir}/src/errno.c
echo "#include <errno.h>" >> ${srcdir}/src/errno.c
echo "void akerr_init_errno(void) {" >> ${srcdir}/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_for_status(${define}, \"${desc}\");" >> ${outdir}/src/errno.c ;
echo " akerr_name_for_status(${define}, \"${desc}\");" >> ${srcdir}/src/errno.c ;
done;
echo "}" >> ${outdir}/src/errno.c
sed "s/#define AKERR_LAST_ERRNO_VALUE .*/#define AKERR_LAST_ERRNO_VALUE ${maxval}/" ${srcdir}/include/akerror.tmpl.h > ${outdir}/include/akerror.h
echo "}" >> ${srcdir}/src/errno.c
sed "s/#define AKERR_LAST_ERRNO_VALUE .*/#define AKERR_LAST_ERRNO_VALUE ${maxval}/" ${srcdir}/include/akerror.tmpl.h > ${srcdir}/include/akerror.h

View File

@@ -14,16 +14,6 @@ char __AKERR_ERROR_NAMES[AKERR_MAX_ERR_VALUE+1][AKERR_MAX_ERROR_NAME_LENGTH];
akerr_ErrorContext AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR];
int akerr_valid_error_address(akerr_ErrorContext *ptr)
{
// Is this within the memory region occupied by AKERR_ARRAY_ERROR?
if ( ptr == NULL ) {
return 1;
}
return ((ptr >= &AKERR_ARRAY_ERROR[0]) &&
(ptr <= &AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR-1]));
}
void akerr_default_logger(const char *fmt, ...)
{
#if defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1
@@ -61,16 +51,15 @@ void akerr_init()
akerr_name_for_status(AKERR_ATTRIBUTE, "Attribute Error");
akerr_name_for_status(AKERR_TYPE, "Type Error");
akerr_name_for_status(AKERR_KEY, "Key Error");
akerr_name_for_status(AKERR_HEAP, "Heap Error");
akerr_name_for_status(AKERR_INDEX, "Index Error");
akerr_name_for_status(AKERR_FORMAT, "Format Error");
akerr_name_for_status(AKERR_IO, "Input Output Error");
akerr_name_for_status(AKERR_REGISTRY, "Registry Error");
akerr_name_for_status(AKERR_VALUE, "Value Error");
akerr_name_for_status(AKERR_BEHAVIOR, "Behavior Error");
akerr_name_for_status(AKERR_RELATIONSHIP, "Relationship Error");
akerr_name_for_status(AKERR_CIRCULAR_REFERENCE, "Circular Reference Error");
akerr_name_for_status(AKERR_BADEXC, "Invalid akerr_ErrorContext");
#if (defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1) || (!defined(AKERR_USE_STDLIB))
akerr_init_errno();
#endif
inited = 1;
}
}

View File

@@ -1,22 +0,0 @@
#include "akerror.h"
#include <stdio.h>
akerr_ErrorContext AKERR_NOIGNORE *improper_closure(void)
{
PREPARE_ERROR(errctx);
ATTEMPT {
} CLEANUP {
} PROCESS(errctx) {
} FINISH(errctx, true);
fprintf(stderr, "Improperly returning from improper_closure\n");
}
int main(void)
{
PREPARE_ERROR(errctx);
ATTEMPT {
CATCH(errctx, improper_closure());
} CLEANUP {
} PROCESS(errctx) {
} FINISH_NORETURN(errctx);
}