OS/2 Shareware BBS: 10 Tools/10-Tools.zip/tcl2-73c.zip/tcl7.3/doc/AddErrInfo.3

Text File | 1993-04-16 | 6KB | 144 lines

'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" All rights reserved.
'\"
'\" Permission is hereby granted, without written agreement and without
'\" license or royalty fees, to use, copy, modify, and distribute this
'\" documentation for any purpose, provided that the above copyright
'\" notice and the following two paragraphs appear in all copies.
'\"
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
'\"
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
'\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
'\"
'\" $Header: /user6/ouster/tcl/man/RCS/AddErrInfo.3,v 1.15 93/04/08 13:54:29 ouster Exp $ SPRITE (Berkeley)
'\"
.so man.macros
.HS Tcl_AddErrorInfo tclc
.BS
.SH NAME
Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
.sp
\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fB (char *) NULL\fR)
.sp
char *
\fBTcl_PosixError\fR(\fIinterp\fR)
.SH ARGUMENTS
.AS Tcl_Interp *message
.AP Tcl_Interp *interp in
Interpreter in which to record information.
.AP char *message in
Identifying string to record in \fBerrorInfo\fR variable.
.AP char *element in
String to record as one element of \fBerrorCode\fR variable.
Last \fIelement\fR argument must be NULL.
.BE

.SH DESCRIPTION
.PP
These procedures are used to manipulate two global variables
that hold information about errors.
The variable \fBerrorInfo\fR holds a stack trace of the
operations that were in progress when an error occurred, and
is intended to be human-readable.
The variable \fBerrorCode\fR holds a list of items that
are intended to be machine-readable.
The first item in \fBerrorCode\fR identifies the class of
.VS
error that occurred (e.g. POSIX means an error occurred in
.VE
a POSIX system call) and additional elements in \fBerrorCode\fR
hold additional pieces of information that depend on the class.
See the Tcl overview manual entry for details on the various
formats for \fBerrorCode\fR.
.PP
The \fBerrorInfo\fR variable is gradually built up as an
error unwinds through the nested operations.
Each time an error code is returned to \fBTcl_Eval\fR
it calls the procedure \fBTcl_AddErrorInfo\fR to add
additional text to \fBerrorInfo\fR describing the
command that was being executed when the error occurred.
By the time the error has been passed all the way back
to the application, it will contain a complete trace
of the activity in progress when the error occurred.
.PP
It is sometimes useful to add additional information to
\fBerrorInfo\fR beyond what can be supplied automatically
by \fBTcl_Eval\fR.
\fBTcl_AddErrorInfo\fR may be used for this purpose:
its \fImessage\fR argument contains an additional
string to be appended to \fBerrorInfo\fR.
For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
to record the name of the file being processed and the
line number on which the error occurred;  for Tcl procedures, the
procedure name and line number within the procedure are recorded,
and so on.
The best time to call \fBTcl_AddErrorInfo\fR is just after
\fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
In calling \fBTcl_AddErrorInfo\fR, you may find it useful to
use the \fBerrorLine\fR field of the interpreter (see the
\fBTcl_Interp\fR manual entry for details).
.PP
The procedure \fBTcl_SetErrorCode\fR is used to set the
\fBerrorCode\fR variable.
Its \fIelement\fR arguments give one or more strings to record
in \fBerrorCode\fR:  each \fIelement\fR will become one item
of a properly-formed Tcl list stored in \fBerrorCode\fR.
\fBTcl_SetErrorCode\fR is typically invoked just before returning
an error.
If an error is returned without calling \fBTcl_SetErrorCode\fR
then the Tcl interpreter automatically sets \fBerrorCode\fR
to \fBNONE\fR.
.PP
\fBTcl_PosixError\fR
.VS
sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
It reads the value of the \fBerrno\fR C variable and calls
\fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the
\fBPOSIX\fR format.
In addition, \fBTcl_PosixError\fR returns a human-readable
.VE
diagnostic message for the error (this is the same value that
will appear as the third element in \fBerrorCode\fR).
It may be convenient to include this string as part of the
error message returned to the application in \fIinterp->result\fR.
.PP
It is important to call the procedures described here rather than
setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
\fBTcl_SetVar\fR.
The reason for this is that the Tcl interpreter keeps information
about whether these procedures have been called.
For example, the first time \fBTcl_AppendResult\fR is called
for an error, it clears the existing value of \fBerrorInfo\fR
and adds the error message in \fIinterp->result\fR to the variable
before appending \fImessage\fR;  in subsequent calls, it just
appends the new \fImessage\fR.
When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
that \fBerrorCode\fR has been set;  this allows the Tcl interpreter
to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
when \fBTcl_SetErrorCode\fR hasn't been called.
.PP
If the procedure \fBTcl_ResetResult\fR is called, it clears all
of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
(but it doesn't actually modify the variables).
If an error had occurred, this will clear the error state to
make it appear as if no error had occurred after all.

.SH "SEE ALSO"
Tcl_ResetResult, Tcl_Interp

.SH KEYWORDS
error, stack, trace, variable