Tcl_PkgRequire(3)

✨ Tcl_PkgRequire — package version control, but make it a vibe ✨

okay bestie, so this is a page from the Tcl Library Procedures manual, and it's all about the C-level functions that let you do package stuff. The whole girlboss squad is here: Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgRequireProc, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, and Tcl_PkgProvideEx. Seven icons. One page. Let's go 💅

---

🎀 SYNOPSIS 🎀

like, here's how you call them, no cap:

#include <tcl.h>

const char *
Tcl_PkgRequire(interp, name, version, exact)

const char *
Tcl_PkgRequireEx(interp, name, version, exact, clientDataPtr)

int
Tcl_PkgRequireProc(interp, name, objc, objv, clientDataPtr)

const char *
Tcl_PkgPresent(interp, name, version, exact)

const char *
Tcl_PkgPresentEx(interp, name, version, exact, clientDataPtr)

int
Tcl_PkgProvide(interp, name, version)

int
Tcl_PkgProvideEx(interp, name, version, clientData)

---

🫶 ARGUMENTS 🫶

• Tcl_Interp *interp (in) — the interpreter where the package is needed or available. it's giving home base 🏠
• const char *name (in) — the package's name. yeah, just the name.
• const char *version (in) — a version specification string, exactly the kind described for package require. so like, it knows what you mean.
• int exact (in) — non-zero means ONLY that one specific version from version is acceptable, periodt. zero means newer versions are also fine, as long as they have the same major version number as version. lowkey flexible ✨
• const void *clientData (in) — an arbitrary value you want associated with the package. anything. no judgement 🍓
• void *clientDataPtr (out) — a pointer to a place where the value associated with the matching package gets stored. it is only changed if the pointer is not NULL and the function completed successfully. the storage can be any pointer type with the same size as a void pointer.
• Tcl_Size objc (in) — the number of requirements. like how many asks you're making.
• Tcl_Obj* objv[] (in) — an array of requirements. the whole list, bestie.

---

💖 DESCRIPTION 💖

so these procedures are the C-level interfaces to Tcl's package and version management facilities. C-level besties for the Tcl-level slay.

• Tcl_PkgRequire is equivalent to the package require command.
• Tcl_PkgPresent is equivalent to the package present command.
• Tcl_PkgProvide is equivalent to the package provide command.

for the deets on what these actually do, go read the docs for the Tcl commands. they spill the tea there 📖

if Tcl_PkgPresent or Tcl_PkgRequire complete successfully, they return a pointer to the version string for the version of the package that is provided in the interpreter — and heads up, that version may be different than version 👀. if an error happens, they return NULL and leave an error message sitting in the interpreter's result.

Tcl_PkgProvide returns TCL_OK when it completes successfully. if an error occurs it returns TCL_ERROR and leaves an error message in the interpreter's result. no in-between, we don't do that here.

Tcl_PkgProvideEx, Tcl_PkgPresentEx, and Tcl_PkgRequireEx let you set and retrieve the client data associated with the package. in all other respects they are equivalent to the matching functions. same energy, extra feature 💅

Tcl_PkgRequireProc is the form of package require that handles multiple requirements. the other forms are there for backward compatibility and translate their invocations to this form. so it's kind of the main character and the others are just doing their little translations 🫡

---

🔥 REFERENCE COUNT MANAGEMENT 🔥

okay this is the part where you pay attention because it's a real caveat:

The requirement values given (in the objv argument) to Tcl_PkgRequireProc must have non-zero reference counts. non-zero. periodt.

---

🌈 KEYWORDS 🌈

package, present, provide, require, version

---

🌸 SEE ALSO 🌸

• package(n)
• Tcl_StaticLibrary(3)

---

and that's the whole page, bestie!! this was Tcl 7.5, dated... well, that's the version and date footer energy right there, and the manual page signs off as Tcl_PkgRequire(3) 💜 go forth and require your packages responsibly 🦋✨