diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2018-01-02 21:03:49 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2018-01-02 21:03:49 (GMT) |
commit | 914501b5b992e7b6c7e0a4c958712a8ba9cab41c (patch) | |
tree | edbc059b9557d5fdb79e5a5c47889bc54708da53 /tcl8.6/doc/InitStubs.3 | |
parent | f88c190a01bc7f57e79dfaf91a3c0c48c2031549 (diff) | |
download | blt-914501b5b992e7b6c7e0a4c958712a8ba9cab41c.zip blt-914501b5b992e7b6c7e0a4c958712a8ba9cab41c.tar.gz blt-914501b5b992e7b6c7e0a4c958712a8ba9cab41c.tar.bz2 |
upgrade to tcl/tk 8.6.8
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 |