Tcl_InitStubs(3)

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 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 recompiled
          or relinked.

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

     The stubs mechanism accomplishes this by exporting  function
     tables  that define an interface to the Tcl API.  The exten-
     sion 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

Tcl                     Last change: 8.1                        1

Tcl_InitStubs(3)     Tcl Library Procedures      Tcl_InitStubs(3)

     mechanism with their extensions.

     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.5.a; on Windows  platforms,
          the library name is tclstub85.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                     Last change: 8.1                        2