bgerror(n)

💖 bgerror(n) — the Tcl Built-In Commands glow-up 💖

okay bestie, pull up a chair, we're talking about bgerror — the command that catches your background errors so they don't just silently ruin your whole day. no cap. 🫶

---

✨ NAME ✨

bgerror — the command that gets invoked to process background errors 💅

---

🎀 SYNOPSIS 🎀

bgerror message

---

🦋 DESCRIPTION 🦋

okay so here's the tea. Tcl Release 8.5 supports the interp bgerror command, and the way that works is it lets applications register, inside an interpreter, the exact command that's gonna handle background errors in that interpreter. very demure, very mindful. ✨

but in older releases of Tcl, that level of control simply did not exist 😭. applications could only control background-error handling by creating a command named bgerror in the global namespace of an interpreter. that was the whole vibe. and what follows in this doc describes the interface requirements of the bgerror command that an application might define to retain compatibility with pre-8.5 releases of Tcl.

💀 so if you're an application that only intends to support Tcl 8.5 and later, do not do all this. just make use of interp bgerror. periodt.

---

🌸 so what even IS bgerror 🌸

not me about to blow your mind: the bgerror command does not exist as a built-in part of Tcl. literally doesn't ship with it. instead, individual applications or users can define a bgerror command themselves (e.g. as a Tcl procedure) if they wish to handle background errors. it's giving DIY. 🎀

---

🌈 okay but what's a background error 🌈

a background error is one that occurs in an event handler or some other command that did not originate with the application. for example, if an error occurs while executing a command specified with the after command, then it is a background error. slay, now you know. 💅

for a non-background error, the error can simply be returned up through nested Tcl command evaluations until it reaches the top-level code in the application — and then the application can report the error in whatever way it wishes. easy. iconic. no drama. ✨

but when a background error occurs, the unwinding ends in the Tcl library, and there is no obvious way for Tcl to report the error. awk. 😭 that's the whole reason this command exists.

---

👑 what Tcl actually does when it detects one 👑

when Tcl detects a background error, it saves information about the error and invokes a handler command registered by interp bgerror later as an idle event handler. and the default handler command? it in turn calls the bgerror command. bestie chain of command fr fr. 🫶

before invoking bgerror, Tcl restores the errorInfo and errorCode variables to their values at the time the error occurred, and then it invokes bgerror with the error message as its only argument. that's it. one arg. don't be extra.

Tcl assumes that the application has implemented the bgerror command, and that the command will report the error in a way that makes sense for the application. and here's the kicker — Tcl will ignore any result returned by the bgerror command as long as no error is generated. it doesn't care what you return. it's not reading your reply. 🙈

⚠️ if another Tcl error occurs within the bgerror command (for example, because no bgerror command has been defined), then Tcl reports the error itself by writing a message to stderr. so like, define your command. please. 😭

---

🌟 multiple errors? we handle those 🌟

if several background errors accumulate before bgerror is invoked to process them, bgerror will be invoked once for each error, in the order they occurred. no skipping, no merging, in order, the way it should be.

but — plot twist — if bgerror returns with a break exception, then any remaining errors are skipped without calling bgerror. so you can tap out early if you want. 💀

---

🚨 a warning for the library girlies 🚨

if you are writing code that will be used by others as part of a package or other kind of library, consider avoiding bgerror. the reason for this is that the application programmer may also want to define a bgerror, or use other code that does, and thus will have trouble integrating your code. it's giving conflict. it's giving friction. don't do that to them. 🫶

---

⭐ EXAMPLE ⭐

this bgerror procedure appends errors to a file, with a timestamp. obsessed.

proc bgerror {message} {
    set timestamp [clock format [clock seconds]]
    set fl [open mylog.txt {WRONLY CREAT APPEND}]
    puts $fl "$timestamp: bgerror in $::argv '$message'"
    close $fl
}

---

👀 SEE ALSO 👀

• after(n)
• errorCode(n)
• errorInfo(n)
• interp(n)

---

🔑 KEYWORDS 🔑

• background error
• reporting

---

and that's the whole page bestie, you ate it up 💅✨ this was bgerror(n) from the Tcl Built-In Commands manual, Tcl version 7.5, dated 7.5 — mwah, go forth and handle your background errors responsibly, ily, bye 🎀🦋💖