diff options
Diffstat (limited to 'tcl8.6/doc/load.n')
-rw-r--r-- | tcl8.6/doc/load.n | 196 |
1 files changed, 0 insertions, 196 deletions
diff --git a/tcl8.6/doc/load.n b/tcl8.6/doc/load.n deleted file mode 100644 index 2ab8f2e..0000000 --- a/tcl8.6/doc/load.n +++ /dev/null @@ -1,196 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH load n 7.5 Tcl "Tcl Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -load \- Load machine code and initialize new commands -.SH SYNOPSIS -\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName\fR -.br -\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName\fR -.br -\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName interp\fR -.BE -.SH DESCRIPTION -.PP -This command loads binary code from a file into the -application's address space and calls an initialization procedure -in the package to incorporate it into an interpreter. \fIfileName\fR -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 \fB.so\fR file under Solaris or a DLL under Windows. -\fIpackageName\fR is the name of the package, and is used to -compute the name of an initialization procedure. -\fIinterp\fR is the path name of the interpreter into which to load -the package (see the \fBinterp\fR manual entry for details); -if \fIinterp\fR is omitted, it defaults to the -interpreter in which the \fBload\fR command was invoked. -.PP -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 -\fIpackageName\fR and whether or not the target interpreter -is a safe one. For normal interpreters the name of the initialization -procedure will have the form \fIpkg\fB_Init\fR, where \fIpkg\fR -is the same as \fIpackageName\fR except that the first letter is -converted to upper case and all other letters -are converted to lower case. For example, if \fIpackageName\fR is -\fBfoo\fR or \fBFOo\fR, the initialization procedure's name will -be \fBFoo_Init\fR. -.PP -If the target interpreter is a safe interpreter, then the name -of the initialization procedure will be \fIpkg\fB_SafeInit\fR -instead of \fIpkg\fB_Init\fR. -The \fIpkg\fB_SafeInit\fR function should be written carefully, so that it -initializes the safe interpreter only with partial functionality provided -by the package that is safe for use by untrusted code. For more information -on Safe\-Tcl, see the \fBsafe\fR manual entry. -.PP -The initialization procedure must match the following prototype: -.PP -.CS -typedef int \fBTcl_PackageInitProc\fR( - Tcl_Interp *\fIinterp\fR); -.CE -.PP -The \fIinterp\fR argument identifies the interpreter in which the -package is to be loaded. The initialization procedure must return -\fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not 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 \fBload\fR command -will be the result returned by the initialization procedure. -.PP -The actual loading of a file will only be done once for each \fIfileName\fR -in an application. If a given \fIfileName\fR is loaded into multiple -interpreters, then the first \fBload\fR will load the code and -call the initialization procedure; subsequent \fBload\fRs will -call the initialization procedure without loading the code again. -For Tcl versions lower than 8.5, it is not possible to unload or reload a -package. From version 8.5 however, the \fBunload\fR command allows the unloading -of libraries loaded with \fBload\fR, for libraries that are aware of the -Tcl's unloading mechanism. -.PP -The \fBload\fR command also supports packages that are statically -linked with the application, if those packages have been registered -by calling the \fBTcl_StaticPackage\fR procedure. -If \fIfileName\fR is an empty string, then \fIpackageName\fR must -be specified. -.PP -If \fIpackageName\fR 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 \fIfileName\fR, strip off the first -three characters if they are \fBlib\fR, and use any following -alphabetic and underline characters as the module name. -For example, the command \fBload libxyz4.2.so\fR uses the module -name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the -module name \fBlast\fR. -.PP -If \fIfileName\fR is an empty string, then \fIpackageName\fR must -be specified. -The \fBload\fR command first searches for a statically loaded package -(one that has been registered by calling the \fBTcl_StaticPackage\fR -procedure) by that name; if one is found, it is used. -Otherwise, the \fBload\fR command searches for a dynamically loaded -package by that name, and uses it if it is found. If several -different files have been \fBload\fRed with different versions of -the package, Tcl picks the file that was loaded first. -.PP -If \fB\-global\fR is specified preceding the filename, all symbols -found in the shared library are exported for global use by other -libraries. The option \fB\-lazy\fR delays the actual loading of -symbols until their first actual use. The options may be abbreviated. -The option \fB\-\-\fR indicates the end of the options, and should -be used if you wish to use a filename which starts with \fB\-\fR -and you provide a packageName to the \fBload\fR command. -.PP -On platforms which do not support the \fB\-global\fR or \fB\-lazy\fR -options, the options still exist but have no effect. Note that use -of the \fB\-global\fR or \fB\-lazy\fR option may lead to crashes -in your application later (in case of symbol conflicts resp. missing -symbols), which cannot be detected during the \fBload\fR. So, only -use this when you know what you are doing, you will not get a nice -error message when something is wrong with the loaded library. -.SH "PORTABILITY ISSUES" -.TP -\fBWindows\fR\0\0\0\0\0 -. -When a load fails with -.QW "library not found" -error, it is also possible -that a dependent library was not found. To see the dependent libraries, -type -.QW "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 -.QW ./ -as a path specifier and use a search heuristic to find the DLL instead. -To avoid this, load the DLL with: -.RS -.PP -.CS -\fBload\fR [file join [pwd] mylib.DLL] -.CE -.RE -.SH BUGS -.PP -If the same file is \fBload\fRed by different \fIfileName\fRs, 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). -.SH EXAMPLE -.PP -The following is a minimal extension: -.PP -.CS -#include <tcl.h> -#include <stdio.h> -static int fooCmd(ClientData clientData, - Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) { - printf("called with %d arguments\en", objc); - return TCL_OK; -} -int Foo_Init(Tcl_Interp *interp) { - if (Tcl_InitStubs(interp, "8.1", 0) == NULL) { - return TCL_ERROR; - } - printf("creating foo command"); - Tcl_CreateObjCommand(interp, "foo", fooCmd, NULL, NULL); - return TCL_OK; -} -.CE -.PP -When built into a shared/dynamic library with a suitable name -(e.g. \fBfoo.dll\fR on Windows, \fBlibfoo.so\fR on Solaris and Linux) -it can then be loaded into Tcl with the following: -.PP -.CS -# Load the extension -switch $tcl_platform(platform) { - windows { - \fBload\fR [file join [pwd] foo.dll] - } - unix { - \fBload\fR [file join [pwd] libfoo[info sharedlibextension]] - } -} - -# Now execute the command defined by the extension -foo -.CE -.SH "SEE ALSO" -info sharedlibextension, package(n), Tcl_StaticPackage(3), safe(n) -.SH KEYWORDS -binary code, dynamic library, load, safe interpreter, shared library -'\"Local Variables: -'\"mode: nroff -'\"End: |