144 lines
5.9 KiB
Groff
144 lines
5.9 KiB
Groff
'\"
|
|
'\" 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
|