Партнёры:
Хостинг:
_________________________________________________________________
NAME
Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode,
Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo -
record information about errors
SYNOPSIS
#include <tcl.h>
Tcl_AddObjErrorInfo(interp, message, length)
Tcl_AddErrorInfo(interp, message)
Tcl_SetObjErrorCode(interp, errorObjPtr)
Tcl_SetErrorCode(interp, element, element, ... (char *) NULL)
Tcl_SetErrorCodeVA(interp, argList)
char *
Tcl_PosixError(interp)
void
Tcl_LogCommandInfo(interp, script, command, commandLength)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to
record information.
char *message (in) For Tcl_AddObjErrorInfo,
this points to the first
byte of an array of bytes
containing a string to
record in the errorInfo
variable. This byte array
may contain embedded null
bytes unless length is
negative. For
Tcl_AddErrorInfo, this is
a conventional C string to
record in the errorInfo
variable.
int length (in) The number of bytes to
copy from message when
setting the errorInfo
variable. If negative,
all bytes up to the first
null byte are used.
Tcl_Obj *errorObjPtr(in) This variable errorCode
will be set to this value.
char *element (in) String to record as one
element of errorCode vari-
able. Last element argu-
ment must be NULL.
va_list argList (in) An argument list which
must have been initialised
using TCL_VARARGS_START,
and cleared using va_end.
char *script (in) Pointer to first character
in script containing com-
mand (must be <= command)
char *command (in) Pointer to first character
in command that generated
the error
int commandLength(in) Number of bytes in com-
mand; -1 means use all
bytes up to first NULL
byte
_________________________________________________________________
DESCRIPTION
These procedures are used to manipulate two Tcl global vari-
ables that hold information about errors. The variable
errorInfo holds a stack trace of the operations that were in
progress when an error occurred, and is intended to be
human-readable. The variable errorCode holds a list of
items that are intended to be machine-readable. The first
item in errorCode identifies the class of error that
occurred (e.g. POSIX means an error occurred in a POSIX sys-
tem call) and additional elements in errorCode hold addi-
tional pieces of information that depend on the class. See
the Tcl overview manual entry for details on the various
formats for errorCode.
The errorInfo variable is gradually built up as an error
unwinds through the nested operations. Each time an error
code is returned to Tcl_EvalObj (or Tcl_Eval, which calls
Tcl_EvalObj) it calls the procedure Tcl_AddObjErrorInfo to
add additional text to errorInfo 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.
It is sometimes useful to add additional information to
errorInfo beyond what can be supplied automatically by
Tcl_EvalObj. Tcl_AddObjErrorInfo may be used for this pur-
pose: its message and length arguments describe an addi-
tional string to be appended to errorInfo. For example, the
source command calls Tcl_AddObjErrorInfo 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 Tcl_AddObjErrorInfo is just after
Tcl_EvalObj has returned TCL_ERROR. In calling
Tcl_AddObjErrorInfo, you may find it useful to use the
errorLine field of the interpreter (see the Tcl_Interp
manual entry for details).
Tcl_AddErrorInfo resembles Tcl_AddObjErrorInfo but differs
in initializing errorInfo 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 informa-
tion to be lost. It also takes a conventional C string in
message instead of Tcl_AddObjErrorInfo's counted string.
The procedure Tcl_SetObjErrorCode is used to set the error-
Code variable. errorObjPtr contains a list object built up
by the caller. errorCode is set to this value.
Tcl_SetObjErrorCode is typically invoked just before return-
ing an error in an object command. If an error is returned
without calling Tcl_SetObjErrorCode or Tcl_SetErrorCode the
Tcl interpreter automatically sets errorCode to NONE.
The procedure Tcl_SetErrorCode is also used to set the
errorCode variable. However, it takes one or more strings to
record instead of an object. Otherwise, it is similar to
Tcl_SetObjErrorCode in behavior.
Tcl_SetErrorCodeVA is the same as Tcl_SetErrorCode except
that instead of taking a variable number of arguments it
takes an argument list.
Tcl_PosixError sets the errorCode variable after an error in
a POSIX kernel call. It reads the value of the errno C
variable and calls Tcl_SetErrorCode to set errorCode in the
POSIX format. The caller must previously have called
Tcl_SetErrno to set errno; this is necessary on some plat-
forms (e.g. Windows) where Tcl is linked into an application
as a shared library, or when the error occurs in a dynami-
cally loaded extension. See the manual entry for
Tcl_SetErrno for more information.
Tcl_PosixError returns a human-readable diagnostic message
for the error (this is the same value that will appear as
the third element in errorCode). It may be convenient to
include this string as part of the error message returned to
the application in the interpreter's result.
Tcl_LogCommandInfo is invoked after an error occurs in an
interpreter. It adds information about the command that was
being executed when the error occured to the errorInfo vari-
able, and the line number stored internally in the inter-
preter is set. On the first call to Tcl_LogCommandInfo or
Tcl_AddObjErrorInfo since an error occurred, the old infor-
mation in errorInfo is deleted.
It is important to call the procedures described here rather
than setting errorInfo or errorCode directly with
Tcl_ObjSetVar2. The reason for this is that the Tcl inter-
preter keeps information about whether these procedures have
been called. For example, the first time
Tcl_AddObjErrorInfo is called for an error, it clears the
existing value of errorInfo and adds the error message in
the interpreter's result to the variable before appending
message; in subsequent calls, it just appends the new mes-
sage. When Tcl_SetErrorCode is called, it sets a flag indi-
cating that errorCode has been set; this allows the Tcl
interpreter to set errorCode to NONE if it receives an error
return when Tcl_SetErrorCode hasn't been called.
If the procedure Tcl_ResetResult is called, it clears all of
the state associated with errorInfo and errorCode (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.
SEE ALSO
Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp,
Tcl_ResetResult, Tcl_SetErrno
KEYWORDS
error, object, object result, stack, trace, variable
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |