Add liberror.h.0

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

2 files changed, 325 insertions, 0 deletions

diff --git a/liberror.h b/liberror.h
index 6062889..1bcbec3 100644
--- a/liberror.h
+++ b/liberror.h
@@ -220,6 +220,8 @@ struct liberror_error {
 
 /**
  * Saved error state for a thread
+ * 
+ * This structure shall be regardes as opaque
  */
 struct liberror_state {
 	/**
diff --git a/liberror.h.0 b/liberror.h.0
new file mode 100644
index 0000000..7e3e4c0
--- /dev/null
+++ b/liberror.h.0
@@ -0,0 +1,323 @@
+.TH LIBERROR.H 0 2019-04-13 liberror
+.SH NAME
+liberror.h \- single interface for custom and standard errors
+.SH SYNOPSIS
+.nf
+#include <liberror.h>
+
+struct liberror_backtrace;
+
+enum liberror_details_type {
+	LIBERROR_DETAILS_NONE,
+	LIBERROR_DETAILS_USER,
+	LIBERROR_DETAILS_ONE_FILE,
+	LIBERROR_DETAILS_TWO_FILES
+};
+
+union liberror_details {
+	struct {
+		const char *\fIlibrary\fP;
+		void *\fIdata\fP;
+		void (*\fIfree_data\fP)(void *);
+		void *(*\fIcopy_data\fP)(void *);
+		void (*\fIprint_data\fP)(void *, FILE *, const char *);
+	} \fIuser\fP;
+
+	struct {
+		int \fIfd\fP;
+		char *\fIname\fP;
+		const char *\fIrole\fP;
+	} \fIone_file\fP;
+
+	struct {
+		int \fIfd1\fP, \fIfd2\fP;
+		char *\fIname1\fP, *\fIname2\fP;
+		const char *\fIrole1\fP, *\fIrole2\fP;
+	} \fItwo_files\fP;
+};
+
+struct liberror_error {
+	struct liberror_backtrace *\fIbacktrace\fP;
+	char \fIdescription\fP[256];
+	char \fIsource\fP[64];
+	char \fIcode_group\fP[64];
+	long long int \fIcode\fP;
+	struct liberror_error *\fIcause\fP;
+	int \fIfailed_to_allocate_cause\fP;
+	int \fIdynamically_allocated\fP;
+	enum liberror_details_type \fIdetails_type\fP;
+	union liberror_details \fIdetails\fP;
+};
+
+struct liberror_state { /* fields omitted */ };
+
+struct liberror_error *liberror_get_error(void);
+struct liberror_error *liberror_copy_error(struct liberror_error *);
+void liberror_free_error(struct liberror_error *);
+void liberror_reset_error(void);
+void liberror_print_backtrace(struct liberror_error *, FILE *, const char *);
+int liberror_save_backtrace(struct liberror_error *);
+void liberror_set_error(const char[256], const char[64], const char[64], long long int);
+void liberror_set_error_errno(const char[256], const char[64], int);
+void liberror_print_error(struct liberror_error *, FILE *, int, const char *);
+void liberror_start(struct liberror_state *);
+void liberror_end(const struct liberror_state *);
+.fi
+.PP
+Link with
+.IR \-lerror .
+.SH DESCRIPTION
+The
+.B liberror.h
+header defines one transparent structure:
+.BR "struct liberror_error" ,
+its fields are:
+.TP
+.I backtrace
+The backtrace for the error.
+.TP
+.I description
+Textual description of the error;
+empty if missing.
+.TP
+.I source
+The function in which the error occurred;
+empty if unknown.
+.TP
+.I code_group
+A string that specifies which group of
+error codes are used.
+.B \(dqerrno\(dq
+for
+.I errno
+values,
+.B \(dqaddrinfo\(dq
+for errors codes used by the
+.BR getaddrinfo (3)
+function, and library or application
+name of custom error codes.
+.TP
+.I code
+The error code.
+.TP
+.I cause
+The error which caused the error,
+.I NULL
+if none of if the process could not
+allocate enough memory to store it.
+.TP
+.I failed_to_allocate_cause
+Whether the
+.I cause
+field was set to
+.I NULL
+because the enough memory cause
+not be allocated for it.
+.TP
+.I dynamically_allocated
+Whether the error is dynamically
+allocated rather than statically
+allocated. This is used by the
+.BR liberror_free_error (3)
+to determine whether the pointer
+to the error shall be deallocated.
+.TP
+.I details_type
+Used to determine which structure in the
+.I details
+field is used. By default, this is set to
+.I LIBERROR_DETAILS_NONE
+when a new error is assigned to a thread,
+and the function that sets the error must
+get the error it created as set this
+information manually.
+.TP
+.I details
+Extended information about the error.
+.PP
+The
+.B liberror.h
+header defines two opaque structures:
+.TP
+.B struct liberror_backtrace
+Backtrace information for an error.
+This is defined as an incomplete type,
+it is a flat structure of variable size.
+.TP
+.B struct liberror_state
+Stored error state for a thread. This
+is defined as a complete type but should
+be regardes as opaque.
+.PP
+The
+.B liberror.h
+header defines one enumerated type:
+.BR "enum liberror_details_type" ,
+it is used to specify which structure in
+.BR "union liberror_details" .
+Its values are:
+.TP
+.I LIBERROR_DETAILS_NONE
+None is used. There is no extended information.
+.TP
+.I LIBERROR_DETAILS_USER
+.I user
+is used. There is library- or application-defined
+extended information.
+.TP
+.I LIBERROR_DETAILS_ONE_FILE
+.I one_file
+is used. There is extended information about one
+file or file descriptor.
+.TP
+.I LIBERROR_DETAILS_TWO_FILES
+.I two_files
+is used. There is extended information about two
+files or file descriptors.
+.PP
+The
+.B liberror.h
+header defines one union:
+.BR "union liberror_details" ,
+it is used for extended error information. Its
+member structures are:
+.TP
+.I user
+Information defined by a library or the application.
+The field
+.I library
+shall be set to a statically allocated string that
+names the library that defines the informations.
+If the application defines the information, the
+application can choose freely how this field shall
+be set as it will not affect other software. The
+information it self shall be stored in the field
+.IR data ,
+and the functions stored in the fields,
+.IR free_data ,
+.IR copy_data ,
+and
+.IR print_data ,
+shall deallocate, copy, and print the extended
+information, respective, the value of the
+.I data
+field is input in these functions' first parameter.
+The second parameter of the
+.IR print_data
+function will be the file the information shall
+be printed to and the third parameter will be a
+string that shall be printed at the beginning of
+each printed line. Neither the second nor the
+third parameter will ever be
+.IR NULL .
+.TP
+.I one_file
+Information about one file. The value of the
+.I fd
+field shall either be the file descriptor number
+of the file given as input to the function in
+which the error occured, or a negative value if
+none. The value of the
+.I name
+field shall either be a dynamically allocated
+string containing the file name or any other
+identifying string, or
+.I NULL
+if none or if enough the string could not be
+allocated. The value of the
+.I role
+string shall be a statically allocated string
+containing the file's role in the function call,
+for example \(dqDirectory\(dq for the
+.BR mkdir (3)
+function.
+.TP
+.I two_files
+Information about two files. This structure is
+similar to that of
+.IR one_file ,
+with the difference that
+.I two_files
+have two copies of each field in
+.IR one_file :
+one with the
+.B 1
+suffix for the first file parameter and one
+with the
+.B 2
+suffix for the second file parameter.
+.PP
+The
+.B liberror.h
+header defines the following functions:
+.TP
+.BR liberror_get_error (3)
+Get the current error, if any, for the calling thread.
+.TP
+.BR liberror_copy_error (3)
+Create a copy if an error.
+.TP
+.BR liberror_free_error (3)
+Delete a copy if an error.
+.TP
+.BR liberror_reset_error (3)
+Deallocate the calling thread's current error, if any,
+and mark that the thread does not have any error.
+.TP
+.BR liberror_print_backtrace (3)
+Print the backtrace for an error. Please see its man
+page for more information.
+.TP
+.BR liberror_save_backtrace (3)
+Set the backtrace for an error or the thread's next
+error. Please see its man page for more information.
+.TP
+.BR liberror_set_error (3)
+Set the error for the calling thread.
+.TP
+.BR liberror_set_error_errno (3)
+Wrapper for
+.BR liberror_set_error (3)
+for errors with
+.I errno
+values.
+.TP
+.BR liberror_print_error (3)
+Print an error, by default the calling thread's
+current error, if any, including description,
+extended information, backtrace, and cause,
+recursively. Optionally deallocate the error
+and clear the thread's error.
+.TP
+.BR liberror_start (3)
+This function shall be called at the beginning
+of signal handlers and other asynchronously
+called functions.
+.TP
+.BR liberror_end (3)
+This function shall be called at the end
+of signal handlers and other asynchronously
+called functions.
+.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_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),
+.BR liberror_start (3)