|
ActiveTcl User Guide |
|
- NAME
- unload - Unload machine code
- SYNOPSIS
- unload ?switches? fileName
- unload ?switches? fileName
packageName
- unload ?switches? fileName packageName
interp
- DESCRIPTION
- -nocomplain
- -keeplibrary
- --
- UNLOAD OPERATION
- UNLOAD HOOK
PROTOTYPE
- NOTES
- PORTABILITY ISSUES
- Unix
- BUGS
- EXAMPLE
- SEE ALSO
- KEYWORDS
unload - Unload machine code
unload ?switches? fileName
unload ?switches? fileName packageName
unload ?switches? fileName packageName
interp
This command tries to unload shared libraries previously loaded
with load from the
application's address space. fileName is the name of the
file containing the library file to be unload; it must be the same
as the filename provided to load for loading the library. The
packageName argument is the name of the package (as
determined by or passed to load), and is used to compute the name
of the unload procedure; if not supplied, it is computed from
fileName in the same manner as load. The interp argument is
the path name of the interpreter from which to unload the package
(see the interp manual
entry for details); if interp is omitted, it defaults to the
interpreter in which the unload command was invoked.
If the initial arguments to unload start with -
then they are treated as switches. The following switches are
currently supported:
- -nocomplain
- Suppresses all error messages. If this switch is given,
unload will never report an error.
- -keeplibrary
- This switch will prevent unload from issuing the
operating system call that will unload the library from the
process.
- --
- Marks the end of switches. The argument following this one will
be treated as a fileName even if it starts with a
-.
When a file containing a shared library is loaded through the load command, Tcl associates two
reference counts to the library file. The first counter shows how
many times the library has been loaded into normal (trusted)
interpreters while the second describes how many times the library
has been loaded into safe interpreters. As a file containing a
shared library can be loaded only once by Tcl (with the first load call on the file), these
counters track how many interpreters use the library. Each
subsequent call to load
after the first simply increments the proper reference count.
unload works in the opposite direction. As a first step,
unload will check whether the library is unloadable: an
unloadable library exports a special unload procedure. The name of
the unload procedure is determined by packageName and
whether or not the target interpreter is a safe one. For normal
interpreters the name of the initialization procedure will have the
form pkg_Unload, where pkg is the same as
packageName except that the first letter is converted to
upper case and all other letters are converted to lower case. For
example, if packageName is foo or FOo, the
initialization procedure's name will be Foo_Unload. If the
target interpreter is a safe interpreter, then the name of the
initialization procedure will be pkg_SafeUnload
instead of pkg_Unload.
If unload determines that a library is not unloadable (or
unload functionality has been disabled during compilation), an
error will be returned. If the library is unloadable, then
unload will call the unload procedure. If the unload
procedure returns TCL_OK, unload will proceed and
decrease the proper reference count (depending on the target
interpreter type). When both reference counts have reached 0, the
library will be detached from the process.
The unload procedure must match the following prototype:
typedef int Tcl_PackageUnloadProc(Tcl_Interp *interp, int flags);
The interp argument identifies the interpreter from which
the library is to be unloaded. The unload procedure must return
TCL_OK or TCL_ERROR 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. In this case,
the result of the unload command will be the result returned
by the unload procedure.
The flags argument can be either
TCL_UNLOAD_DETACH_FROM_INTERPRETER or
TCL_UNLOAD_DETACH_FROM_PROCESS. In case the library will
remain attached to the process after the unload procedure returns
(i.e. because the library is used by other interpreters),
TCL_UNLOAD_DETACH_FROM_INTERPRETER will be defined. However,
if the library is used only by the target interpreter and the
library will be detached from the application as soon as the unload
procedure returns, the flags argument will be set to
TCL_UNLOAD_DETACH_FROM_PROCESS.
The unload command cannot unload libraries that are
statically linked with the application. If fileName is an
empty string, then the packageName argument must be
specified.
If packageName 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
fileName, strip off the first three characters if they are
lib, and use any following alphabetic and underline
characters as the module name. For example, the command unload
libxyz4.2.so uses the module name xyz and the command
unload bin/last.so {} uses the module name last.
- Unix
- Not all unix operating systems support library unloading. Under
such an operating system unload returns an error (unless
-nocomplain has been specified).
If the same file is loaded
by different fileNames, 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). In case a library has been silently detached by
the operating system (and as a result Tcl thinks the library is
still loaded), it may be dangerous to use unload on such a
library (as the library will be completely detached from the
application while some interpreters will continue to use it).
If an unloadable module in the file foobar.dll had been
loaded using the load
command like this (on Windows):
load c:/some/dir/foobar.dll
then it would be unloaded like this:
unload c:/some/dir/foobar.dll
This allows a C code module to be installed temporarily into a
long-running Tcl program and then removed again (either because it
is no longer needed or because it is being updated with a new
version) without having to shut down the overall Tcl process.
info sharedlibextension,
load, safe
binary code, unloading, safe interpreter, shared library
Copyright © 1995-1997 Roger E. Critchlow Jr.
Copyright © 2003 George Petasis
<petasis(at)iit.demokritos.gr>.