And man pages for the function, and add print function to user specifiec error details

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

12 files changed, 596 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index ea88b2f..e8bdb7c 100644
--- a/Makefile
+++ b/Makefile
@@ -29,6 +29,17 @@ OBJ =\
 	set_error.o\
 	set_error_errno.o
 
+MAN3 =\
+	liberror_copy_error.3\
+	liberror_free_error.3\
+	liberror_get_error.3\
+	liberror_print_bactrace.3\
+	liberror_print_error.3\
+	liberror_reset_error.3\
+	liberror_save_backtrace.3\
+	liberror_set_error.3\
+	liberror_set_error_errno.3
+
 LOBJ = $(OBJ:.o=.lo)
 
 
diff --git a/liberror.h b/liberror.h
index 7b5176a..f4b2b41 100644
--- a/liberror.h
+++ b/liberror.h
@@ -35,6 +35,7 @@ union liberror_details {
 		void *data;
 		void (*free_data)(void *);
 		void *(*copy_data)(void *);
+		void (*print_data)(void *, FILE *, const char *);
 	} user;
 
 	/**
diff --git a/liberror_copy_error.3 b/liberror_copy_error.3
new file mode 100644
index 0000000..e9bc67e
--- /dev/null
+++ b/liberror_copy_error.3
@@ -0,0 +1,56 @@
+.TH LIBERROR_COPY_ERROR 3 2019-04-13 liberror
+.SH NAME
+liberror_copy_error \- create a copy of an error
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+struct liberror_error *liberror_copy_error(struct liberror_error *\fIerror\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_copy_error ()
+function creates a copy of if the error specified in the
+.I error
+parameter.
+.PP
+The returned error shall be deallocated with the
+.BR liberror_free_error (3)
+function.
+.SH RETURN VALUE
+The
+.BR liberror_copy_error ()
+returns a copy of
+.I error
+upon successful completion, or
+.I NULL
+on failure, without changing
+.IR errno .
+.SH ERRORS
+This function can only fail of enough memory cannot be
+allocated, however the function never change
+.IR errno .
+.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_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/liberror_free_error.3 b/liberror_free_error.3
new file mode 100644
index 0000000..12d2624
--- /dev/null
+++ b/liberror_free_error.3
@@ -0,0 +1,47 @@
+.TH LIBERROR_FREE_ERROR 3 2019-04-13 liberror
+.SH NAME
+liberror_free_error \- deallocate an error
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+void liberror_free_error(struct liberror_error *\fIerror\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_free_error ()
+function deallocates
+.I error
+recursively. If
+.I error
+is
+.I NULL
+the function will return without doing anything.
+.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_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/liberror_get_error.3 b/liberror_get_error.3
new file mode 100644
index 0000000..0aa9add
--- /dev/null
+++ b/liberror_get_error.3
@@ -0,0 +1,55 @@
+.TH LIBERROR_GET_ERROR 3 2019-04-13 liberror
+.SH NAME
+liberror_get_error \- get the current error for the thread
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+struct liberror_error *liberror_get_error(void);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_get_error ()
+function returns a pointer to the threads current
+error. If the thread does not have an error assigned,
+.I NULL
+is returned.
+.PP
+After handling the error, call the
+.BR liberror_reset_error (3)
+function.
+.SH RETURN VALUE
+The
+.BR liberror_get_error ()
+returns the error assigned to the thread, or
+.I NULL
+if none is assigned to the threa. Failure is impossible.
+.PP
+Note, this contents of this error will change when a new
+error is assigned to the thread.
+.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_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/liberror_print_bactrace.3 b/liberror_print_bactrace.3
new file mode 100644
index 0000000..9edd680
--- /dev/null
+++ b/liberror_print_bactrace.3
@@ -0,0 +1,62 @@
+.TH LIBERROR_PRINT_BACKTRACE 3 2019-04-13 liberror
+.SH NAME
+liberror_print_backtrace \- print the backtrace of an error
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+void liberror_print_backtrace(struct liberror_error *\fIerror\fP, FILE *\fIfp\fP, const char *\fIindent\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_print_backtrace ()
+function prints the backtrace of the error
+specified in the
+.I error
+parameter. If no backtrace have been assigned,
+for example if the backtace record could not be
+allocated, the function will return without
+side-effects.
+.PP
+The
+.BR liberror_print_error (3)
+function calls the
+.BR liberror_print_backtrace ()
+function, so there is no need to call the
+.BR liberror_print_backtrace ()
+function unless you are doing a custom error print.
+.PP
+.B liberror
+only implements a no-operation function, the actual
+implementation is implemented in the
+.BR liberror-backtrace (7)
+library.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+.I errno
+will never be changed.
+.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_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/liberror_print_error.3 b/liberror_print_error.3
new file mode 100644
index 0000000..a069835
--- /dev/null
+++ b/liberror_print_error.3
@@ -0,0 +1,90 @@
+.TH LIBERROR_PRINT_ERROR 3 2019-04-13 liberror
+.SH NAME
+liberror_print_error \- print an error
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+int liberror_print_error(struct liberror_error *\fIerror\fP, FILE *\fIfp\fP, int \fIreset\fP, const char *\fIprefix\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_print_error ()
+function prints the error, including available details, backtrace,
+and cause recursively, specified in the
+.I error
+parameter, or the error currently assigned to the thread if
+.I error
+is
+.IR NULL ,
+to
+.IR fp ,
+or to the standard error if
+.I fp
+is
+.IR NULL .
+Unless
+.I prefix
+is
+.I NULL
+or the empty string, each printed line will becoming with with
+.I prefix
+followed by a space and a colon. Under normal usage,
+.I prefix
+shall be
+.I argv[0]
+from the
+.BR main ()
+function.
+.PP
+If
+.I reset
+is non-zero,
+.I error
+will be deallocated with the
+.BR liberror_free_error (3)
+function, or if
+.I error
+is
+.IR NULL ,
+with the
+.BR liberror_reset_error (3)
+function, which marks that the thread does not have any error
+assigned to it. Thus, if
+.I error
+is
+.I NULL
+and
+.I reset
+is non-zero, there is no need to call the
+.BR liberror_reset_error (3)
+function.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+.I errno
+will never be changed.
+.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_reset_error (3),
+.BR liberror_save_backtrace (3),
+.BR liberror_set_error (3),
+.BR liberror_set_error_errno (3)
diff --git a/liberror_reset_error.3 b/liberror_reset_error.3
new file mode 100644
index 0000000..0c80928
--- /dev/null
+++ b/liberror_reset_error.3
@@ -0,0 +1,50 @@
+.TH LIBERROR_RESET_ERROR 3 2019-04-13 liberror
+.SH NAME
+liberror_reset_error \- remove the error currently assigned to the thread
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+void liberror_reset_error(void);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_reset_error ()
+function recursivelt deallocates the thread's
+currently assigned error, if any, and marks
+that the thread does not currently have any
+error assigned to it.
+.PP
+It is important to call this function after
+an error has been handles, or ignored, otherwise
+the error currently assigned to the thread will
+be marked as the cause of the next error assigned
+to the thread.
+.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_save_backtrace (3),
+.BR liberror_set_error (3),
+.BR liberror_set_error_errno (3)
diff --git a/liberror_save_backtrace.3 b/liberror_save_backtrace.3
new file mode 100644
index 0000000..35a4844
--- /dev/null
+++ b/liberror_save_backtrace.3
@@ -0,0 +1,69 @@
+.TH LIBERROR_SAVE_BACKTRACE 3 2019-04-13 liberror
+.SH NAME
+liberror_save_backtrace \- fetch backtrace and assign it to an error
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+int liberror_save_backtrace(struct liberror_error *\fIerror\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_save_backtrace ()
+function fetches the backtrace for the call to the function
+and stores it in
+.IR error ,
+deallocating any already assigned backtrace. If
+.I error
+is
+.IR NULL ,
+the backtrace will assigned to the next error that is
+assigned to the thread. The
+.IR liberror_set_error (3)
+function calls this function, so there is no need for the
+user to call this function, however, calling this function
+before or after (preferably before for better performance)
+call the
+.IR liberror_set_error (3)
+function or any helper function that calls the
+.IR liberror_set_error (3)
+function will produce a cleaner backtrace.
+.PP
+.B liberror
+only implements a no-operation function that returns 0,
+the actual implementation is implemented in the
+.BR liberror-backtrace (7)
+library.
+.SH RETURN VALUE
+The
+.BR liberror_save_backtrace ()
+function returns 0 upon successful completion,
+on failure -1 is returned without changing
+.IR errno .
+.SH ERRORS
+.I errno
+will never be changed.
+.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_set_error (3),
+.BR liberror_set_error_errno (3)
diff --git a/liberror_set_error.3 b/liberror_set_error.3
new file mode 100644
index 0000000..93387fc
--- /dev/null
+++ b/liberror_set_error.3
@@ -0,0 +1,102 @@
+.TH LIBERROR_SET_ERROR 3 2019-04-13 liberror
+.SH NAME
+liberror_set_error \- set the current error for the thread
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+void liberror_set_error(const char \fIdescription\fP[256], const char \fIsource\fP[64], const char \fIcode_group\fP[64], long long int \fIcode\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_set_error ()
+function assigns a new error to the thread. If the
+thread already has an error assigned to it, that
+error will be copied and stored as the cause of the
+new error. If the process cannot allocate enough
+memory to copy the error (which is statically allocated),
+the
+.I cause
+field in the new error will be set to
+.I NULL
+and the
+.I failed_to_allocate_cause
+field will be set to 1.
+.PP
+The
+.I description
+parameter shall be a single line description of the
+error, or the empty string; it must not be
+.IR NULL .
+If the empty string is specified, the value of
+.I code_group
+and
+.I code
+parameters will be printed when the error is printed
+by the
+.I liberror_print_error
+is called, however, if the value of the
+.I code_group
+parameter is recognised, the error string for the
+.I code
+error will be used.
+.PP
+The
+.I source
+parameter shall be the name of the function that
+failed, or the empty string; it must not be
+.IR NULL .
+.PP
+The
+.I code
+parameter shall be the error number that describes
+the error. The
+.I code_group
+shall be a non-empty string (and must not be
+.IR NULL )
+that specifies the what error number group is used
+for the error code. For values assigned to
+.IR errno ,
+.I code_group
+shall be
+.B \(dqerrno\(dq
+and for errors returned by the
+.BR getaddrinfo (3)
+function,
+.I code_group
+shall be
+.BR \(dqerrno\(dq .
+In other cases, the value of
+.I code_group
+shall be the name of the library or application.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+Errors will be marked in the new error.
+.I errno
+will never be changed. Failure to create the error is
+impossible.
+.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_errno (3)
diff --git a/liberror_set_error_errno.3 b/liberror_set_error_errno.3
new file mode 100644
index 0000000..f40d184
--- /dev/null
+++ b/liberror_set_error_errno.3
@@ -0,0 +1,48 @@
+.TH LIBERROR_SET_ERROR_ERRNO 3 2019-04-13 liberror
+.SH NAME
+liberror_set_error_errno \- set the current error for the thread
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+void liberror_set_error_errno(const char \fIdescription\fP[256], const char \fIsource\fP[64], int \fIcode\fP);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.BR liberror_set_error_errno ()
+function is equivalent to calling
+.nf
+
+	liberror_set_error(description, source, \(dqerrno\(dq, (long long int)code)
+.fi
+.SH RETURN VALUE
+None.
+.SH ERRORS
+Errors will be marked in the new error.
+.I errno
+will never be changed. Failure to create the error is
+impossible.
+.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)
diff --git a/print_error.c b/print_error.c
index 245caa0..9c8bf1c 100644
--- a/print_error.c
+++ b/print_error.c
@@ -19,6 +19,11 @@ print_error(struct liberror_error *error, FILE *fp, char *prefix)
 	*strchr(prefix, '\0') = ' ';
 
 	switch (error->details_type) {
+	case LIBERROR_DETAILS_USER:
+		if (error->details.user.print_data)
+			error->details.user.print_data(error->details.user.data, fp, prefix);
+		break;
+
 	case LIBERROR_DETAILS_ONE_FILE:
 		if (error->details.one_file.fd >= 0 || error->details.one_file.name) {
 			fprintf(fp, "%sDetails:\n", prefix);
@@ -57,7 +62,6 @@ print_error(struct liberror_error *error, FILE *fp, char *prefix)
 		break;
 
 	case LIBERROR_DETAILS_NONE:
-	case LIBERROR_DETAILS_USER:
 	default:
 		break;
 	}