90 lines
3.4 KiB
Groff
90 lines
3.4 KiB
Groff
|
'\"
|
||
|
|
'\" 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
|