.ds Vv 1.2.14
.TH VistaIOSetErrorHandler 3 "16 February 1994" "VistaIO Version \*(Vv"
.SH NAME
VistaIOSetErrorHandler \- register a procedure to be called on any fatal error
.SH SYNOPSIS
.nf
.ft B
void VistaIOSetErrorHandler (VistaIOErrorHandler *\fIhandler\fP);
.PP
.ft B
typedef void VistaIOErrorHandler (VistaIOStringConst \fImessage\fP);
.PP
.ft B
void VistaIODefaultError (VistaIOStringConst \fImessage\fP);
.fi
.SH ARGUMENTS
.IP \fIhandler\fP 10n
Specifies the new fatal error handler.
.IP \fImessage\fP 10n
Specifies a null-terminated error message string to be reported. 
.SH DESCRIPTION
\fBVistaIOSetErrorHandler\fP registers a procedure, \fIhandler\fP, as the fatal
error handler. That procedure is called by \fBVistaIOError\fP(3) or by
\fBVistaIOSystemError\fP(3) to report any fatal error. When called, it is passed
a string, \fImessage\fP, containing a textual description of the error.
.PP
Only one procedure serves as the fatal error handler at any one time.
.PP
Prior to the first call to \fBVistaIOSetErrorHandler\fP, the procedure 
\fBVistaIODefaultError\fP is the fatal error handler. This procedure will
write the error message to the standard error stream, then terminate
the program by calling \fBexit\fP(3) with a status value of 1. 
\fBVistaIODefaultError\fP can be re-established as the fatal error handler
at any time by calling \fBVistaIOSetErrorHandler\fP with a 
.SB NULL
argument.
.SH "RETURN VALUES"
A fatal error handler should never return.
.SH EXAMPLES
To adopt an error handler that writes messages both to the standard error
stream and to a log file, one might do the following:
.RS
.PP
.nf
.ft B
FILE *log_file;

void MyErrorHandler (message)
	VistaIOStringConst message;
{
	fputs (message, stderr);
	fputs (message, log_file);
	exit (1);
}

int main (\fR...\fP)
{
	\fR...\fP
	log_file = fopen ("log", "w");
	VistaIOSetErrorHandler (MyErrorHandler);
	\fR...\fP
}
.fi
.RE
.SH "SEE ALSO"
.BR VistaIOError (3),
.BR VistaIOSetWarningHandler (3),

.SH AUTHOR
Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>