1 | '\" |
---|
2 | '\" Copyright (c) 1998-1999 Scriptics Corporation |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" RCS: @(#) $Id: InitStubs.3,v 1.11 2004/10/07 15:15:38 dkf Exp $ |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures" |
---|
11 | .BS |
---|
12 | .SH NAME |
---|
13 | Tcl_InitStubs \- initialize the Tcl stubs mechanism |
---|
14 | .SH SYNOPSIS |
---|
15 | .nf |
---|
16 | \fB#include <tcl.h>\fR |
---|
17 | .sp |
---|
18 | const char * |
---|
19 | \fBTcl_InitStubs\fR(\fIinterp, version, exact\fR) |
---|
20 | .SH ARGUMENTS |
---|
21 | .AS Tcl_Interp *interp |
---|
22 | .AP Tcl_Interp *interp in |
---|
23 | Tcl interpreter handle. |
---|
24 | .AP "const char" *version in |
---|
25 | A version string consisting of one or more decimal numbers |
---|
26 | separated by dots. |
---|
27 | .AP int exact in |
---|
28 | Non-zero means that only the particular version specified by |
---|
29 | \fIversion\fR is acceptable. |
---|
30 | Zero means that versions newer than \fIversion\fR are also |
---|
31 | acceptable as long as they have the same major version number |
---|
32 | as \fIversion\fR. |
---|
33 | .BE |
---|
34 | .SH INTRODUCTION |
---|
35 | .PP |
---|
36 | The Tcl stubs mechanism defines a way to dynamically bind |
---|
37 | extensions to a particular Tcl implementation at run time. |
---|
38 | This provides two significant benefits to Tcl users: |
---|
39 | .IP 1) 5 |
---|
40 | Extensions that use the stubs mechanism can be loaded into |
---|
41 | multiple versions of Tcl without being recompiled or |
---|
42 | relinked. |
---|
43 | .IP 2) 5 |
---|
44 | Extensions that use the stubs mechanism can be dynamically |
---|
45 | loaded into statically-linked Tcl applications. |
---|
46 | .PP |
---|
47 | The stubs mechanism accomplishes this by exporting function tables |
---|
48 | that define an interface to the Tcl API. The extension then accesses |
---|
49 | the Tcl API through offsets into the function table, so there are no |
---|
50 | direct references to any of the Tcl library's symbols. This |
---|
51 | redirection is transparent to the extension, so an extension writer |
---|
52 | can continue to use all public Tcl functions as documented. |
---|
53 | .PP |
---|
54 | The stubs mechanism requires no changes to applications incorporating |
---|
55 | Tcl interpreters. Only developers creating C-based Tcl extensions |
---|
56 | need to take steps to use the stubs mechanism with their extensions. |
---|
57 | .PP |
---|
58 | Enabling the stubs mechanism for an extension requires the following |
---|
59 | steps: |
---|
60 | .IP 1) 5 |
---|
61 | Call \fBTcl_InitStubs\fR in the extension before calling any other |
---|
62 | Tcl functions. |
---|
63 | .IP 2) 5 |
---|
64 | Define the \fBUSE_TCL_STUBS\fR symbol. Typically, you would include the |
---|
65 | \fB\-DUSE_TCL_STUBS\fR flag when compiling the extension. |
---|
66 | .IP 3) 5 |
---|
67 | Link the extension with the Tcl stubs library instead of the standard |
---|
68 | Tcl library. On Unix platforms, the library name is |
---|
69 | \fIlibtclstub8.1.a\fR; on Windows platforms, the library name is |
---|
70 | \fItclstub81.lib\fR. |
---|
71 | .PP |
---|
72 | If the extension also requires the Tk API, it must also call |
---|
73 | \fBTk_InitStubs\fR to initialize the Tk stubs interface and link |
---|
74 | with the Tk stubs libraries. See the \fBTk_InitStubs\fR page for |
---|
75 | more information. |
---|
76 | .SH DESCRIPTION |
---|
77 | \fBTcl_InitStubs\fR attempts to initialize the stub table pointers |
---|
78 | and ensure that the correct version of Tcl is loaded. In addition |
---|
79 | to an interpreter handle, it accepts as arguments a version number |
---|
80 | and a Boolean flag indicating whether the extension requires |
---|
81 | an exact version match or not. If \fIexact\fR is 0, then the |
---|
82 | extension is indicating that newer versions of Tcl are acceptable |
---|
83 | as long as they have the same major version number as \fIversion\fR; |
---|
84 | non-zero means that only the specified \fIversion\fR is acceptable. |
---|
85 | \fBTcl_InitStubs\fR returns a string containing the actual version |
---|
86 | of Tcl satisfying the request, or NULL if the Tcl version is not |
---|
87 | acceptable, does not support stubs, or any other error condition occurred. |
---|
88 | .SH "SEE ALSO" |
---|
89 | Tk_InitStubs |
---|
90 | .SH KEYWORDS |
---|
91 | stubs |
---|