Update docs, replace the missing VALID() macro to safeguard against misbehaving functions, add PASS, remove CATCH_AND_RETURN

CMakeLists.txt

@@ -7,27 +7,37 @@ include(CMakePackageConfigHelpers)
 set(AKERR_USE_STDLIB 1 CACHE BOOL "Use the C standard library")
 set(akerror_install_cmakedir "${CMAKE_INSTALL_LIBDIR}/cmake/akerror")
 
-set(SCRIPT ${CMAKE_SOURCE_DIR}/scripts/generrno.sh)
+set(SCRIPT ${CMAKE_CURRENT_SOURCE_DIR}/scripts/generrno.sh)
-set(INFILE ${CMAKE_SOURCE_DIR}/include/akerror.tmpl.h)
+set(INFILE ${CMAKE_CURRENT_SOURCE_DIR}/include/akerror.tmpl.h)
-set(OUTFILES ${CMAKE_SOURCE_DIR}/src/errno.c ${CMAKE_SOURCE_DIR}/include/akerror.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)
+
 add_custom_command(
-  OUTPUT ${OUTFILES}
+  OUTPUT ${GENERATED_ERRNO_C} ${GENERATED_AKERROR_H}
-  COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}
+  COMMAND ${CMAKE_COMMAND} -E make_directory ${GENERATED_DIR}
-  COMMAND /usr/bin/env bash ${SCRIPT} ${CMAKE_SOURCE_DIR}
+  COMMAND /usr/bin/env bash
+          ${SCRIPT}
+          ${CMAKE_CURRENT_SOURCE_DIR}
+          ${GENERATED_DIR}
   DEPENDS ${SCRIPT} ${INFILE}
   VERBATIM
 )
 
-set_source_files_properties(src/errno.c PROPERTIES GENERATED TRUE)
+add_library(akerror SHARED
+  src/error.c
+  ${GENERATED_ERRNO_C}
+)
 
-add_custom_target(generrno DEPENDS src/errno.c)
+target_include_directories(akerror PUBLIC
+  $<BUILD_INTERFACE:${GENERATED_DIR}>/include
+  $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+)
 
 find_package(PkgConfig REQUIRED)
-add_library(akerror STATIC
+add_library(akerror::akerror ALIAS akerror)
-  src/error.c
-  src/errno.c
-)
-add_dependencies(akerror generrno)
 
 target_compile_definitions(akerror
     PUBLIC AKERR_USE_STDLIB=${AKERR_USE_STDLIB}
@@ -36,24 +46,18 @@ 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_unhandled tests/err_unhandled.c)
+add_executable(test_err_improper_closure tests/err_improper_closure.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_unhandled COMMAND test_err_unhandled)
+add_test(NAME err_improper_closure COMMAND test_err_improper_closure)
 
-# 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_unhandled PRIVATE akerror)
+target_link_libraries(test_err_improper_closure 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}
@@ -62,13 +66,10 @@ install(TARGETS akerror
   INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
 
-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}

README.md

@@ -137,6 +137,14 @@ 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
 
@@ -222,6 +230,28 @@ 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`.
@@ -310,20 +340,24 @@ 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 `ERROR_NOIGNORE`.
+Any function which returns `akerr_ErrorContext *` should also be marked with `AKERROR_NOIGNORE`.
 
 ```c
-akerr_ErrorContext ERROR_NOIGNORE *f(...);
+akerr_ErrorContext AKERROR_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 `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`.
+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`.
 
 ```c
