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 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
       must return TCL_OK or TCL_ERROR to indicate whether or not
       it  completed  successfully;   in the event of an error it
       should set interp->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 and it must give the name  of  a  stati-
       cally loaded package.  The appropriate initialization pro-
       cedure for that package will then be invoked  to  incorpo-
       rate the package into the target interpreter.

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


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


KEYWORDS
       binary code, loading, shared library
