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 appli­
       cation's address space and calls an initialization  proce­
       dure 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 sys­
       tems 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 ini­
       tialization  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 ini­
       tialization procedure will have the form  pkg_Init,  where
       pkg  is the same as packageName except that the first let­
       ter 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  inter­
       preter  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 pro­
       totype:
              typedef int Tcl_PackageInitProc(Tcl_Interp *interp);
       The interp argument identifies the  interpreter  in  which
       the package is to be loaded.  The initialization procedure

       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  stati­
       cally  linked with the application, if those packages have
       been registered by calling  the  Tcl_StaticPackage  proce­
       dure.   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 alpha­ |
       betic 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 mod­
       ule name last.

       If  fileName  is an empty string, then packageName must be |
       specified.  The load command first searches for  a  stati­ |
       cally  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 heuris­
              tic to find the DLL instead.  To avoid  this,  load
              the DLL with
                  load [file join [pwd] mylib.DLL]

       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(3), safe(n)


KEYWORDS

       binary code, loading, safe interpreter, shared library


Man(1) output converted with man2html