diff options
| author | kjnash <k.j.nash@usa.net> | 2022-08-31 14:28:57 (GMT) |
|---|---|---|
| committer | kjnash <k.j.nash@usa.net> | 2022-08-31 14:28:57 (GMT) |
| commit | 19f8c3bb6b2aa8d571a7534b588ddacfb49952d3 (patch) | |
| tree | 5051f34456c20c798d30e7741fae52575927fd7a /doc | |
| parent | d9b5be0959a8ee2b81ba519ff3d4c70b2da9a6ce (diff) | |
| parent | ff1e919a1bae9ff88ab6dbc094b18cfadedfe8af (diff) | |
| download | tcl-19f8c3bb6b2aa8d571a7534b588ddacfb49952d3.zip tcl-19f8c3bb6b2aa8d571a7534b588ddacfb49952d3.tar.gz tcl-19f8c3bb6b2aa8d571a7534b588ddacfb49952d3.tar.bz2 | |
Merge old 8.7 674a6ad0472c7
Diffstat (limited to 'doc')
44 files changed, 365 insertions, 319 deletions
diff --git a/doc/CrtAlias.3 b/doc/CrtAlias.3 index 10192e9..92f9b0c 100644 --- a/doc/CrtAlias.3 +++ b/doc/CrtAlias.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands +Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -20,31 +20,40 @@ int \fBTcl_MakeSafe\fR(\fIinterp\fR) .sp Tcl_Interp * +\fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR) +.sp +Tcl_Interp * \fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR) .sp Tcl_Interp * \fBTcl_GetSlave\fR(\fIinterp, name\fR) .sp Tcl_Interp * +\fBTcl_GetChild\fR(\fIinterp, name\fR) +.sp +Tcl_Interp * \fBTcl_GetMaster\fR(\fIinterp\fR) .sp +Tcl_Interp * +\fBTcl_GetParent\fR(\fIinterp\fR) +.sp int -\fBTcl_GetInterpPath\fR(\fIinterp, slaveInterp\fR) +\fBTcl_GetInterpPath\fR(\fIinterp, childInterp\fR) .sp int -\fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd, +\fBTcl_CreateAlias\fR(\fIchildInterp, childCmd, targetInterp, targetCmd, argc, argv\fR) .sp int -\fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd, +\fBTcl_CreateAliasObj\fR(\fIchildInterp, childCmd, targetInterp, targetCmd, objc, objv\fR) .sp int -\fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr, +\fBTcl_GetAlias\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR) .sp int -\fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr, +\fBTcl_GetAliasObj\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr\fR) .sp int @@ -57,16 +66,16 @@ int .AP Tcl_Interp *interp in Interpreter in which to execute the specified command. .AP "const char" *name in -Name of slave interpreter to create or manipulate. +Name of child interpreter to create or manipulate. .AP int isSafe in If non-zero, a .QW safe -slave that is suitable for running untrusted code -is created, otherwise a trusted slave is created. -.AP Tcl_Interp *slaveInterp in +child that is suitable for running untrusted code +is created, otherwise a trusted child is created. +.AP Tcl_Interp *childInterp in Interpreter to use for creating the source command for an alias (see below). -.AP "const char" *slaveCmd in +.AP "const char" *childCmd in Name of source command for alias. .AP Tcl_Interp *targetInterp in Interpreter that contains the target command for an alias. @@ -121,17 +130,19 @@ interpreter. The return value for those procedures that return an \fBint\fR is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned then the interpreter's result contains an error message. .PP -\fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR. -It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which -allows \fIinterp\fR to manipulate the new slave. -If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl +\fBTcl_CreateChild\fR creates a new interpreter as a child of \fIinterp\fR. +It also creates a child command named \fIname\fR in \fIinterp\fR which +allows \fIinterp\fR to manipulate the new child. +If \fIisSafe\fR is zero, the command creates a trusted child in which Tcl code has access to all the Tcl commands. If it is \fB1\fR, the command creates a .QW safe -slave in which Tcl code has access only to set of Tcl commands defined as +child in which Tcl code has access only to set of Tcl commands defined as .QW "Safe Tcl" ; see the manual entry for the Tcl \fBinterp\fR command for details. -If the creation of the new slave interpreter failed, \fBNULL\fR is returned. +If the creation of the new child interpreter failed, \fBNULL\fR is returned. +.PP +\fBTcl_CreateSlave\fR is a synonym for \fBTcl_CreateChild\fR. .PP \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is .QW safe @@ -147,34 +158,38 @@ from \fIinterp\fR. However, it cannot know what parts of an extension or application are safe and does not make any attempt to remove those parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR. Callers will want to take care with their use of \fBTcl_MakeSafe\fR -to avoid false claims of safety. For many situations, \fBTcl_CreateSlave\fR +to avoid false claims of safety. For many situations, \fBTcl_CreateChild\fR may be a better choice, since it creates interpreters in a known-safe state. .PP -\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of -\fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR. -If no such slave interpreter exists, \fBNULL\fR is returned. +\fBTcl_GetChild\fR returns a pointer to a child interpreter of +\fIinterp\fR. The child interpreter is identified by \fIname\fR. +If no such child interpreter exists, \fBNULL\fR is returned. .PP -\fBTcl_GetMaster\fR returns a pointer to the master interpreter of -\fIinterp\fR. If \fIinterp\fR has no master (it is a +\fBTcl_GetSlave\fR is a synonym for \fBTcl_GetChild\fR. +.PP +\fBTcl_GetParent\fR returns a pointer to the parent interpreter of +\fIinterp\fR. If \fIinterp\fR has no parent (it is a top-level interpreter) then \fBNULL\fR is returned. .PP +\fBTcl_GetMaster\fR is a synonym for \fBTcl_GetParent\fR. +.PP \fBTcl_GetInterpPath\fR stores in the result of \fIinterp\fR -the relative path between \fIinterp\fR and \fIslaveInterp\fR; -\fIslaveInterp\fR must be a slave of \fIinterp\fR. If the computation +the relative path between \fIinterp\fR and \fIchildInterp\fR; +\fIchildInterp\fR must be a child of \fIinterp\fR. If the computation of the relative path succeeds, \fBTCL_OK\fR is returned, else \fBTCL_ERROR\fR is returned and an error message is stored as the result of \fIinterp\fR. .PP -\fBTcl_CreateAlias\fR creates a command named \fIslaveCmd\fR in -\fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR +\fBTcl_CreateAlias\fR creates a command named \fIchildCmd\fR in +\fIchildInterp\fR that when invoked, will cause the command \fItargetCmd\fR to be invoked in \fItargetInterp\fR. The arguments specified by the strings contained in \fIargv\fR are always prepended to any arguments supplied in the -invocation of \fIslaveCmd\fR and passed to \fItargetCmd\fR. +invocation of \fIchildCmd\fR and passed to \fItargetCmd\fR. This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if it fails; in that case, an error message is left in the value result -of \fIslaveInterp\fR. +of \fIchildInterp\fR. Note that there are no restrictions on the ancestry relationship (as -created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and +created by \fBTcl_CreateChild\fR) between \fIchildInterp\fR and \fItargetInterp\fR. Any two interpreters can be used, without any restrictions on how they are related. .PP @@ -233,4 +248,4 @@ interp .SH KEYWORDS alias, command, exposed commands, hidden commands, interpreter, invoke, -master, slave +parent, child diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 929b1b8..0092cfb 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -259,7 +259,8 @@ outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to the generic layer that the events specified by \fImask\fR have occurred on the channel. Channel drivers are responsible for invoking this function whenever the channel handlers need to be called for the -channel. See \fBWATCHPROC\fR below for more details. +channel (or other pending tasks like a write flush should be performed). +See \fBWATCHPROC\fR below for more details. .PP \fBTcl_BadChannelOption\fR is called from driver specific \fIsetOptionProc\fR or \fIgetOptionProc\fR to generate a complete diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index d5353ac..b1e6483 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -1,7 +1,7 @@ '\" '\" Copyright (c) 1989-1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 2002 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +'\" Copyright (c) 2002 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/doc/DumpActiveMemory.3 b/doc/DumpActiveMemory.3 index 43333da..226209a 100644 --- a/doc/DumpActiveMemory.3 +++ b/doc/DumpActiveMemory.3 @@ -1,6 +1,6 @@ '\" -'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans. -'\" Copyright (c) 2000 by Scriptics Corporation. +'\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans. +'\" Copyright (c) 2000 Scriptics Corporation. '\" All rights reserved. '\" .TH "Tcl_DumpActiveMemory" 3 8.1 Tcl "Tcl Library Procedures" diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index 3b50232..4e77114 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -414,7 +414,7 @@ caller (with a reference count of 0). the encoding identified by \fIencodingName\fR and evaluates its contents as a Tcl script. It returns the same information as \fBTcl_EvalObjEx\fR. -If \fIencodingName\fR is NULL, the system encoding is used for +If \fIencodingName\fR is NULL, the utf-8 encoding is used for reading the file contents. If the file could not be read then a Tcl error is returned to describe why the file could not be read. @@ -430,7 +430,7 @@ or which will be safely substituted by the Tcl interpreter into .QW ^Z . \fBTcl_FSEvalFile\fR is a simpler version of -\fBTcl_FSEvalFileEx\fR that always uses the system encoding +\fBTcl_FSEvalFileEx\fR that always uses the utf-8 encoding when reading the file. .PP \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and @@ -1340,11 +1340,11 @@ is considered to be owned by the filesystem (not by Tcl's core), but should be given a reference count for Tcl. Tcl will use the contents of the list and then decrement that reference count. This allows filesystems to choose whether they actually want to retain a -.QW "master list" +.QW "global list" of volumes or not (if not, they generate the list on the fly and pass it to Tcl with a reference count of 1 and then forget about the list, if yes, then -they simply increment the reference count of their master list and pass it +they simply increment the reference count of their global list and pass it to Tcl which will copy the contents and then decrement the count back to where it was). .PP diff --git a/doc/GetHostName.3 b/doc/GetHostName.3 index 73432d3..8e43f8e 100644 --- a/doc/GetHostName.3 +++ b/doc/GetHostName.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tcl_GetHostName 3 8.3 Tcl "Tcl Library Procedures" diff --git a/doc/GetIndex.3 b/doc/GetIndex.3 index 17a31d4..8591c56 100644 --- a/doc/GetIndex.3 +++ b/doc/GetIndex.3 @@ -27,19 +27,22 @@ Interpreter to use for error reporting; if NULL, then no message is provided on errors. .AP Tcl_Obj *objPtr in/out The string value of this value is used to search through \fItablePtr\fR. -The internal representation is modified to hold the index of the matching +If the \fBTCL_INDEX_TEMP_TABLE\fR flag is not specified, +the internal representation is modified to hold the index of the matching table entry. .AP "const char *const" *tablePtr in An array of null-terminated strings. The end of the array is marked by a NULL string pointer. -Note that references to the \fItablePtr\fR may be retained in the +Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified, +references to the \fItablePtr\fR may be retained in the internal representation of \fIobjPtr\fR, so this should represent the address of a statically-allocated array. .AP "const void" *structTablePtr in An array of arbitrary type, typically some \fBstruct\fR type. The first member of the structure must be a null-terminated string. The size of the structure is given by \fIoffset\fR. -Note that references to the \fIstructTablePtr\fR may be retained in the +Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified, +references to the \fIstructTablePtr\fR may be retained in the internal representation of \fIobjPtr\fR, so this should represent the address of a statically-allocated array of structures. .AP int offset in @@ -50,7 +53,8 @@ Null-terminated string describing what is being looked up, such as \fBoption\fR. This string is included in error messages. .AP int flags in OR-ed combination of bits providing additional information for -operation. The only bit that is currently defined is \fBTCL_EXACT\fR. +operation. The only bits that are currently defined are \fBTCL_EXACT\fR +and \fBTCL_INDEX_TEMP_TABLE\fR. .AP int *indexPtr out The index of the string in \fItablePtr\fR that matches the value of \fIobjPtr\fR is returned here. @@ -76,7 +80,8 @@ error message to indicate what was being looked up. For example, if \fImsg\fR is \fBoption\fR the error message will have a form like .QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" . .PP -If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the +If the \fBTCL_INDEX_TEMP_TABLE\fR was not specified, when +\fBTcl_GetIndexFromObj\fR completes successfully it modifies the internal representation of \fIobjPtr\fR to hold the address of the table and the index of the matching entry. If \fBTcl_GetIndexFromObj\fR is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR @@ -84,7 +89,9 @@ arguments (e.g. during a reinvocation of a Tcl command), it returns the matching index immediately without having to redo the lookup operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries in \fItablePtr\fR are static: they must not change between -invocations. If the value of \fIobjPtr\fR is the empty string, +invocations. This caching mechanism can be disallowed by specifying +the \fBTCL_INDEX_TEMP_TABLE\fR flag. +If the value of \fIobjPtr\fR is the empty string, \fBTcl_GetIndexFromObj\fR will treat it as a non-matching value and return \fBTCL_ERROR\fR. .PP diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3 index be0e79f..3472fee 100644 --- a/doc/GetStdChan.3 +++ b/doc/GetStdChan.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1996 by Sun Microsystems, Inc. +'\" Copyright (c) 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. diff --git a/doc/GetTime.3 b/doc/GetTime.3 index 9f96be5..9dc4056 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>. +'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" diff --git a/doc/Limit.3 b/doc/Limit.3 index 5939a80..3d202fc 100644 --- a/doc/Limit.3 +++ b/doc/Limit.3 @@ -116,7 +116,7 @@ execution of the callbacks is unspecified) execution in the limited interpreter is stopped by raising an error and setting a flag that prevents the \fBcatch\fR command in that interpreter from trapping that error. It is up to the context that started execution in that -interpreter (typically a master interpreter) to handle the error. +interpreter (typically the main interpreter) to handle the error. .SH "LIMIT CHECKING API" .PP To check the resource limits for an interpreter, call @@ -1,6 +1,6 @@ .\" -.\" Copyright (c) 2008 by Kevin B. Kenny. -.\" Copyright (c) 2018 by Nathan Coulter. +.\" Copyright (c) 2008 Kevin B. Kenny. +.\" Copyright (c) 2018 Nathan Coulter. .\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -232,5 +232,5 @@ Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandF .SH KEYWORDS stackless, nonrecursive, execute, command, global, value, result, script .SH COPYRIGHT -Copyright (c) 2008 by Kevin B. Kenny. -Copyright (c) 2018 by Nathan Coulter. +Copyright \(co 2008 Kevin B. Kenny. +Copyright \(co 2018 Nathan Coulter. diff --git a/doc/SaveResult.3 b/doc/SaveResult.3 index e62d22d..804f9ec 100644 --- a/doc/SaveResult.3 +++ b/doc/SaveResult.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1997 by Sun Microsystems, Inc. +'\" Copyright (c) 1997 Sun Microsystems, Inc. '\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright) '\" Copyright (c) 2018 Nathan Coulter. '\" diff --git a/doc/SourceRCFile.3 b/doc/SourceRCFile.3 index 0afb66b..bf8c527 100644 --- a/doc/SourceRCFile.3 +++ b/doc/SourceRCFile.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tcl_SourceRCFile 3 8.3 Tcl "Tcl Library Procedures" diff --git a/doc/StdChannels.3 b/doc/StdChannels.3 index 7cb75a0..d3ecff2 100644 --- a/doc/StdChannels.3 +++ b/doc/StdChannels.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 2001 by ActiveState Corporation +'\" Copyright (c) 2001 ActiveState Corporation '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3 index 3a014d4..59af6ba 100644 --- a/doc/TCL_MEM_DEBUG.3 +++ b/doc/TCL_MEM_DEBUG.3 @@ -1,6 +1,6 @@ '\" -'\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans. -'\" Copyright (c) 2000 by Scriptics Corporation. +'\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans. +'\" Copyright (c) 2000 Scriptics Corporation. '\" All rights reserved. '\" .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures" @@ -224,7 +224,7 @@ is reached. The upper bits of the Unicode character will be 0. .RS .PP The range U+00D800\(enU+00DFFF is reserved for surrogates, which -are illegal on its own. Therefore, such sequences will result in +are illegal on their own. Therefore, such sequences will result in the replacement character U+FFFD. Surrogate pairs should be encoded as single \e\fBU\fIhhhhhhhh\fR character. .RE diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index dc4f45f..62ceeab 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.3 @@ -79,7 +79,7 @@ against the standard Tcl library. Extensions (stub-enabled or not) are not intended to call \fBTcl_Main\fR. .PP \fBTcl_Main\fR is not thread-safe. It should only be called by -a single master thread of a multi-threaded application. This +a single main thread of a multi-threaded application. This restriction is not a problem with normal use described above. .PP \fBTcl_Main\fR and therefore all applications based upon it, like @@ -112,7 +112,7 @@ The file name and encoding values managed by the routines \fBTcl_SetStartupScript\fR and \fBTcl_GetStartupScript\fR are stored per-thread. Although the storage and retrieval functions of these routines work in any thread, only those -calls in the same master thread as \fBTcl_Main\fR can have +calls in the same main thread as \fBTcl_Main\fR can have any influence on it. .PP The caller of \fBTcl_Main\fR may call \fBTcl_SetStartupScript\fR @@ -126,7 +126,7 @@ a \fIstartup script\fR, and \fIname\fR is taken to be the name of the encoding of the contents of that file. \fBTcl_Main\fR then calls \fBTcl_SetStartupScript\fR with these values. .PP -\fBTcl_Main\fR then defines in its master interpreter +\fBTcl_Main\fR then defines in its main interpreter the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR. .PP @@ -154,9 +154,9 @@ When the \fIappInitProc\fR is finished, \fBTcl_Main\fR calls been requested, if any. If a startup script has been provided, \fBTcl_Main\fR attempts to evaluate it. Otherwise, interactive mode begins with examination of the variable \fItcl_rcFileName\fR -in the master interpreter. If that variable exists and holds the +in the main interpreter. If that variable exists and holds the name of a readable file, the contents of that file are evaluated -in the master interpreter. Then interactive operations begin, +in the main interpreter. Then interactive operations begin, with prompts and command evaluation results written to the standard output channel, and commands read from the standard input channel and then evaluated. The prompts written to the standard output @@ -164,7 +164,7 @@ channel may be customized by defining the Tcl variables \fItcl_prompt1\fR and \fItcl_prompt2\fR as described in the documentation for \fBtclsh\fR. The prompts and command evaluation results are written to the standard output channel only if the Tcl variable \fItcl_interactive\fR in the -master interpreter holds a non-zero integer value. +main interpreter holds a non-zero integer value. .PP \fBTcl_SetMainLoop\fR allows setting an event loop procedure to be run. This allows, for example, Tk to be dynamically loaded and set its event diff --git a/doc/ToUpper.3 b/doc/ToUpper.3 index fd9ddfb..37ebd2b 100644 --- a/doc/ToUpper.3 +++ b/doc/ToUpper.3 @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1997 by Sun Microsystems, Inc. +'\" Copyright (c) 1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/doc/binary.n b/doc/binary.n index 0e8b28e..4a5d6c8 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -1,6 +1,6 @@ '\" -'\" Copyright (c) 1997 by Sun Microsystems, Inc. -'\" Copyright (c) 2008 by Donal K. Fellows +'\" Copyright (c) 1997 Sun Microsystems, Inc. +'\" Copyright (c) 2008 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -762,6 +762,15 @@ high-to-low order within each byte. For example, will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and \fB1000011100000101\fR stored in \fIvar2\fR. .RE +.IP \fBC\fR 5 +This form is similar to \fBA\fR, except that it scans the data from start +and terminates at the first null (C string semantics). For example, +.RS +.CS +\fBbinary scan\fR "abc\e000efghi" C* var1 +.CE +will return \fB1\fR with \fBabc\fR stored in \fIvar1\fR. +.RE .IP \fBH\fR 5 The data is turned into a string of \fIcount\fR hexadecimal digits in high-to-low order represented as a sequence of characters in the set @@ -772,7 +772,7 @@ set offset 0 \fI# Search for string "FOOBAR" in the file\fR while {[\fBchan gets\fR $f line] >= 0} { set idx [string first FOOBAR $line] - if {$idx > -1} { + if {$idx >= 0} { \fI# Found it; rewrite line\fR \fBchan seek\fR $f [expr {$offset + $idx}] diff --git a/doc/clock.n b/doc/clock.n index a3f934a..6a887d9 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -951,7 +951,7 @@ msgcat(n) .SH KEYWORDS clock, date, time .SH "COPYRIGHT" -Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +Copyright \(co 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" Local Variables: '\" mode: nroff '\" End: @@ -61,7 +61,7 @@ of the given patterns (in the style of \fBstring match\fR.) . The script rule tests for matching by assigning the key to the \fIkeyVariable\fR and the value to the \fIvalueVariable\fR, and then evaluating -the given script which should return a boolean value (with the +the given script which should result in a boolean value (with the key/value pair only being included in the result of the \fBdict filter\fR when a true value is returned.) Note that the first argument after the rule selection word is a two-element list. If the diff --git a/doc/encoding.n b/doc/encoding.n index 50ad083..5aac181 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998 by Scriptics Corporation. +'\" Copyright (c) 1998 Scriptics Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -246,15 +246,6 @@ the backslash character. If an argument contains forward slashes as the path separator, it may or may not be recognized as a path name, depending on the program. .PP -Additionally, when calling a 16-bit DOS or Windows 3.X application, all path -names must use the short, cryptic, path format (e.g., using -.QW applba~1.def -instead of -.QW applbakery.default ), -which can be obtained with the -.QW "\fBfile attributes\fI fileName \fB\-shortname\fR" -command. -.PP Two or more forward or backward slashes in a row in a path refer to a network path. For example, a simple concatenation of the root directory \fBc:/\fR with a subdirectory \fB/windows/system\fR will yield @@ -295,11 +286,9 @@ The directory from which the Tcl executable was loaded. .IP \(bu 3 The current directory. .IP \(bu 3 -The Windows NT 32-bit system directory. -.IP \(bu 3 -The Windows NT 16-bit system directory. +The Windows 32-bit system directory. .IP \(bu 3 -The Windows NT home directory. +The Windows home directory. .IP \(bu 3 The directories listed in the path. .PP @@ -1,7 +1,7 @@ '\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994-2000 Sun Microsystems, Inc. -'\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved +'\" Copyright (c) 2005 Kevin B. Kenny <kennykb@acm.org>. All rights reserved '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -41,6 +41,12 @@ When an expression evaluates to an integer, the value is the decimal form of the integer, and when an expression evaluates to a floating-point number, the value is the form produced by the \fB%g\fR format specifier of Tcl's \fBformat\fR command. +.PP +.VS "TIP 582" +You can use \fB#\fR at any point in the expression (except inside double +quotes or braces) to start a comment. Comments last to the end of the line or +the end of the expression, whichever comes first. +.VE "TIP 582" .SS OPERANDS .PP An expression consists of a combination of operands, operators, parentheses and @@ -82,9 +88,9 @@ produces the value on the right side. .PP .CS .ta 9c -\fBexpr\fR 3.1 + $a \fI6.1\fR -\fBexpr\fR 2 + "$a.$b" \fI5.6\fR -\fBexpr\fR 4*[llength "6 2"] \fI8\fR +\fBexpr\fR {3.1 + $a} \fI6.1\fR +\fBexpr\fR {2 + "$a.$b"} \fI5.6\fR +\fBexpr\fR {4*[llength "6 2"]} \fI8\fR \fBexpr\fR {{word one} < "word $a"} \fI0\fR .CE .PP @@ -270,7 +276,7 @@ which means that operands are not evaluated if they are not needed to determine the outcome. For example, in .PP .CS -\fBexpr\fR {$v ? [a] : [b]} +\fBexpr\fR {$v?[a]:[b]} .CE .PP only one of \fB[a]\fR or \fB[b]\fR is evaluated, @@ -487,7 +493,9 @@ value of true: .PP .CS set isTrue [\fBexpr\fR { + # Does the environment variable exist, and... [info exists ::env(SOME_ENV_VAR)] && + # ...does it contain a proper true value? [string is true -strict $::env(SOME_ENV_VAR)] }] .CE @@ -506,8 +514,9 @@ arithmetic, boolean, compare, expression, fuzzy comparison, integer value .nf Copyright \(co 1993 The Regents of the University of California. Copyright \(co 1994-2000 Sun Microsystems Incorporated. -Copyright \(co 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +Copyright \(co 2005 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. .fi '\" Local Variables: '\" mode: nroff +'\" fill-column: 78 '\" End: diff --git a/doc/fpclassify.n b/doc/fpclassify.n index 5bf21c5..41c658c 100644 --- a/doc/fpclassify.n +++ b/doc/fpclassify.n @@ -1,6 +1,6 @@ '\" -'\" Copyright (c) 2018 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved -'\" Copyright (c) 2019 by Donal Fellows +'\" Copyright (c) 2018 Kevin B. Kenny <kennykb@acm.org>. All rights reserved +'\" Copyright (c) 2019 Donal Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -1,6 +1,6 @@ '\" '\" Copyright (c) 1995-1997 Sun Microsystems, Inc. -'\" Copyright (c) 1998-2000 by Ajuba Solutions. +'\" Copyright (c) 1998-2000 Ajuba Solutions. '\" Copyright (c) 2004 ActiveState Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution @@ -78,6 +78,9 @@ when the transaction completes. For this to work, the Tcl event loop must be active. In Tk applications this is always true. For pure-Tcl applications, the caller can use \fB::http::wait\fR after calling \fB::http::geturl\fR to start the event loop. +.PP +\fBNote:\fR The event queue is even used without the \fB-command\fR option. +As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR is running. .SH COMMANDS .TP \fB::http::config\fR ?\fIoptions\fR? @@ -325,9 +328,11 @@ otherwise complain about HTTP/1.1. \fB\-query\fR \fIquery\fR . This flag causes \fB::http::geturl\fR to do a POST request that passes the -\fIquery\fR to the server. The \fIquery\fR must be an x-url-encoding -formatted query. The \fB::http::formatQuery\fR procedure can be used to -do the formatting. +\fIquery\fR as payload verbatim to the server. +The content format (and encoding) of \fIquery\fR is announced by the header +field \fBcontent-type\fR set by the option \fB-type\fR. +\fIquery\fR is an x-url-encoding formatted query, if used for html forms. +The \fB::http::formatQuery\fR procedure can be used to do the formatting. .TP \fB\-queryblocksize\fR \fIsize\fR . @@ -551,6 +556,14 @@ is raised, but the status of the transaction will be \fBeof\fR. . The error message will also be stored in the \fBerror\fR status array element, accessible via \fB::http::error\fR. +.TP +\fBtimeout\fR +. +A timeout occurred before the transaction could complete +.TP +\fBreset\fR +. +user-reset .PP Another error possibility is that \fB::http::geturl\fR is unable to write all the post query data to the server before the server @@ -666,10 +679,9 @@ the post query data to the server. .TP \fBstatus\fR . -Either \fBok\fR, for successful completion, \fBreset\fR for -user-reset, \fBtimeout\fR if a timeout occurred before the transaction -could complete, or \fBerror\fR for an error condition. During the -transaction this value is the empty string. +See description in the chapter \fBERRORS\fR above for a +list and description of \fBstatus\fR. +During the transaction this value is the empty string. .TP \fBtotalsize\fR . diff --git a/doc/interp.n b/doc/interp.n index 54555e3..2943404 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -19,18 +19,18 @@ interp \- Create and manipulate Tcl interpreters .PP This command makes it possible to create one or more new Tcl interpreters that co-exist with the creating interpreter in the -same application. The creating interpreter is called the \fImaster\fR -and the new interpreter is called a \fIslave\fR. -A master can create any number of slaves, and each slave can -itself create additional slaves for which it is master, resulting +same application. The creating interpreter is called the \fIparent\fR +and the new interpreter is called a \fIchild\fR. +A parent can create any number of children, and each child can +itself create additional children for which it is parent, resulting in a hierarchy of interpreters. .PP Each interpreter is independent from the others: it has its own name space for commands, procedures, and global variables. -A master interpreter may create connections between its slaves and +A parent interpreter may create connections between its children and itself using a mechanism called an \fIalias\fR. An \fIalias\fR is -a command in a slave interpreter which, when invoked, causes a -command to be invoked in its master interpreter or in another slave +a command in a child interpreter which, when invoked, causes a +command to be invoked in its parent interpreter or in another child interpreter. The only other connections between interpreters are through environment variables (the \fBenv\fR variable), which are normally shared among all interpreters in the application, @@ -41,7 +41,7 @@ share files and to transfer references to open files from one interpreter to another. .PP The \fBinterp\fR command also provides support for \fIsafe\fR -interpreters. A safe interpreter is a slave whose functions have +interpreters. A safe interpreter is a child whose functions have been greatly restricted, so that it is safe to execute untrusted scripts without fear of them damaging other interpreters or the application's environment. For example, all IO channel creation @@ -54,18 +54,18 @@ instead, it is \fIhidden\fR, so that only trusted interpreters can obtain access to it. For a detailed explanation of hidden commands, see \fBHIDDEN COMMANDS\fR, below. The alias mechanism can be used for protected communication (analogous to a -kernel call) between a slave interpreter and its master. +kernel call) between a child interpreter and its parent. See \fBALIAS INVOCATION\fR, below, for more details on how the alias mechanism works. .PP -A qualified interpreter name is a proper Tcl lists containing a subset of its +A qualified interpreter name is a proper Tcl list containing a subset of its ancestors in the interpreter hierarchy, terminated by the string naming the -interpreter in its immediate master. Interpreter names are relative to the +interpreter in its immediate parent. Interpreter names are relative to the interpreter in which they are used. For example, if .QW \fBa\fR -is a slave of the current interpreter and it has a slave +is a child of the current interpreter and it has a child .QW \fBa1\fR , -which in turn has a slave +which in turn has a child .QW \fBa11\fR , the qualified name of .QW \fBa11\fR @@ -77,14 +77,14 @@ is the list The \fBinterp\fR command, described below, accepts qualified interpreter names as arguments; the interpreter in which the command is being evaluated can always be referred to as \fB{}\fR (the empty list or string). Note that -it is impossible to refer to a master (ancestor) interpreter by name in a -slave interpreter except through aliases. Also, there is no global name by +it is impossible to refer to a parent (ancestor) interpreter by name in a +child interpreter except through aliases. Also, there is no global name by which one can refer to the first interpreter created in an application. Both restrictions are motivated by safety concerns. .SH "THE INTERP COMMAND" .PP The \fBinterp\fR command is used to create, delete, and manipulate -slave interpreters, and to share or transfer +child interpreters, and to share or transfer channels between interpreters. It can have any of several forms, depending on the \fIsubcommand\fR argument: .TP @@ -94,11 +94,11 @@ Returns a Tcl list whose elements are the \fItargetCmd\fR and \fIarg\fRs associated with the alias represented by \fIsrcToken\fR (this is the value returned when the alias was created; it is possible that the name of the source command in the -slave is different from \fIsrcToken\fR). +child is different from \fIsrcToken\fR). .TP \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR . -Deletes the alias for \fIsrcToken\fR in the slave interpreter identified by +Deletes the alias for \fIsrcToken\fR in the child interpreter identified by \fIsrcPath\fR. \fIsrcToken\fR refers to the value returned when the alias was created; if the source command has been renamed, the renamed @@ -106,9 +106,9 @@ command will be deleted. .TP \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR? . -This command creates an alias between one slave and another (see the -\fBalias\fR slave command below for creating aliases between a slave -and its master). In this command, either of the slave interpreters +This command creates an alias between one child and another (see the +\fBalias\fR child command below for creating aliases between a child +and its parent). In this command, either of the child interpreters may be anywhere in the hierarchy of interpreters under the interpreter invoking the command. \fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias. @@ -117,9 +117,9 @@ interpreter. For example, .QW "\fBa b\fR" identifies an interpreter .QW \fBb\fR , -which is a slave of interpreter +which is a child of interpreter .QW \fBa\fR , -which is a slave of the invoking interpreter. An empty list specifies +which is a child of the invoking interpreter. An empty list specifies the interpreter invoking the command. \fIsrcCmd\fR gives the name of a new command, which will be created in the source interpreter. \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter @@ -169,33 +169,33 @@ used. .TP \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? . -Creates a slave interpreter identified by \fIpath\fR and a new command, -called a \fIslave command\fR. The name of the slave command is the last -component of \fIpath\fR. The new slave interpreter and the slave command +Creates a child interpreter identified by \fIpath\fR and a new command, +called a \fIchild command\fR. The name of the child command is the last +component of \fIpath\fR. The new child interpreter and the child command are created in the interpreter identified by the path obtained by removing the last component from \fIpath\fR. For example, if \fIpath\fR is \fBa b -c\fR then a new slave interpreter and slave command named \fBc\fR are +c\fR then a new child interpreter and child command named \fBc\fR are created in the interpreter identified by the path \fBa b\fR. -The slave command may be used to manipulate the new interpreter as +The child command may be used to manipulate the new interpreter as described below. If \fIpath\fR is omitted, Tcl creates a unique name of the form \fBinterp\fIx\fR, where \fIx\fR is an integer, and uses it for the -interpreter and the slave command. If the \fB\-safe\fR switch is specified -(or if the master interpreter is a safe interpreter), the new slave +interpreter and the child command. If the \fB\-safe\fR switch is specified +(or if the parent interpreter is a safe interpreter), the new child interpreter will be created as a safe interpreter with limited -functionality; otherwise the slave will include the full set of Tcl +functionality; otherwise the child will include the full set of Tcl built-in commands and variables. The \fB\-\|\-\fR switch can be used to mark the end of switches; it may be needed if \fIpath\fR is an unusual value such as \fB\-safe\fR. The result of the command is the name of the -new interpreter. The name of a slave interpreter must be unique among all -the slaves for its master; an error occurs if a slave interpreter by the -given name already exists in this master. -The initial recursion limit of the slave interpreter is set to the +new interpreter. The name of a child interpreter must be unique among all +the children for its parent; an error occurs if a child interpreter by the +given name already exists in this parent. +The initial recursion limit of the child interpreter is set to the current recursion limit of its parent interpreter. .TP \fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR?? . Controls whether frame-level stack information is captured in the -slave interpreter identified by \fIpath\fR. If no arguments are +child interpreter identified by \fIpath\fR. If no arguments are given, option and current setting are returned. If \fB\-frame\fR is given, the debug setting is set to the given boolean if provided and the current setting is returned. @@ -237,8 +237,8 @@ consistency of the underlying interpreter's state. \fBinterp\fR \fBdelete \fR?\fIpath ...\fR? . Deletes zero or more interpreters given by the optional \fIpath\fR -arguments, and for each interpreter, it also deletes its slaves. The -command also deletes the slave command for each interpreter deleted. +arguments, and for each interpreter, it also deletes its children. The +command also deletes the child command for each interpreter deleted. For each \fIpath\fR argument, if no interpreter by that name exists, the command raises an error. .TP @@ -246,20 +246,20 @@ exists, the command raises an error. . This command concatenates all of the \fIarg\fR arguments in the same fashion as the \fBconcat\fR command, then evaluates the resulting string as -a Tcl script in the slave interpreter identified by \fIpath\fR. The result +a Tcl script in the child interpreter identified by \fIpath\fR. The result of this evaluation (including all \fBreturn\fR options, such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an error occurs) is returned to the invoking interpreter. Note that the script will be executed in the current context stack frame of the -\fIpath\fR interpreter; this is so that the implementations (in a master -interpreter) of aliases in a slave interpreter can execute scripts in -the slave that find out information about the slave's current state +\fIpath\fR interpreter; this is so that the implementations (in a parent +interpreter) of aliases in a child interpreter can execute scripts in +the child that find out information about the child's current state and stack frame. .TP \fBinterp exists \fIpath\fR . -Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR -exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the +Returns \fB1\fR if a child interpreter by the specified \fIpath\fR +exists in this parent, \fB0\fR otherwise. If \fIpath\fR is omitted, the invoking interpreter is used. .TP \fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR? @@ -285,7 +285,7 @@ Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can not contain namespace qualifiers, or an error is raised. Commands to be hidden by \fBinterp hide\fR are looked up in the global namespace even if the current namespace is not the global one. This -prevents slaves from fooling a master interpreter into hiding the wrong +prevents children from fooling a parent interpreter into hiding the wrong command, by making the current namespace be different from the global one. Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. .TP @@ -369,12 +369,16 @@ Both interpreters must close it to close the underlying IO channel; IO channels accessible in an interpreter are automatically closed when an interpreter is destroyed. .TP -\fBinterp\fR \fBslaves\fR ?\fIpath\fR? +\fBinterp\fR \fBchildren\fR ?\fIpath\fR? . -Returns a Tcl list of the names of all the slave interpreters associated +Returns a Tcl list of the names of all the child interpreters associated with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, the invoking interpreter is used. .TP +\fBinterp\fR \fBslaves\fR ?\fIpath\fR? +. +Synonym for . \fBinterp\fR \fBchildren\fR ?\fIpath\fR? +.TP \fBinterp\fR \fBtarget\fR \fIpath alias\fR . Returns a Tcl list describing the target interpreter for an alias. The @@ -391,48 +395,48 @@ The target command does not have to be defined at the time of this invocation. Causes the IO channel identified by \fIchannelId\fR to become available in the interpreter identified by \fIdestPath\fR and unavailable in the interpreter identified by \fIsrcPath\fR. -.SH "SLAVE COMMAND" +.SH "CHILD COMMAND" .PP -For each slave interpreter created with the \fBinterp\fR command, a -new Tcl command is created in the master interpreter with the same +For each child interpreter created with the \fBinterp\fR command, a +new Tcl command is created in the parent interpreter with the same name as the new interpreter. This command may be used to invoke various operations on the interpreter. It has the following general form: .PP .CS -\fIslave command \fR?\fIarg arg ...\fR? +\fIchild command \fR?\fIarg arg ...\fR? .CE .PP -\fISlave\fR is the name of the interpreter, and \fIcommand\fR +\fIChild\fR is the name of the interpreter, and \fIcommand\fR and the \fIarg\fRs determine the exact behavior of the command. The valid forms of this command are: .TP -\fIslave \fBaliases\fR +\fIchild \fBaliases\fR . Returns a Tcl list whose elements are the tokens of all the -aliases in \fIslave\fR. The tokens correspond to the values returned when +aliases in \fIchild\fR. The tokens correspond to the values returned when the aliases were created (which may not be the same as the current names of the commands). .TP -\fIslave \fBalias \fIsrcToken\fR +\fIchild \fBalias \fIsrcToken\fR . Returns a Tcl list whose elements are the \fItargetCmd\fR and \fIarg\fRs associated with the alias represented by \fIsrcToken\fR (this is the value returned when the alias was created; it is possible that the actual source command in the -slave is different from \fIsrcToken\fR). +child is different from \fIsrcToken\fR). .TP -\fIslave \fBalias \fIsrcToken \fB{}\fR +\fIchild \fBalias \fIsrcToken \fB{}\fR . -Deletes the alias for \fIsrcToken\fR in the slave interpreter. +Deletes the alias for \fIsrcToken\fR in the child interpreter. \fIsrcToken\fR refers to the value returned when the alias was created; if the source command has been renamed, the renamed command will be deleted. .TP -\fIslave \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR? +\fIchild \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR? . Creates an alias such that whenever \fIsrcCmd\fR is invoked -in \fIslave\fR, \fItargetCmd\fR is invoked in the master. +in \fIchild\fR, \fItargetCmd\fR is invoked in the parent. The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional arguments, prepended before any arguments passed in the invocation of \fIsrcCmd\fR. @@ -441,69 +445,69 @@ The command returns a token that uniquely identifies the command created \fIsrcCmd\fR, even if the command is renamed afterwards. The token may but does not have to be equal to \fIsrcCmd\fR. .TP -\fIslave \fBbgerror\fR ?\fIcmdPrefix\fR? +\fIchild \fBbgerror\fR ?\fIcmdPrefix\fR? . This command either gets or sets the current background exception handler -for the \fIslave\fR interpreter. If \fIcmdPrefix\fR is +for the \fIchild\fR interpreter. If \fIcmdPrefix\fR is absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes what to set the interpreter's background exception handler to. See the \fBBACKGROUND EXCEPTION HANDLING\fR section for more details. .TP -\fIslave \fBeval \fIarg \fR?\fIarg ..\fR? +\fIchild \fBeval \fIarg \fR?\fIarg ..\fR? . This command concatenates all of the \fIarg\fR arguments in the same fashion as the \fBconcat\fR command, then evaluates -the resulting string as a Tcl script in \fIslave\fR. +the resulting string as a Tcl script in \fIchild\fR. The result of this evaluation (including all \fBreturn\fR options, such as \fB\-errorinfo\fR and \fB\-errorcode\fR information, if an error occurs) is returned to the invoking interpreter. Note that the script will be executed in the current context stack frame -of \fIslave\fR; this is so that the implementations (in a master -interpreter) of aliases in a slave interpreter can execute scripts in -the slave that find out information about the slave's current state +of \fIchild\fR; this is so that the implementations (in a parent +interpreter) of aliases in a child interpreter can execute scripts in +the child that find out information about the child's current state and stack frame. .TP -\fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR? +\fIchild \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR? . This command exposes the hidden command \fIhiddenName\fR, eventually bringing it back under a new \fIexposedCmdName\fR name (this name is currently accepted only if it is a valid global name space name without any ::), -in \fIslave\fR. +in \fIchild\fR. If an exposed command with the targeted name already exists, this command fails. For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. .TP -\fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? +\fIchild \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? . This command hides the exposed command \fIexposedCmdName\fR, renaming it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if the -argument is not given, in the \fIslave\fR interpreter. +argument is not given, in the \fIchild\fR interpreter. If a hidden command with the targeted name already exists, this command fails. Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can not contain namespace qualifiers, or an error is raised. Commands to be hidden are looked up in the global namespace even if the current namespace is not the global one. This -prevents slaves from fooling a master interpreter into hiding the wrong +prevents children from fooling a parent interpreter into hiding the wrong command, by making the current namespace be different from the global one. For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. .TP -\fIslave \fBhidden\fR +\fIchild \fBhidden\fR . -Returns a list of the names of all hidden commands in \fIslave\fR. +Returns a list of the names of all hidden commands in \fIchild\fR. .TP -\fIslave \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR? +\fIchild \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR? . This command invokes the hidden command \fIhiddenName\fR with the -supplied arguments, in \fIslave\fR. No substitutions or evaluations are +supplied arguments, in \fIchild\fR. No substitutions or evaluations are applied to the arguments. Three \fI\-option\fRs are supported, all of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR. If the \fB\-namespace\fR flag is given, the hidden command is invoked in -the specified namespace in the slave. +the specified namespace in the child. If the \fB\-global\fR flag is given, the command is invoked at the global -level in the slave; otherwise it is invoked at the current call frame and +level in the child; otherwise it is invoked at the current call frame and can access local variables in that or outer call frames. The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a .QW \- @@ -511,37 +515,37 @@ character, and is otherwise unnecessary. If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the \fB\-namespace\fR flag is ignored. Note that the hidden command will be executed (by default) in the -current context stack frame of \fIslave\fR. +current context stack frame of \fIchild\fR. For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. .TP -\fIslave \fBissafe\fR +\fIchild \fBissafe\fR . -Returns \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise. +Returns \fB1\fR if the child interpreter is safe, \fB0\fR otherwise. .TP -\fIslave \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? +\fIchild \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? . Sets up, manipulates and queries the configuration of the resource -limit \fIlimitType\fR for the slave interpreter. If no \fI\-option\fR +limit \fIlimitType\fR for the child interpreter. If no \fI\-option\fR is specified, return the current configuration of the limit. If \fI\-option\fR is the sole argument, return the value of that option. Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of what limits and options are supported. .TP -\fIslave \fBmarktrusted\fR +\fIchild \fBmarktrusted\fR . -Marks the slave interpreter as trusted. Can only be invoked by a +Marks the child interpreter as trusted. Can only be invoked by a trusted interpreter. This command does not expose any hidden -commands in the slave interpreter. The command has no effect if the slave +commands in the child interpreter. The command has no effect if the child is already trusted. .TP -\fIslave\fR \fBrecursionlimit\fR ?\fInewlimit\fR? +\fIchild\fR \fBrecursionlimit\fR ?\fInewlimit\fR? . -Returns the maximum allowable nesting depth for the \fIslave\fR interpreter. -If \fInewlimit\fR is specified, the recursion limit in \fIslave\fR will be +Returns the maximum allowable nesting depth for the \fIchild\fR interpreter. +If \fInewlimit\fR is specified, the recursion limit in \fIchild\fR will be set so that nesting of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR -and related procedures in \fIslave\fR will return an error. +and related procedures in \fIchild\fR will return an error. The \fInewlimit\fR value is also returned. The \fInewlimit\fR value must be a positive integer between 1 and the maximum value of a non-long integer on the platform. @@ -565,14 +569,14 @@ For example, commands to create files on disk are removed, and the \fBexec\fR command is removed, since it could be used to cause damage through subprocesses. Limited access to these facilities can be provided, by creating -aliases to the master interpreter which check their arguments carefully +aliases to the parent interpreter which check their arguments carefully and provide restricted access to a safe subset of facilities. For example, file creation might be allowed in a particular subdirectory and subprocess invocation might be allowed for a carefully selected and fixed set of programs. .PP A safe interpreter is created by specifying the \fB\-safe\fR switch -to the \fBinterp create\fR command. Furthermore, any slave created +to the \fBinterp create\fR command. Furthermore, any child created by a safe interpreter will also be safe. .PP A safe interpreter is created with exactly the following set of @@ -659,15 +663,15 @@ including itself. .SH "ALIAS INVOCATION" .PP The alias mechanism has been carefully designed so that it can -be used safely when an untrusted script is executing -in a safe slave and the target of the alias is a trusted -master. The most important thing in guaranteeing safety is to -ensure that information passed from the slave to the master is -never evaluated or substituted in the master; if this were to -occur, it would enable an evil script in the slave to invoke -arbitrary functions in the master, which would compromise security. -.PP -When the source for an alias is invoked in the slave interpreter, the +be used safely in an untrusted script which is being executed in a +safe interpreter even if the target of the alias is not a safe +interpreter. The most important thing in guaranteeing safety is to +ensure that information passed from the child to the parent is +never evaluated or substituted in the parent; if this were to +occur, it would enable an evil script in the child to invoke +arbitrary functions in the parent, which would compromise security. +.PP +When the source for an alias is invoked in the child interpreter, the usual Tcl substitutions are performed when parsing that command. These substitutions are carried out in the source interpreter just as they would be for any other command invoked in that interpreter. @@ -694,8 +698,8 @@ the alias's source command is parsed in the source interpreter. When writing the \fItargetCmd\fRs for aliases in safe interpreters, it is very important that the arguments to that command never be evaluated or substituted, since this would provide an escape -mechanism whereby the slave interpreter could execute arbitrary -code in the master. This in turn would compromise the security +mechanism whereby the child interpreter could execute arbitrary +code in the parent. This in turn would compromise the security of the system. .SH "HIDDEN COMMANDS" .PP @@ -722,28 +726,28 @@ invoke\fR. Hidden commands and exposed commands reside in separate name spaces. It is possible to define a hidden command and an exposed command by the same name within one interpreter. .PP -Hidden commands in a slave interpreter can be invoked in the body of -procedures called in the master during alias invocation. For example, an -alias for \fBsource\fR could be created in a slave interpreter. When it is -invoked in the slave interpreter, a procedure is called in the master +Hidden commands in a child interpreter can be invoked in the body of +procedures called in the parent during alias invocation. For example, an +alias for \fBsource\fR could be created in a child interpreter. When it is +invoked in the child interpreter, a procedure is called in the parent interpreter to check that the operation is allowable (e.g. it asks to -source a file that the slave interpreter is allowed to access). The -procedure then it invokes the hidden \fBsource\fR command in the slave +source a file that the child interpreter is allowed to access). The +procedure then it invokes the hidden \fBsource\fR command in the child interpreter to actually source in the contents of the file. Note that two -commands named \fBsource\fR exist in the slave interpreter: the alias, and +commands named \fBsource\fR exist in the child interpreter: the alias, and the hidden command. .PP -Because a master interpreter may invoke a hidden command as part of +Because a parent interpreter may invoke a hidden command as part of handling an alias invocation, great care must be taken to avoid evaluating any arguments passed in through the alias invocation. -Otherwise, malicious slave interpreters could cause a trusted master +Otherwise, malicious child interpreters could cause a trusted parent interpreter to execute dangerous commands on their behalf. See the section on \fBALIAS INVOCATION\fR for a more complete discussion of this topic. To help avoid this problem, no substitutions or evaluations are applied to arguments of \fBinterp invokehidden\fR. .PP Safe interpreters are not allowed to invoke hidden commands in themselves -or in their descendants. This prevents safe slaves from gaining access to +or in their descendants. This prevents them from gaining access to hidden functionality in themselves or their descendants. .PP The set of hidden commands in an interpreter can be manipulated by a trusted @@ -762,12 +766,12 @@ qualifiers, and you must first rename a command in a namespace to the global namespace before you can hide it. Commands to be hidden by \fBinterp hide\fR are looked up in the global namespace even if the current namespace is not the global one. This -prevents slaves from fooling a master interpreter into hiding the wrong +prevents children from fooling a parent interpreter into hiding the wrong command, by making the current namespace be different from the global one. .SH "RESOURCE LIMITS" .PP Every interpreter has two kinds of resource limits that may be imposed by any -master interpreter upon its slaves. Command limits (of type \fBcommand\fR) +parent interpreter upon its children. Command limits (of type \fBcommand\fR) restrict the total number of Tcl commands that may be executed by an interpreter (as can be inspected via the \fBinfo cmdcount\fR command), and time limits (of type \fBtime\fR) place a limit by which execution within the @@ -776,7 +780,7 @@ interpreter must complete. Note that time limits are expressed as \fBafter\fR) because they may be modified after creation. .PP When a limit is exceeded for an interpreter, first any handler callbacks -defined by master interpreters are called. If those callbacks increase or +defined by parent interpreters are called. If those callbacks increase or remove the limit, execution within the (previously) limited interpreter continues. If the limit is still in force, an error is generated at that point and normal processing of errors within the interpreter (by the \fBcatch\fR @@ -833,13 +837,13 @@ This option specifies the number of commands that the interpreter may execute before triggering the command limit. This option may be the empty string, which indicates that a command limit is not set for the interpreter. .PP -Where an interpreter with a resource limit set on it creates a slave -interpreter, that slave interpreter will have resource limits imposed on it -that are at least as restrictive as the limits on the creating master -interpreter. If the master interpreter of the limited master wishes to relax +Where an interpreter with a resource limit set on it creates a child +interpreter, that child interpreter will have resource limits imposed on it +that are at least as restrictive as the limits on the creating parent +interpreter. If the parent interpreter of the limited parent wishes to relax these conditions, it should hide the \fBinterp\fR command in the child and then use aliases and the \fBinterp invokehidden\fR subcommand to provide such -access as it chooses to the \fBinterp\fR command to the limited master as +access as it chooses to the \fBinterp\fR command to the limited parent as necessary. .SH "BACKGROUND EXCEPTION HANDLING" .PP @@ -900,9 +904,9 @@ set i [\fBinterp create\fR] } .CE .SH "SEE ALSO" -bgerror(n), load(n), safe(n), Tcl_CreateSlave(3), Tcl_Eval(3), Tcl_BackgroundException(3) +bgerror(n), load(n), safe(n), Tcl_CreateChild(3), Tcl_Eval(3), Tcl_BackgroundException(3) .SH KEYWORDS -alias, master interpreter, safe interpreter, slave interpreter +alias, parent interpreter, safe interpreter, child interpreter '\"Local Variables: '\"mode: nroff '\"End: diff --git a/doc/library.n b/doc/library.n index 4dcd598..8aa8af7 100644 --- a/doc/library.n +++ b/doc/library.n @@ -124,7 +124,7 @@ will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR and generate a new index file \fBfoo/tclIndex\fR. .PP \fBAuto_mkindex\fR parses the Tcl scripts by sourcing them into a -slave interpreter and monitoring the proc and namespace commands that +child interpreter and monitoring the proc and namespace commands that are executed. Extensions can use the (undocumented) auto_mkindex_parser package to register other commands that can contribute to the auto_load index. You will have to read through diff --git a/doc/lindex.n b/doc/lindex.n index 01e0d8b..75fe5e8 100644 --- a/doc/lindex.n +++ b/doc/lindex.n @@ -1,7 +1,7 @@ '\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 2018 by Peter Spjuth. All rights reserved. +'\" Copyright (c) 2018 Peter Spjuth. All rights reserved. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/doc/lrepeat.n b/doc/lrepeat.n index 2e17f9c..9a3fc88 100644 --- a/doc/lrepeat.n +++ b/doc/lrepeat.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 2003 by Simon Geard. All rights reserved. +'\" Copyright (c) 2003 Simon Geard. All rights reserved. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/doc/lreverse.n b/doc/lreverse.n index 2ed496a..e2e3b69 100644 --- a/doc/lreverse.n +++ b/doc/lreverse.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 2006 by Donal K. Fellows. All rights reserved. +'\" Copyright (c) 2006 Donal K. Fellows. All rights reserved. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/doc/mathfunc.n b/doc/mathfunc.n index 375d867..3b7d915 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -1,7 +1,7 @@ '\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994-2000 Sun Microsystems, Inc. -'\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved +'\" Copyright (c) 2005 Kevin B. Kenny <kennykb@acm.org>. All rights reserved '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -360,7 +360,7 @@ expr(n), fpclassify(n), mathop(n), namespace(n) .nf Copyright \(co 1993 The Regents of the University of California. Copyright \(co 1994-2000 Sun Microsystems Incorporated. -Copyright \(co 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>. +Copyright \(co 2005-2006 Kevin B. Kenny <kennykb@acm.org>. .fi '\" Local Variables: '\" mode: nroff diff --git a/doc/memory.n b/doc/memory.n index c8cdb21..4d6a7d1 100644 --- a/doc/memory.n +++ b/doc/memory.n @@ -1,6 +1,6 @@ '\" -'\" Copyright (c) 1992-1999 by Karl Lehenbauer and Mark Diekhans -'\" Copyright (c) 2000 by Scriptics Corporation. +'\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans +'\" Copyright (c) 2000 Scriptics Corporation. '\" All rights reserved. '\" .TH memory n 8.1 Tcl "Tcl Built-In Commands" diff --git a/doc/packagens.n b/doc/packagens.n index a6eee1e..65535ef 100644 --- a/doc/packagens.n +++ b/doc/packagens.n @@ -1,5 +1,5 @@ '\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH pkg::create n 8.3 Tcl "Tcl Built-In Commands" diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n index ec39be9..5a6b905 100644 --- a/doc/pkgMkIndex.n +++ b/doc/pkgMkIndex.n @@ -42,7 +42,7 @@ The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR. \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR with package information about all the files given by the \fIpattern\fR arguments. -It does this by loading each file into a slave +It does this by loading each file into a child interpreter and seeing what packages and new commands appear (this is why it is essential to have \fBpackage provide\fR commands or \fBTcl_PkgProvide\fR calls @@ -109,7 +109,7 @@ the use of \fIauto_reset\fR, and therefore its use is discouraged. .TP 15 \fB\-load \fIpkgPat\fR The index process will pre-load any packages that exist in the -current interpreter and match \fIpkgPat\fR into the slave interpreter used to +current interpreter and match \fIpkgPat\fR into the child interpreter used to generate the index. The pattern match uses string match rules, but without making case distinctions. See \fBCOMPLEX CASES\fR below. diff --git a/doc/re_syntax.n b/doc/re_syntax.n index 8d732ed..4504a58 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -293,12 +293,12 @@ treatment is as if the enclosing delimiters were .QW \fB[.\fR \& and .QW \fB.]\fR .) -For example, if \fBo\fR and \fB\[^o]\fR are the members of an +For example, if \fBo\fR and \fB\(^o\fR are the members of an equivalence class, then .QW \fB[[=o=]]\fR , -.QW \fB[[=\[^o]=]]\fR , +.QW \fB[[=\(^o=]]\fR , and -.QW \fB[o\[^o]]\fR \& +.QW \fB[o\(^o]\fR \& are all synonymous. An equivalence class may not be an endpoint of a range. .RS .PP @@ -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::setSyncMode\fR ?\fInewValue\fR? .sp @@ -47,7 +47,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. @@ -56,47 +56,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. @@ -116,14 +116,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. @@ -131,14 +131,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. @@ -146,7 +146,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 @@ -157,7 +157,7 @@ When an argument is supplied, the command returns an error if the argument is not a boolean value, or if any Safe Base interpreters exist. Typically the value will be set as part of initialization - boolean true for "Sync Mode" on (the default), false for "Sync Mode" off. With "Sync Mode" -on, the Safe Base keeps each slave interpreter's ::auto_path synchronized +on, the Safe Base keeps each child interpreter's ::auto_path synchronized with its access path. See the section \fBSYNC MODE\fR below for details. .TP \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? @@ -188,10 +188,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 @@ -207,7 +207,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 @@ -243,7 +243,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 @@ -308,8 +308,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 @@ -318,7 +318,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 @@ -347,27 +347,27 @@ 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 to \fB::safe::interpCreate\fR or \fB::safe::interpInit\fR 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 @@ -394,7 +394,7 @@ the command Use \fB::safe::interpCreate\fR or \fB::safe::interpInit\fR to create an interpreter with the properties that you require. The simplest way is not to specify \fB\-accessPath\fR or \fB\-autoPath\fR, which means the safe -interpreter will use the same paths as the master interpreter. However, +interpreter will use the same paths as the parent interpreter. However, if \fB\-accessPath\fR is specified, then \fB\-autoPath\fR must also be specified, or else it will be set to {}. .PP @@ -403,7 +403,7 @@ and pkgIndex.txt files according to the same rules as an unsafe interpreter (see pkg_mkIndex(n) and library(n)). .PP With "Sync Mode" on, the option \fB\-autoPath\fR is undefined, and -the Safe Base sets the slave's ::auto_path to a tokenized form of the +the Safe Base sets the child's ::auto_path to a tokenized form of the access path. In addition to the directories present if "Safe Mode" is off, the ::auto_path includes the numerous subdirectories and module paths that belong to the access path. @@ -430,10 +430,10 @@ to call \fB::safe::interpCreate\fR or \fB::safe::interpInit\fR without the \fB\-accessPath\fR or \fB\-autoPath\fR options (or with the \fB\-accessPath\fR option set to the empty list), which will give the safe interpreter the same access as the -master interpreter to packages, modules, and autoloader files. With +parent interpreter to packages, modules, and autoloader files. With "Sync Mode" off, the Safe Base will set the value of \fB\-autoPath\fR to the -master's ::auto_path, and will set the slave's ::auto_path to a tokenized form -of the master's ::auto_path. +parent's ::auto_path, and will set the child's ::auto_path to a tokenized form +of the parent's ::auto_path. .PP With "Sync Mode" off, if a value is specified for \fB\-autoPath\fR, even the empty list, in a call to \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, or @@ -441,11 +441,11 @@ list, in a call to \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, or interpreter's ::auto_path. Any directories that do not also belong to the access path cannot be tokenized and will be silently ignored. However, the value of \fB\-autoPath\fR will remain as specified, and will be used to -re-tokenize the slave's ::auto_path if \fB::safe::interpConfigure\fR is called +re-tokenize the child's ::auto_path if \fB::safe::interpConfigure\fR is called to change the value of \fB\-accessPath\fR. .PP With "Sync Mode" off, if the access path is reset to the values in the -master interpreter by calling \fB::safe::interpConfigure\fR with arguments +parent interpreter by calling \fB::safe::interpConfigure\fR with arguments \fB\-accessPath\fR {}, then the ::auto_path will also be reset unless the argument \fB\-autoPath\fR is supplied to specify a different value. .PP @@ -457,7 +457,7 @@ value for \fB\-autoPath\fR, it will be applied after the \fB\-accessPath\fR argu been processed. Examples of use with "Sync Mode" off: any of these commands will set the -::auto_path to a tokenized form of its value in the master interpreter: +::auto_path to a tokenized form of its value in the parent interpreter: .RS .PP .CS @@ -484,7 +484,7 @@ own value is also specified: /usr/local/TclHome/lib } - # The slave's ::auto_path must be given a suitable value: + # The child's ::auto_path must be given a suitable value: safe::interpConfigure foo -autoPath { /usr/local/TclHome/lib/tcl8.6 @@ -515,9 +515,9 @@ Example of use with "Sync Mode" off: the command .CS safe::interpAddToAccessPath foo /usr/local/TclHome/lib/extras/Img1.4.11 - lassign [safe::interpConfigure foo -autoPath] DUM slaveAutoPath - lappend slaveAutoPath /usr/local/TclHome/lib/extras/Img1.4.11 - safe::interpConfigure foo -autoPath $slaveAutoPath + lassign [safe::interpConfigure foo -autoPath] DUM childAutoPath + lappend childAutoPath /usr/local/TclHome/lib/extras/Img1.4.11 + safe::interpConfigure foo -autoPath $childAutoPath .CE .RE .TP @@ -525,8 +525,8 @@ Example of use with "Sync Mode" off: the command interp(n), library(n), load(n), package(n), pkg_mkIndex(n), source(n), tm(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: diff --git a/doc/socket.n b/doc/socket.n index 823dbd5..8836150 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -1,6 +1,6 @@ '\" '\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998-1999 by Scriptics Corporation. +'\" Copyright (c) 1998-1999 Scriptics Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/doc/source.n b/doc/source.n index 353b8fb..8757cb8 100644 --- a/doc/source.n +++ b/doc/source.n @@ -47,7 +47,7 @@ A leading BOM (Byte order mark) contained in the file is ignored for unicode enc .PP The \fB\-encoding\fR option is used to specify the encoding of the data stored in \fIfileName\fR. When the \fB\-encoding\fR option -is omitted, the system encoding is assumed. +is omitted, the utf-8 encoding is assumed. .SH EXAMPLE .PP Run the script in the file \fBfoo.tcl\fR and then the script in the diff --git a/doc/tcltest.n b/doc/tcltest.n index b161a2b..25e5e5e 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -203,7 +203,7 @@ array. Returns an empty string. .TP \fBrunAllTests\fR . -This is a master command meant to run an entire suite of tests, +This is a main command meant to run an entire suite of tests, spanning multiple files and/or directories, as governed by the configurable options of \fBtcltest\fR. See \fBRUNNING ALL TESTS\fR below for a complete description of the many variations possible @@ -804,17 +804,17 @@ then a copy of \fBinterpreter\fR will be \fBexec\fR'd to evaluate each file. The multi-process operation is useful when testing can cause errors so severe that a process terminates. Although such an error may terminate a child -process evaluating one file, the master process can continue +process evaluating one file, the main process can continue with the rest of the test suite. In multi-process operation, -the configuration of \fBtcltest\fR in the master process is +the configuration of \fBtcltest\fR in the main process is passed to the child processes as command line arguments, with the exception of \fBconfigure \-outfile\fR. The \fBrunAllTests\fR command in the -master process collects all output from the child processes -and collates their results into one master report. Any +main process collects all output from the child processes +and collates their results into one main report. Any reports of individual test failures, or messages requested by a \fBconfigure \-verbose\fR setting are passed directly -on to \fBoutputChannel\fR by the master process. +on to \fBoutputChannel\fR by the main process. .PP After evaluating all selected test files, a summary of the results is printed to \fBoutputChannel\fR. The summary @@ -1134,7 +1134,7 @@ A good namespace to use is a child namespace \fBtest\fR of the namespace of the module you are testing. .PP A test file should also be able to be evaluated directly as a script, -not depending on being called by a master \fBrunAllTests\fR. This +not depending on being called by a main \fBrunAllTests\fR. This means that each test file should process command line arguments to give the tester all the configuration control that \fBtcltest\fR provides. .PP @@ -1145,7 +1145,7 @@ Here is a sketch of a sample test file illustrating those points: .RS .PP .CS -package require tcltest 2.2 +package require tcltest 2.5 eval \fB::tcltest::configure\fR $argv package require example namespace eval ::example::test { @@ -1175,12 +1175,12 @@ doing any necessary setup. This script is usually named \fBall.tcl\fR because that is the default name used by \fBrunAllTests\fR when combining multiple test suites into one testing run. .IP [8] -Here is a sketch of a sample test suite master script: +Here is a sketch of a sample test suite main script: .RS .PP .CS -package require Tcl 8.4 -package require tcltest 2.2 +package require Tcl 8.6 +package require tcltest 2.5 package require example \fB::tcltest::configure\fR -testdir \e [file dirname [file normalize [info script]]] |