NAME
Tcl_InitStubs - initialize the Tcl stubs mechanism
SYNOPSIS
#include <tcl.h>
char *
Tcl_InitStubs(interp, version, exact)
ARGUMENTS
Tcl_Interp *interp (in) Tcl interpreter handle.
char *version (in) A version string consist
ing of one or more deci
mal numbers separated by
dots.
int exact (in) Non-zero means that only
the particular version
specified by version is
acceptable. Zero means
that versions newer than
version are also accept
able as long as they have
the same major version
number as version.
_________________________________________________________________
INTRODUCTION
The Tcl stubs mechanism defines a way to dynamically bind
extensions to a particular Tcl implementation at run time.
This provides two significant benefits to Tcl users:
1) Extensions that use the stubs mechanism can be loaded
into multiple versions of Tcl without being recom
piled or relinked.
2) Extensions that use the stubs mechanism can be dynam
ically loaded into statically-linked Tcl applica
tions.
The stubs mechanism accomplishes this by exporting func
tion 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. This redirection is
transparent to the extension, so an extension writer can
continue to use all public Tcl functions as documented.
The stubs mechanism requires no changes to applications
incorporating Tcl interpreters. Only developers creating
C-based Tcl extensions need to take steps to use the stubs
Enabling the stubs mechanism for an extension requires the
following steps:
1) Call Tcl_InitStubs in the extension before calling
any other Tcl functions.
2) Define the USE_TCL_STUBS symbol. Typically, you
would 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. On Unix platforms, the
library name is libtclstub8.1.a; on Windows plat
forms, the library name is tclstub81.lib.
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 information.
DESCRIPTION
Tcl_InitStubs attempts to initialize the stub table point
ers and ensure that the correct version of Tcl is loaded.
In addition to an interpreter handle, it accepts as argu
ments a version number and a Boolean flag indicating
whether the extension requires an exact version match or
not. If exact is 0, then the extension is indicating that
newer versions of Tcl are acceptable as long as they have
the same major version number as version; non-zero means
that only the specified version is acceptable. Tcl_Init
Stubs returns a string containing the actual version of
Tcl satisfying the request, or NULL if the Tcl version is
not acceptable, does not support stubs, or any other error
condition occurred.
SEE ALSO
Tk_InitStubs
KEYWORDS
stubs
Man(1) output converted with
man2html