The Error/Tracing Utility

--MUTS encourages a programming discipline that makes the debugging of the applications easier. The error facility creates error descriptors, maintains a per thread invocation stack, and defines modules. It has a trace facility for debugging. However, all this is only included if MUTS_DEBUG is defined. If you don't define MUTS_DEBUG, this module degenerates to a simplified version that only creates very simple error descriptors which creates no overhead.

SOURCES

include/muts/error.h
src/muts/error.c

INCLUDE

#include "muts.h"

SWITCHES

#define MUTS_DEBUG	/* enables debugging facilities */
#define TRACE		/* sets the size of the trace buffer */

INTERFACE

void e_init(void);

Initializes this module.

error_t e_module(
	char *name,
	mod_t *mp
);

Define a module. Name is a user chosen name to describe the module, which is mainly used for debugging purposes and nice error descriptions. It need not be unique, but it helps. It initialized the given module descriptor.

error_t e_declare(
	mod_t m,
	void *func,
	char *name
);

Declare a function within a module. m is the module descriptor, and func a pointer to the C function. Name is the ASCII string version of the function name, and, as usual, need not be unique. A function should only be declared in one single module though.

void e_enter(void *func);

This routine should be called on function entry for each function that returns an error descriptor error_t, or a function that can be trapped, or any other function for that matter. Func is a pointer to the function itself, which is pushed on the invocation stack. A function that called e_enter has to invoke either e_ok, e_exit, e_return, or e_pass when it exits.

error_t e_ok(void);

This routine should be invoked when an error_t routine returns successfully. It pops one element from the invocation stack, and returns an OK error descriptor. e_ok has been redefined as e_exit for routines that called e_enter but do not return an error_t.

error_t e_return(
	int eclass,
	char *descr
);

Create and return an error descriptor. Class is the class of the error, and descriptor a string that describes the error in more detail.

error_t e_pass(error_t r);

Return an error descriptor that was created by some other function. This is used to pass errors on.

void e_dump(void);

Dump a stack trace for the current thread.

error_t e_class(
	error_t r,
	int *eclass
);

Returns in *eclass the error class associated with the given error r.