doc/man3/tst_set_error.3

.\"
.\" $Id: tst_set_error.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of version 2 of the GNU General Public License as
.\" published by the Free Software Foundation.
.\"
.\" This program is distributed in the hope that it would be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" Further, this software is distributed without any warranty that it is
.\" free of the rightful claim of any third person regarding infringement
.\" or the like.  Any license provided herein, whether implied or
.\" otherwise, applies only to this software file.  Patent licenses, if
.\" any, provided herein do not apply to combinations of this program with
.\" other software, or any other product whatsoever.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
.\" Mountain View, CA  94043, or:
.\"
.\" http://www.sgi.com
.\"
.\" For further information regarding this notice, see:
.\"
.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
.\"
.TH TST_SET_ERROR 3 07/25/2000 "Linux Test Project"
.SH NAME
tst_set_error \- Sets global tst_error values
.br
tst_clear_error \- clears global tst_error values
.SH SYNOPSIS
.nf
\fB
#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()
\fR
.fi

.SH DESCRIPTION
These two functions provide a simple interface to allow
a programmer set and clear the global variables in
\fBtst_error\fR defined in \fItest_error.c\fR.

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.

\fBtst_error\fR is a global variable, which is really a structure
of five elements.   The structure is defined \fItest.h\fR and looks
like:

.nf
    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 */
.fi

Any new or existing function will be able to call \fBtst_set_error()\fR
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 \fBte_mesg\fR 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.

\fBtst_set_error()\fR will not overwrite these global variables if
\fBtst_error.te_level\fR is not zero.

\fBtst_clear_error()\fR 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
\fBtst_set_error\fR, should provide another way to indicating that an error
has occurred.  These variables should be used reporting the error message.
Although, if you use \fBtst_clear_error()\fR prior to calling any functions
and \fBtst_error.te_mesg\fR[0] != '\0', you know someone reported an error or
at least used the space.

.RE

.SH "Examples"

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

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

To report an error, use tst_set_error() function:

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

To access the error information an issue an error message:

.nf
#include "test.h"
 	....
	fprintf(stderr, "%s: funcname failed: %s\n", Prog, tst_error.te_mesg);

.fi

.SH DIAGNOSTICS
Both functions are void, thus not return value.

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