Tcl_AddErrorInfo(3tcl)

📦
version 9.0.4 · 4 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 Tcl_AddErrorInfo(3tcl) — Tcl Library Procedures 💖

✨ NAME ✨

okay bestie, this page is the Tcl Library Procedures one about retrieving or recording info about errors and other return options. The whole squad is: Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo — retrieve or record information about errors and other return options. no cap. 💅

📜 SYNOPSIS 📜

#include <tcl.h>

Tcl_Obj *
Tcl_GetReturnOptions(interp, code)

int
Tcl_SetReturnOptions(interp, options)

Tcl_AddErrorInfo(interp, message)

Tcl_AppendObjToErrorInfo(interp, objPtr)

Tcl_AddObjErrorInfo(interp, message, length)

Tcl_SetObjErrorCode(interp, errorObjPtr)

Tcl_SetErrorCode(interp, element, element, ... (char *)NULL)

int
Tcl_GetErrorLine(interp)

Tcl_SetErrorLine(interp, lineNum)

const char *
Tcl_PosixError(interp)

Tcl_LogCommandInfo(interp, script, command, commandLength)

🎀 ARGUMENTS 🎀

  • Tcl_Interp *interp (in) — the interpreter where we’re recording all this info. main character interp energy. 💖
  • int code — the code returned from script evaluation. fr fr.
  • Tcl_Obj *options — a dictionary of return options. it’s giving options. ✨
  • const char *message (in) — for Tcl_AddErrorInfo, this is a conventional C string to append to the -errorinfo return option. For Tcl_AddObjErrorInfo, this points to the first byte of an array of length bytes containing a string to append to the -errorinfo return option. This byte array may contain embedded null bytes unless length is negative. embedded nulls are lowkey iconic. 🦋
  • Tcl_Obj *objPtr (in) — a message to be appended to the -errorinfo return option in the form of a Tcl_Obj value. obj-coded. 💅
  • Tcl_Size length (in) — the number of bytes to copy from message when appending to the -errorinfo return option. If negative, all bytes up to the first null byte are used. negative means “just go until null”. 🍓
  • Tcl_Obj *errorObjPtr (in) — the -errorcode return option will be set to this value. error code set, periodt. 👑
  • const char *element (in) — string to record as one element of the -errorcode return option. Last element argument must be (char *)NULL. do not forget the NULL terminator bestie. 😭
  • int lineNum — the line number of a script where an error occurred. line number realness. 🔥
  • const char *script (in) — pointer to first character in script containing command (must be <= command). pointer math but make it fashion. 🌈
  • const char *command (in) — pointer to first character in the command that generated the error; must point within the string given by script. stay in your string. 💀
  • Tcl_Size commandLength (in) — number of bytes in command; a negative value means use all bytes up to the first null byte. negative = vibes until null. 🙈

✨ DESCRIPTION ✨

okay bestie, so Tcl_SetReturnOptions and Tcl_GetReturnOptions are literally the C-interface twins of the return and catch commands respectively. same energy, different language, iykyk. 💅

🫶 the getter: Tcl_GetReturnOptions

Tcl_GetReturnOptions snatches the dictionary of return options out of an interpreter after a script has been evaluated. routines like Tcl_Eval are the ones you call to evaluate a script in an interpreter, and they hand back an integer completion code. those routines also leave two lil gifts behind in the interpreter: a result, and a dictionary of return options that came from the script evaluation. just like Tcl_GetObjResult grabs the result, Tcl_GetReturnOptions grabs the dictionary of return options.

you should pass that integer completion code as the code argument to Tcl_GetReturnOptions, fr fr — that's how you make sure all the required options actually show up in the dictionary.

specifically (get ready): a code value of TCL_ERROR guarantees that entries for the keys -errorinfo, -errorcode, and -errorline appear in the dictionary. also, the entries for the keys -code and -level get adjusted if necessary so they agree with the value of code.

