1load(n) Tcl Built-In Commands load(n)
2______________________________________________________________________________
6
8 load - Load machine code and initialize new commands
9
11 load ?-global? ?-lazy? ?--? fileName
12 load ?-global? ?-lazy? ?--? fileName prefix
13 load ?-global? ?-lazy? ?--? fileName prefix interp
14______________________________________________________________________________
15
17 This command loads binary code from a file into the application's ad‐
18 dress space and calls an initialization procedure in the library to in‐
19 corporate it into an interpreter. fileName is the name of the file
20 containing the code; its exact form varies from system to system but
21 on most systems it is a shared library, such as a .so file under So‐
22 laris or a DLL under Windows. prefix is used to compute the name of an
23 initialization procedure. interp is the path name of the interpreter
24 into which to load the library (see the interp manual entry for de‐
25 tails); if interp is omitted, it defaults to the interpreter in which
26 the load command was invoked.
27 Once the file has been loaded into the application's address space, one
29 of two initialization procedures will be invoked in the new code. Typ‐
30 ically the initialization procedure will add new commands to a Tcl in‐
31 terpreter. The name of the initialization procedure is determined by
32 prefix and whether or not the target interpreter is a safe one. For
33 normal interpreters the name of the initialization procedure will have
34 the form pfx_Init, where pfx is the same as prefix except that the
35 first letter is converted to upper case and all other letters are con‐
36 verted to lower case. For example, if prefix is foo or FOo, the ini‐
37 tialization procedure's name will be Foo_Init.
38 If the target interpreter is a safe interpreter, then the name of the
40 initialization procedure will be pfx_SafeInit instead of pfx_Init. The
41 pfx_SafeInit function should be written carefully, so that it initial‐
42 izes the safe interpreter only with partial functionality provided by
43 the library that is safe for use by untrusted code. For more informa‐
44 tion on Safe-Tcl, see the safe manual entry.
45 The initialization procedure must match the following prototype:
47 typedef int Tcl_PackageInitProc(
49 Tcl_Interp *interp);
50 The interp argument identifies the interpreter in which the library is
52 to be loaded. The initialization procedure must return TCL_OK or
53 TCL_ERROR to indicate whether or not it completed successfully; in the
54 event of an error it should set the interpreter's result to point to an
55 error message. The result of the load command will be the result re‐
56 turned by the initialization procedure.
57 The actual loading of a file will only be done once for each fileName
59 in an application. If a given fileName is loaded into multiple inter‐
60 preters, then the first load will load the code and call the initial‐
61 ization procedure; subsequent loads will call the initialization pro‐
62 cedure without loading the code again. For Tcl versions lower than
63 8.5, it is not possible to unload or reload a library. From version 8.5
64 however, the unload command allows the unloading of libraries loaded
65 with load, for libraries that are aware of the Tcl's unloading mecha‐
66 nism.
67 The load command also supports libraries that are statically linked
69 with the application, if those libraries have been registered by call‐
70 ing the Tcl_StaticPackage procedure. If fileName is an empty string,
71 then prefix must be specified.
72 If prefix is omitted or specified as an empty string, Tcl tries to
74 guess the prefix. This may be done differently on different platforms.
75 The default guess, which is used on most UNIX platforms, is to take the
76 last element of fileName, strip off the first three characters if they
77 are lib, and use any following alphabetic and underline characters,
78 converted to titlecase as the prefix. For example, the command load
79 libxyz4.2.so uses the prefix Xyz and the command load bin/last.so {}
80 uses the prefix Last.
81 If fileName is an empty string, then prefix must be specified. The
83 load command first searches for a statically loaded library (one that
84 has been registered by calling the Tcl_StaticPackage procedure) by that
85 name; if one is found, it is used. Otherwise, the load command
86 searches for a dynamically loaded library by that name, and uses it if
87 it is found. If several different files have been loaded with differ‐
88 ent versions of the library, Tcl picks the file that was loaded first.
89 If -global is specified preceding the filename, all symbols found in
91 the shared library are exported for global use by other libraries. The
92 option -lazy delays the actual loading of symbols until their first ac‐
93 tual use. The options may be abbreviated. The option -- indicates the
94 end of the options, and should be used if you wish to use a filename
95 which starts with - and you provide a prefix to the load command.
96 On platforms which do not support the -global or -lazy options, the op‐
98 tions still exist but have no effect. Note that use of the -global or
99 -lazy option may lead to crashes in your application later (in case of
100 symbol conflicts resp. missing symbols), which cannot be detected dur‐
101 ing the load. So, only use this when you know what you are doing, you
102 will not get a nice error message when something is wrong with the
103 loaded library.
104
106 Windows
107 When a load fails with “library not found” error, it is also
108 possible that a dependent library was not found. To see the de‐
109 pendent libraries, type “dumpbin -imports <dllname>” in a DOS
110 console to see what the library must import. When loading a DLL
111 in the current directory, Windows will ignore “./” as a path
112 specifier and use a search heuristic to find the DLL instead.
113 To avoid this, load the DLL with:
114 load [file join [pwd] mylib.DLL]
116
118 If the same file is loaded by different fileNames, it will be loaded
119 into the process's address space multiple times. The behavior of this
120 varies from system to system (some systems may detect the redundant
121 loads, others may not).
122
124 The following is a minimal extension:
125 #include <tcl.h>
127 #include <stdio.h>
128 static int fooCmd(void *clientData,
129 Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
130 printf("called with %d arguments\n", objc);
131 return TCL_OK;
132 }
133 int Foo_Init(Tcl_Interp *interp) {
134 if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
135 return TCL_ERROR;
136 }
137 printf("creating foo command");
138 Tcl_CreateObjCommand(interp, "foo", fooCmd, NULL, NULL);
139 return TCL_OK;
140 }
141 When built into a shared/dynamic library with a suitable name (e.g.
143 foo.dll on Windows, libfoo.so on Solaris and Linux) it can then be
144 loaded into Tcl with the following:
145 # Load the extension
147 switch $tcl_platform(platform) {
148 windows {
149 load [file join [pwd] foo.dll]
150 }
151 unix {
152 load [file join [pwd] libfoo[info sharedlibextension]]
153 }
154 }
155 # Now execute the command defined by the extension
157 foo
158
160 info sharedlibextension, package(n), Tcl_StaticPackage(3), safe(n)
161
163 binary code, dynamic library, load, safe interpreter, shared library
164Tcl 7.5 load(n)