diff options
Diffstat (limited to 'doc/safe.n')
| -rw-r--r-- | doc/safe.n | 104 |
1 files changed, 52 insertions, 52 deletions
@@ -11,17 +11,17 @@ .SH NAME safe \- Creating and manipulating safe interpreters .SH SYNOPSIS -\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR? +\fB::safe::interpCreate\fR ?\fIchild\fR? ?\fIoptions...\fR? .sp -\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR? +\fB::safe::interpInit\fR \fIchild\fR ?\fIoptions...\fR? .sp -\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR? +\fB::safe::interpConfigure\fR \fIchild\fR ?\fIoptions...\fR? .sp -\fB::safe::interpDelete\fR \fIslave\fR +\fB::safe::interpDelete\fR \fIchild\fR .sp -\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR +\fB::safe::interpAddToAccessPath\fR \fIchild\fR \fIdirectory\fR .sp -\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR +\fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR .sp \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? .SS OPTIONS @@ -44,7 +44,7 @@ application or computer. Untrusted scripts are also prevented from disclosing information stored on the hosting computer or in the hosting application to any party. .PP -Safe Tcl allows a master interpreter to create safe, restricted +Safe Tcl allows a parent interpreter to create safe, restricted interpreters that contain a set of predefined aliases for the \fBsource\fR, \fBload\fR, \fBfile\fR, \fBencoding\fR, and \fBexit\fR commands and are able to use the auto-loading and package mechanisms. @@ -53,47 +53,47 @@ 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 +parent 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. .PP -All commands provided in the master interpreter by Safe Tcl reside in +All commands provided in the parent interpreter by Safe Tcl reside in the \fBsafe\fR namespace. .SH COMMANDS -The following commands are provided in the master interpreter: +The following commands are provided in the parent interpreter: .TP -\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR? +\fB::safe::interpCreate\fR ?\fIchild\fR? ?\fIoptions...\fR? Creates a safe interpreter, installs the aliases described in the section \fBALIASES\fR and initializes the auto-loading and package mechanism as specified by the supplied \fIoptions\fR. See the \fBOPTIONS\fR section below for a description of the optional arguments. -If the \fIslave\fR argument is omitted, a name will be generated. +If the \fIchild\fR argument is omitted, a name will be generated. \fB::safe::interpCreate\fR always returns the interpreter name. .sp -The interpreter name \fIslave\fR may include namespace separators, +The interpreter name \fIchild\fR may include namespace separators, but may not have leading or trailing namespace separators, or excess colon characters in namespace separators. The interpreter name is qualified relative to the global namespace ::, not the namespace in which the \fB::safe::interpCreate\fR command is evaluated. .TP -\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR? +\fB::safe::interpInit\fR \fIchild\fR ?\fIoptions...\fR? This command is similar to \fBinterpCreate\fR except it that does not -create the safe interpreter. \fIslave\fR must have been created by some +create the safe interpreter. \fIchild\fR must have been created by some other means, like \fBinterp create\fR \fB\-safe\fR. The interpreter -name \fIslave\fR may include namespace separators, subject to the same +name \fIchild\fR may include namespace separators, subject to the same restrictions as for \fBinterpCreate\fR. .TP -\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR? +\fB::safe::interpConfigure\fR \fIchild\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 \fIchild\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 -for that option and the \fIslave\fR. +for that option and the \fIchild\fR. If more than two additional arguments are provided, it will reconfigure the safe interpreter and change each and only the provided options. See the section on \fBOPTIONS\fR below for options description. @@ -113,14 +113,14 @@ safe::interpConfigure $i0 \-delete {foo bar} \-statics 0 .CE .RE .TP -\fB::safe::interpDelete\fR \fIslave\fR +\fB::safe::interpDelete\fR \fIchild\fR Deletes the safe interpreter and cleans up the corresponding -master interpreter data structures. +parent 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 interpreter as an additional argument. .TP -\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR +\fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR This command finds and returns the token for the real directory \fIdirectory\fR in the safe interpreter's current virtual access path. It generates an error if the directory is not found. @@ -128,14 +128,14 @@ Example of use: .RS .PP .CS -$slave eval [list set tk_library \e +$child eval [list set tk_library \e [::safe::interpFindInAccessPath $name $tk_library]] .CE .RE .TP -\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR +\fB::safe::interpAddToAccessPath\fR \fIchild\fR \fIdirectory\fR This command adds \fIdirectory\fR to the virtual path maintained for the -safe interpreter in the master, and returns the token that can be used in +safe interpreter in the parent, and returns the token that can be used in the safe interpreter to obtain access to files in that directory. If the directory is already in the virtual path, it only returns the token without adding the directory to the virtual path again. @@ -143,7 +143,7 @@ Example of use: .RS .PP .CS -$slave eval [list set tk_library \e +$child eval [list set tk_library \e [::safe::interpAddToAccessPath $name $tk_library]] .CE .RE @@ -176,10 +176,10 @@ Note that the safe interpreter only received an error message saying that the file was not found: .PP .CS -NOTICE for slave interp10 : Created -NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=() -NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)} -ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory +NOTICE for child interp10 : Created +NOTICE for child interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=() +NOTICE for child interp10 : auto_path in interp10 has been set to {$p(:0:)} +ERROR for child interp10 : /foo/bar/init.tcl: no such file or directory .CE .RE .SS OPTIONS @@ -195,7 +195,7 @@ 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. +parent for auto-loading. See the section \fBSECURITY\fR below for more detail about virtual paths, tokens and access control. .TP @@ -224,7 +224,7 @@ to load packages into its own sub-interpreters. .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 +evaluated in the parent with the name of the safe interpreter as an additional argument just before actually deleting the safe interpreter. Giving an empty value removes any currently installed deletion hook @@ -289,8 +289,8 @@ potential for information leakage about its directory structure. To prevent this, commands that take file names as arguments in a safe interpreter use tokens instead of the real directory names. These tokens are translated to the real directory name while a request to, -e.g., source a file is mediated by the master interpreter. -This virtual path system is maintained in the master interpreter for each safe +e.g., source a file is mediated by the parent interpreter. +This virtual path system is maintained in the parent 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 @@ -299,7 +299,7 @@ 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 +for the \fBsource\fR and \fBload\fR aliases provided to the child 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 @@ -328,26 +328,26 @@ or be called .PP Each element of the initial access path 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. +the child \fBauto_path\fR and the first element of that list will be set as +the \fBtcl_library\fR for that child. .PP 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: +the default behavior is to let the child access the same packages +as the parent 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. -In order that the slave successfully loads the Tcl library files +as they run in the child interpreter) and C extensions that +provides a _SafeInit entry point). For that purpose, the parent's +\fBauto_path\fR will be used to construct the child access path. +In order that the child 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 -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). -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. +child access path, so the child +\fBtcl_library\fR will be the same as the parent's (its real +path will still be invisible to the child though). +In order that auto-loading works the same for the child and +the parent in this by default case, the first-level +sub directories of each directory in the parent \fBauto_path\fR will +also be added (if not already included) to the child access path. You can always specify a more restrictive path for which sub directories will never be searched by explicitly specifying your directory list with the \fB\-accessPath\fR flag @@ -360,8 +360,8 @@ to synchronize its \fBauto_index\fR with the new token list. .SH "SEE ALSO" 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 +alias, auto\-loading, auto_mkindex, load, parent interpreter, safe +interpreter, child interpreter, source '\" Local Variables: '\" mode: nroff '\" End: |