diff options
Diffstat (limited to 'tcl8.6/doc/InitStubs.3')
| -rw-r--r-- | tcl8.6/doc/InitStubs.3 | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/tcl8.6/doc/InitStubs.3 b/tcl8.6/doc/InitStubs.3 new file mode 100644 index 0000000..73c3437 --- /dev/null +++ b/tcl8.6/doc/InitStubs.3 @@ -0,0 +1,89 @@ +'\" +'\" Copyright (c) 1998-1999 Scriptics Corporation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +Tcl_InitStubs \- initialize the Tcl stubs mechanism +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +const char * +\fBTcl_InitStubs\fR(\fIinterp, version, exact\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp +.AP Tcl_Interp *interp in +Tcl interpreter handle. +.AP "const char" *version in +A version string consisting of one or more decimal numbers +separated by dots. +.AP int exact in +Non-zero means that only the particular version specified by +\fIversion\fR is acceptable. +Zero means that versions newer than \fIversion\fR are also +acceptable as long as they have the same major version number +as \fIversion\fR. +.BE +.SH INTRODUCTION +.PP +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: +.IP 1) 5 +Extensions that use the stubs mechanism can be loaded into +multiple versions of Tcl without being recompiled or +relinked. +.IP 2) 5 +Extensions that use the stubs mechanism can be dynamically +loaded into statically-linked Tcl applications. +.PP +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. +.PP +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. +.PP +Enabling the stubs mechanism for an extension requires the following +steps: +.IP 1) 5 +Call \fBTcl_InitStubs\fR in the extension before calling any other +Tcl functions. +.IP 2) 5 +Define the \fBUSE_TCL_STUBS\fR symbol. Typically, you would include the +\fB\-DUSE_TCL_STUBS\fR flag when compiling the extension. +.IP 3) 5 +Link the extension with the Tcl stubs library instead of the standard +Tcl library. For example, to use the Tcl 8.6 ABI on Unix platforms, +the library name is \fIlibtclstub8.6.a\fR; on Windows platforms, the +library name is \fItclstub86.lib\fR. +.PP +If the extension also requires the Tk API, it must also call +\fBTk_InitStubs\fR to initialize the Tk stubs interface and link +with the Tk stubs libraries. See the \fBTk_InitStubs\fR page for +more information. +.SH DESCRIPTION +\fBTcl_InitStubs\fR 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 \fIexact\fR 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 \fIversion\fR; +non-zero means that only the specified \fIversion\fR is acceptable. +\fBTcl_InitStubs\fR 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. +.SH "SEE ALSO" +Tk_InitStubs +.SH KEYWORDS +stubs |