Tcl_Panic(3tcl)

💖 Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc — report fatal error and abort 💖

okay bestie, gather round, because this is a Tcl Library Procedures page and it's literally about the moment everything goes 💀. Yes, it's Tcl_Panic(3tcl), and no, you can't manifest your way out of this one.

✨ SYNOPSIS ✨

#include <tcl.h>

void
Tcl_Panic(format, arg, arg, ...)

void
Tcl_PanicVA(format, argList)

void
Tcl_SetPanicProc(panicProc)

🌸 ARGUMENTS 🌸

• const char* format (in) — a printf-style format string. the blueprint, the vibe, the template 🎀
• arg (in) — the arguments that match up with the format string. one for one, no cap.
• va_list argList (in) — an argument list of arguments matching the format string. it must have been initialized using va_start, and cleared using va_end. like, mandatory mandatory 🫶
• Tcl_PanicProc *panicProc (in) — the procedure that reports the fatal error message and aborts. your custom panic handler, your moment to shine ✨

💅 DESCRIPTION 💅

so here's the tea. when the Tcl library notices that its internal data structures are in an inconsistent state, or that its C procedures got called in a way that straight-up contradicts their documentation, it calls Tcl_Panic to show a message describing the error and then abort the process. iconic of it, honestly.

the format argument is a format string describing how to format the rest of the arguments, arg, into an error message — following the exact same formatting rules used by the printf family of functions. and fun fact: the built-in Tcl command format uses those same formatting rules too. iykyk 😌

in a freshly loaded Tcl library, Tcl_Panic prints the formatted error message to the standard error file of the process, and then calls abort to terminate the process. Tcl_Panic does not return. periodt. 🔥

on Windows, when a debugger is running, the formatted error message gets sent to the debugger instead. and if the windows executable doesn't have a stderr channel (like, say, wish.exe), then a system dialog box is used to display the panic message. so very extra of it 💀

Tcl_SetPanicProc may be used to modify the behavior of Tcl_Panic. the panicProc argument should match the type Tcl_PanicProc:

typedef void Tcl_PanicProc(
        const char *format,
        arg, arg,...);

after Tcl_SetPanicProc returns, any future calls to Tcl_Panic will call panicProc, passing along the format and arg arguments. 🦋

⚠️ okay important one: panicProc should avoid making calls into the Tcl library, or into other libraries that may call the Tcl library — because the original call to Tcl_Panic is literally telling you the Tcl library is not in a state of reliable operation. do not go knocking on that door bestie, it is not okay in there 😭

the typical use of Tcl_SetPanicProc arranges for the error message to be displayed or reported in a manner more suitable for the application or the platform. glow-up for your error output, basically 👑

even though the primary callers of Tcl_Panic are the procedures of the Tcl library, Tcl_Panic is a public function and may be called by any extension or application that wishes to abort the process and have a panic message displayed the same way that panic messages from Tcl will be displayed. main character energy, you're allowed here 💜

Tcl_PanicVA is the same as Tcl_Panic except that instead of taking a variable number of arguments, it takes an argument list. same girl, different entrance 💅

🌈 SEE ALSO 🌈

• abort(3)
• printf(3)
• exec(3tcl)
• format(3tcl)

⭐ KEYWORDS ⭐

abort, fatal, error

and that's the whole page bestie!! 🎀 this one's from the <strong>Tcl 8.4</strong> era, filed under Tcl_Panic(3tcl), and it's the most dramatic thing in the whole library — it shows up, says its piece, and kills the process. no notes. obsessed. bye now 💖✨🦋