the (Tcl_Obj *) that Tcl_GetReturnOptions returns points to an unshared Tcl_Obj with a reference count of zero. the way that it's unshared means you can write to the dictionary — add, remove, or overwrite any entries — with zero need to check for a shared value first. 🎀 but like any Tcl_Obj with reference count zero, it is up to the caller to arrange for its disposal with Tcl_DecrRefCount, or to add a reference to it via Tcl_IncrRefCount (or one of the many functions that call that, notably including Tcl_SetObjResult and Tcl_SetVar2Ex).

a classic usage of Tcl_GetReturnOptions is to retrieve the stack trace when script evaluation returns TCL_ERROR, like so:

int code = Tcl_EvalEx(interp, script, -1, 0);
if (code == TCL_ERROR) {
    Tcl_Obj *options = Tcl_GetReturnOptions(interp, code);
    Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
    Tcl_Obj *stackTrace;
    Tcl_IncrRefCount(key);
    Tcl_DictObjGet(NULL, options, key, &stackTrace);
    Tcl_DecrRefCount(key);
    /* Do something with stackTrace */
    Tcl_DecrRefCount(options);
}

💖 the setter: Tcl_SetReturnOptions

Tcl_SetReturnOptions sets the return options of interp to be options. and here's the vibe check: if options contains any invalid value for any key, TCL_ERROR gets returned, and the interp result is set to an appropriate error message. otherwise, you get back a completion code that's in agreement with the -code and -level keys in options. 🌈

as an example, Tcl's own return command could be implemented in terms of Tcl_SetReturnOptions like so:

if ((objc % 2) == 0) { /* explicit result argument */
    objc--;
    Tcl_SetObjResult(interp, objv[objc]);
}
return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));

(and no, it is not really implemented that way. internal access privileges allow for a more efficient alternative that meshes better with the bytecode compiler. main character shortcut energy only. 👑)

not me pointing out that a newly created Tcl_Obj may be passed in as the options argument with zero need to tend to any reference counting. this is analogous to Tcl_SetObjResult. slay. ✨

🌸 the frequently-used return options

while Tcl_SetReturnOptions is the general interface for setting any collection of return options, there are a handful of return options that get used constantly. most notably, the -errorinfo and -errorcode return options should be set properly when the command procedure of a command returns TCL_ERROR. the -errorline return option is also read by commands that evaluate scripts and wish to supply detailed error location information in the stack trace text they append to the -errorinfo option. Tcl provides several simpler interfaces to more directly set these return options, because of course it does, it's an icon. 💅

  • -errorinfo holds a stack trace of the operations that were in progress when an error occurred, and is intended to be human-readable. 🦋
  • -errorcode holds a Tcl list of items that are intended to be machine-readable. the first item in the -errorcode value identifies the class of error that occurred (e.g., POSIX means an error occurred in a POSIX system call) and additional elements hold additional pieces of information that depend on the class. see the manual entry on the errorCode variable for details on the various formats for the -errorcode option used by Tcl's built-in commands.

the -errorinfo option value is gradually built up as an error unwinds through the nested operations. each time an error code is returned to Tcl_Eval, or any of the routines that performs script evaluation, the procedure Tcl_AddErrorInfo is called to add additional text to the -errorinfo value 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's giving receipt trail. 🧚

🎀 adding your own info to -errorinfo

sometimes it's useful to add additional information to the -errorinfo value beyond what the script evaluation routines can supply automatically. Tcl_AddErrorInfo is your girl for this purpose: its message argument is an additional string to be appended to the -errorinfo option.

for example, when an error arises during the source command, the procedure Tcl_AddErrorInfo is called to record the name of the file being processed and the line number on which the error occurred. likewise, when an error arises during evaluation of a Tcl procedure, the procedure name and line number within the procedure are recorded, and so on. 📝

the best time to call Tcl_AddErrorInfo is just after a script evaluation routine has returned TCL_ERROR.

the value of the -errorline return option (retrieved via a call to Tcl_GetReturnOptions) often makes up a useful part of the message passed to Tcl_AddErrorInfo.

🦋 the other error-info friends

