unload(3tcl)						       Tcl Built-In Commands						      unload(3tcl)

__________________________________________________________________________________________________________________________________________________

NAME

       unload - Unload machine code

SYNOPSIS

       unload ?switches? fileName
       unload ?switches? fileName packageName
       unload ?switches? fileName packageName interp
_________________________________________________________________

DESCRIPTION

       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 proce-
       dure; 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 -.

   UNLOAD OPERATION
       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  packa-
       geName except that the first letter is converted to upper case and all other letters are converted to lower case.  For example, if package-
       Name 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.

   UNLOAD HOOK PROTOTYPE
       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.

   NOTES
       The unload command cannot unload libraries that are statically linked with the application.  If fileName is an empty string, then the pack-
       ageName 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.

PORTABILITY ISSUES

       Unix
	      Not all unix operating systems support library unloading. Under such an operating system unload returns an error (unless -nocomplain
	      has been specified).

BUGS

       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).

EXAMPLE

       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.

SEE ALSO

       info sharedlibextension, load(3tcl), safe(3tcl)

KEYWORDS

       binary code, unloading, safe interpreter, shared library

Tcl									8.5							      unload(3tcl)