Tcl_InitStubs(3)

💖 Tcl_InitStubs 💖

okay bestie, so this is a Tcl Library Procedure — literally the little ritual you do to wake up the stubs mechanism. yes it's giving very "first day of school" energy. let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <tcl.h>

const char *
Tcl_InitStubs(interp, version, exact)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the Tcl interpreter handle. your main character, your it-girl, your whole entire point of reference 💅
• const char *version (in) — a version string saying which minimal version of Tcl you'll accept. normally it's just "9.0". but if you're chill with both 8.6 and 9.0, you write "8.6-" ✨
• int exact (in) — 1 means only that exact version specified by version is accepted, no substitutes, periodt. 0 means versions newer than version are also accepted. and okay pay attention here: if version ends with -, higher major versions are accepted too — otherwise the major version has to match the one in version. any other bits in this flag? literally no effect, they just vibe there 🦋

---

🌸 INTRODUCTION 🌸

The Tcl stubs mechanism defines a way to dynamically bind extensions to a particular Tcl implementation at run time. and this is not just cute, it gives Tcl users two genuinely significant benefits:

1. Extensions that use the stubs mechanism can be loaded into multiple versions of Tcl without being recompiled or relinked, as long as the major Tcl version is the same. no rebuild era, we love to see it 🔥
2. Extensions that use the stubs mechanism can be dynamically loaded into statically-linked Tcl applications. iconic behaviour honestly.

The stubs mechanism pulls this off by exporting function tables that define an interface to the Tcl API. the extension then accesses the Tcl API through offsets into the function table, so there are no direct references to any of the Tcl library's symbols. and the bestie part? this redirection is transparent to the extension, so an extension writer can keep using all the public Tcl functions exactly as documented. no cap 💯

Also, the stubs mechanism requires no changes to applications incorporating Tcl interpreters. only the devs creating C-based Tcl extensions need to do anything to use stubs with their extensions.

Enabling the stubs mechanism for an extension is a whole three-step routine, and you're gonna slay it:

1. Call Tcl_InitStubs in the extension before calling any other Tcl functions. first. always first. that's the rule.
2. Define the USE_TCL_STUBS symbol. typically you'd include the -DUSE_TCL_STUBS flag when compiling the extension 🎀
3. Link the extension with the Tcl stubs library instead of the standard Tcl library. for example, to use the Tcl 9.0 ABI on Unix platforms, the library name is libtclstub.a; on Windows platforms, the library name is tclstub.lib. write that down, bestie 📝

And if the extension also requires the Tk API, it must also call Tk_InitStubs to initialize the Tk stubs interface and link with the Tk stubs libraries. see the Tk_InitStubs page for more info, iykyk ✨

---

💅 DESCRIPTION 💅

Tcl_InitStubs attempts to initialize the stub table pointers and make sure the correct version of Tcl is loaded. besides an interpreter handle, it takes a version number and a Boolean flag telling it whether the extension needs an exact version match or not.

If exact is 0, then versions newer than version are also accepted. and if version ends with -, higher major versions are accepted as well — otherwise the major version must be the same as in version. 1 means only the specified version is accepted, no wiggle room, no negotiation 🌈

version can be any construct as described for package require (the PACKAGE manual page, in the REQUIREMENT section). but heads up: multiple requirement strings, like the way package require lets you do, are not supported. one only, bestie.

Tcl_InitStubs returns a string containing the actual version of Tcl satisfying the request, or NULL if the Tcl version isn't accepted, doesn't support stubs, or literally any other error condition happened. NULL is the "it's not giving" response 😭

---

👀 SEE ALSO 👀

• Tk_InitStubs
• package

---

🔑 KEYWORDS 🔑

• stubs

---

and that's the whole page, bestie! this one comes straight from the Tcl docs, version 8.1, dated Tcl_InitStubs(3) — so yeah, she's an elder icon, still serving 💖 go call Tcl_InitStubs first, define USE_TCL_STUBS, link the stubs lib, and you're literally unstoppable 🦋✨