Load(3tcl)

💖 Load(3tcl) — Tcl Library Procedures 💖

okay so bestie, welcome to Load(3tcl), the page about Tcl_LoadFile and Tcl_FindSymbol — aka how you do platform-independent dynamic library loading in Tcl. yes, the actual loading of the shared libraries. the real ones. 🦋

---

✨ NAME ✨

Tcl_LoadFile, Tcl_FindSymbol — platform-independent dynamic library loading 👑

---

✨ SYNOPSIS ✨

#include <tcl.h>

int
Tcl_LoadFile(interp, pathPtr, symbols, flags, procPtrs, loadHandlePtr)

void *
Tcl_FindSymbol(interp, loadHandle, symbol)

---

✨ ARGUMENTS ✨

• Tcl_Interp *interp (in) — the interpreter you wanna use for reporting error messages. she's the one who's gonna tell you what went wrong, so be nice to her. 💅
• Tcl_Obj *pathPtr (in) — the name of the file to load. if it's just a single name, then the library search path of the current environment is gonna be used to resolve it. iykyk 🎀
• const char *const symbols[] (in) — array of names of symbols to be resolved while the library loads, or NULL if there's no symbols to resolve. and listen — if you do give an array, the last entry in it must be NULL. no exceptions, bestie, the terminator is not optional. 🚨
• int flags (in) — normally this should be 0, but TCL_LOAD_GLOBAL or TCL_LOAD_LAZY, or honestly a combo of those two, is allowed as well. lowkey flexible of it.
• void *procPtrs (out) — points to an array that's gonna hold the addresses of the functions described in the symbols argument. should be NULL if no symbols are to be resolved. keep it consistent, queen. ✨
• Tcl_LoadHandle *loadHandlePtr (out) — points to a variable that'll hold the handle to the abstract token describing the library that has been loaded. it's giving receipt 🧾
• Tcl_LoadHandle loadHandle (in) — abstract token describing the library you wanna look up a symbol in. 🔍
• const char *symbol (in) — the name of the symbol to look up. that's it, that's the whole job. 🌸

---

✨ DESCRIPTION ✨

so Tcl_LoadFile loads a file from the filesystem — and yes, that includes potentially any virtual filesystem that's been installed, the way it just handles that for you — and hands you back a handle to it that you can use in further operations. iconic behaviour fr. 💜

the symbols array, if it's non-NULL, supplies a set of names of symbols (typically functions, but like, whatever) that must be resolved from the library, and those are gonna get stored in the array indicated by procPtrs. and if any of the symbols is not resolved? the loading of the file fails, with an error message left in the interpreter (if that one's non-NULL). no half-loads, no vibes-based resolution, she's strict. 💀

the result of Tcl_LoadFile is a standard Tcl error code. and the library can be unloaded with Tcl_FSUnloadFile when you're done with her. 🫶

Tcl_FindSymbol locates a symbol in a loaded library and returns it. if the symbol can't be found, it returns NULL and sets an error message in the given interp (if that's non-NULL). 😭

⚠️ and now the important part: note that it is unsafe to use this operation on a handle that has been passed to Tcl_FSUnloadFile. like, genuinely unsafe. don't do it. that handle is gone, bestie, let her rest. 💀

---

✨ REFERENCE COUNT MANAGEMENT ✨

the reference count of the pathPtr argument to Tcl_LoadFile may be incremented. as such, it should not be given a zero reference count value. protect the count. count protection squad. 🛡️✨

---

✨ SEE ALSO ✨

• Tcl_FSLoadFile(3tcl)
• Tcl_FSUnloadFile(3tcl)
• load(3tcl)
• unload(3tcl)

---

✨ KEYWORDS ✨

binary code, loading, shared library 🌈

---

and that's the whole page, bestie — no notes, she ate. 💅 this one's from the Tcl source, version 8.6, and it's filed under Load(3tcl). go load something responsibly, mwah 🎀💖🦋