Tcl_SaveInterpState(3)

💖 Tcl_SaveInterpState — the save/restore-your-interp-state manual, bestie edition 💖

okay so this is a page from the Tcl Library Procedures collection, and it's all about Tcl_SaveInterpState(3) — plus its two ride-or-die besties Tcl_RestoreInterpState and Tcl_DiscardInterpState. if you write C extensions for Tcl, this trio is about to become your whole personality. 🫶

---

✨ NAME ✨

Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState — save and restore an interpreter's state, no cap 💅

---

✨ SYNOPSIS ✨

the whole squad, together at last:

#include <tcl.h>

Tcl_InterpState
Tcl_SaveInterpState(interp, status)

int
Tcl_RestoreInterpState(interp, state)

Tcl_DiscardInterpState(state)

---

✨ ARGUMENTS ✨

• Tcl_Interp *interp (in) — the interpreter whose state you're trying to save. it's giving "main character interp". ✨
• int status (in) — the return code value you want stored as part of the interpreter state.
• Tcl_InterpState state (in) — the saved state token, the one you're gonna restore or discard. it's the little ticket you keep in your pocket. 🎀

---

✨ DESCRIPTION ✨

so these routines let a C procedure take a snapshot 📸 of the current state of an interpreter — so you can bring that exact vibe back after calling Tcl_Eval or literally any other routine that messes with the interpreter state. it's a save point. it's the checkpoint before the boss fight. iconic behavior, honestly.

Tcl_SaveInterpState stores a snapshot of the interpreter state in an opaque token returned by Tcl_SaveInterpState. that token value can then be handed back to either Tcl_RestoreInterpState or Tcl_DiscardInterpState, depending on whether the interp state is actually getting restored or not. and here's the slay part: as long as you call one of those latter two routines, Tcl handles the memory management for you. no manual cleanup. we love a service. 💖

Tcl_SaveInterpState takes a snapshot of those portions of interpreter state that make up the full result of script evaluation. that includes:

• the interpreter result
• the return code (passed in as the status argument)
• any return options, including -errorinfo and -errorcode when an error is in progress 😭

that snapshot comes back to you as an opaque token of type Tcl_InterpState. and important: the call to Tcl_SaveInterpState does not itself change the state of the interpreter. it just looks. it does not touch. respectful king. 👑

Tcl_RestoreInterpState accepts a Tcl_InterpState token that was previously returned by Tcl_SaveInterpState and restores the state of the interp to whatever was held in that snapshot. and the return value of Tcl_RestoreInterpState is the status value originally passed to Tcl_SaveInterpState back when the snapshot token was created. so it gives you the receipt back. 🧾

Tcl_DiscardInterpState is the one you call to release a Tcl_InterpState token previously returned by Tcl_SaveInterpState when that snapshot is not going to be restored to an interp. it's the "nah, we're not doing that anymore" button. 🙈

⚠️ okay bestie, this next part is the real one, do not scroll past it: the Tcl_InterpState token returned by Tcl_SaveInterpState must eventually be passed to either Tcl_RestoreInterpState or Tcl_DiscardInterpState to avoid a memory leak. 💀 and once that Tcl_InterpState token has been passed to one of them, the token is no longer valid and should not be used anymore. periodt. don't text it back. it's over. ✋

---

✨ KEYWORDS ✨

result, state, interp 🌸

---

and that's the whole page, bestie!! this one's from the Tcl manual, version 8.1, filed under Tcl_SaveInterpState(3) — go forth and snapshot responsibly. 🦋✨💜