tcl7.6 User Commands - load






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 pro-
     cedure 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  pack-
     age,  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  inter-
     preter 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 pack-
     ageName 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 initialization procedure must match the following proto-
     type:
          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  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 speci-
     fied.

     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.



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 sys-
     tems may detect the redundant loads, others may not).



SEE ALSO

     info sharedlibextension, Tcl_StaticPackage



KEYWORDS

     binary code, loading, shared library