NAME
       load - Load machine code and initialize new commands.

SYNOPSIS
       load fileName
       load fileName packageName
       load fileName packageName interp


DESCRIPTION
       This  command  loads  binary  code  from  a  file into the
       application's address space and  calls  an  initialization
       procedure  in  the  package  to  incorporate  it  into  an
       interpreter.  fileName is the name of the file  containing
       the code;  its exact form varies from system to system but
       on most systems it is a shared library, such as a .so file
       under  Solaris or a DLL under Windows.  packageName is the
       name of the package, and is used to compute the name of an
       initialization  procedure.  interp is the path name of the
       interpreter into which to load the package (see the interp
       manual  entry  for  details);  if  interp  is  omitted, it
       defaults to the interpreter in which the load command  was
       invoked.

       Once  the  file  has  been  loaded  into the application's
       address space, one of two initialization  procedures  will
       be  invoked in the new code.  Typically the initialization
       procedure will add new commands to a Tcl interpreter.  The
       name  of  the  initialization  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_Init,
       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_Init.

       If  the target interpreter is a safe interpreter, then the
       name of the initialization procedure will be  pkg_SafeInit
       instead  of pkg_Init.  The pkg_SafeInit function should be
       written  carefully,  so  that  it  initializes  the   safe
       interpreter  only  with  partial functionality provided by
       the package that is safe for use by  untrusted  code.  For
       more information on Safe-Tcl, see the safe manual entry.

       The  initialization  procedure  must  match  the following
       prototype:
              typedef int Tcl_PackageInitProc(Tcl_Interp *interp);
       The interp argument identifies the  interpreter  in  which
       the package is to be loaded.  The initialization 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.   The  result  of  the  load  command will be the
       result returned by the initialization procedure.

       The actual loading of a file will only be  done  once  for
       each  fileName  in an application.  If a given fileName is
       loaded into multiple interpreters,  then  the  first  load
       will  load the code and call the initialization procedure;
       subsequent loads will call  the  initialization  procedure
       without  loading  the  code  again.  It is not possible to
       unload or reload a package.

       The  load  command  also  supports   packages   that   are
       statically  linked with the application, if those packages
       have been  registered  by  calling  the  Tcl_StaticPackage
       procedure.    If   fileName   is  an  empty  string,  then
       packageName 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 load libxyz4.2.so uses the module
       name xyz and the command  load  bin/last.so  {}  uses  the
       module name last.

       If  fileName  is an empty string, then packageName must be
       specified.   The  load  command  first  searches   for   a
       statically loaded package (one that has been registered by
       calling the Tcl_StaticPackage procedure) by that name;  if
       one  is  found,  it  is used.  Otherwise, the load command
       searches for a dynamically loaded package  by  that  name,
       and  uses  it  if it is found.  If several different files
       have been loaded with different versions of  the  package,
       Tcl picks the file that was loaded first.


PORTABILITY ISSUES
       Windows
              When  a  load fails with "library not found" error,
              it is also possible that a  dependent  library  was
              not  found.   To  see the dependent libraries, type
              ``dumpbin -imports <dllname>'' in a DOS console  to
              see  what  the library must import.  When loading a
              DLL in the current directory, Windows  will  ignore
              ``./''  as  a  path  specifier  and  use  a  search
              heuristic to find the DLL instead.  To avoid  this,
              load the DLL with
                  load [file join [pwd] mylib.DLL]


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


SEE ALSO
       info sharedlibextension, Tcl_StaticPackage, safe(n)


KEYWORDS
