diff options
Diffstat (limited to 'doc/safe.n')
| -rw-r--r-- | doc/safe.n | 48 |
1 files changed, 24 insertions, 24 deletions
@@ -3,9 +3,9 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.so man.macros +'\" .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -53,8 +53,8 @@ No knowledge of the file system structure is leaked to the safe interpreter, because it has access only to a virtualized path containing tokens. When the safe interpreter requests to source a file, it uses the token in the virtual path as part of the file name to source; the -master interpreter transparently -translates the token into a real directory name and executes the +master interpreter transparently +translates the token into a real directory name and executes the requested operation (see the section \fBSECURITY\fR below for details). Different levels of security can be selected by using the optional flags of the commands described below. @@ -81,7 +81,7 @@ other means, like \fBinterp create\fR \fB\-safe\fR. \fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR? If no \fIoptions\fR are given, returns the settings for all options for the named safe interpreter as a list of options and their current values -for that \fIslave\fR. +for that \fIslave\fR. If a single additional argument is provided, it will return a list of 2 elements \fIname\fR and \fIvalue\fR where \fIname\fR is the full name of that option and \fIvalue\fR the current value @@ -106,7 +106,7 @@ safe::interpConfigure $i0 \-delete {foo bar} \-statics 0 .RE .TP \fB::safe::interpDelete\fR \fIslave\fR -Deletes the safe interpreter and cleans up the corresponding +Deletes the safe interpreter and cleans up the corresponding master interpreter data structures. If a \fIdeleteHook\fR script was specified for this interpreter it is evaluated before the interpreter is deleted, with the name of the @@ -175,26 +175,26 @@ ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory .CE .RE .SS OPTIONS -The following options are common to -\fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, +The following options are common to +\fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, and \fB::safe::interpConfigure\fR. -Any option name can be abbreviated to its minimal +Any option name can be abbreviated to its minimal non-ambiguous name. Option names are not case sensitive. -.TP +.TP \fB\-accessPath\fR \fIdirectoryList\fR This option sets the list of directories from which the safe interpreter can \fBsource\fR and \fBload\fR files. If this option is not specified, or if it is given as the empty list, the safe interpreter will use the same directories as its master for auto-loading. -See the section \fBSECURITY\fR below for more detail about virtual paths, +See the section \fBSECURITY\fR below for more detail about virtual paths, tokens and access control. .TP \fB\-statics\fR \fIboolean\fR This option specifies if the safe interpreter will be allowed to load statically linked packages (like \fBload {} Tk\fR). -The default value is \fBtrue\fR : +The default value is \fBtrue\fR : safe interpreters are allowed to load statically linked packages. .TP \fB\-noStatics\fR @@ -205,7 +205,7 @@ to load statically linked packages. \fB\-nested\fR \fIboolean\fR This option specifies if the safe interpreter will be allowed to load packages into its own sub-interpreters. -The default value is \fBfalse\fR : +The default value is \fBfalse\fR : safe interpreters are not allowed to load packages into their own sub-interpreters. .TP @@ -213,7 +213,7 @@ their own sub-interpreters. This option is a convenience shortcut for \fB\-nested true\fR and thus specifies the safe interpreter will be allowed to load packages into its own sub-interpreters. -.TP +.TP \fB\-deleteHook\fR \fIscript\fR When this option is given a non-empty \fIscript\fR, it will be evaluated in the master with the name of @@ -286,17 +286,17 @@ This virtual path system is maintained in the master interpreter for each safe interpreter created by \fB::safe::interpCreate\fR or initialized by \fB::safe::interpInit\fR and the path maps tokens accessible in the safe interpreter into real path -names on the local file system thus preventing safe interpreters +names on the local file system thus preventing safe interpreters from gaining knowledge about the structure of the file system of the host on which the interpreter is executing. The only valid file names arguments for the \fBsource\fR and \fBload\fR aliases provided to the slave -are path in the form of +are path in the form of \fB[file join \fItoken filename\fB]\fR (i.e. when using the native file path formats: \fItoken\fB/\fIfilename\fR on Unix and \fItoken\fB\e\fIfilename\fR on Windows), -where \fItoken\fR is representing one of the directories +where \fItoken\fR is representing one of the directories of the \fIaccessPath\fR list and \fIfilename\fR is one file in that directory (no sub directories access are allowed). .PP @@ -323,25 +323,25 @@ list will be assigned a token that will be set in the slave \fBauto_path\fR and the first element of that list will be set as the \fBtcl_library\fR for that slave. .PP -If the access path argument is not given or is the empty list, +If the access path argument is not given or is the empty list, the default behavior is to let the slave access the same packages -as the master has access to (Or to be more precise: +as the master has access to (Or to be more precise: only packages written in Tcl (which by definition cannot be dangerous as they run in the slave interpreter) and C extensions that -provides a _SafeInit entry point). For that purpose, the master's -\fBauto_path\fR will be used to construct the slave access path. +provides a _SafeInit entry point). For that purpose, the master's +\fBauto_path\fR will be used to construct the slave access path. In order that the slave successfully loads the Tcl library files (which includes the auto-loading mechanism itself) the \fBtcl_library\fR will be -added or moved to the first position if necessary, in the +added or moved to the first position if necessary, in the slave access path, so the slave \fBtcl_library\fR will be the same as the master's (its real -path will still be invisible to the slave though). +path will still be invisible to the slave though). In order that auto-loading works the same for the slave and the master in this by default case, the first-level sub directories of each directory in the master \fBauto_path\fR will also be added (if not already included) to the slave access path. You can always specify a more -restrictive path for which sub directories will never be searched by +restrictive path for which sub directories will never be searched by explicitly specifying your directory list with the \fB\-accessPath\fR flag instead of relying on this default mechanism. .PP |