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

       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