--- name: "AddErrInfo" section: "3tcl" platform: "linux" package: "tcl8.3-doc" version: "8.3.5-13" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/AddErrInfo/3tcl" --- # AddErrInfo(3tcl) record information about errors ``` ``` ## NAME Tcl\_AddObjErrorInfo, Tcl\_AddErrorInfo, Tcl\_SetObjErrorCode, Tcl\_SetErrorCode, Tcl\_SetErrorCodeVA, Tcl\_PosixError, Tcl\_LogCommandInfo - record information about errors ## SYNOPSIS ``` #include 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** variable. Last *element* argument 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 command (must be \<= command) - 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 **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 system call) and additional elements in **errorCode** hold additional 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\_EvalObjEx** (or **Tcl\_Eval**, which calls **Tcl\_EvalObjEx**) 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\_EvalObjEx**. **Tcl\_AddObjErrorInfo** may be used for this purpose: its *message* and *length* arguments describe an additional 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\_EvalObjEx** 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 information 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 **errorCode** variable. *errorObjPtr* contains a list object built up by the caller. **errorCode** is set to this value. **Tcl\_SetObjErrorCode** is typically invoked just before returning 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 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 **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** variable, and the line number stored internally in the interpreter is set. On the first call to **Tcl\_LogCommandInfo** or **Tcl\_AddObjErrorInfo** since an error occurred, the old information 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 interpreter 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 *message*. When **Tcl\_SetErrorCode** is called, it sets a flag indicating 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