MAN page from Old RedHat 6.X tcl-8.0.5-35.i386.rpm

Tcl_AddErrorInfo

Section: Tcl Library Procedures (3)
Updated: 7.5
Index

NAME

Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError - 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)char *Tcl_PosixError(interp)

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 bytescontaining a string to record in the errorInfo variable.This byte array may contain embedded null bytesunless 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 whensetting 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 variable.Last element argument must be NULL.

DESCRIPTION

These procedures are used to manipulate two Tcl global variablesthat hold information about errors.The variable errorInfo holds a stack trace of theoperations that were in progress when an error occurred,and is intended to be human-readable.The variable errorCode holds a list of items thatare intended to be machine-readable.The first item in errorCode identifies the class oferror that occurred(e.g. POSIX means an error occurred in a POSIX system call)and additional elements in errorCode hold additional piecesof information that depend on the class.See the Tcl overview manual entry for details on the variousformats for errorCode.

The errorInfo variable is gradually built up as anerror 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 addadditional text to errorInfo describing thecommand that was being executed when the error occurred.By the time the error has been passed all the way backto the application, it will contain a complete traceof the activity in progress when the error occurred.

It is sometimes useful to add additional information toerrorInfo beyond what can be supplied automaticallyby Tcl_EvalObj.Tcl_AddObjErrorInfo may be used for this purpose:its message and length arguments describe an additionalstring to be appended to errorInfo.For example, the source command calls Tcl_AddObjErrorInfoto record the name of the file being processed and theline number on which the error occurred;for Tcl procedures, the procedure name and line numberwithin the procedure are recorded, and so on.The best time to call Tcl_AddObjErrorInfo is just afterTcl_EvalObj has returned TCL_ERROR.In calling Tcl_AddObjErrorInfo, you may find it useful touse the errorLine field of the interpreter (see theTcl_Interp manual entry for details).

Tcl_AddErrorInfo resembles Tcl_AddObjErrorInfobut differs in initializing errorInfo from the stringvalue of the interpreter's resultif the error is just starting to be logged.It does not use the result as a Tcl objectso any embedded null characters in the resultwill cause information to be lost.It also takes a conventional C string in messageinstead of Tcl_AddObjErrorInfo's counted string.

The procedure Tcl_SetObjErrorCode is used to set theerrorCode variable. errorObjPtr contains a list objectbuilt up by the caller. errorCode is set to thisvalue. Tcl_SetObjErrorCode is typically invoked just before returning an error in an object command. If an error isreturned without calling Tcl_SetObjErrorCode orTcl_SetErrorCode the Tcl interpreter automatically setserrorCode to NONE.

The procedure Tcl_SetErrorCode is also used to set theerrorCode variable. However, it takes one or more strings torecord instead of an object. Otherwise, it is similar toTcl_SetObjErrorCode in behavior.

Tcl_PosixErrorsets the errorCode variable after an error in a POSIX kernel call.It reads the value of the errno C variable and callsTcl_SetErrorCode to set errorCode in the POSIX format.The caller must previously have called Tcl_SetErrno to seterrno; this is necessary on some platforms (e.g. Windows) where Tclis linked into an application as a shared library, or when the erroroccurs in a dynamically loaded extension. See the manual entry forTcl_SetErrno for more information.

Tcl_PosixError returns a human-readable diagnostic messagefor the error(this is the same value that will appear as the third elementin errorCode).It may be convenient to include this string as part of theerror message returned to the application inthe interpreter's result.

It is important to call the procedures described here rather thansetting errorInfo or errorCode directly withTcl_ObjSetVar2.The reason for this is that the Tcl interpreter keeps informationabout whether these procedures have been called.For example, the first time Tcl_AddObjErrorInfo is calledfor an error, it clears the existing value of errorInfoand adds the error message in the interpreter's result to the variablebefore appending message;in subsequent calls, it just appends the new message.When Tcl_SetErrorCode is called, it sets a flag indicatingthat errorCode has been set;this allows the Tcl interpreter to set errorCode to NONEif it receives an error returnwhen Tcl_SetErrorCode hasn't been called.

If the procedure Tcl_ResetResult is called,it clears all of the state associated witherrorInfo and errorCode(but it doesn't actually modify the variables).If an error had occurred, this will clear the error state tomake it appear as if no error had occurred after all.

KEYWORDS

error, object, object result, stack, trace, variable

This document was created byman2html,using the manual pages.