Add liberror_start and liberror_end

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

17 files changed, 228 insertions, 12 deletions

diff --git a/Makefile b/Makefile
index 091428c..5634a9c 100644
--- a/Makefile
+++ b/Makefile
@@ -19,6 +19,7 @@ HDR =\
 
 OBJ =\
 	copy_error.o\
+	end.o\
 	free_error.o\
 	get_error.o\
 	internal.o\
@@ -27,10 +28,12 @@ OBJ =\
 	reset_error.o\
 	save_backtrace.o\
 	set_error.o\
-	set_error_errno.o
+	set_error_errno.o\
+	start.o
 
 MAN3 =\
 	liberror_copy_error.3\
+	liberror_end.3\
 	liberror_free_error.3\
 	liberror_get_error.3\
 	liberror_print_bactrace.3\
@@ -38,7 +41,8 @@ MAN3 =\
 	liberror_reset_error.3\
 	liberror_save_backtrace.3\
 	liberror_set_error.3\
-	liberror_set_error_errno.3
+	liberror_set_error_errno.3\
+	liberror_start.3
 
 MAN7 =\
 	liberror.7
diff --git a/README b/README
index e127c9c..3395d2f 100644
--- a/README
+++ b/README
@@ -31,3 +31,9 @@ The important functions are:
 		its backtrace if liberror-backtrace is also
 		linked, the errors cause, and optionally remove
 		the error for the calling thread.
+
+	liberror_start
+		Shall be called when entering a signal handler
+
+	liberror_end
+		Shall be called when a signal handler exits
diff --git a/end.c b/end.c
new file mode 100644
index 0000000..54995d0
--- /dev/null
+++ b/end.c
@@ -0,0 +1,12 @@
+/* See LICENSE file for copyright and license details. */
+#include "internal.h"
+
+
+void
+liberror_end(const struct liberror_state *state)
+{
+	liberror_saved_backtrace = state->backtrace;
+	liberror_have_error_ = state->have_error;
+	errno = state->errnum;
+	memcpy(&liberror_error_, &state->error, sizeof(liberror_error_));
+}
diff --git a/liberror.7 b/liberror.7
index cfa4cc3..c4c7589 100644
--- a/liberror.7
+++ b/liberror.7
@@ -55,6 +55,12 @@ backtrace if the
 .B liberror-backtrace
 library is also linked, the errors cause, and optionally
 remove the error for the calling thread.
+.TP
+.BR liberror_start (3)
+Shall be called when entering a signal handler.
+.TP
+.BR liberror_end (3)
+Shall be called when a signal handler exits.
 .SH ERRORS
 None.
 .SH EXAMPLES
@@ -70,6 +76,7 @@ None.
 .SH SEE ALSO
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_get_error (3),
 .BR liberror_print_bactrace (3),
