This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

This manual page is associated with the Mac OS X developer tools. The software or headers described may not be present on your Mac OS X installation until you install the developer tools package. This package is available on your Mac OS X installation DVD, and the latest versions can be downloaded from developer.apple.com.

For more information about the manual page format, see the manual page for manpages(5).

Tcl_InitStubs(3)                           Tcl Library Procedures                           Tcl_InitStubs(3)



____________________________________________________________________________________________________________

NAME
       Tcl_InitStubs - initialize the Tcl stubs mechanism

SYNOPSIS
       #include <tcl.h>

       CONST char *
       Tcl_InitStubs(interp, version, exact)

ARGUMENTS
       Tcl_Interp   *interp   (in)      Tcl interpreter handle.

       CONST char   *version  (in)      A version string consisting of one or more decimal 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
                                        acceptable 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 implementa-tion implementation
       tion 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 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 devel-opers developers
       opers creating C-based Tcl extensions need to take steps to use the stubs mechanism with their exten-sions. extensions.
       sions.

       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 platforms, 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 pointers and ensure that the correct version of
       Tcl is loaded.  In addition to an interpreter 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  version 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 occurred.

SEE ALSO
       Tk_InitStubs

KEYWORDS
       stubs



Tcl                                                  8.1                                    Tcl_InitStubs(3)