Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
unload(n)		     Tcl Built-In Commands		     unload(n)

______________________________________________________________________________

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  un-
       load  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 sys-
	      tem 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 com-
       mand, 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 contain-
       ing 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  in-
       crements	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	deter-
       mined by	packageName and	whether	or not the  target  interpreter	 is  a
       safe  one.  For normal interpreters the name of the initialization pro-
       cedure will have	the form pkg_Unload, where pkg is the same as package-
       Name  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 func-
       tionality has been disabled during compilation),	an error will  be  re-
       turned.	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	inter-
       preter 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_ER-
       ROR 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 at-
       tached to the process after the unload procedure	returns	(i.e.  because
       the  library is used by other interpreters), TCL_UNLOAD_DETACH_FROM_IN-
       TERPRETER will be defined. However, if the library is used only by  the
       target  interpreter  and	the library will be detached from the applica-
       tion 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	packa-
       geName 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 differ-
       ent  platforms.	 The  default  guess, which is used on most UNIX plat-
       forms, 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  un-
       load  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 -nocom-
	      plain 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 in-
       terpreters 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)	 with-
       out having to shut down the overall Tcl process.

SEE ALSO
       info sharedlibextension,	load(n), safe(n)

KEYWORDS
       binary code, unloading, safe interpreter, shared	library

Tcl				      8.5			     unload(n)

NAME | SYNOPSIS | DESCRIPTION | PORTABILITY ISSUES | BUGS | EXAMPLE | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=unload.tcl86&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help