summaryrefslogtreecommitdiffstats
path: root/tcl8.6/doc/load.n
diff options
context:
space:
mode:
Diffstat (limited to 'tcl8.6/doc/load.n')
-rw-r--r--tcl8.6/doc/load.n196
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: