aboutsummaryrefslogtreecommitdiffstats
path: root/liberror.h
diff options
context:
space:
mode:
authorMattias Andrée <maandree@kth.se>2019-04-12 21:12:12 +0200
committerMattias Andrée <maandree@kth.se>2019-04-12 21:13:19 +0200
commit1484b1264552ad05d75a4ca4f40972ac94e729e9 (patch)
treeb9f6d6212866699db66e8bd64310d445498db2f3 /liberror.h
downloadliberror-1484b1264552ad05d75a4ca4f40972ac94e729e9.tar.gz
liberror-1484b1264552ad05d75a4ca4f40972ac94e729e9.tar.bz2
liberror-1484b1264552ad05d75a4ca4f40972ac94e729e9.tar.xz
First commit
Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat (limited to 'liberror.h')
-rw-r--r--liberror.h179
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