196 lines
7.7 KiB
Plaintext
196 lines
7.7 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
.TH load n 7.5 Tcl "Tcl Built-In Commands"
|
|
.so man.macros
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
load \- Load machine code and initialize new commands
|
|
.SH SYNOPSIS
|
|
\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName\fR
|
|
.br
|
|
\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName prefix\fR
|
|
.br
|
|
\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName prefix interp\fR
|
|
.BE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
This command loads binary code from a file into the
|
|
application's address space and calls an initialization procedure
|
|
in the library to incorporate it into an interpreter. \fIfileName\fR
|
|
is the name of the file containing the code; its exact form varies
|
|
from system to system but on most systems it is a shared library,
|
|
such as a \fB.so\fR file under Solaris or a DLL under Windows.
|
|
\fIprefix\fR is used to compute the name of an initialization procedure.
|
|
\fIinterp\fR is the path name of the interpreter into which to load
|
|
the library (see the \fBinterp\fR manual entry for details);
|
|
if \fIinterp\fR is omitted, it defaults to the
|
|
interpreter in which the \fBload\fR command was invoked.
|
|
.PP
|
|
Once the file has been loaded into the application's address space,
|
|
one of two initialization procedures will be invoked in the new code.
|
|
Typically the initialization procedure will add new commands to a
|
|
Tcl interpreter.
|
|
The name of the initialization procedure is determined by
|
|
\fIprefix\fR and whether or not the target interpreter
|
|
is a safe one. For normal interpreters the name of the initialization
|
|
procedure will have the form \fIpfx\fB_Init\fR, where \fIpfx\fR
|
|
is the same as \fIprefix\fR except that the first letter is
|
|
converted to upper case and all other letters
|
|
are converted to lower case. For example, if \fIprefix\fR is
|
|
\fBfoo\fR or \fBFOo\fR, the initialization procedure's name will
|
|
be \fBFoo_Init\fR.
|
|
.PP
|
|
If the target interpreter is a safe interpreter, then the name
|
|
of the initialization procedure will be \fIpfx\fB_SafeInit\fR
|
|
instead of \fIpfx\fB_Init\fR.
|
|
The \fIpfx\fB_SafeInit\fR function should be written carefully, so that it
|
|
initializes the safe interpreter only with partial functionality provided
|
|
by the library that is safe for use by untrusted code. For more information
|
|
on Safe\-Tcl, see the \fBsafe\fR manual entry.
|
|
.PP
|
|
The initialization procedure must match the following prototype:
|
|
.PP
|
|
.CS
|
|
typedef int \fBTcl_PackageInitProc\fR(
|
|
Tcl_Interp *\fIinterp\fR);
|
|
.CE
|
|
.PP
|
|
The \fIinterp\fR argument identifies the interpreter in which the
|
|
library is to be loaded. The initialization procedure must return
|
|
\fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed
|
|
successfully; in the event of an error it should set the interpreter's result
|
|
to point to an error message. The result of the \fBload\fR command
|
|
will be the result returned by the initialization procedure.
|
|
.PP
|
|
The actual loading of a file will only be done once for each \fIfileName\fR
|
|
in an application. If a given \fIfileName\fR is loaded into multiple
|
|
interpreters, then the first \fBload\fR will load the code and
|
|
call the initialization procedure; subsequent \fBload\fRs will
|
|
call the initialization procedure without loading the code again.
|
|
For Tcl versions lower than 8.5, it is not possible to unload or reload a
|
|
library. From version 8.5 however, the \fBunload\fR command allows the unloading
|
|
of libraries loaded with \fBload\fR, for libraries that are aware of the
|
|
Tcl's unloading mechanism.
|
|
.PP
|
|
The \fBload\fR command also supports libraries that are statically
|
|
linked with the application, if those libraries have been registered
|
|
by calling the \fBTcl_StaticPackage\fR procedure.
|
|
If \fIfileName\fR is an empty string, then \fIprefix\fR must
|
|
be specified.
|
|
.PP
|
|
If \fIprefix\fR is omitted or specified as an empty string,
|
|
Tcl tries to guess the prefix. This may be done differently on
|
|
different platforms. The default guess, which is used on most
|
|
UNIX platforms, is to take the last element of
|
|
\fIfileName\fR, strip off the first three characters if they
|
|
are \fBlib\fR, and use any following alphabetic and
|
|
underline characters, converted to titlecase as the prefix.
|
|
For example, the command \fBload libxyz4.2.so\fR uses the prefix
|
|
\fBXyz\fR and the command \fBload bin/last.so {}\fR uses the
|
|
prefix \fBLast\fR.
|
|
.PP
|
|
If \fIfileName\fR is an empty string, then \fIprefix\fR must
|
|
be specified.
|
|
The \fBload\fR command first searches for a statically loaded library
|
|
(one that has been registered by calling the \fBTcl_StaticPackage\fR
|
|
procedure) by that name; if one is found, it is used.
|
|
Otherwise, the \fBload\fR command searches for a dynamically loaded
|
|
library by that name, and uses it if it is found. If several
|
|
different files have been \fBload\fRed with different versions of
|
|
the library, Tcl picks the file that was loaded first.
|
|
.PP
|
|
If \fB\-global\fR is specified preceding the filename, all symbols
|
|
found in the shared library are exported for global use by other
|
|
libraries. The option \fB\-lazy\fR delays the actual loading of
|
|
symbols until their first actual use. The options may be abbreviated.
|
|
The option \fB\-\-\fR indicates the end of the options, and should
|
|
be used if you wish to use a filename which starts with \fB\-\fR
|
|
and you provide a prefix to the \fBload\fR command.
|
|
.PP
|
|
On platforms which do not support the \fB\-global\fR or \fB\-lazy\fR
|
|
options, the options still exist but have no effect. Note that use
|
|
of the \fB\-global\fR or \fB\-lazy\fR option may lead to crashes
|
|
in your application later (in case of symbol conflicts resp. missing
|
|
symbols), which cannot be detected during the \fBload\fR. So, only
|
|
use this when you know what you are doing, you will not get a nice
|
|
error message when something is wrong with the loaded library.
|
|
.SH "PORTABILITY ISSUES"
|
|
.TP
|
|
\fBWindows\fR\0\0\0\0\0
|
|
.
|
|
When a load fails with
|
|
.QW "library not found"
|
|
error, it is also possible
|
|
that a dependent library was not found. To see the dependent libraries,
|
|
type
|
|
.QW "dumpbin -imports <dllname>"
|
|
in a DOS console to see what the library must import.
|
|
When loading a DLL in the current directory, Windows will ignore
|
|
.QW ./
|
|
as a path specifier and use a search heuristic to find the DLL instead.
|
|
To avoid this, load the DLL with:
|
|
.RS
|
|
.PP
|
|
.CS
|
|
\fBload\fR [file join [pwd] mylib.DLL]
|
|
.CE
|
|
.RE
|
|
.SH BUGS
|
|
.PP
|
|
If the same file is \fBload\fRed by different \fIfileName\fRs, it will
|
|
be loaded into the process's address space multiple times. The
|
|
behavior of this varies from system to system (some systems may
|
|
detect the redundant loads, others may not).
|
|
.SH EXAMPLE
|
|
.PP
|
|
The following is a minimal extension:
|
|
.PP
|
|
.CS
|
|
#include <tcl.h>
|
|
#include <stdio.h>
|
|
static int fooCmd(void *clientData,
|
|
Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
|
|
printf("called with %d arguments\en", objc);
|
|
return TCL_OK;
|
|
}
|
|
int Foo_Init(Tcl_Interp *interp) {
|
|
if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
|
|
return TCL_ERROR;
|
|
}
|
|
printf("creating foo command");
|
|
Tcl_CreateObjCommand(interp, "foo", fooCmd, NULL, NULL);
|
|
return TCL_OK;
|
|
}
|
|
.CE
|
|
.PP
|
|
When built into a shared/dynamic library with a suitable name
|
|
(e.g. \fBfoo.dll\fR on Windows, \fBlibfoo.so\fR on Solaris and Linux)
|
|
it can then be loaded into Tcl with the following:
|
|
.PP
|
|
.CS
|
|
# Load the extension
|
|
switch $tcl_platform(platform) {
|
|
windows {
|
|
\fBload\fR [file join [pwd] foo.dll]
|
|
}
|
|
unix {
|
|
\fBload\fR [file join [pwd] libfoo[info sharedlibextension]]
|
|
}
|
|
}
|
|
|
|
# Now execute the command defined by the extension
|
|
foo
|
|
.CE
|
|
.SH "SEE ALSO"
|
|
info sharedlibextension, package(n), Tcl_StaticPackage(3), safe(n)
|
|
.SH KEYWORDS
|
|
binary code, dynamic library, load, safe interpreter, shared library
|
|
'\"Local Variables:
|
|
'\"mode: nroff
|
|
'\"End:
|