@@ -77,4 +84,5 @@ None.
 .BR liberror_reset_error (3),
 .BR liberror_save_backtrace (3),
 .BR liberror_set_error (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror.h b/liberror.h
index 3cad426..6062889 100644
--- a/liberror.h
+++ b/liberror.h
@@ -218,6 +218,31 @@ struct liberror_error {
 	union liberror_details details;
 };
 
+/**
+ * Saved error state for a thread
+ */
+struct liberror_state {
+	/**
+	 * The backtrace for the next error
+	 */
+	struct liberror_backtrace *backtrace;
+
+	/**
+	 * The thread's error
+	 */
+	struct liberror_error error;
+
+	/**
+	 * Whether the thread hade an error
+	 */
+	int have_error;
+
+	/**
+	 * The thread's value of `errno`
+	 */
+	int errnum;
+};
+
 
 /**
  * Get the current error for the thread
@@ -346,5 +371,29 @@ void liberror_set_error_errno(const char[256], const char[64], int);
  */
 void liberror_print_error(struct liberror_error *, FILE *, int, const char *);
 
+/**
+ * Save the thread's liberror error, pending backtrace,
+ * and `errno`, and then reset the error information
+ * for the thread
+ * 
+ * Asynchronously called functions such as signal handlers
+ * should call this function the first thing they do
+ * 
+ * @param  state  Output parameter for the error state
+ */
+void liberror_start(struct liberror_state *);
+
+/**
+ * Restore the thread's liberror error, pending backtrace,
+ * and `errno`
+ * 
+ * Asynchronously called functions such as signal handlers
+ * should call this function the last thing they do before
+ * returning
+ * 
+ * @param  state  The saved error state to restore
+ */
+void liberror_end(const struct liberror_state *);
+
 
 #endif
diff --git a/liberror_copy_error.3 b/liberror_copy_error.3
index e9bc67e..eebb90b 100644
--- a/liberror_copy_error.3
+++ b/liberror_copy_error.3
@@ -46,6 +46,7 @@ None.
 .SH SEE ALSO
 .BR liberror (7),
 .BR liberror.h (0),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_get_error (3),
 .BR liberror_print_bactrace (3),
@@ -53,4 +54,5 @@ None.
 .BR liberror_reset_error (3),
 .BR liberror_save_backtrace (3),
 .BR liberror_set_error (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_end.3 b/liberror_end.3
new file mode 100644
index 0000000..db36d56
--- /dev/null
+++ b/liberror_end.3
@@ -0,0 +1,50 @@
+.TH LIBERROR_END 3 2019-04-13 liberror
+.SH NAME
+liberror_end \- restore the thread's error state
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+void liberror_end(const struct liberror_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_end ()
+function restores the state saved and cleared
+by the
+.BR liberror_stasrt ()
+function.
+.PP
+Asynchronously called functions such as single
+handlers shall call this function the last thing
+they do before returning.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.SH EXAMPLES
+None.
+.SH APPLICATION USAGE
+None.
+.SH RATIONALE
+None.
+.SH FUTURE DIRECTIONS
+None.
+.SH NOTES
+None.
+.SH SEE ALSO
+.BR liberror (7),
+.BR liberror.h (0),
+.BR liberror_copy_error (3),
+.BR liberror_free_error (3),
+.BR liberror_get_error (3),
+.BR liberror_print_bactrace (3),
+.BR liberror_print_error (3),
+.BR liberror_reset_error (3),
+.BR liberror_save_backtrace (3),
+.BR liberror_set_error (3),
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_free_error.3 b/liberror_free_error.3
index 12d2624..53998f0 100644
--- a/liberror_free_error.3
+++ b/liberror_free_error.3
@@ -38,10 +38,12 @@ None.
 .BR liberror (7),
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_get_error (3),
 .BR liberror_print_bactrace (3),
 .BR liberror_print_error (3),
 .BR liberror_reset_error (3),
 .BR liberror_save_backtrace (3),
 .BR liberror_set_error (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_get_error.3 b/liberror_get_error.3
index 0aa9add..18636ef 100644
--- a/liberror_get_error.3
+++ b/liberror_get_error.3
@@ -46,10 +46,12 @@ None.
 .BR liberror (7),
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_print_bactrace (3),
 .BR liberror_print_error (3),
 .BR liberror_reset_error (3),
 .BR liberror_save_backtrace (3),
 .BR liberror_set_error (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_print_bactrace.3 b/liberror_print_bactrace.3
index 9edd680..d8fb1ef 100644
--- a/liberror_print_bactrace.3
+++ b/liberror_print_bactrace.3
@@ -53,10 +53,12 @@ None.
 .BR liberror (7),
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_get_error (3),
 .BR liberror_print_error (3),
 .BR liberror_reset_error (3),
 .BR liberror_save_backtrace (3),
 .BR liberror_set_error (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_print_error.3 b/liberror_print_error.3
index a069835..f0cfa8e 100644
--- a/liberror_print_error.3
+++ b/liberror_print_error.3
@@ -81,10 +81,12 @@ None.
 .BR liberror (7),
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_get_error (3),
 .BR liberror_print_bactrace (3),
 .BR liberror_reset_error (3),
 .BR liberror_save_backtrace (3),
 .BR liberror_set_error (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_reset_error.3 b/liberror_reset_error.3
index 0c80928..3ad3925 100644
--- a/liberror_reset_error.3
+++ b/liberror_reset_error.3
@@ -41,10 +41,12 @@ None.
 .BR liberror (7),
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_get_error (3),
 .BR liberror_print_bactrace (3),
 .BR liberror_print_error (3),
 .BR liberror_save_backtrace (3),
 .BR liberror_set_error (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_save_backtrace.3 b/liberror_save_backtrace.3
index 35a4844..d9ef871 100644
--- a/liberror_save_backtrace.3
+++ b/liberror_save_backtrace.3
@@ -60,10 +60,12 @@ None.
 .BR liberror (7),
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_get_error (3),
 .BR liberror_print_bactrace (3),
 .BR liberror_print_error (3),
 .BR liberror_reset_error (3),
 .BR liberror_set_error (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_set_error.3 b/liberror_set_error.3
index 93387fc..e6db570 100644
--- a/liberror_set_error.3
+++ b/liberror_set_error.3
@@ -93,10 +93,12 @@ None.
 .BR liberror (7),
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_get_error (3),
 .BR liberror_print_bactrace (3),
 .BR liberror_print_error (3),
 .BR liberror_reset_error (3),
 .BR liberror_save_backtrace (3),
-.BR liberror_set_error_errno (3)
+.BR liberror_set_error_errno (3),
+.BR liberror_start (3)
diff --git a/liberror_set_error_errno.3 b/liberror_set_error_errno.3
index f40d184..052c24f 100644
--- a/liberror_set_error_errno.3
+++ b/liberror_set_error_errno.3
@@ -39,10 +39,12 @@ None.
 .BR liberror (7),
 .BR liberror.h (0),
 .BR liberror_copy_error (3),
+.BR liberror_end (3),
 .BR liberror_free_error (3),
 .BR liberror_get_error (3),
 .BR liberror_print_bactrace (3),
 .BR liberror_print_error (3),
 .BR liberror_reset_error (3),
 .BR liberror_save_backtrace (3),
-.BR liberror_set_error (3)
+.BR liberror_set_error (3),
+.BR liberror_start (3)
diff --git a/liberror_start.3 b/liberror_start.3
new file mode 100644
index 0000000..1c9b33e
--- /dev/null
+++ b/liberror_start.3
@@ -0,0 +1,53 @@
+.TH LIBERROR_START 3 2019-04-13 liberror
+.SH NAME
+liberror_start \- save and reset the thread's error state
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+void liberror_start(struct liberror_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_start ()
+function saves the thread-local
+.B liberror
+variables to
+.I state
+as well as the value of
+.IR errno ,
+and resets these variables.
+.PP
+Asynchronously called functions such as single
+handlers shall call this function the first thing
+they do.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.SH EXAMPLES
+None.
+.SH APPLICATION USAGE
+None.
+.SH RATIONALE
+None.
+.SH FUTURE DIRECTIONS
+None.
+.SH NOTES
+None.
+.SH SEE ALSO
+.BR liberror (7),
+.BR liberror.h (0),
+.BR liberror_copy_error (3),
+.BR liberror_end (3),
+.BR liberror_free_error (3),
+.BR liberror_get_error (3),
+.BR liberror_print_bactrace (3),
+.BR liberror_print_error (3),
+.BR liberror_reset_error (3),
+.BR liberror_save_backtrace (3),
+.BR liberror_set_error (3),
+.BR liberror_set_error_errno (3)
diff --git a/start.c b/start.c
new file mode 100644
index 0000000..788011f
--- /dev/null
+++ b/start.c
@@ -0,0 +1,16 @@
+/* See LICENSE file for copyright and license details. */
+#include "internal.h"
+
+
+void
+liberror_start(struct liberror_state *state)
+{
+	state->backtrace = liberror_saved_backtrace;
+	liberror_saved_backtrace = NULL;
+	state->have_error = liberror_have_error_;
+	liberror_have_error_ = 0;
+	state->errnum = errno;
+	errno = 0;
+	memcpy(&state->error, &liberror_error_, sizeof(liberror_error_));
+	memset(&liberror_error_, 0, sizeof(liberror_error_));
+}