131 lines
6.7 KiB
HTML
131 lines
6.7 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - load manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="load.htm#M2" NAME="L663">NAME</A>
|
|
<DL><DD>load - Load machine code and initialize new commands.</DL>
|
|
<DD><A HREF="load.htm#M3" NAME="L664">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>load </B><I>fileName</I>
|
|
<DD><B>load </B><I>fileName packageName</I>
|
|
<DD><B>load </B><I>fileName packageName interp</I>
|
|
</DL>
|
|
<DD><A HREF="load.htm#M4" NAME="L665">DESCRIPTION</A>
|
|
<DD><A HREF="load.htm#M5" NAME="L666">PORTABILITY ISSUES</A>
|
|
<DL>
|
|
<DD><A HREF="load.htm#M6" NAME="L667"><B>Windows</B></A>
|
|
</DL>
|
|
<DD><A HREF="load.htm#M7" NAME="L668">BUGS</A>
|
|
<DD><A HREF="load.htm#M8" NAME="L669">SEE ALSO</A>
|
|
<DD><A HREF="load.htm#M9" NAME="L670">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
load - Load machine code and initialize new commands.
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>load </B><I>fileName</I><BR>
|
|
<B>load </B><I>fileName packageName</I><BR>
|
|
<B>load </B><I>fileName packageName interp</I><BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
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. <I>fileName</I>
|
|
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 <B>.so</B> file under Solaris or a DLL under Windows.
|
|
<I>packageName</I> is the name of the package, and is used to
|
|
compute the name of an initialization procedure.
|
|
<I>interp</I> is the path name of the interpreter into which to load
|
|
the package (see the <B><A HREF="../TkCmd/interp.htm">interp</A></B> manual entry for details);
|
|
if <I>interp</I> is omitted, it defaults to the
|
|
interpreter in which the <B>load</B> command was invoked.
|
|
<P>
|
|
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
|
|
<I>packageName</I> and whether or not the target interpreter
|
|
is a safe one. For normal interpreters the name of the initialization
|
|
procedure will have the form <I>pkg</I><B>_Init</B>, where <I>pkg</I>
|
|
is the same as <I>packageName</I> except that the first letter is
|
|
converted to upper case and all other letters
|
|
are converted to lower case. For example, if <I>packageName</I> is
|
|
<B>foo</B> or <B>FOo</B>, the initialization procedure's name will
|
|
be <B>Foo_Init</B>.
|
|
<P>
|
|
If the target interpreter is a safe interpreter, then the name
|
|
of the initialization procedure will be <I>pkg</I><B>_SafeInit</B>
|
|
instead of <I>pkg</I><B>_Init</B>.
|
|
The <I>pkg</I><B>_SafeInit</B> 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 <B>safe</B> manual entry.
|
|
<P>
|
|
The initialization procedure must match the following prototype:
|
|
<PRE>typedef int Tcl_PackageInitProc(<A HREF="../TkLib/Interp.htm">Tcl_Interp</A> *<I>interp</I>);</PRE>
|
|
The <I>interp</I> argument identifies the interpreter in which the
|
|
package is to be loaded. The initialization procedure must return
|
|
<B>TCL_OK</B> or <B>TCL_ERROR</B> 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 <B>load</B> command
|
|
will be the result returned by the initialization procedure.
|
|
<P>
|
|
The actual loading of a file will only be done once for each <I>fileName</I>
|
|
in an application. If a given <I>fileName</I> is loaded into multiple
|
|
interpreters, then the first <B>load</B> will load the code and
|
|
call the initialization procedure; subsequent <B>load</B>s will
|
|
call the initialization procedure without loading the code again.
|
|
It is not possible to unload or reload a package.
|
|
<P>
|
|
The <B>load</B> command also supports packages that are statically
|
|
linked with the application, if those packages have been registered
|
|
by calling the <B><A HREF="../TkLib/StaticPkg.htm">Tcl_StaticPackage</A></B> procedure.
|
|
If <I>fileName</I> is an empty string, then <I>packageName</I> must
|
|
be specified.
|
|
<P>
|
|
If <I>packageName</I> 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 <I>fileName</I>, strip off the first
|
|
three characters if they are <B>lib</B>, and use any following
|
|
alphabetic and underline characters as the module name.
|
|
For example, the command <B>load libxyz4.2.so</B> uses the module
|
|
name <B>xyz</B> and the command <B>load bin/last.so {}</B> uses the
|
|
module name <B>last</B>.
|
|
<P>
|
|
If <I>fileName</I> is an empty string, then <I>packageName</I> must
|
|
be specified.
|
|
The <B>load</B> command first searches for a statically loaded package
|
|
(one that has been registered by calling the <B><A HREF="../TkLib/StaticPkg.htm">Tcl_StaticPackage</A></B>
|
|
procedure) by that name; if one is found, it is used.
|
|
Otherwise, the <B>load</B> command searches for a dynamically loaded
|
|
package by that name, and uses it if it is found. If several
|
|
different files have been <B>load</B>ed with different versions of
|
|
the package, Tcl picks the file that was loaded first.
|
|
|
|
<H3><A NAME="M5">PORTABILITY ISSUES</A></H3>
|
|
<DL>
|
|
<P><DT><A NAME="M6"><B>Windows</B></A><DD>
|
|
When a load fails with "library not found" error, it is also possible
|
|
that a dependent library was not found. To see the dependent libraries,
|
|
type ``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 ``./'' as
|
|
a path specifier and use a search heuristic to find the DLL instead.
|
|
To avoid this, load the DLL with
|
|
<PRE>load [file join [pwd] mylib.DLL]</PRE>
|
|
<P></DL>
|
|
<H3><A NAME="M7">BUGS</A></H3>
|
|
If the same file is <B>load</B>ed by different <I>fileName</I>s, 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).
|
|
|
|
<H3><A NAME="M8">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/info.htm">info sharedlibextension</A></B>, <B><A HREF="../TkLib/StaticPkg.htm">Tcl_StaticPackage</A></B>, <B>safe</B>
|
|
<H3><A NAME="M9">KEYWORDS</A></H3>
|
|
<A href="../Keywords/B.htm#binary code">binary code</A>, <A href="../Keywords/L.htm#loading">loading</A>, <A href="../Keywords/S.htm#safe interpreter">safe interpreter</A>, <A href="../Keywords/S.htm#shared library">shared library</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|