


load(n)               Tcl Built-In Commands               load(n)


NAME
       load - Load machine code and initialize new commands.

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

       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 target interpreter is the same as the invoking  inter-
       preter  unless  the interp option is specified.  If interp
       is specified it gives the path name of an  interpreter  in
       which to load the package (see the interp manual entry for
       details on interpreter path names).  It is not possible to
       unload or reload a package.

       The  actual  loading  of a file will only be done once for
       each fileName in an application.  If a given  fileName  is



Tcl                            7.5                              1





load(n)               Tcl Built-In Commands               load(n)


       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.


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


KEYWORDS
       binary code, loading, shared library