Tcl_AppendObjToErrorInfo is an alternative interface to the same functionality as Tcl_AddErrorInfo. Tcl_AppendObjToErrorInfo is called when the string value to be appended to the -errorinfo option is available as a Tcl_Obj instead of as a char array.

Tcl_AddObjErrorInfo is nearly identical to Tcl_AddErrorInfo, except that it has an additional length argument. this allows the message string to contain embedded null bytes.

bestie. this is essentially never a good idea. 😭 if the message needs to contain the null character U+0000, Tcl's usual internal encoding rules should be used to avoid the need for a null byte. if the Tcl_AddObjErrorInfo interface is used at all, it should be with a negative length value.

💜 setting -errorcode

the procedure Tcl_SetObjErrorCode is used to set the -errorcode return option to the list value errorObjPtr built up by the caller. Tcl_SetObjErrorCode is typically invoked just before returning an error. and if an error is returned without calling Tcl_SetObjErrorCode or Tcl_SetErrorCode, the Tcl interpreter automatically sets the -errorcode return option to NONE. no cap, it just does it for you. 🫶

the procedure Tcl_SetErrorCode is also used to set the -errorcode return option. however, it takes one or more strings to record instead of a value. otherwise, it is similar to Tcl_SetObjErrorCode in behavior.

⭐ -errorline shortcuts

the procedure Tcl_GetErrorLine is used to read the integer value of the -errorline return option without the overhead of a full call to Tcl_GetReturnOptions. likewise, Tcl_SetErrorLine sets the -errorline return option value. lowkey efficient queen behavior. 👑

🔥 POSIX errors

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 the -errorcode return option 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 the -errorcode value). 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

Tcl_LogCommandInfo 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 -errorinfo value, and the line number stored internally in the interpreter is set.

💀 the ancient lore (older Tcl releases)

in older releases of Tcl, there was no Tcl_GetReturnOptions routine. in its place, the global Tcl variables errorInfo and errorCode were the only place to retrieve the error information. much existing code written for older Tcl releases still accesses this information via those global variables.

it is important to realize that while reading from those global variables remains a supported way to access these return option values, it is important not to assume that writing to those global variables will properly set the corresponding return options. it has long been emphasized in this manual page that it is important to call the procedures described here rather than setting errorInfo or errorCode directly with Tcl_ObjSetVar2. 🙈

🍓 Tcl_ResetResult and the global variables

if the procedure Tcl_ResetResult is called, it clears all of the state of the interpreter associated with script evaluation, including the entire return options dictionary. in particular, the -errorinfo and -errorcode options are reset. if an error had occurred, the Tcl_ResetResult call will clear the error state to make it appear as if no error had occurred after all — the audacity, honestly. 💀

the global variables errorInfo and errorCode are not modified by Tcl_ResetResult, so they continue to hold a record of information about the most recent error seen in an interpreter.

🎀 REFERENCE COUNT MANAGEMENT 🎀

okay this section is literally the "who owns what" drama and we must respect it:

  • the result of Tcl_GetReturnOptions will have at least one reference to it from the Tcl interpreter. if you're not using it immediately, you should use Tcl_IncrRefCount to add your own reference.
  • the options argument to Tcl_SetReturnOptions will have a reference added by the Tcl interpreter; it may safely be called with a zero-reference value.
  • Tcl_AppendObjToErrorInfo only reads its objPtr argument; it does not modify its reference count at all.
  • the errorObjPtr argument to Tcl_SetObjErrorCode will have a reference added by the Tcl interpreter; it may safely be called with a zero-reference value.

👀 SEE ALSO 👀

Tcl_DecrRefCount(3tcl), Tcl_IncrRefCount(3tcl), Tcl_Interp(3tcl), Tcl_ResetResult(3tcl), Tcl_SetErrno(3tcl), errorCode(3tcl), errorInfo(3tcl)

🔑 KEYWORDS 🔑

error, value, value result, stack, trace, variable

and that's a wrap on Tcl_AddErrorInfo(3tcl) 💖 this lil page shipped with Tcl 8.5, and it's serving peak 8.5 energy. go forth and manage your reference counts responsibly bestie 🫶✨

📦 where this page comes from