Improvements to libtest

Signed-off-by: Mattias Andrée <m@maandree.se>

1 files changed, 384 insertions, 3 deletions

diff --git a/libtest/libtest.h b/libtest/libtest.h
index 3a3d963..b6484b2 100644
--- a/libtest/libtest.h
+++ b/libtest/libtest.h
@@ -1,23 +1,404 @@
 /* See LICENSE file for copyright and license details. */
+#include <stddef.h>
+#include <signal.h>
 
+
+/**
+ * Start tracking resources which `libtest_check_no_leaks`
+ * will detect if they are not released
+ */
 void libtest_start_tracking(void);
+
+/**
+ * Stop tracking resources, so that `libtest_check_no_leaks`
+ * will not detect if they are not released
+ */
 void libtest_stop_tracking(void);
+
+/**
+ * Check for resource leaks
+ * 
+ * Any leak will be printed to standard error
+ * 
+ * @return  1 if there was no leaks, 0 otherwise
+ */
 int libtest_check_no_leaks(void);
-void libtest_force_zero_on_alloc(int);
-void libtest_expect_zeroed_on_free(int);
 
+
+/**
+ * Make all overriden memory allocation functions
+ * full the usable memory area with null bytes,
+ * or disable this feature
+ * 
+ * @param  enabled  1 to enable, 0 to disable
+ */
+void libtest_force_zero_on_alloc(int enabled);
+
+/**
+ * Make all overriden memory deallocation functions
+ * check that the entire usable memory area is filled
+ * with null bytes, or disable this feature
+ * 
+ * @param  enabled  1 to enable, 0 to disable
+ */
+void libtest_expect_zeroed_on_free(int enabled);
+
+
+/**
+ * Test whether malloc(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_malloc(void);
+
+/**
+ * Test whether calloc(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_calloc(void);
+
+/**
+ * Test whether realloc(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_realloc(void);
+
+/**
+ * Test whether reallocarray(3) has been overridden,
+ * allowing allocations to be tracked, and memory
+ * allocation failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_reallocarray(void);
+
+/**
+ * Test whether valloc(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_valloc(void);
+
+/**
+ * Test whether pvalloc(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_pvalloc(void);
+
+/**
+ * Test whether memalign(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_memalign(void);
+
+/**
+ * Test whether aligned_alloc(3) has been overridden,
+ * allowing allocations to be tracked, and memory
+ * allocation failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_aligned_alloc(void);
+
+/**
+ * Test whether posix_memalign(3) has been overridden,
+ * allowing allocations to be tracked, and memory
+ * allocation failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_posix_memalign(void);
+
+/**
+ * Test whether strdup(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
+int libtest_have_custom_strdup(void);
+
+/**
+ * Test whether strndup(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
+int libtest_have_custom_strndup(void);
+
+/**
+ * Test whether wcsdup(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
+int libtest_have_custom_wcsdup(void);
+
+/**
+ * Test whether wcsndup(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
+int libtest_have_custom_wcsndup(void);
+
+/**
+ * Test whether memdup(3) has been overridden, allowing
+ * allocations to be tracked, and memory allocation
+ * failures to be injected
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * functions from being overridden as they may override
+ * such functions themselves in order to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
+int libtest_have_custom_memdup(void);
+
+/**
+ * Test whether malloc_usable_size(3) has been overridden,
+ * allowing it to be used for override implementations of
+ * memory allocation functions
+ * 
+ * Tools like valgrind(1) prevent resource allocation
+ * inspection functions from being overridden as they
+ * may override such functions themselves as they may
+ * override memory allocation functions to detect leaks
+ * and invalid memory access patterns
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_malloc_usable_size(void);
+
+/**
+ * Test whether free(3) has been overridden, allowing it
+ * to be used for override implementations of memory
+ * allocation functions
+ * 
+ * Tools like valgrind(1) prevent resource deallocation
+ * functions from being overridden as they may override
+ * such functions themselves as they may override memory
+ * allocation functions to detect leaks and invalid
+ * memory access patterns
+ * 
+ * You don't have to call this function yourself,
+ * overriden memory allocation function will call it
+ * and abort the process if this function return 0,
+ * likewise free(3) will abort the process if one of
+ * the memory allocation functions have not been
+ * overriden
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_free(void);
+
+/**
+ * Test whether free_sized(3) has been overridden,
+ * allowing it to be used for override implementations
+ * of memory allocation functions
+ * 
+ * Tools like valgrind(1) prevent resource deallocation
+ * functions from being overridden as they may override
+ * such functions themselves as they may override memory
+ * allocation functions to detect leaks and invalid
+ * memory access patterns
+ * 
+ * You don't have to call this function yourself,
+ * overriden memory allocation function will call it
+ * and abort the process if this function return 0,
+ * likewise free_sized(3) will abort the process if
+ * one of the memory allocation functions, whose
+ * alloactions it can deallocate, have not been
+ * overriden
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_free_sized(void);
+
+/**
+ * Test whether free_aligned_sized(3) has been overridden,
+ * allowing it to be used for override implementations
+ * of memory allocation functions
+ * 
+ * Tools like valgrind(1) prevent resource deallocation
+ * functions from being overridden as they may override
+ * such functions themselves as they may override memory
+ * allocation functions to detect leaks and invalid
+ * memory access patterns
+ * 
+ * You don't have to call this function yourself,
+ * overriden memory allocation function will call it
+ * and abort the process if this function return 0,
+ * likewise free_aligned_sized(3) will abort the process
+ * if one of the memory allocation functions, whose
+ * alloactions it can deallocate, have not been
+ * overriden
+ * 
+ * @return  1 if overridden, 0 otherwise
+ */
 int libtest_have_custom_free_aligned_sized(void);
 
