summaryrefslogtreecommitdiffstats
path: root/doc/unload.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/unload.n')
-rw-r--r--doc/unload.n33
1 files changed, 24 insertions, 9 deletions
diff --git a/doc/unload.n b/doc/unload.n
index 916c565..b0aab2e 100644
--- a/doc/unload.n
+++ b/doc/unload.n
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: unload.n,v 1.3 2004/03/17 18:14:12 das Exp $
+'\" RCS: @(#) $Id: unload.n,v 1.4 2004/05/30 14:25:51 dkf Exp $
'\"
.so man.macros
.TH unload n 8.5 Tcl "Tcl Built-In Commands"
@@ -27,11 +27,13 @@ with \fBload\fR from the application's address space. \fIfileName\fR
is the name of the file containing the library file to be unload; it
must be the same as the filename provided to \fBload\fR for
loading the library.
-\fIpackageName\fR is the name of the package, and is used to
-compute the name of the unload procedure.
-\fIinterp\fR is the path name of the interpreter from which to unload
-the package (see the \fBinterp\fR manual entry for details);
-if \fIinterp\fR is omitted, it defaults to the
+The \fIpackageName\fR argument is the name of the package (as
+determined by or passed to \fBload\fR), and is used to
+compute the name of the unload procedure; if not supplied, it is
+computed from \fIfileName\fR in the same manner as \fBload\fR.
+The \fIinterp\fR argument is the path name of the interpreter from
+which to unload the package (see the \fBinterp\fR manual entry for
+details); if \fIinterp\fR is omitted, it defaults to the
interpreter in which the \fBunload\fR command was invoked.
.LP
If the initial arguments to \fBunload\fR start with \fB\-\fR then
@@ -120,7 +122,6 @@ alphabetic and underline characters as the module name.
For example, the command \fBunload libxyz4.2.so\fR uses the module
name \fBxyz\fR and the command \fBunload bin/last.so {}\fR uses the
module name \fBlast\fR.
-
.SH "PORTABILITY ISSUES"
.TP
\fBUnix\fR\0\0\0\0\0
@@ -128,7 +129,6 @@ module name \fBlast\fR.
Not all unix operating systems support library unloading. Under such
an operating system \fBunload\fR returns an error (unless -nocomplain has
been specified).
-
.SH BUGS
.PP
If the same file is \fBload\fRed by different \fIfileName\fRs, it will
@@ -139,9 +139,24 @@ silently detached by the operating system (and as a result Tcl thinks the
library is still loaded), it may be dangerous to use
\fBunload\fR on such a library (as the library will be completely detached
from the application while some interpreters will continue to use it).
+.SH EXAMPLE
+If an unloadable module in the file \fBfoobar.dll\fR had been loaded
+using the \fBload\fR command like this (on Windows):
+.CS
+load c:/some/dir/foobar.dll
+.CE
+then it would be unloaded like this:
+.CS
+\fBunload\fR c:/some/dir/foobar.dll
+.CE
+.PP
+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.
.SH "SEE ALSO"
-info sharedlibextension, load, safe(n)
+info sharedlibextension, load(n), safe(n)
.SH KEYWORDS
binary code, unloading, safe interpreter, shared library