'\"
'\" 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.7.4.1 2004/03/04 17:26:13 dgp Exp $
'\" RCS: @(#) $Id: load.n,v 1.7.4.2 2004/09/08 23:02:34 dgp 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.
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

(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 "PORTABILITY ISSUES"
.TP
\fBWindows\fR\0\0\0\0\0
.
When a load fails with "library not found" error, it is also possible
that a dependent library was not found.  To see the dependent libraries,
type ``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 ``./'' as
a path specifier and use a search heuristic to find the DLL instead.
To avoid this, load the DLL with
To avoid this, load the DLL with:
.CS
    load [file join [pwd] mylib.DLL]
load [file join [pwd] mylib.DLL]
.CE

.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
The following is a minimal extension:
.PP
.CS
#include <tcl.h>
#include <stdio.h>
static int fooCmd(ClientData clientData,
        Tcl_Interp *interp, int objc, char * CONST objv[]) {
    printf("called with %d arguments\\n", 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 ./foo.dll
    }
    unix {
        \fBload\fR ./libfoo[info sharedlibextension]
    }
}

# Now execute the command defined by the extension
foo
.CE

.SH "SEE ALSO"
info sharedlibextension, Tcl_StaticPackage(3), safe(n)

.SH KEYWORDS
binary code, loading, safe interpreter, shared library