Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tcl_InitStubs(3)	    Tcl	Library	Procedures	      Tcl_InitStubs(3)


       Tcl_InitStubs - initialize the Tcl stubs	mechanism

       #include	<tcl.h>

       const char *
       Tcl_InitStubs(interp, version, exact)

       Tcl_Interp *interp (in)		Tcl interpreter	handle.

       const char *version (in)		A  version string consisting of	one or
					more  decimal  numbers	separated   by

       int exact (in)			1  means that only the particular ver-
					sion specified by version  is  accept-
					able.	0  means  that	versions newer
					than version are  also	acceptable  as
					long  as they have the same major ver-
					sion number  as	 version.  Other  bits
					have no	effect.

       The Tcl stubs mechanism defines a way to	dynamically bind extensions to
       a particular Tcl	implementation at run time.  This provides two signif-
       icant benefits to Tcl users:

       1)   Extensions	that use the stubs mechanism can be loaded into	multi-
	    ple	versions of Tcl	without	being recompiled or relinked.

       2)   Extensions that use	the stubs mechanism can	be dynamically	loaded
	    into statically-linked Tcl applications.

       The stubs mechanism accomplishes	this by	exporting function 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 mechanism	with their extensions.

       Enabling	the stubs mechanism for	an extension  requires	the  following

       1)   Call  Tcl_InitStubs	 in the	extension before calling any other Tcl

       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 stan-
	    dard Tcl library.  For example, to use the Tcl  8.6	 ABI  on  Unix
	    platforms,	the  library name is libtclstub8.6.a; on Windows plat-
	    forms, the library name is tclstub86.lib.

       If the extension	also requires the Tk API, it must also	call  Tk_Init-
       Stubs  to  initialize the Tk stubs interface and	link with the Tk stubs
       libraries.  See the Tk_InitStubs	page for more information.

       Tcl_InitStubs attempts to initialize the	stub table pointers and	ensure
       that  the  correct  version of Tcl is loaded.  In addition to an	inter-
       preter handle, it accepts as arguments 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 ver-
       sion number as version; non-zero	means that only	the specified  version
       is  acceptable.	 Tcl_InitStubs	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



Tcl				      8.1		      Tcl_InitStubs(3)


Want to link to this manual page? Use this URL:

home | help