diff options
Diffstat (limited to 'doc/load.n')
| -rw-r--r-- | doc/load.n | 120 |
1 files changed, 0 insertions, 120 deletions
diff --git a/doc/load.n b/doc/load.n deleted file mode 100644 index 9d3e1eb..0000000 --- a/doc/load.n +++ /dev/null @@ -1,120 +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. -'\" -'\" RCS: @(#) $Id: load.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH load n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -load \- Load machine code and initialize new commands. -.SH SYNOPSIS -\fBload \fIfileName\fR -.br -\fBload \fIfileName packageName\fR -.br -\fBload \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: -.CS -typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); -.CE -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 \fIinterp->result\fR -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. -It is not possible to unload or reload a package. -.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 -.VS -alphabetic and underline characters as the module name. -.VE -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. -.VS "" br -.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. -.VE - -.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 "SEE ALSO" -\fBinfo sharedlibextension\fR, Tcl_StaticPackage, safe(n) - -.SH KEYWORDS -binary code, loading, safe interpreter, shared library |