-#define ERROR_NOIGNORE __attribute__((warn_unused_result))
+#define AKERROR_NOIGNORE __attribute__((warn_unused_result))
 ```
 
 ## Stack Traces

include/akerror.tmpl.h

@@ -30,9 +30,10 @@
 #define AKERR_VALUE                 (AKERR_LAST_ERRNO_VALUE + 12)
 #define AKERR_BEHAVIOR              (AKERR_LAST_ERRNO_VALUE + 13)
 #define AKERR_RELATIONSHIP          (AKERR_LAST_ERRNO_VALUE + 14)
+#define AKERR_EOF                   (AKERR_LAST_ERRNO_VALUE + 15)
 
 #ifndef AKERR_MAX_ERR_VALUE
-#define AKERR_MAX_ERR_VALUE (AKERR_LAST_ERRNO_VALUE + 14)
+#define AKERR_MAX_ERR_VALUE (AKERR_LAST_ERRNO_VALUE + 15)
 #elif AKERR_MAX_ERR_VALUE < 256
 #error user-defined AKERR_MAX_ERR_VALUE must be >= 256
 #endif
@@ -55,7 +56,6 @@ typedef struct
     bool reported;
     char stacktracebuf[AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH];
     char *stacktracebufptr;
-    int stacktracebufremaining;
 } akerr_ErrorContext;
 
 #define AKERR_NOIGNORE __attribute__((warn_unused_result))
@@ -68,7 +68,6 @@ extern akerr_ErrorUnhandledErrorHandler akerr_handler_unhandled_error;
 extern akerr_ErrorLogFunction akerr_log_method;
 extern akerr_ErrorContext *__akerr_last_ignored;
 
-akerr_ErrorContext AKERR_NOIGNORE *akerr_user_main(int argc, char **argv);
 akerr_ErrorContext AKERR_NOIGNORE *akerr_release_error(akerr_ErrorContext *ptr);
 akerr_ErrorContext AKERR_NOIGNORE *akerr_next_error();
 char *akerr_name_for_status(int status, char *name);
@@ -177,8 +176,14 @@ void akerr_init_errno(void);
     switch ( 0 ) {				\
     case 0:					\
 
-#define DETECT(__err_context, __stmt)					\
+#define VALID(__err_context, __stmt)                       \
     __stmt;                                                \
+    if ( akerr_valid_error_address(__err_context) == 0 ) { \
+	FAIL(__err_context, AKERR_BEHAVIOR, "Received (akerr_Error *) from an invalid memory region. (Did the method finish without calling SUCCEED_RETURN?)"); \
+    }
+
+#define DETECT(__err_context, __stmt)					\
+    VALID(__err_context, __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 ) {				\
@@ -190,6 +195,13 @@ 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 ) {				\
@@ -222,15 +234,18 @@ void akerr_init_errno(void);
     __err_context->stacktracebufptr = (char *)&__err_context->stacktracebuf; \
     __err_context->handled = true;
 
-#define FINISH(__err_context, __pass_up)				\
+#define FINISH_LOGIC(__err_context, __pass_up)                          \
-    };									\
-    };									\
     if ( __err_context != NULL ) {					\
 	if ( __err_context->handled == false && __pass_up == true ) {	\
 	    __err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d\n", (char *)__FILE__, (char *)__func__, __LINE__); \
 	    return __err_context;					\
 	}								\
     }									\
+
+#define FINISH(__err_context, __pass_up)				\
+    };									\
+    };									\
+    FINISH_LOGIC(__err_context, __pass_up)                              \
     RELEASE_ERROR(__err_context);
 
 #define FINISH_NORETURN(__err_context)					\
@@ -244,12 +259,4 @@ 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_

scripts/generrno.sh

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

src/error.c

@@ -14,26 +14,10 @@ char __AKERR_ERROR_NAMES[AKERR_MAX_ERR_VALUE+1][AKERR_MAX_ERROR_NAME_LENGTH];
 
 akerr_ErrorContext AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR];
 
-int main(int argc, char **argv)
+int akerr_valid_error_address(akerr_ErrorContext *ptr)
 {
-    int i = 0;
+    // Is this within the memory region occupied by AKERR_ARRAY_ERROR?
-    PREPARE_ERROR(e);
+    return ((ptr >= &AKERR_ARRAY_ERROR[0]) && (ptr <= &AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR-1]));
-    ATTEMPT {
-	CATCH(e, akerr_user_main(argc, argv));
-	if ( e == NULL || e->status == 0 ) {
-	    /* User code claims everything went fine, doublecheck the error array before we quit */
-	    for ( i = AKERR_MAX_ARRAY_ERROR - 1; i >= 0; i-- ) {
-		if ( AKERR_ARRAY_ERROR[i].status != 0 && AKERR_ARRAY_ERROR[i].refcount != 0 ) {
-		    akerr_log_method("%s:%s:%d: Found unhandled and unreported error in the array at index %d\n", __FILE__, (char *)__func__, __LINE__, i);
-		    e = &AKERR_ARRAY_ERROR[i];
-		}
-	    }
-	}
-    } CLEANUP {
-    } PROCESS(e) {
-    } FINISH_NORETURN(e);
-    SUCCEED(e);
-    return 0;
 }
 
 void akerr_default_logger(const char *fmt, ...)
@@ -81,7 +65,9 @@ void akerr_init()
 	akerr_name_for_status(AKERR_VALUE, "Value Error");
 	akerr_name_for_status(AKERR_BEHAVIOR, "Behavior Error");
 	akerr_name_for_status(AKERR_RELATIONSHIP, "Relationship Error");
-	
+#if (defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1) || (!defined(AKERR_USE_STDLIB))
+	akerr_init_errno();
+#endif
 	inited = 1;
     }
 }

tests/err_catch.c

@@ -23,7 +23,7 @@ akerr_ErrorContext *func1(void)
 }
 
 
-akerr_ErrorContext *akerr_user_main(int argc, char **argv)
+int main(void)
 {
     PREPARE_ERROR(errctx);
     ATTEMPT {
@@ -32,6 +32,5 @@ akerr_ErrorContext *akerr_user_main(int argc, char **argv)
     } PROCESS(errctx) {
     } HANDLE(errctx, AKERR_NULLPOINTER) {
       akerr_log_method("Caught exception");
-    } FINISH(errctx, true);
+    } FINISH_NORETURN(errctx);
-    SUCCEED(errctx);
 }

tests/err_cleanup.c

@@ -25,7 +25,7 @@ akerr_ErrorContext *func1(void)
     SUCCEED_RETURN(errctx);
 }
 
-akerr_ErrorContext *akerr_user_main(int argc, char **argv)
+int main(void)
 {
     x = 12345;
     PREPARE_ERROR(errctx);
@@ -35,8 +35,9 @@ akerr_ErrorContext *akerr_user_main(int argc, char **argv)
     } PROCESS(errctx) {
     } HANDLE(errctx, AKERR_NULLPOINTER) {
 	if ( x == 0 ) {
-	    FAIL_RETURN(errctx, AKERR_API, "Cleanup does not work");	    
+	    fprintf(stderr, "Cleanup works\n");
+	    return 0;
 	}
-    } FINISH(errctx, true);
+	return 1;
-    SUCCEED(errctx);
+    } FINISH_NORETURN(errctx);
 }

tests/err_improper_closure.c

@@ -0,0 +1,22 @@
+#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);
+}

tests/err_trace.c

@@ -23,13 +23,12 @@ akerr_ErrorContext *func1(void)
 }
 
 
-akerr_ErrorContext *akerr_user_main(int argc, char **argv)
+int main(void)
 {
     PREPARE_ERROR(errctx);
     ATTEMPT {
 	CATCH(errctx, func1());
     } CLEANUP {
     } PROCESS(errctx) {
-    } FINISH(errctx, true);
+    } FINISH_NORETURN(errctx);
-    SUCCEED(errctx);
 }