diff options
| -rw-r--r-- | Makefile | 11 | ||||
| -rw-r--r-- | liberror.h | 1 | ||||
| -rw-r--r-- | liberror_copy_error.3 | 56 | ||||
| -rw-r--r-- | liberror_free_error.3 | 47 | ||||
| -rw-r--r-- | liberror_get_error.3 | 55 | ||||
| -rw-r--r-- | liberror_print_bactrace.3 | 62 | ||||
| -rw-r--r-- | liberror_print_error.3 | 90 | ||||
| -rw-r--r-- | liberror_reset_error.3 | 50 | ||||
| -rw-r--r-- | liberror_save_backtrace.3 | 69 | ||||
| -rw-r--r-- | liberror_set_error.3 | 102 | ||||
| -rw-r--r-- | liberror_set_error_errno.3 | 48 | ||||
| -rw-r--r-- | print_error.c | 6 |
12 files changed, 596 insertions, 1 deletions
@@ -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) @@ -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; } |