167 lines
6.8 KiB
Groff
167 lines
6.8 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) AddErrInfo.3 1.28 97/06/12 13:39:53
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
|
|
.sp
|
|
\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
|
|
.sp
|
|
\fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\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
|
|
For \fBTcl_AddObjErrorInfo\fR,
|
|
this points to the first byte of an array of bytes
|
|
containing a string to record in the \fBerrorInfo\fR variable.
|
|
This byte array may contain embedded null bytes
|
|
unless \fIlength\fR is negative.
|
|
For \fBTcl_AddErrorInfo\fR,
|
|
this is a conventional C string to record in the \fBerrorInfo\fR variable.
|
|
.AP int length in
|
|
The number of bytes to copy from \fImessage\fR when
|
|
setting the \fBerrorInfo\fR variable.
|
|
If negative, all bytes up to the first null byte are used.
|
|
.AP Tcl_Obj *errorObjPtr in
|
|
This variable \fBerrorCode\fR will be set to this value.
|
|
.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 Tcl 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
|
|
error that occurred
|
|
(e.g. POSIX means an error occurred in 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_EvalObj\fR
|
|
(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObj\fR)
|
|
it calls the procedure \fBTcl_AddObjErrorInfo\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_EvalObj\fR.
|
|
\fBTcl_AddObjErrorInfo\fR may be used for this purpose:
|
|
its \fImessage\fR and \fIlength\fR arguments describe an additional
|
|
string to be appended to \fBerrorInfo\fR.
|
|
For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\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_AddObjErrorInfo\fR is just after
|
|
\fBTcl_EvalObj\fR has returned \fBTCL_ERROR\fR.
|
|
In calling \fBTcl_AddObjErrorInfo\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
|
|
\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR
|
|
but differs in initializing \fBerrorInfo\fR from the string
|
|
value of the interpreter's result
|
|
if the error is just starting to be logged.
|
|
It does not use the result as a Tcl object
|
|
so any embedded null characters in the result
|
|
will cause information to be lost.
|
|
It also takes a conventional C string in \fImessage\fR
|
|
instead of \fBTcl_AddObjErrorInfo\fR's counted string.
|
|
.PP
|
|
The procedure \fBTcl_SetObjErrorCode\fR is used to set the
|
|
\fBerrorCode\fR variable. \fIerrorObjPtr\fR contains a list object
|
|
built up by the caller. \fBerrorCode\fR is set to this
|
|
value. \fBTcl_SetObjErrorCode\fR is typically invoked just
|
|
before returning an error in an object command. If an error is
|
|
returned without calling \fBTcl_SetObjErrorCode\fR or
|
|
\fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
|
|
\fBerrorCode\fR to \fBNONE\fR.
|
|
.PP
|
|
The procedure \fBTcl_SetErrorCode\fR is also used to set the
|
|
\fBerrorCode\fR variable. However, it takes one or more strings to
|
|
record instead of an object. Otherwise, it is similar to
|
|
\fBTcl_SetObjErrorCode\fR in behavior.
|
|
.PP
|
|
\fBTcl_PosixError\fR
|
|
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.
|
|
The caller must previously have called \fBTcl_SetErrno\fR to set
|
|
\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
|
|
is linked into an application as a shared library, or when the error
|
|
occurs in a dynamically loaded extension. See the manual entry for
|
|
\fBTcl_SetErrno\fR for more information.
|
|
.PP
|
|
\fBTcl_PosixError\fR returns a human-readable 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
|
|
the interpreter's result.
|
|
.PP
|
|
It is important to call the procedures described here rather than
|
|
setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
|
|
\fBTcl_ObjSetVar2\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_AddObjErrorInfo\fR is called
|
|
for an error, it clears the existing value of \fBerrorInfo\fR
|
|
and adds the error message in the interpreter's result 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\fR
|
|
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_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
|
|
|
|
.SH KEYWORDS
|
|
error, object, object result, stack, trace, variable
|