"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/tcl8.6/doc/load.n" (13 Nov 2019, 7995 Bytes) of package /linux/misc/ds9.8.1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Nemerle source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 '\"
    2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
    3 '\"
    4 '\" See the file "license.terms" for information on usage and redistribution
    5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
    6 '\" 
    7 .TH load n 7.5 Tcl "Tcl Built-In Commands"
    8 .so man.macros
    9 .BS
   10 '\" Note:  do not modify the .SH NAME line immediately below!
   11 .SH NAME
   12 load \- Load machine code and initialize new commands
   13 .SH SYNOPSIS
   14 \fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName\fR
   15 .br
   16 \fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName\fR
   17 .br
   18 \fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName interp\fR
   19 .BE
   20 .SH DESCRIPTION
   21 .PP
   22 This command loads binary code from a file into the
   23 application's address space and calls an initialization procedure
   24 in the package to incorporate it into an interpreter.  \fIfileName\fR
   25 is the name of the file containing the code;  its exact form varies
   26 from system to system but on most systems it is a shared library,
   27 such as a \fB.so\fR file under Solaris or a DLL under Windows.
   28 \fIpackageName\fR is the name of the package, and is used to
   29 compute the name of an initialization procedure.
   30 \fIinterp\fR is the path name of the interpreter into which to load
   31 the package (see the \fBinterp\fR manual entry for details);
   32 if \fIinterp\fR is omitted, it defaults to the
   33 interpreter in which the \fBload\fR command was invoked.
   34 .PP
   35 Once the file has been loaded into the application's address space,
   36 one of two initialization procedures will be invoked in the new code.
   37 Typically the initialization procedure will add new commands to a
   38 Tcl interpreter.
   39 The name of the initialization procedure is determined by
   40 \fIpackageName\fR and whether or not the target interpreter
   41 is a safe one.  For normal interpreters the name of the initialization
   42 procedure will have the form \fIpkg\fB_Init\fR, where \fIpkg\fR
   43 is the same as \fIpackageName\fR except that the first letter is
   44 converted to upper case and all other letters
   45 are converted to lower case.  For example, if \fIpackageName\fR is
   46 \fBfoo\fR or \fBFOo\fR, the initialization procedure's name will
   47 be \fBFoo_Init\fR.
   48 .PP
   49 If the target interpreter is a safe interpreter, then the name
   50 of the initialization procedure will be \fIpkg\fB_SafeInit\fR
   51 instead of \fIpkg\fB_Init\fR.
   52 The \fIpkg\fB_SafeInit\fR function should be written carefully, so that it
   53 initializes the safe interpreter only with partial functionality provided
   54 by the package that is safe for use by untrusted code. For more information
   55 on Safe\-Tcl, see the \fBsafe\fR manual entry.
   56 .PP
   57 The initialization procedure must match the following prototype:
   58 .PP
   59 .CS
   60 typedef int \fBTcl_PackageInitProc\fR(
   61         Tcl_Interp *\fIinterp\fR);
   62 .CE
   63 .PP
   64 The \fIinterp\fR argument identifies the interpreter in which the
   65 package is to be loaded.  The initialization procedure must return
   66 \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed
   67 successfully;  in the event of an error it should set the interpreter's result
   68 to point to an error message.  The result of the \fBload\fR command
   69 will be the result returned by the initialization procedure.
   70 .PP
   71 The actual loading of a file will only be done once for each \fIfileName\fR
   72 in an application.  If a given \fIfileName\fR is loaded into multiple
   73 interpreters, then the first \fBload\fR will load the code and
   74 call the initialization procedure;  subsequent \fBload\fRs will
   75 call the initialization procedure without loading the code again.
   76 For Tcl versions lower than 8.5, it is not possible to unload or reload a
   77 package. From version 8.5 however, the \fBunload\fR command allows the unloading
   78 of libraries loaded with \fBload\fR, for libraries that are aware of the
   79 Tcl's unloading mechanism.
   80 .PP
   81 The \fBload\fR command also supports packages that are statically
   82 linked with the application, if those packages have been registered
   83 by calling the \fBTcl_StaticPackage\fR procedure.
   84 If \fIfileName\fR is an empty string, then \fIpackageName\fR must
   85 be specified.
   86 .PP
   87 If \fIpackageName\fR is omitted or specified as an empty string,
   88 Tcl tries to guess the name of the package.
   89 This may be done differently on different platforms.
   90 The default guess, which is used on most UNIX platforms, is to
   91 take the last element of \fIfileName\fR, strip off the first
   92 three characters if they are \fBlib\fR, and use any following
   93 alphabetic and underline characters as the module name.
   94 For example, the command \fBload libxyz4.2.so\fR uses the module
   95 name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the
   96 module name \fBlast\fR.
   97 .PP
   98 If \fIfileName\fR is an empty string, then \fIpackageName\fR must
   99 be specified.
  100 The \fBload\fR command first searches for a statically loaded package
  101 (one that has been registered by calling the \fBTcl_StaticPackage\fR
  102 procedure) by that name; if one is found, it is used.
  103 Otherwise, the \fBload\fR command searches for a dynamically loaded
  104 package by that name, and uses it if it is found.  If several
  105 different files have been \fBload\fRed with different versions of
  106 the package, Tcl picks the file that was loaded first.
  107 .PP
  108 If \fB\-global\fR is specified preceding the filename, all symbols
  109 found in the shared library are exported for global use by other
  110 libraries. The option \fB\-lazy\fR delays the actual loading of
  111 symbols until their first actual use. The options may be abbreviated.
  112 The option \fB\-\-\fR indicates the end of the options, and should
  113 be used if you wish to use a filename which starts with \fB\-\fR
  114 and you provide a packageName to the \fBload\fR command.
  115 .PP
  116 On platforms which do not support the \fB\-global\fR or \fB\-lazy\fR
  117 options, the options still exist but have no effect. Note that use
  118 of the \fB\-global\fR or \fB\-lazy\fR option may lead to crashes
  119 in your application later (in case of symbol conflicts resp. missing
  120 symbols), which cannot be detected during the \fBload\fR. So, only
  121 use this when you know what you are doing, you will not get a nice
  122 error message when something is wrong with the loaded library.
  123 .SH "PORTABILITY ISSUES"
  124 .TP
  125 \fBWindows\fR\0\0\0\0\0
  126 .
  127 When a load fails with
  128 .QW "library not found"
  129 error, it is also possible
  130 that a dependent library was not found.  To see the dependent libraries,
  131 type
  132 .QW "dumpbin -imports <dllname>"
  133 in a DOS console to see what the library must import.
  134 When loading a DLL in the current directory, Windows will ignore
  135 .QW ./
  136 as a path specifier and use a search heuristic to find the DLL instead.
  137 To avoid this, load the DLL with:
  138 .RS
  139 .PP
  140 .CS
  141 \fBload\fR [file join [pwd] mylib.DLL]
  142 .CE
  143 .RE
  144 .SH BUGS
  145 .PP
  146 If the same file is \fBload\fRed by different \fIfileName\fRs, it will
  147 be loaded into the process's address space multiple times.  The
  148 behavior of this varies from system to system (some systems may
  149 detect the redundant loads, others may not).
  150 .SH EXAMPLE
  151 .PP
  152 The following is a minimal extension:
  153 .PP
  154 .CS
  155 #include <tcl.h>
  156 #include <stdio.h>
  157 static int fooCmd(ClientData clientData,
  158         Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
  159     printf("called with %d arguments\en", objc);
  160     return TCL_OK;
  161 }
  162 int Foo_Init(Tcl_Interp *interp) {
  163     if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
  164     return TCL_ERROR;
  165     }
  166     printf("creating foo command");
  167     Tcl_CreateObjCommand(interp, "foo", fooCmd, NULL, NULL);
  168     return TCL_OK;
  169 }
  170 .CE
  171 .PP
  172 When built into a shared/dynamic library with a suitable name
  173 (e.g. \fBfoo.dll\fR on Windows, \fBlibfoo.so\fR on Solaris and Linux)
  174 it can then be loaded into Tcl with the following:
  175 .PP
  176 .CS
  177 # Load the extension
  178 switch $tcl_platform(platform) {
  179     windows {
  180         \fBload\fR [file join [pwd] foo.dll]
  181     }
  182     unix {
  183         \fBload\fR [file join [pwd] libfoo[info sharedlibextension]]
  184     }
  185 }
  186 
  187 # Now execute the command defined by the extension
  188 foo
  189 .CE
  190 .SH "SEE ALSO"
  191 info sharedlibextension, package(n), Tcl_StaticPackage(3), safe(n)
  192 .SH KEYWORDS
  193 binary code, dynamic library, load, safe interpreter, shared library
  194 '\"Local Variables:
  195 '\"mode: nroff
  196 '\"End: