$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/

tst_set_error - Sets global tst_error values

tst_clear_error - clears global tst_error values

#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()

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] != '\0', you know someone reported an error or at least used the space. 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\n", Prog, tst_error.te_mesg);

Both functions are void, thus not return value. 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.