121 lines
5.1 KiB
Plaintext
121 lines
5.1 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.
|
|
'\"
|
|
'\" SCCS: @(#) load.n 1.9 97/08/22 18:51:18
|
|
'\"
|
|
.so man.macros
|
|
.TH load n 7.5 Tcl "Tcl Built-In Commands"
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
load \- Load machine code and initialize new commands.
|
|
.SH SYNOPSIS
|
|
\fBload \fIfileName\fR
|
|
.br
|
|
\fBload \fIfileName packageName\fR
|
|
.br
|
|
\fBload \fIfileName packageName 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 package 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.
|
|
\fIpackageName\fR is the name of the package, and is used to
|
|
compute the name of an initialization procedure.
|
|
\fIinterp\fR is the path name of the interpreter into which to load
|
|
the package (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
|
|
\fIpackageName\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 \fIpkg\fB_Init\fR, where \fIpkg\fR
|
|
is the same as \fIpackageName\fR except that the first letter is
|
|
converted to upper case and all other letters
|
|
are converted to lower case. For example, if \fIpackageName\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 \fIpkg\fB_SafeInit\fR
|
|
instead of \fIpkg\fB_Init\fR.
|
|
The \fIpkg\fB_SafeInit\fR function should be written carefully, so that it
|
|
initializes the safe interpreter only with partial functionality provided
|
|
by the package 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:
|
|
.CS
|
|
typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR);
|
|
.CE
|
|
The \fIinterp\fR argument identifies the interpreter in which the
|
|
package 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 \fIinterp->result\fR
|
|
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.
|
|
It is not possible to unload or reload a package.
|
|
.PP
|
|
The \fBload\fR command also supports packages that are statically
|
|
linked with the application, if those packages have been registered
|
|
by calling the \fBTcl_StaticPackage\fR procedure.
|
|
If \fIfileName\fR is an empty string, then \fIpackageName\fR must
|
|
be specified.
|
|
.PP
|
|
If \fIpackageName\fR is omitted or specified as an empty string,
|
|
Tcl tries to guess the name of the package.
|
|
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
|
|
.VS
|
|
alphabetic and underline characters as the module name.
|
|
.VE
|
|
For example, the command \fBload libxyz4.2.so\fR uses the module
|
|
name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the
|
|
module name \fBlast\fR.
|
|
.VS "" br
|
|
.PP
|
|
If \fIfileName\fR is an empty string, then \fIpackageName\fR must
|
|
be specified.
|
|
The \fBload\fR command first searches for a statically loaded package
|
|
(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
|
|
package by that name, and uses it if it is found. If several
|
|
different files have been \fBload\fRed with different versions of
|
|
the package, Tcl picks the file that was loaded first.
|
|
.VE
|
|
|
|
.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 "SEE ALSO"
|
|
\fBinfo sharedlibextension\fR, Tcl_StaticPackage, safe(n)
|
|
|
|
.SH KEYWORDS
|
|
binary code, loading, safe interpreter, shared library
|