path: root/doc/AddErrInfo.3

'\"
'\" 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.
'\" 
'\" RCS: @(#) $Id: AddErrInfo.3,v 1.8 2002/07/01 18:24:38 jenglish Exp $
'\" 
.so man.macros
.TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- 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
\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
.sp
CONST char *
\fBTcl_PosixError\fR(\fIinterp\fR)
.sp
void
\fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\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.
.AP va_list argList in
An argument list which must have been initialized using
\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
.AP "CONST char" *script in
Pointer to first character in script containing command (must be <= command)
.AP "CONST char" *command in
Pointer to first character in command that generated the error
.AP int commandLength in
Number of bytes in command; -1 means use all bytes up to first NULL byte
.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_EvalObjEx\fR
(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObjEx\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_EvalObjEx\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_EvalObjEx\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_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
instead of taking a variable number of arguments it takes an argument list.
.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
\fBTcl_LogCommandInfo\fR is invoked after an error occurs in an
interpreter.  It adds information about the command that was being
executed when the error occurred to the \fBerrorInfo\fR variable, and
the line number stored internally in the interpreter is set.  On the
first call to \fBTcl_LogCommandInfo\fR or \fBTcl_AddObjErrorInfo\fR
since an error occurred, the old information in \fBerrorInfo\fR is
deleted.
.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