First commit

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

1 files changed, 179 insertions, 0 deletions

diff --git a/liberror.h b/liberror.h
new file mode 100644
index 0000000..27c700d
--- /dev/null
+++ b/liberror.h
@@ -0,0 +1,179 @@
+/* See LICENSE file for copyright and license details. */
+#ifndef LIBERROR_H
+#define LIBERROR_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+
+
+/**
+ * Opaque backtrace structure
+ */
+struct liberror_backtrace;
+
+/**
+ * Error structure
+ */
+struct liberror_error {
+	/**
+	 * Backtrace for the error, `NULL` if the it could
+	 * not be allocated or if the program is not linked
+	 * with `-lerror-backtrace`
+	 */
+	struct liberror_backtrace *backtrace;
+
+	/**
+	 * Description of the error
+	 */
+	char description[256];
+
+	/**
+	 * The function that failed
+	 */
+	char source[64];
+
+	/**
+	 * Name of error code group, for normal `errno`
+	 * errors this is "error", for getaddrinfo(3) errors
+	 * this is "addrinfo", for custom errors it is the
+	 * name of the library or application
+	 */
+	char code_group[64];
+
+	/**
+	 * The error code
+	 */
+	long long int code;
+
+	/**
+	 * The error that caused this error, `NULL` if
+	 * none or it could not be allocated (if and only
+	 * if so, `.failed_to_allocate_cause` will be set
+	 * to a non-zero value, specifically 1)
+	 */
+	struct liberror_error *cause;
+
+	/**
+	 * Whether allocation of `.cause` failed
+	 */
+	int failed_to_allocate_cause;
+
+	/**
+	 * Whether the error is physically allocated
+	 */
+	int dynamically_allocated;
+};
+
+
+/**
+ * Get the current error for the thread
+ * 
+ * @return  The current error, `NULL` if none
+ */
+struct liberror_error *liberror_get_error(void);
+
+/**
+ * Create a copy of an error
+ * 
+ * This function will only fail of enough memory
+ * cannot be allocated, however `errno` will not
+ * be changed
+ * 
+ * @param   error  The error to copy
+ * @return         Copy of the error, `NULL` on failure
+ */
+struct liberror_error *liberror_copy_error(struct liberror_error *);
+
+/**
+ * Deallocate and error and the error stored as
+ * its cause (recursively)
+ * 
+ * @param  error  The error to deallocate
+ */
+void liberror_free_error(struct liberror_error *);
+
+/**
+ * Deallocate the current error for the thread
+ * and reset the error for the thread
+ * 
+ * This function shall be called after handling
+ * the error
+ */
+void liberror_reset_error(void);
+
+/**
+ * Print the backtrace of an error
+ * 
+ * If the backtrace could not be allocated,
+ * nothing will be printed
+ * 
+ * This function will never change `errno`
+ * 
+ * Note: this library does not actually save
+ * a backtrace, `-lerror-backtrace` is needed
+ * for that functionallity (it will replace
+ * some things in this library, so no other
+ * action is required)
+ * 
+ * @param  error   The error
+ * @param  fp      The file to print the backtrace to
+ * @param  indent  Text to print at the beginning of each line
+ */
+void liberror_print_backtrace(struct liberror_error *, FILE *, const char *);
+
+/**
+ * Set the current error for the thread
+ * 
+ * If the thread already has an error saved,
+ * it will be stored as the cause of the new
+ * error
+ * 
+ * @param  description  Description of the error, empty for default description
+ * @param  source       The function that failed
+ * @param  code_group   Name of error code group, for normal `errno` errors
+ *                      this shall be "error", for getaddrinfo(3) errors
+ *                      this shall be "addrinfo", for custom errors it shall
+ *                      be the name of the library or application
+ * @param  code         The error code
+ */
+void liberror_set_error(const char[256], const char[64], const char[64], long long int);
+
+/**
+ * Set the current error for the thread
+ * 
+ * This function can be used as an alternative
+ * to `liberror_set_error` for `errno` errors
+ * 
+ * If the thread already has an error saved,
+ * it will be stored as the cause of the new
+ * error
+ * 
+ * @param  description  Description of the error, empty for default description
+ * @param  source       The function that failed
+ * @param  code         The `errno` value
+ */
+void liberror_set_error_errno(const char[256], const char[64], int);
+
+/**
+ * The an error, its backtrace, and its
+ * cause (recursively)
+ * 
+ * If `error` is `NULL` and the thread does
+ * not have any error set, this function
+ * will not do anything
+ * 
+ * @param  error   The error, the thread's current error if `NULL`
+ * @param  fp      Output stream, standard error if `NULL`
+ * @param  reset   Whether `error` shall be deallocated, `error`
+ *                 is null and `reset` is non-zero, the thread's
+ *                 error will be reset
+ * @param  prefix  Prefix for each printed line, ": " will be
+ *                 appended to this prefix; if `NULL` or empty,
+ *                 no prefix is used; this should normally be
+ *                 `argv[0]` from the main() function
+ */
+void liberror_print_error(struct liberror_error *, FILE *, int, const char *);
+
+
+#endif