Initial revision

1 files changed, 86 insertions, 0 deletions

diff --git a/doc/loadTk.n b/doc/loadTk.n
new file mode 100644
index 0000000..16e3532
--- /dev/null
+++ b/doc/loadTk.n
@@ -0,0 +1,86 @@
+'\"
+'\" 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.
+'\" 
+'\" SCCS: @(#) loadTk.n 1.5 97/08/18 17:44:43
+'\" 
+.so man.macros
+.TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+loadTk \- Load Tk into a safe interpreter.
+.SH SYNOPSIS
+\fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR?
+.BE
+
+Safe Tk is based on Safe Tcl, which provides a mechanism 
+that allows restricted and mediated
+access to auto-loading and packages for safe interpreters.
+Safe Tk adds the ability to configure the interpreter
+for safe Tk operations and load Tk into safe 
+interpreters.
+
+.SH DESCRIPTION
+.PP
+The \fB::safe::loadTk\fR command initializes the required data structures
+in the named safe interpreter and then loads Tk into it.
+The command returns the name of the safe interpreter.
+If \fB\-use\fR is specified, the window identified by the specified system
+dependent identifier \fIwindowId\fR is used to contain the \fB``.''\fR
+window of the safe interpreter; it can be any valid id, eventually 
+referencing a window belonging to another application.
+Otherwise, a new toplevel window is created for the \fB``.''\fR window of
+the safe interpreter.
+See the \fBSECURITY ISSUES\fR section below for implementation details.
+
+.SH SECURITY ISSUES
+.PP
+Please read the \fBsafe\fR manual page for Tcl to learn about the basic
+security considerations for Safe Tcl.
+.PP
+Information in the safe interpreter should never be trusted for security
+purposes.
+However, because Tk initialization of the safe interpreter do use 
+local information, it is unsafe if the safe interpreter 
+could have gained control before Tk is loaded.
+This will be fixed in an upcoming release, by making Tk initialization in a
+safe interpreter use only information found in the interpreter's master
+instead of relying on the (un)safe interpreter state.
+.PP
+You should therefore use \fBsafe::loadTk $slave\fR as soon as possible
+after \fBsafe::interpCreate\fR and before any code is evaluated in the safe
+interpreter.
+The preferred sequence is:
+.CS
+set slave [::safe::loadTk [::safe::interpCreate]]
+.CE
+If you want to prevent safe interpreters from loading Tk entirely, you
+should create the interpreter as follows:
+.CS
+::safe::interpCreate \-nostatics \-accesspath \fI{directories...}\fR
+.CE
+and you must also insure that the virtual access path \fIdirectories\fR for
+the interpreter does not contain a dynamically loadable version of Tk.
+.PP
+\fB::safe::loadTk\fR adds the value of \fBtk_library\fR taken from the master
+interpreter to the virtual access path of the safe interpreter so that
+auto-loading will work in the safe interpreter.
+It also sets \fBenv(DISPLAY)\fR in the safe interpreter to the value of
+\fBenv(DISPLAY)\fR in the master interpreter, if it exists.
+Finally, it sets the slave's Tcl variable \fBargv\fR to \fB\-use\fR 
+\fIwindowId\fR in the safe interpreter.
+
+When \fB\-use\fR is not used, the new toplevel created is specially
+decorated so the user is always aware that the user interface presented comes
+from a potentially unsafe code and can easily delete the corresponding
+interpreter.
+
+.SH "SEE ALSO"
+safe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n)
+ 
+.SH KEYWORDS
+alias, auto\-loading, auto_mkindex, load, master interpreter, safe
+interpreter, slave interpreter, source