Load(3)

✨ NAME ✨

Tcl_LoadFile, Tcl_FindSymbol — platform-independent dynamic library loading, aka this is Load(3) from the Tcl Library Procedures and it's giving "load a library literally anywhere, no platform drama" 💅

---

🌈 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 use for reporting error messages, bestie. She's the messenger 🫶
• Tcl_Obj *pathPtr (in) — the name of the file to load. If it's a single name, the library search path of the current environment gets used to resolve it 🔍
• const char *const symbols[] (in) — array of names of symbols to be resolved during the load of the library, or NULL if no symbols are to be resolved. If you do give an array, the last entry in it must be NULL. No exceptions, no cap 🚨
• int flags (in) — the value should normally be 0, but TCL_LOAD_GLOBAL or TCL_LOAD_LAZY or a combination of those two is allowed as well ✨
• void *procPtrs (out) — points to an array that will hold the addresses of the functions described in the symbols argument. Should be NULL if no symbols are to be resolved 📦
• Tcl_LoadHandle *loadHandlePtr (out) — points to a variable that will hold the handle to the abstract token describing the library that has been loaded 🎟️
• Tcl_LoadHandle loadHandle (in) — abstract token describing the library to look up a symbol in 🔎
• const char *symbol (in) — the name of the symbol to look up 👀

---

💖 DESCRIPTION 💖

Tcl_LoadFile loads a file from the filesystem (including potentially any virtual filesystem that has been installed, yes really, she's flexible like that 🌐) and provides a handle to it that may be used in further operations. The symbols array, if it's non-NULL, supplies a set of names of symbols (typically functions) that must be resolved from the library and which will be stored in the array indicated by procPtrs. If any of the symbols is not resolved, the loading of the file will fail with an error message left in the interpreter (if that is non-NULL). The result of Tcl_LoadFile is a standard Tcl error code. The library may be unloaded with Tcl_FSUnloadFile.

Tcl_FindSymbol locates a symbol in a loaded library and returns it. If the symbol cannot be found, it returns NULL and sets an error message in the given interp (if that is non-NULL).

⚠️ okay so real talk bestie, note this: it is unsafe to use this operation on a handle that has been passed to Tcl_FSUnloadFile. Like, genuinely unsafe. Do not do it. It's giving 💀 🔥

---

🔥 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. So like... don't do that. Periodt 💅

---

🦋 SEE ALSO 🦋

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

---

🌸 KEYWORDS 🌸

binary code, loading, shared library

---

and that's the whole page, bestie 🫶 this was Tcl 8.6, Load(3) — mwah, iconic, no notes 💖✨