[25] | 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 |
---|