| 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 | '\" RCS: @(#) $Id: StaticPkg.3,v 1.9 2007/12/13 15:22:32 dgp Exp $ |
|---|
| 8 | '\" |
|---|
| 9 | .so man.macros |
|---|
| 10 | .TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" |
|---|
| 11 | .BS |
|---|
| 12 | .SH NAME |
|---|
| 13 | Tcl_StaticPackage \- make a statically linked package available via the 'load' command |
|---|
| 14 | .SH SYNOPSIS |
|---|
| 15 | .nf |
|---|
| 16 | \fB#include <tcl.h>\fR |
|---|
| 17 | .sp |
|---|
| 18 | \fBTcl_StaticPackage\fR(\fIinterp, pkgName, initProc, safeInitProc\fR) |
|---|
| 19 | .SH ARGUMENTS |
|---|
| 20 | .AS Tcl_PackageInitProc *safeInitProc |
|---|
| 21 | .AP Tcl_Interp *interp in |
|---|
| 22 | If not NULL, points to an interpreter into which the package has |
|---|
| 23 | already been loaded (i.e., the caller has already invoked the |
|---|
| 24 | appropriate initialization procedure). NULL means the package |
|---|
| 25 | has not yet been incorporated into any interpreter. |
|---|
| 26 | .AP "const char" *pkgName in |
|---|
| 27 | Name of the package; should be properly capitalized (first letter |
|---|
| 28 | upper-case, all others lower-case). |
|---|
| 29 | .AP Tcl_PackageInitProc *initProc in |
|---|
| 30 | Procedure to invoke to incorporate this package into a trusted |
|---|
| 31 | interpreter. |
|---|
| 32 | .AP Tcl_PackageInitProc *safeInitProc in |
|---|
| 33 | Procedure to call to incorporate this package into a safe interpreter |
|---|
| 34 | (one that will execute untrusted scripts). NULL means the package |
|---|
| 35 | cannot be used in safe interpreters. |
|---|
| 36 | .BE |
|---|
| 37 | |
|---|
| 38 | .SH DESCRIPTION |
|---|
| 39 | .PP |
|---|
| 40 | This procedure may be invoked to announce that a package has been |
|---|
| 41 | linked statically with a Tcl application and, optionally, that it |
|---|
| 42 | has already been loaded into an interpreter. |
|---|
| 43 | Once \fBTcl_StaticPackage\fR has been invoked for a package, it |
|---|
| 44 | may be loaded into interpreters using the \fBload\fR command. |
|---|
| 45 | \fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR |
|---|
| 46 | procedure for the application, not by packages for themselves |
|---|
| 47 | (\fBTcl_StaticPackage\fR should only be invoked for statically |
|---|
| 48 | loaded packages, and code in the package itself should not need |
|---|
| 49 | to know whether the package is dynamically or statically loaded). |
|---|
| 50 | .PP |
|---|
| 51 | When the \fBload\fR command is used later to load the package into |
|---|
| 52 | an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will |
|---|
| 53 | be invoked, depending on whether the target interpreter is safe |
|---|
| 54 | or not. |
|---|
| 55 | \fIinitProc\fR and \fIsafeInitProc\fR must both match the |
|---|
| 56 | following prototype: |
|---|
| 57 | .CS |
|---|
| 58 | typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); |
|---|
| 59 | .CE |
|---|
| 60 | The \fIinterp\fR argument identifies the interpreter in which the package |
|---|
| 61 | is to be loaded. The initialization procedure must return \fBTCL_OK\fR or |
|---|
| 62 | \fBTCL_ERROR\fR to indicate whether or not it completed successfully; in |
|---|
| 63 | the event of an error it should set the interpreter's result to point to an |
|---|
| 64 | error message. The result or error from the initialization procedure will |
|---|
| 65 | be returned as the result of the \fBload\fR command that caused the |
|---|
| 66 | initialization procedure to be invoked. |
|---|
| 67 | |
|---|
| 68 | .SH KEYWORDS |
|---|
| 69 | initialization procedure, package, static linking |
|---|
