Tcl_PkgRequire(3tcl)

💖 Tcl_PkgRequire — the package version control page (from the Tcl Library Procedures, bestie) 💖

okay so welcome to Tcl_PkgRequire(3tcl), which is the manual page all about package version control at the C level. no cap, this is the one that lets your C code do the same little dance that package require does in Tcl script land. let's get into it 🫶

---

✨ NAME ✨

Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgRequireProc, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx — package version control, literally the whole squad 👑

---

🌸 SYNOPSIS 🌸

#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 the main character, everything happens in here.
• const char *name (in) — name of the package. just the name, bestie.
• const char *version (in) — a version specification string, described the same way as for package require.
• int exact (in) — non-zero means only the exact version you named in version is acceptable, periodt. zero means newer versions than version are also fine, as long as they've got the same major version number as version.
• const void *clientData (in) — an arbitrary value you wanna associate with the package. like a lil personality trait for it 💅
• void *clientDataPtr (out) — pointer to a place to store the value associated with the matching package. important: it's only changed if the pointer isn't NULL and the function completed successfully. also the storage can be any pointer type that's the same size as a void pointer.
• Tcl_Size objc (in) — number of requirements.
• Tcl_Obj* objv[] (in) — array of requirements. a whole lineup ✨

---

💜 DESCRIPTION 💜

These procedures are the C-level interfaces to Tcl's package and version management facilities. iykyk.

So like, mapping time:

• 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 procedures actually do, go read the documentation for those Tcl commands. this page is the vibes, that page is the lore.

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 lowkey note that this may be different than version. if an error occurs, they return NULL and leave an error message in the interpreter's result. 😭

Tcl_PkgProvide returns TCL_OK if it completes successfully; if an error occurs it returns TCL_ERROR and leaves an error message in the interpreter's result.

Tcl_PkgProvideEx, Tcl_PkgPresentEx and Tcl_PkgRequireEx are the ones that let you set and retrieve the client data associated with the package. in all other respects they are equivalent to the matching functions. so same energy, just with a lil extra 🎁

Tcl_PkgRequireProc is the form of package require that handles multiple requirements. the other forms are just there for backward compatibility and they translate their invocations into this form. iconic behavior honestly.

---

🌈 REFERENCE COUNT MANAGEMENT 🌈

heads up, bestie, this one's important!

The requirements values given (in the objv argument) to Tcl_PkgRequireProc must have non-zero reference counts. non-zero. not zero. fr fr, don't skip this one.

---

⭐ KEYWORDS ⭐

package, present, provide, require, version

---

🦋 SEE ALSO 🦋

• package(3tcl)
• Tcl_StaticLibrary(3tcl)

---

and that's the whole page, bestie, you ate it 💅✨ this was Tcl version 7.5, page Tcl_PkgRequire(3tcl), and if you read all the way down here then you're genuinely the main character. go require a package, slay, no cap 🎀💖🌸🫶