Manual Pages for UNIX Darwin command on man Tcl

Manual Pages for UNIX Darwin command on man Tcl_AddObjErrorInfo

TclAddErrorInfo(3) Tcl Library Procedures TclAddErrorInfo(3)

NAME

TclAddObjErrorInfo, TclAddErrorInfo, TclSetObjErrorCode, TclSetEr-

rorCode, TclSetErrorCodeVA, TclPosixError, TclLogCommandInfo -

record information about errors

SYNOPSIS

##iinncclluuddee <>

TTccllAAddddOObbjjEErrrroorrIInnffoo(interp, message, length) TTccllAAddddEErrrroorrIInnffoo(interp, message) TTccllSSeettOObbjjEErrrroorrCCooddee(interp, errorObjPtr) TTccllSSeettEErrrroorrCCooddee(interp, element, element, ... ((cchhaarr **)) NNUULLLL) TTccllSSeettEErrrroorrCCooddeeVVAA(interp, argList) CONST char * TTccllPPoossiixxEErrrroorr(interp) void TTccllLLooggCCoommmmaannddIInnffoo(interp, script, command, commandLength) AARRGGUUMMEENNTTSS

TclInterp *interp (in) Interpreter in which to record infor-

mation. char *message (in) For TTccllAAddddOObbjjEErrrroorrIInnffoo, this points to the first byte of an array of bytes containing a string to record in the eerrrroorrIInnffoo variable. This byte array may contain embedded null bytes unless length is negative. For

TTccllAAddddEErrrroorrIInnffoo, this is a conven-

tional C string to record in the eerrrroorrIInnffoo variable.

int length (in) The number of bytes to copy from mes-

sage when setting the eerrrroorrIInnffoo vari-

able. If negative, all bytes up to the first null byte are used. TclObj *errorObjPtr(in) This variable eerrrroorrCCooddee will be set to this value. char *element (in) String to record as one element of eerrrroorrCCooddee variable. Last element argument must be NULL. valist argList (in) An argument list which must have been initialized using TTCCLLVVAARRAARRGGSSSSTTAARRTT, and cleared using vvaaeenndd. CONST char *script (in) Pointer to first character in script

containing command (must be <= com-

mand) CONST char *command (in) Pointer to first character in command that generated the error

int commandLength(in) Number of bytes in command; -1 means

use all bytes up to first null byte

DESCRIPTION

These procedures are used to manipulate two Tcl global variables that hold information about errors. The variable eerrrroorrIInnffoo holds a stack trace of the operations that were in progress when an error occurred,

and is intended to be human-readable. The variable eerrrroorrCCooddee holds a

list of items that are intended to be machine-readable. The first item

in eerrrroorrCCooddee identifies the class of error that occurred (e.g. POSIX means an error occurred in a POSIX system call) and additional elements in eerrrroorrCCooddee hold additional pieces of information that depend on the class. See the Tcl overview manual entry for details on the various formats for eerrrroorrCCooddee. The eerrrroorrIInnffoo variable is gradually built up as an error unwinds through the nested operations. Each time an error code is returned to TTccllEEvvaallOObbjjEExx (or TTccllEEvvaall, which calls TTccllEEvvaallOObbjjEExx) it calls the procedure TTccllAAddddOObbjjEErrrroorrIInnffoo to add additional text to eerrrroorrIInnffoo 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 applica-

tion, it will contain a complete trace of the activity in progress when the error occurred. It is sometimes useful to add additional information to eerrrroorrIInnffoo

beyond what can be supplied automatically by TTccllEEvvaallOObbjjEExx. TTccllAAddddOObb-

jjEErrrroorrIInnffoo may be used for this purpose: its message and length argu-

ments describe an additional string to be appended to eerrrroorrIInnffoo. For example, the ssoouurrccee command calls TTccllAAddddOObbjjEErrrroorrIInnffoo 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 TTccllAAddddOObbjjEErrrroorrIInnffoo is just after TTccllEEvvaallOObbjjEExx has returned TTCCLLEERRRROORR. In calling TTccllAAddddOObbjjEErrrroorrIInnffoo, you may find it useful to use the eerrrroorrLLiinnee field of the interpreter (see the TTccllIInntteerrpp manual entry for details).

TTccllAAddddEErrrroorrIInnffoo resembles TTccllAAddddOObbjjEErrrroorrIInnffoo but differs in initial-

izing eerrrroorrIInnffoo 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 mes-

sage instead of TTccllAAddddOObbjjEErrrroorrIInnffoo's counted string.

The procedure TTccllSSeettOObbjjEErrrroorrCCooddee is used to set the eerrrroorrCCooddee vari-

able. errorObjPtr contains a list object built up by the caller. eerrrroorr-

CCooddee is set to this value. TTccllSSeettOObbjjEErrrroorrCCooddee is typically invoked just before returning an error in an object command. If an error is returned without calling TTccllSSeettOObbjjEErrrroorrCCooddee or TTccllSSeettEErrrroorrCCooddee the Tcl interpreter automatically sets eerrrroorrCCooddee to NNOONNEE.

The procedure TTccllSSeettEErrrroorrCCooddee is also used to set the eerrrroorrCCooddee vari-

able. However, it takes one or more strings to record instead of an object. Otherwise, it is similar to TTccllSSeettOObbjjEErrrroorrCCooddee in behavior. TTccllSSeettEErrrroorrCCooddeeVVAA is the same as TTccllSSeettEErrrroorrCCooddee except that instead of taking a variable number of arguments it takes an argument list. TTccllPPoossiixxEErrrroorr sets the eerrrroorrCCooddee variable after an error in a POSIX kernel call. It reads the value of the eerrrrnnoo C variable and calls TTccllSSeettEErrrroorrCCooddee to set eerrrroorrCCooddee in the PPOOSSIIXX format. The caller must previously have called TTccllSSeettEErrrrnnoo to set eerrrrnnoo; 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 TTccllSSeettEErrrrnnoo for more information.

TTccllPPoossiixxEErrrroorr returns a human-readable diagnostic message for the

error (this is the same value that will appear as the third element in eerrrroorrCCooddee). It may be convenient to include this string as part of the error message returned to the application in the interpreter's result. TTccllLLooggCCoommmmaannddIInnffoo 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 eerrrroorrIInnffoo variable, and the line number stored

internally in the interpreter is set. On the first call to TTccllLLooggCCoomm-

mmaannddIInnffoo or TTccllAAddddOObbjjEErrrroorrIInnffoo since an error occurred, the old infor-

mation in eerrrroorrIInnffoo is deleted.

It is important to call the procedures described here rather than set-

ting eerrrroorrIInnffoo or eerrrroorrCCooddee directly with TTccllOObbjjSSeettVVaarr22. The reason for this is that the Tcl interpreter keeps information about whether these procedures have been called. For example, the first time TTccllAAddddOObbjjEErrrroorrIInnffoo is called for an error, it clears the existing value of eerrrroorrIInnffoo and adds the error message in the interpreter's result to the variable before appending message; in subsequent calls, it just appends the new message. When TTccllSSeettEErrrroorrCCooddee is called, it sets a flag indicating that eerrrroorrCCooddee has been set; this allows the Tcl interpreter to set eerrrroorrCCooddee to NNOONNEE if it receives an error return when TTccllSSeettEErrrroorrCCooddee hasn't been called. If the procedure TTccllRReesseettRReessuulltt is called, it clears all of the state associated with eerrrroorrIInnffoo and eerrrroorrCCooddee (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.