1 | '\" |
---|
2 | '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. |
---|
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: load.n,v 1.22 2007/12/13 15:22:32 dgp Exp $ |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH load n 7.5 Tcl "Tcl Built-In Commands" |
---|
11 | .BS |
---|
12 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
13 | .SH NAME |
---|
14 | load \- Load machine code and initialize new commands |
---|
15 | .SH SYNOPSIS |
---|
16 | \fBload \fIfileName\fR |
---|
17 | .br |
---|
18 | \fBload \fIfileName packageName\fR |
---|
19 | .br |
---|
20 | \fBload \fIfileName packageName interp\fR |
---|
21 | .BE |
---|
22 | |
---|
23 | .SH DESCRIPTION |
---|
24 | .PP |
---|
25 | This command loads binary code from a file into the |
---|
26 | application's address space and calls an initialization procedure |
---|
27 | in the package to incorporate it into an interpreter. \fIfileName\fR |
---|
28 | is the name of the file containing the code; its exact form varies |
---|
29 | from system to system but on most systems it is a shared library, |
---|
30 | such as a \fB.so\fR file under Solaris or a DLL under Windows. |
---|
31 | \fIpackageName\fR is the name of the package, and is used to |
---|
32 | compute the name of an initialization procedure. |
---|
33 | \fIinterp\fR is the path name of the interpreter into which to load |
---|
34 | the package (see the \fBinterp\fR manual entry for details); |
---|
35 | if \fIinterp\fR is omitted, it defaults to the |
---|
36 | interpreter in which the \fBload\fR command was invoked. |
---|
37 | .PP |
---|
38 | Once the file has been loaded into the application's address space, |
---|
39 | one of two initialization procedures will be invoked in the new code. |
---|
40 | Typically the initialization procedure will add new commands to a |
---|
41 | Tcl interpreter. |
---|
42 | The name of the initialization procedure is determined by |
---|
43 | \fIpackageName\fR and whether or not the target interpreter |
---|
44 | is a safe one. For normal interpreters the name of the initialization |
---|
45 | procedure will have the form \fIpkg\fB_Init\fR, where \fIpkg\fR |
---|
46 | is the same as \fIpackageName\fR except that the first letter is |
---|
47 | converted to upper case and all other letters |
---|
48 | are converted to lower case. For example, if \fIpackageName\fR is |
---|
49 | \fBfoo\fR or \fBFOo\fR, the initialization procedure's name will |
---|
50 | be \fBFoo_Init\fR. |
---|
51 | .PP |
---|
52 | If the target interpreter is a safe interpreter, then the name |
---|
53 | of the initialization procedure will be \fIpkg\fB_SafeInit\fR |
---|
54 | instead of \fIpkg\fB_Init\fR. |
---|
55 | The \fIpkg\fB_SafeInit\fR function should be written carefully, so that it |
---|
56 | initializes the safe interpreter only with partial functionality provided |
---|
57 | by the package that is safe for use by untrusted code. For more information |
---|
58 | on Safe\-Tcl, see the \fBsafe\fR manual entry. |
---|
59 | .PP |
---|
60 | The initialization procedure must match the following prototype: |
---|
61 | .CS |
---|
62 | typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); |
---|
63 | .CE |
---|
64 | The \fIinterp\fR argument identifies the interpreter in which the |
---|
65 | package is to be loaded. The initialization procedure must return |
---|
66 | \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed |
---|
67 | successfully; in the event of an error it should set the interpreter's result |
---|
68 | to point to an error message. The result of the \fBload\fR command |
---|
69 | will be the result returned by the initialization procedure. |
---|
70 | .PP |
---|
71 | The actual loading of a file will only be done once for each \fIfileName\fR |
---|
72 | in an application. If a given \fIfileName\fR is loaded into multiple |
---|
73 | interpreters, then the first \fBload\fR will load the code and |
---|
74 | call the initialization procedure; subsequent \fBload\fRs will |
---|
75 | call the initialization procedure without loading the code again. |
---|
76 | .VS 8.5 |
---|
77 | For Tcl versions lower than 8.5, it is not possible to unload or reload a |
---|
78 | package. From version 8.5 however, the \fBunload\fR command allows the unloading |
---|
79 | of libraries loaded with \fBload\fR, for libraries that are aware of the |
---|
80 | Tcl's unloading mechanism. |
---|
81 | .VE 8.5 |
---|
82 | .PP |
---|
83 | The \fBload\fR command also supports packages that are statically |
---|
84 | linked with the application, if those packages have been registered |
---|
85 | by calling the \fBTcl_StaticPackage\fR procedure. |
---|
86 | If \fIfileName\fR is an empty string, then \fIpackageName\fR must |
---|
87 | be specified. |
---|
88 | .PP |
---|
89 | If \fIpackageName\fR is omitted or specified as an empty string, |
---|
90 | Tcl tries to guess the name of the package. |
---|
91 | This may be done differently on different platforms. |
---|
92 | The default guess, which is used on most UNIX platforms, is to |
---|
93 | take the last element of \fIfileName\fR, strip off the first |
---|
94 | three characters if they are \fBlib\fR, and use any following |
---|
95 | alphabetic and underline characters as the module name. |
---|
96 | For example, the command \fBload libxyz4.2.so\fR uses the module |
---|
97 | name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the |
---|
98 | module name \fBlast\fR. |
---|
99 | .PP |
---|
100 | If \fIfileName\fR is an empty string, then \fIpackageName\fR must |
---|
101 | be specified. |
---|
102 | The \fBload\fR command first searches for a statically loaded package |
---|
103 | (one that has been registered by calling the \fBTcl_StaticPackage\fR |
---|
104 | procedure) by that name; if one is found, it is used. |
---|
105 | Otherwise, the \fBload\fR command searches for a dynamically loaded |
---|
106 | package by that name, and uses it if it is found. If several |
---|
107 | different files have been \fBload\fRed with different versions of |
---|
108 | the package, Tcl picks the file that was loaded first. |
---|
109 | .SH "PORTABILITY ISSUES" |
---|
110 | .TP |
---|
111 | \fBWindows\fR\0\0\0\0\0 |
---|
112 | . |
---|
113 | When a load fails with |
---|
114 | .QW "library not found" |
---|
115 | error, it is also possible |
---|
116 | that a dependent library was not found. To see the dependent libraries, |
---|
117 | type |
---|
118 | .QW "dumpbin -imports <dllname>" |
---|
119 | in a DOS console to see what the library must import. |
---|
120 | When loading a DLL in the current directory, Windows will ignore |
---|
121 | .QW ./ |
---|
122 | as a path specifier and use a search heuristic to find the DLL instead. |
---|
123 | To avoid this, load the DLL with: |
---|
124 | .CS |
---|
125 | \fBload\fR [file join [pwd] mylib.DLL] |
---|
126 | .CE |
---|
127 | .SH BUGS |
---|
128 | .PP |
---|
129 | If the same file is \fBload\fRed by different \fIfileName\fRs, it will |
---|
130 | be loaded into the process's address space multiple times. The |
---|
131 | behavior of this varies from system to system (some systems may |
---|
132 | detect the redundant loads, others may not). |
---|
133 | .SH EXAMPLE |
---|
134 | The following is a minimal extension: |
---|
135 | .PP |
---|
136 | .CS |
---|
137 | #include <tcl.h> |
---|
138 | #include <stdio.h> |
---|
139 | static int fooCmd(ClientData clientData, |
---|
140 | Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) { |
---|
141 | printf("called with %d arguments\en", objc); |
---|
142 | return TCL_OK; |
---|
143 | } |
---|
144 | int Foo_Init(Tcl_Interp *interp) { |
---|
145 | if (Tcl_InitStubs(interp, "8.1", 0) == NULL) { |
---|
146 | return TCL_ERROR; |
---|
147 | } |
---|
148 | printf("creating foo command"); |
---|
149 | Tcl_CreateObjCommand(interp, "foo", fooCmd, NULL, NULL); |
---|
150 | return TCL_OK; |
---|
151 | } |
---|
152 | .CE |
---|
153 | .PP |
---|
154 | When built into a shared/dynamic library with a suitable name |
---|
155 | (e.g. \fBfoo.dll\fR on Windows, \fBlibfoo.so\fR on Solaris and Linux) |
---|
156 | it can then be loaded into Tcl with the following: |
---|
157 | .PP |
---|
158 | .CS |
---|
159 | # Load the extension |
---|
160 | switch $tcl_platform(platform) { |
---|
161 | windows { |
---|
162 | \fBload\fR [file join [pwd] foo.dll] |
---|
163 | } |
---|
164 | unix { |
---|
165 | \fBload\fR [file join [pwd] libfoo[info sharedlibextension]] |
---|
166 | } |
---|
167 | } |
---|
168 | |
---|
169 | # Now execute the command defined by the extension |
---|
170 | foo |
---|
171 | .CE |
---|
172 | |
---|
173 | .SH "SEE ALSO" |
---|
174 | info sharedlibextension, Tcl_StaticPackage(3), safe(n) |
---|
175 | |
---|
176 | .SH KEYWORDS |
---|
177 | binary code, loading, safe interpreter, shared library |
---|