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

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

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

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