-void libtest_dump_stack(const char *indent);
+
+/**
+ * Print a stack trace, to standard error, provided
+ * that backtrace support was enabled at compile-time
+ * 
+ * @param  prefix  The text to print at the beginning of the first line
+ * @param  indent  The text to print at the beginning of the other lines
+ * 
+ * If one if `prefix` or `indent` is `NULL`, the other
+ * will be used as both. Both may not be `NULL` at the
+ * same time.
+ */
+void libtest_dump_stack(const char *prefix, const char *indent);
+
+/**
+ * Set up a signal handler to print a stack trace when
+ * a signal is received
+ * 
+ * This function has no affect if backtrace support
+ * was disbled at compile-time, and therefore `*old_out`
+ * is only set if backtrace support was enabled
+ * 
+ * @param  signo    The signal to catch
+ * @param  old_out  Output parameter for the older signal handler
+ */
+void libtest_stack_on_signal(int signo, struct sigaction *old_out);
+
+/**
+ * Undo `libtest_stack_on_signal`
+ * 
+ * This function has no affect if backtrace support
+ * was disbled at compile-time, making it safe,
+ * unlike sigaction(3), to use to to restore the
+ * old signal handler returned by `libtest_stack_on_signal`
+ * when backtrace support is disabled. Additionally,
+ * this function will deallocate the alternative stack
+ * set up by `libtest_stack_on_signal` once it has been
+ * called as many times as `libtest_stack_on_signal`.
+ * 
+ * @param  signo  The signal handler to stop catching
+ * @param  old    The old signal handler to restore
+ */
+void libtest_stop_stack_on_signal(int signo, const struct sigaction *old);
+
+
+/**
+ * Get the number of allocation attempts
+ * before the next allocation will fail
+ * (ENOMEM), including that attempt in
+ * the count
+ *
+ * @return  0 if no memory allocation failure is scheduled,
+ *          1 if the next memory allocation will fail,
+ *          2 if the attempt after that will fail,
+ *          and so on
+ */
+#if defined(__GNUC__)
+__attribute__((__pure__))
+#endif
+size_t libtest_get_alloc_failure_in(void);
+
+/**
+ * Get the number of allocation attempts
+ * before the next allocation will fail
+ * (ENOMEM), including that attempt in
+ * the count
+ *
+ * @param  n  0 if no memory allocation should fail,
+ *            1 if the next memory allocation shall fail,
+ *            2 if the attempt after that shall fail,
+ *            and so on
+ * 
+ * Once the scheduled memory allocation
+ * failure as occurred, the schedule is
+ * cleared and the next attempt will be
+ * successful (provided that there isn't
+ * a real failure)
+ */
+void libtest_set_alloc_failure_in(size_t n);