TST_SET_ERROR(3)

NAME
tst_set_error - Sets global Tst_error values
tst_clear_error - clears global Tst_error values

SYNOPSIS

#include "test.h"

void
tst_set_error(file, line, func, fmt...)
char *file;
int line;
char *func;
char *fmt;     /* printf format */

void
tst_clear_error()

DESCRIPTION
These two functions provide a simple interface to allow a programmer set and clear the global variables in Tst_error defined in test_error.c.

The purpose of these global variables to provide space for error messages passing. Functions within our library can use this space and these routines to a pass error messages and some debug data to the caller.

Tst_error is a global variable, which is really a structure of five elements. The structure is defined test.h and looks like:

    int  te_line;
				/* line where last error was reported. */
				/* Use "__LINE__" and let compiler do */
				/* the rest */
    int  te_level;
				/* If set, will prevent current stored */
				/* error to not be overwritten */
    char te_func[TST_ERR_FUNC_SIZE+1];
				/* name of function of last error */
				/* Name of function or NULL */
    char te_file[TST_ERR_FILE_SIZE+1];
				/* module of last error.  Use */
				/* "__FILE__" and let compiler do the */
				/* rest */
    char te_mesg[TST_ERR_MESG_SIZE+1];
				/* string of last error */

Any new or existing function will be able to call tst_set_error() to save error information. Any caller of a function that uses this data, can access the data fields directly and print any of error data in desired format.

Do not append newline to the end te_mesg string, it is the responsibility of the user of these mesg to print the trailing newline. This does not say that for long error messages, that there can not be newlines in the message.

tst_set_error() will not overwrite these global variables if Tst_error.te_level is not zero.

tst_clear_error() will make all strings zero length and set all integers to zero.

These global variables should not be used as the method for determining if there is an error. The functions that use tst_set_error, should provide another way to indicating that an error has occurred. These variables should be used reporting the error message. Although, if you use tst_clear_error() prior to calling any functions and Tst_error.te_mesg[0] != ' ', you know someone reported an error or at least used the space.

Examples

To clear/initialize a programmer can use the tst_clear_error() function or access the variables directly.

#include "test.h"
	....
	tst_clear_error();

To report an error, use tst_set_error() function:

#include "test.h"
	....
	tst_set_error(__LINE__, __FILE__, "funcname",
		"Malloc(%d) failed, errno:%d", size, errno);

To access the error information an issue an error message:

#include "test.h"
 	....
	fprintf(stderr, "%s: funcname failed: %s, Prog, Tst_error.te_mesg);

DIAGNOSTICS
Both functions are void, thus not return value.

BUGS
There is no space overwrite preventions on the Tst_error.te_mesg field. If fmt parameter of tst_set_error expands to a string larger than the space in Tst_error.te_mesg, you will start overwriting memory. This field contains 1024 bytes, which is fairly big error message.