aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/tcl/doc
diff options
context:
space:
mode:
authorPoul-Henning Kamp <phk@FreeBSD.org>1997-07-25 19:27:55 +0000
committerPoul-Henning Kamp <phk@FreeBSD.org>1997-07-25 19:27:55 +0000
commit3d33409926539d866dcea9fc5cb14113b312adf0 (patch)
treed2f88b3e9ffa79ffb2cc1a0699dd3ee96c47c3e5 /contrib/tcl/doc
parent8569730d6bc2e4cb5e784997313325b13518e066 (diff)
downloadsrc-3d33409926539d866dcea9fc5cb14113b312adf0.tar.gz
src-3d33409926539d866dcea9fc5cb14113b312adf0.zip
Import TCL release 8.0 beta 2.
Notes
Notes: svn path=/vendor/tcl/dist/; revision=27676
Diffstat (limited to 'contrib/tcl/doc')
-rw-r--r--contrib/tcl/doc/AddErrInfo.3133
-rw-r--r--contrib/tcl/doc/AppInit.34
-rw-r--r--contrib/tcl/doc/Async.310
-rw-r--r--contrib/tcl/doc/BoolObj.383
-rw-r--r--contrib/tcl/doc/Concat.36
-rw-r--r--contrib/tcl/doc/CrtChannel.3360
-rw-r--r--contrib/tcl/doc/CrtCommand.3129
-rw-r--r--contrib/tcl/doc/CrtFileHdlr.336
-rw-r--r--contrib/tcl/doc/CrtMathFnc.34
-rw-r--r--contrib/tcl/doc/CrtObjCmd.3249
-rw-r--r--contrib/tcl/doc/CrtSlave.3142
-rw-r--r--contrib/tcl/doc/CrtTimerHdlr.37
-rw-r--r--contrib/tcl/doc/DString.310
-rw-r--r--contrib/tcl/doc/DetachPids.36
-rw-r--r--contrib/tcl/doc/DoOneEvent.34
-rw-r--r--contrib/tcl/doc/DoWhenIdle.33
-rw-r--r--contrib/tcl/doc/DoubleObj.379
-rw-r--r--contrib/tcl/doc/Eval.398
-rw-r--r--contrib/tcl/doc/EvalObj.391
-rw-r--r--contrib/tcl/doc/Exit.363
-rw-r--r--contrib/tcl/doc/ExprLong.346
-rw-r--r--contrib/tcl/doc/ExprLongObj.3104
-rw-r--r--contrib/tcl/doc/FindExec.34
-rw-r--r--contrib/tcl/doc/GetIndex.374
-rw-r--r--contrib/tcl/doc/GetOpnFl.312
-rw-r--r--contrib/tcl/doc/IntObj.3104
-rw-r--r--contrib/tcl/doc/LinkVar.39
-rw-r--r--contrib/tcl/doc/ListObj.3249
-rw-r--r--contrib/tcl/doc/Notifier.3475
-rw-r--r--contrib/tcl/doc/ObjSetVar.3162
-rw-r--r--contrib/tcl/doc/Object.3336
-rw-r--r--contrib/tcl/doc/ObjectType.3198
-rw-r--r--contrib/tcl/doc/OpenFileChnl.3146
-rw-r--r--contrib/tcl/doc/OpenTcp.337
-rw-r--r--contrib/tcl/doc/PrintDbl.325
-rw-r--r--contrib/tcl/doc/RecordEval.36
-rw-r--r--contrib/tcl/doc/RegExp.310
-rw-r--r--contrib/tcl/doc/SetResult.3200
-rw-r--r--contrib/tcl/doc/SetVar.377
-rw-r--r--contrib/tcl/doc/SplitList.323
-rw-r--r--contrib/tcl/doc/SplitPath.36
-rw-r--r--contrib/tcl/doc/StaticPkg.311
-rw-r--r--contrib/tcl/doc/StringObj.3132
-rw-r--r--contrib/tcl/doc/Tcl.n10
-rw-r--r--contrib/tcl/doc/TraceVar.312
-rw-r--r--contrib/tcl/doc/Translate.312
-rw-r--r--contrib/tcl/doc/WrongNumArgs.359
-rw-r--r--contrib/tcl/doc/array.n14
-rw-r--r--contrib/tcl/doc/binary.n532
-rw-r--r--contrib/tcl/doc/break.n4
-rw-r--r--contrib/tcl/doc/clock.n12
-rw-r--r--contrib/tcl/doc/concat.n6
-rw-r--r--contrib/tcl/doc/continue.n4
-rw-r--r--contrib/tcl/doc/exec.n204
-rw-r--r--contrib/tcl/doc/expr.n91
-rw-r--r--contrib/tcl/doc/fcopy.n127
-rw-r--r--contrib/tcl/doc/file.n276
-rw-r--r--contrib/tcl/doc/flush.n4
-rw-r--r--contrib/tcl/doc/for.n20
-rw-r--r--contrib/tcl/doc/format.n10
-rw-r--r--contrib/tcl/doc/gets.n4
-rw-r--r--contrib/tcl/doc/glob.n6
-rw-r--r--contrib/tcl/doc/global.n19
-rw-r--r--contrib/tcl/doc/http.n359
-rw-r--r--contrib/tcl/doc/if.n4
-rw-r--r--contrib/tcl/doc/info.n56
-rw-r--r--contrib/tcl/doc/interp.n292
-rw-r--r--contrib/tcl/doc/library.n77
-rw-r--r--contrib/tcl/doc/lindex.n4
-rw-r--r--contrib/tcl/doc/linsert.n4
-rw-r--r--contrib/tcl/doc/list.n6
-rw-r--r--contrib/tcl/doc/load.n31
-rw-r--r--contrib/tcl/doc/lrange.n4
-rw-r--r--contrib/tcl/doc/lreplace.n4
-rw-r--r--contrib/tcl/doc/lsearch.n4
-rw-r--r--contrib/tcl/doc/lsort.n36
-rw-r--r--contrib/tcl/doc/namespace.n663
-rw-r--r--contrib/tcl/doc/open.n136
-rw-r--r--contrib/tcl/doc/pkgMkIndex.n36
-rw-r--r--contrib/tcl/doc/proc.n9
-rw-r--r--contrib/tcl/doc/puts.n6
-rw-r--r--contrib/tcl/doc/read.n4
-rw-r--r--contrib/tcl/doc/regexp.n4
-rw-r--r--contrib/tcl/doc/registry.n162
-rw-r--r--contrib/tcl/doc/regsub.n8
-rw-r--r--contrib/tcl/doc/return.n4
-rw-r--r--contrib/tcl/doc/safe.n303
-rw-r--r--contrib/tcl/doc/scan.n8
-rw-r--r--contrib/tcl/doc/seek.n7
-rw-r--r--contrib/tcl/doc/set.n24
-rw-r--r--contrib/tcl/doc/string.n13
-rw-r--r--contrib/tcl/doc/tclsh.14
-rw-r--r--contrib/tcl/doc/tclvars.n124
-rw-r--r--contrib/tcl/doc/tell.n4
-rw-r--r--contrib/tcl/doc/trace.n8
-rw-r--r--contrib/tcl/doc/unknown.n4
-rw-r--r--contrib/tcl/doc/upvar.n4
-rw-r--r--contrib/tcl/doc/variable.n67
-rw-r--r--contrib/tcl/doc/while.n24
99 files changed, 6692 insertions, 1204 deletions
diff --git a/contrib/tcl/doc/AddErrInfo.3 b/contrib/tcl/doc/AddErrInfo.3
index 51e75c219b00..91708b81b6ce 100644
--- a/contrib/tcl/doc/AddErrInfo.3
+++ b/contrib/tcl/doc/AddErrInfo.3
@@ -1,24 +1,28 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) AddErrInfo.3 1.21 96/03/25 19:55:32
+'\" SCCS: @(#) AddErrInfo.3 1.28 97/06/12 13:39:53
'\"
.so man.macros
.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
+Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
+\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
+.sp
\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
.sp
-\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fB (char *) NULL\fR)
+\fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
+.sp
+\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
.sp
char *
\fBTcl_PosixError\fR(\fIinterp\fR)
@@ -27,7 +31,19 @@ char *
.AP Tcl_Interp *interp in
Interpreter in which to record information.
.AP char *message in
-Identifying string to record in \fBerrorInfo\fR variable.
+For \fBTcl_AddObjErrorInfo\fR,
+this points to the first byte of an array of bytes
+containing a string to record in the \fBerrorInfo\fR variable.
+This byte array may contain embedded null bytes
+unless \fIlength\fR is negative.
+For \fBTcl_AddErrorInfo\fR,
+this is a conventional C string to record in the \fBerrorInfo\fR variable.
+.AP int length in
+The number of bytes to copy from \fImessage\fR when
+setting the \fBerrorInfo\fR variable.
+If negative, all bytes up to the first null byte are used.
+.AP Tcl_Obj *errorObjPtr in
+This variable \fBerrorCode\fR will be set to this value.
.AP char *element in
String to record as one element of \fBerrorCode\fR variable.
Last \fIelement\fR argument must be NULL.
@@ -38,23 +54,23 @@ Last \fIelement\fR argument must be NULL.
These procedures are used to manipulate two Tcl global variables
that hold information about errors.
The variable \fBerrorInfo\fR holds a stack trace of the
-operations that were in progress when an error occurred, and
-is intended to be human-readable.
+operations that were in progress when an error occurred,
+and is intended to be human-readable.
The variable \fBerrorCode\fR holds a list of items that
are intended to be machine-readable.
The first item in \fBerrorCode\fR identifies the class of
-.VS
-error that occurred (e.g. POSIX means an error occurred in
-.VE
-a POSIX system call) and additional elements in \fBerrorCode\fR
-hold additional pieces of information that depend on the class.
+error that occurred
+(e.g. POSIX means an error occurred in a POSIX system call)
+and additional elements in \fBerrorCode\fR hold additional pieces
+of information that depend on the class.
See the Tcl overview manual entry for details on the various
formats for \fBerrorCode\fR.
.PP
The \fBerrorInfo\fR variable is gradually built up as an
error unwinds through the nested operations.
-Each time an error code is returned to \fBTcl_Eval\fR
-it calls the procedure \fBTcl_AddErrorInfo\fR to add
+Each time an error code is returned to \fBTcl_EvalObj\fR
+(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObj\fR)
+it calls the procedure \fBTcl_AddObjErrorInfo\fR to add
additional text to \fBerrorInfo\fR describing the
command that was being executed when the error occurred.
By the time the error has been passed all the way back
@@ -63,34 +79,46 @@ of the activity in progress when the error occurred.
.PP
It is sometimes useful to add additional information to
\fBerrorInfo\fR beyond what can be supplied automatically
-by \fBTcl_Eval\fR.
-\fBTcl_AddErrorInfo\fR may be used for this purpose:
-its \fImessage\fR argument contains an additional
+by \fBTcl_EvalObj\fR.
+\fBTcl_AddObjErrorInfo\fR may be used for this purpose:
+its \fImessage\fR and \fIlength\fR arguments describe an additional
string to be appended to \fBerrorInfo\fR.
-For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
+For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\fR
to record the name of the file being processed and the
-line number on which the error occurred; for Tcl procedures, the
-procedure name and line number within the procedure are recorded,
-and so on.
-The best time to call \fBTcl_AddErrorInfo\fR is just after
-\fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
-In calling \fBTcl_AddErrorInfo\fR, you may find it useful to
+line number on which the error occurred;
+for Tcl procedures, the procedure name and line number
+within the procedure are recorded, and so on.
+The best time to call \fBTcl_AddObjErrorInfo\fR is just after
+\fBTcl_EvalObj\fR has returned \fBTCL_ERROR\fR.
+In calling \fBTcl_AddObjErrorInfo\fR, you may find it useful to
use the \fBerrorLine\fR field of the interpreter (see the
\fBTcl_Interp\fR manual entry for details).
.PP
-The procedure \fBTcl_SetErrorCode\fR is used to set the
-\fBerrorCode\fR variable.
-Its \fIelement\fR arguments give one or more strings to record
-in \fBerrorCode\fR: each \fIelement\fR will become one item
-of a properly-formed Tcl list stored in \fBerrorCode\fR.
-\fBTcl_SetErrorCode\fR is typically invoked just before returning
-an error.
-If an error is returned without calling \fBTcl_SetErrorCode\fR
-then the Tcl interpreter automatically sets \fBerrorCode\fR
-to \fBNONE\fR.
+\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR
+but differs in initializing \fBerrorInfo\fR from the string
+value of the interpreter's result
+if the error is just starting to be logged.
+It does not use the result as a Tcl object
+so any embedded null characters in the result
+will cause information to be lost.
+It also takes a conventional C string in \fImessage\fR
+instead of \fBTcl_AddObjErrorInfo\fR's counted string.
+.PP
+The procedure \fBTcl_SetObjErrorCode\fR is used to set the
+\fBerrorCode\fR variable. \fIerrorObjPtr\fR contains a list object
+built up by the caller. \fBerrorCode\fR is set to this
+value. \fBTcl_SetObjErrorCode\fR is typically invoked just
+before returning an error in an object command. If an error is
+returned without calling \fBTcl_SetObjErrorCode\fR or
+\fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
+\fBerrorCode\fR to \fBNONE\fR.
+.PP
+The procedure \fBTcl_SetErrorCode\fR is also used to set the
+\fBerrorCode\fR variable. However, it takes one or more strings to
+record instead of an object. Otherwise, it is similar to
+\fBTcl_SetObjErrorCode\fR in behavior.
.PP
\fBTcl_PosixError\fR
-.VS
sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
It reads the value of the \fBerrno\fR C variable and calls
\fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the \fBPOSIX\fR format.
@@ -100,36 +128,39 @@ is linked into an application as a shared library, or when the error
occurs in a dynamically loaded extension. See the manual entry for
\fBTcl_SetErrno\fR for more information.
.PP
-\fBTcl_PosixError\fR returns a human-readable
-.VE
-diagnostic message for the error (this is the same value that
-will appear as the third element in \fBerrorCode\fR).
+\fBTcl_PosixError\fR returns a human-readable diagnostic message
+for the error
+(this is the same value that will appear as the third element
+in \fBerrorCode\fR).
It may be convenient to include this string as part of the
-error message returned to the application in \fIinterp->result\fR.
+error message returned to the application in
+the interpreter's result.
.PP
It is important to call the procedures described here rather than
setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
-\fBTcl_SetVar\fR.
+\fBTcl_ObjSetVar2\fR.
The reason for this is that the Tcl interpreter keeps information
about whether these procedures have been called.
-For example, the first time \fBTcl_AppendResult\fR is called
+For example, the first time \fBTcl_AddObjErrorInfo\fR is called
for an error, it clears the existing value of \fBerrorInfo\fR
-and adds the error message in \fIinterp->result\fR to the variable
-before appending \fImessage\fR; in subsequent calls, it just
-appends the new \fImessage\fR.
+and adds the error message in the interpreter's result to the variable
+before appending \fImessage\fR;
+in subsequent calls, it just appends the new \fImessage\fR.
When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
-that \fBerrorCode\fR has been set; this allows the Tcl interpreter
-to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
+that \fBerrorCode\fR has been set;
+this allows the Tcl interpreter to set \fBerrorCode\fR to \fBNONE\fR
+if it receives an error return
when \fBTcl_SetErrorCode\fR hasn't been called.
.PP
-If the procedure \fBTcl_ResetResult\fR is called, it clears all
-of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
+If the procedure \fBTcl_ResetResult\fR is called,
+it clears all of the state associated with
+\fBerrorInfo\fR and \fBerrorCode\fR
(but it doesn't actually modify the variables).
If an error had occurred, this will clear the error state to
make it appear as if no error had occurred after all.
.SH "SEE ALSO"
-Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
+Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
.SH KEYWORDS
-error, stack, trace, variable
+error, object, object result, stack, trace, variable
diff --git a/contrib/tcl/doc/AppInit.3 b/contrib/tcl/doc/AppInit.3
index 874266187cfe..ca78003a2bee 100644
--- a/contrib/tcl/doc/AppInit.3
+++ b/contrib/tcl/doc/AppInit.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) AppInit.3 1.9 96/03/25 19:56:02
+'\" SCCS: @(#) AppInit.3 1.10 96/08/26 12:59:40
'\"
.so man.macros
.TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
@@ -49,7 +49,6 @@ Tcl variables \fBargv\fR and \fBargv0\fR in \fIinterp\fR.
.IP [3]
Invoke a startup script to initialize the application.
.LP
-.VS
\fBTcl_AppInit\fR returns TCL_OK or TCL_ERROR.
If it returns TCL_ERROR then it must leave an error message in
\fIinterp->result\fR; otherwise the result is ignored.
@@ -69,7 +68,6 @@ The best way to get started is to make a copy of the file
\fBtclAppInit.c\fR from the Tcl library or source directory.
It already contains a \fBmain\fR procedure and a template for
\fBTcl_AppInit\fR that you can modify for your application.
-.VE
.SH KEYWORDS
application, argument, command, initialization, interpreter
diff --git a/contrib/tcl/doc/Async.3 b/contrib/tcl/doc/Async.3
index e40cbca011b2..9a58b097e9fa 100644
--- a/contrib/tcl/doc/Async.3
+++ b/contrib/tcl/doc/Async.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) Async.3 1.13 96/03/25 19:56:31
+'\" SCCS: @(#) Async.3 1.14 96/08/26 12:59:41
'\"
.so man.macros
.TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
@@ -25,11 +25,9 @@ int
\fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
.sp
\fBTcl_AsyncDelete\fR(\fIasync\fR)
-.VS
.sp
int
\fBTcl_AsyncReady\fR()
-.VE
.SH ARGUMENTS
.AS Tcl_AsyncHandler clientData
.AP Tcl_AsyncProc *proc in
@@ -107,21 +105,15 @@ In this case \fIinterp\fR will be NULL and \fIcode\fR will be
.PP
The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the
handlers that are ready.
-.VS
The procedure \fBTcl_AsyncReady\fR will return non-zero whenever any
-.VE
asynchronous handlers are ready; it can be checked to avoid calls
to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
-.VS
Tcl calls \fBTcl_AsyncReady\fR after each command is evaluated
-.VE
and calls \fBTcl_AsyncInvoke\fR if needed.
Applications may also call \fBTcl_AsyncInvoke\fR at interesting
times for that application.
-.VS
For example, Tcl's event handler calls \fBTcl_AsyncReady\fR
after each event and calls \fBTcl_AsyncInvoke\fR if needed.
-.VE
The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR
have the same meaning as for \fIproc\fR: they identify the active
interpreter, if any, and the completion code from the command
diff --git a/contrib/tcl/doc/BoolObj.3 b/contrib/tcl/doc/BoolObj.3
new file mode 100644
index 000000000000..691e5aa679a1
--- /dev/null
+++ b/contrib/tcl/doc/BoolObj.3
@@ -0,0 +1,83 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) @(#) BoolObj.3 1.7 97/05/08 19:50:57
+'\"
+.so man.macros
+.TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- manipulate Tcl objects as boolean values
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewBooleanObj\fR(\fIboolValue\fR)
+.sp
+\fBTcl_SetBooleanObj\fR(\fIobjPtr, boolValue\fR)
+.sp
+int
+\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP int boolValue in
+Integer value used to initialize or set a boolean object.
+If the integer is nonzero, the boolean object is set to 1;
+otherwise the boolean object is set to 0.
+.AP Tcl_Obj *objPtr in/out
+For \fBTcl_SetBooleanObj\fR, this points to the object to be converted
+to boolean type.
+For \fBTcl_GetBooleanFromObj\fR, this refers to the object
+from which to get a boolean value;
+if \fIobjPtr\fR does not already point to a boolean object,
+an attempt will be made to convert it to one.
+.AP Tcl_Interp *interp in/out
+If an error occurs during conversion,
+an error message is left in the interpreter's result object
+unless \fIinterp\fR is NULL.
+.AP int *boolPtr out
+Points to place where \fBTcl_GetBooleanFromObj\fR
+stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures are used to create, modify, and read
+boolean Tcl objects from C code.
+\fBTcl_NewBooleanObj\fR and \fBTcl_SetBooleanObj\fR
+will create a new object of boolean type
+or modify an existing object to have boolean type.
+Both of these procedures set the object to have the
+boolean value (0 or 1) specified by \fIboolValue\fR;
+if \fIboolValue\fR is nonzero, the object is set to 1,
+otherwise to 0.
+\fBTcl_NewBooleanObj\fR returns a pointer to a newly created object
+with reference count zero.
+Both procedures set the object's type to be boolean
+and assign the boolean value to the object's internal representation
+\fIlongValue\fR member.
+\fBTcl_SetBooleanObj\fR invalidates any old string representation
+and, if the object is not already a boolean object,
+frees any old internal representation.
+.PP
+\fBTcl_GetBooleanFromObj\fR attempts to return a boolean value
+from the Tcl object \fIobjPtr\fR.
+If the object is not already a boolean object,
+it will attempt to convert it to one.
+If an error occurs during conversion, it returns \fBTCL_ERROR\fR
+and leaves an error message in the interpreter's result object
+unless \fIinterp\fR is NULL.
+Otherwise, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR
+and stores the boolean value in the address given by \fIboolPtr\fR.
+If the object is not already a boolean object,
+the conversion will free any old internal representation.
+
+.SH "SEE ALSO"
+Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
+
+.SH KEYWORDS
+boolean, boolean object, boolean type, internal representation, object, object type, string representation
diff --git a/contrib/tcl/doc/Concat.3 b/contrib/tcl/doc/Concat.3
index 807fcad28ec8..be657324fc6e 100644
--- a/contrib/tcl/doc/Concat.3
+++ b/contrib/tcl/doc/Concat.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) Concat.3 1.11 96/06/05 18:00:12
+'\" SCCS: @(#) Concat.3 1.12 97/06/11 17:54:12
'\"
.so man.macros
.TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures"
@@ -48,6 +48,8 @@ The result string is dynamically allocated
using \fBTcl_Alloc\fR; the caller must eventually release the space
by calling \fBTcl_Free\fR.
.VE
-
+.VS
+.SH "SEE ALSO"
+Tcl_ConcatObj
.SH KEYWORDS
concatenate, strings
diff --git a/contrib/tcl/doc/CrtChannel.3 b/contrib/tcl/doc/CrtChannel.3
index e54f74e25f12..354665a9cf72 100644
--- a/contrib/tcl/doc/CrtChannel.3
+++ b/contrib/tcl/doc/CrtChannel.3
@@ -1,22 +1,22 @@
'\"
-'\" Copyright (c) 1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1996-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.
'\"
-'\" SCCS: @(#) CrtChannel.3 1.23 96/03/28 17:55:41
+'\" SCCS: @(#) CrtChannel.3 1.29 97/06/20 13:37:45
.so man.macros
-.TH Tcl_CreateChannel 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_CreateChannel 3 8.0 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelFile, Tcl_GetChannelBufferSize, Tcl_SetDefaultTranslation, Tcl_SetChannelBufferSize \- procedures for creating and manipulating channels
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetDefaultTranslation, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Channel
-\fBTcl_CreateChannel\fR(\fItypePtr, channelName, inFile, outFile, instanceData\fR)
+\fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
.sp
ClientData
\fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
@@ -26,21 +26,31 @@ Tcl_ChannelType *
.sp
char *
\fBTcl_GetChannelName\fR(\fIchannel\fR)
+.VS
.sp
-Tcl_File
-\fBTcl_GetChannelFile\fR(\fIchannel, direction\fR)
+int
+\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
+.VE
+.sp
+int
+\fBTcl_GetChannelFlags\fR(\fIchannel\fR)
.sp
-void
\fBTcl_SetDefaultTranslation\fR(\fIchannel, transMode\fR)
.sp
int
\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
.sp
-void
\fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
.sp
+.VS
+\fBTcl_NotifyChannel\fR(\fIchannel, mask\fR)
+.sp
+int
+\fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
+.VE
+.sp
.SH ARGUMENTS
-.AS Tcl_FileHandle pipelineSpec in
+.AS Tcl_EolTranslation *channelName in
.AP Tcl_ChannelType *typePtr in
Points to a structure containing the addresses of procedures that
can be called to perform I/O and other functions on the channel.
@@ -48,25 +58,42 @@ can be called to perform I/O and other functions on the channel.
The name of this channel, such as \fBfile3\fR; must not be in use
by any other channel. Can be NULL, in which case the channel is
created without a name.
-.AP Tcl_File inFile in
-Tcl file for the input device to associate with this channel. If NULL,
-input will not be allowed on the channel.
-.AP Tcl_File outFile in
-Tcl file for the output device to associate with this channel. If NULL,
-output will not be allowed on the channel.
.AP ClientData instanceData in
Arbitrary one-word value to be associated with this channel. This
value is passed to procedures in \fItypePtr\fR when they are invoked.
+.AP int mask in
+OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
+whether a channel is readable and writable.
.AP Tcl_Channel channel in
The channel to operate on.
+.VS
.AP int direction in
-\fBTCL_READABLE\fR means the input file is wanted; \fBTCL_WRITABLE\fR
-means the output file is wanted.
+\fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
+means the output handle is wanted.
+.AP ClientData *handlePtr out
+Points to the location where the desired OS-specific handle should be
+stored.
+.VE
.AP Tcl_EolTranslation transMode in
The translation mode; one of the constants \fBTCL_TRANSLATE_AUTO\fR,
\fBTCL_TRANSLATE_CR\fR, \fBTCL_TRANSLATE_LF\fR and \fBTCL_TRANSLATE_CRLF\fR.
.AP int size in
The size, in bytes, of buffers to allocate in this channel.
+.VS
+.AP int mask in
+An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
+and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
+this channel.
+.AP Tcl_Interp *interp in
+Current interpreter. (can be NULL)
+.AP char *optionName in
+Name of the invalid option.
+.AP char *optionList in
+Specific options list (space separated words, without "-")
+to append to the standard generic options list.
+Can be NULL for generic options error message only.
+.VE
+
.BE
.SH DESCRIPTION
@@ -76,12 +103,11 @@ layer to enable C and Tcl programs to perform input and output using the
same APIs for a variety of files, devices, sockets etc. The generic C APIs
are described in the manual entry for \fBTcl_OpenFileChannel\fR.
.PP
-The lower layer provides type-specific channel drivers for each type of
-file, socket and device supported on each platform.
-This manual entry describes the C APIs
-used by the generic layer to communicate with type-specific channel drivers
-to perform the input and output operations. It also explains how new types
-of channels can be added by providing new channel drivers.
+The lower layer provides type-specific channel drivers for each type
+of device supported on each platform. This manual entry describes the
+C APIs used to communicate between the generic layer and the
+type-specific channel drivers. It also explains how new types of
+channels can be added by providing new channel drivers.
.PP
Channel drivers consist of a number of components: First, each channel
driver provides a \fBTcl_ChannelType\fR structure containing pointers to
@@ -90,17 +116,17 @@ communicate with the channel driver. The \fBTcl_ChannelType\fR structure
and the functions referenced by it are described in the section
TCL_CHANNELTYPE, below.
.PP
-Second, channel drivers usually provide a Tcl command to create instances
-of that type of channel. For example, the Tcl \fBopen\fR command creates
-channels that use the \fBfile\fR and \fBcommand\fR channel drivers, and
-the Tcl \fBsocket\fR command creates channels that use TCP sockets for
-network communication.
-.PP
-Third, a channel driver optionally provides a C function to open channel
-instances of that type. For example, \fBTcl_OpenFileChannel\fR opens a
-channel that uses the \fBfile\fR channel driver, and
-\fBTcl_OpenTcpClient\fR opens a channel that uses the TCP network protocol.
-These creation functions typically use
+Second, channel drivers usually provide a Tcl command to create
+instances of that type of channel. For example, the Tcl \fBopen\fR
+command creates channels that use the file and command channel
+drivers, and the Tcl \fBsocket\fR command creates channels that use
+TCP sockets for network communication.
+.PP
+Third, a channel driver optionally provides a C function to open
+channel instances of that type. For example, \fBTcl_OpenFileChannel\fR
+opens a channel that uses the file channel driver, and
+\fBTcl_OpenTcpClient\fR opens a channel that uses the TCP network
+protocol. These creation functions typically use
\fBTcl_CreateChannel\fR internally to open the channel.
.PP
To add a new type of channel you must implement a C API or a Tcl command
@@ -112,7 +138,8 @@ The generic layer will then invoke the functions referenced in that
structure to perform operations on the channel.
.PP
\fBTcl_CreateChannel\fR opens a new channel and associates the supplied
-\fItypePtr\fR, \fIinFile\fR, \fIoutFile\fR and \fIinstanceData\fR with it.
+\fItypePtr\fR and \fIinstanceData\fR with it. The channel is opened in the
+mode indicated by \fImask\fR.
For a discussion of channel drivers, their operations and the
\fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
.PP
@@ -129,11 +156,19 @@ the same as the \fItypePtr\fR argument in the call to
with the channel, or NULL if the \fIchannelName\fR argument to
\fBTcl_CreateChannel\fR was NULL.
.PP
-\fBTcl_GetChannelFile\fR returns the \fIinFile\fR associated with
-\fIchannel\fR if \fIdirection\fR is \fBTCL_READABLE\fR, or the
-\fIoutFile\fR if \fIdirection\fR is \fBTCL_WRITABLE\fR. The operation
-returns NULL if the respective value was specified as NULL in the call to
-\fBTcl_CreateChannel\fR that created \fIchannel\fR.
+.VS
+\fBTcl_GetChannelHandle\fR places the OS-specific device handle
+associated with \fIchannel\fR for the given \fIdirection\fR in the
+location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR. If
+the channel does not have a device handle for the specified direction,
+then \fBTCL_ERROR\fR is returned instead. Different channel drivers
+will return different types of handle. Refer to the manual entries
+for each driver to determine what type of handle is returned.
+.VE
+.PP
+\fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
+and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
+and output.
.PP
\fBTcl_SetDefaultTranslation\fR sets the default end of line translation
mode. This mode will be installed as the translation mode for the channel
@@ -152,6 +187,19 @@ output. The \fIsize\fR argument should be between ten and one million,
allowing buffers of ten bytes to one million bytes. If \fIsize\fR is
outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
4096.
+.PP
+.VS
+\fBTcl_NotifyChannel\fR is called by a channel driver to indicate 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.
+.VE
+.PP
+.VS
+\fBTcl_BadChannelOption\fR is called from driver specific set or get option
+procs to generate a complete error message.
+.VE
.SH TCL_CHANNELTYPE
.PP
@@ -160,6 +208,7 @@ pointers to functions that implement the various operations on a channel;
these operations are invoked as needed by the generic layer. The
\fBTcl_ChannelType\fR structure contains the following fields:
.PP
+.VS
.CS
typedef struct Tcl_ChannelType {
char *\fItypeName\fR;
@@ -170,8 +219,11 @@ typedef struct Tcl_ChannelType {
Tcl_DriverSeekProc *\fIseekProc\fR;
Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
+ Tcl_DriverWatchProc *\fIwatchProc\fR;
+ Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
} Tcl_ChannelType;
.CE
+.VE
.PP
The driver must provide implementations for all functions except
\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, and
@@ -195,25 +247,22 @@ the generic layer to set blocking and nonblocking mode on the device.
.CS
typedef int Tcl_DriverBlockModeProc(
ClientData \fIinstanceData\fR,
- Tcl_File \fIinFile\fR,
- Tcl_File \fIoutFile\fR,
int \fImode\fR);
.CE
.PP
-The \fIinstanceData\fR, \fIinFile\fR and \fIoutFile\fR arguments are the same
-as the values passed to \fBTcl_CreateChannel\fR when this channel was created.
-The \fImode\fR argument is either \fBTCL_MODE_BLOCKING\fR or
-\fBTCL_MODE_NONBLOCKING\fR to set the device into blocking or nonblocking
-mode. The function should return zero if the operation was successful,
-or a nonzero POSIX error code if the operation failed.
+The \fIinstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created. The \fImode\fR
+argument is either \fBTCL_MODE_BLOCKING\fR or \fBTCL_MODE_NONBLOCKING\fR to
+set the device into blocking or nonblocking mode. The function should
+return zero if the operation was successful, or a nonzero POSIX error code
+if the operation failed.
.PP
If the operation is successful, the function can modify the supplied
-\fIinstanceData\fR to record that the channel
-entered blocking or nonblocking mode, and modify \fIinFile\fR and
-\fIoutFile\fR to implement the blocking or nonblocking behavior.
+\fIinstanceData\fR to record that the channel entered blocking or
+nonblocking mode and to implement the blocking or nonblocking behavior.
For some device types, the blocking and nonblocking behavior can be
-implemented by the underlying operating system; for other device types,
-the behavior must be emulated in the channel driver.
+implemented by the underlying operating system; for other device types, the
+behavior must be emulated in the channel driver.
.SH CLOSEPROC
.PP
@@ -224,22 +273,19 @@ closed. \fICloseProc\fR must match the following prototype:
.CS
typedef int Tcl_DriverCloseProc(
ClientData \fIinstanceData\fR,
- Tcl_Interp *\fIinterp\fR,
- Tcl_File \fIinFile\fR,
- Tcl_File \fIoutFile\fR);
+ Tcl_Interp *\fIinterp\fR);
.CE
.PP
-The \fIinstanceData\fR, \fIinFile\fR, and \fIoutFile\fR arguments are the
-same as the respective values provided to \fBTcl_CreateChannel\fR when the
-channel was created. The function should release any storage maintained by
-the channel driver for this channel, and close the input and output devices
-identified by \fIinFile\fR and \fIoutFile\fR. All queued output will have
-been flushed to the device before this function is called, and no further
-driver operations will be invoked on this instance after calling the
-\fIcloseProc\fR. If the close operation is successful, the procedure should
-return zero; otherwise it should return a nonzero POSIX error code. In
-addition, if an error occurs and \fIinterp\fR is not NULL, the procedure
-should store an error message in \fIinterp->result\fR.
+The \fIinstanceData\fR argument is the same as the value provided to
+\fBTcl_CreateChannel\fR when the channel was created. The function should
+release any storage maintained by the channel driver for this channel, and
+close the input and output devices encapsulated by this channel. All queued
+output will have been flushed to the device before this function is called,
+and no further driver operations will be invoked on this instance after
+calling the \fIcloseProc\fR. If the close operation is successful, the
+procedure should return zero; otherwise it should return a nonzero POSIX
+error code. In addition, if an error occurs and \fIinterp\fR is not NULL,
+the procedure should store an error message in \fIinterp->result\fR.
.SH INPUTPROC
.PP
@@ -250,28 +296,27 @@ internal buffer. \fIInputProc\fR must match the following prototype:
.CS
typedef int Tcl_DriverInputProc(
ClientData \fIinstanceData\fR,
- Tcl_File \fIinFile\fR,
char *\fIbuf\fR,
int \fIbufSize\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
-\fIInstanceData\fR and \fIInFile\fR are the same as the values passed to
+\fIInstanceData\fR is the same as the value passed to
\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
-argument points to an array of bytes in which to store input from
-the device, and the \fIbufSize\fR argument indicates how many bytes are
+argument points to an array of bytes in which to store input from the
+device, and the \fIbufSize\fR argument indicates how many bytes are
available at \fIbuf\fR.
.PP
The \fIerrorCodePtr\fR argument points to an integer variable provided by
the generic layer. If an error occurs, the function should set the variable
to a POSIX error code that identifies the error that occurred.
.PP
-The function should read data from the input device identified by
-\fIinFile\fR and store it at \fIbuf\fR. On success, the function should
-return a positive integer indicating how many bytes were read from the
-input device and stored at \fIbuf\fR. On error, the function should return
--1. If an error occurs after some data has been read from the device, that
-data is lost.
+The function should read data from the input device encapsulated by the
+channel and store it at \fIbuf\fR. On success, the function should return
+a nonnegative integer indicating how many bytes were read from the input
+device and stored at \fIbuf\fR. On error, the function should return -1. If
+an error occurs after some data has been read from the device, that data is
+lost.
.PP
If \fIinputProc\fR can determine that the input device has some data
available but less than requested by the \fIbufSize\fR argument, the
@@ -293,13 +338,12 @@ generic layer to transfer data from an internal buffer to the output device.
.CS
typedef int Tcl_DriverOutputProc(
ClientData \fIinstanceData\fR,
- Tcl_File \fIoutFile\fR,
char *\fIbuf\fR,
int \fItoWrite\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
-\fIInstanceData\fR and \fIOutFile\fR are the same as the values passed to
+\fIInstanceData\fR is the same as the value passed to
\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
argument contains an array of bytes to be written to the device, and the
\fItoWrite\fR argument indicates how many bytes are to be written from the
@@ -310,14 +354,12 @@ the generic layer. If an error occurs, the function should set this
variable to a POSIX error code that identifies the error.
.PP
The function should write the data at \fIbuf\fR to the output device
-identified by \fIoutFile\fR. On success, the function should return a
-positive integer indicating how many bytes were written to the output
-device.
-The return value is normally the same as \fItoWrite\fR, but may be
-less in some cases such as if the output operation is interrupted
-by a signal.
-If an error occurs the function should return -1.
-In case of error, some data may have been written to the device.
+encapsulated by the channel. On success, the function should return a
+nonnegative integer indicating how many bytes were written to the output
+device. The return value is normally the same as \fItoWrite\fR, but may be
+less in some cases such as if the output operation is interrupted by a
+signal. If an error occurs the function should return -1. In case of
+error, some data may have been written to the device.
.PP
If the channel is nonblocking and the output device is unable to absorb any
data whatsoever, the function should return -1 with an \fBEAGAIN\fR error
@@ -333,25 +375,21 @@ prototype:
.CS
typedef int Tcl_DriverSeekProc(
ClientData \fIinstanceData\fR,
- Tcl_File \fIinFile\fR,
- Tcl_File \fIoutFile\fR,
long \fIoffset\fR,
int \fIseekMode\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
-The \fIinstanceData\fR, \fIinFile\fR and \fIoutFile\fR arguments are the
-same as the values given to \fBTcl_CreateChannel\fR when this channel was
-created. \fIOffset\fR and \fIseekMode\fR have the same meaning as for the
-\fBTcl_SeekChannel\fR procedure (described in the manual entry for
-\fBTcl_OpenFileChannel\fR).
+The \fIinstanceData\fR argument is the same as the value given to
+\fBTcl_CreateChannel\fR when this channel was created. \fIOffset\fR and
+\fIseekMode\fR have the same meaning as for the \fBTcl_SeekChannel\fR
+procedure (described in the manual entry for \fBTcl_OpenFileChannel\fR).
.PP
-The \fIerrorCodePtr\fR argument points to
-an integer variable provided by the generic layer for returning
-\fBerrno\fR values from the function.
-The function should set this variable to a POSIX error code
-if an error occurs. The function should store an \fBEINVAL\fR error code if
-the channel type does not implement seeking.
+The \fIerrorCodePtr\fR argument points to an integer variable provided by
+the generic layer for returning \fBerrno\fR values from the function. The
+function should set this variable to a POSIX error code if an error occurs.
+The function should store an \fBEINVAL\fR error code if the channel type
+does not implement seeking.
.PP
The return value is the new access point or -1 in case of error. If an
error occurred, the function should not move the access point.
@@ -384,9 +422,15 @@ be NULL, which indicates that this channel type supports no type specific
options.
.PP
If the option value is successfully modified to the new value, the function
-returns \fBTCL_OK\fR. It returns \fBTCL_ERROR\fR if the \fIoptionName\fR is
-unrecognized or if \fIoptionValue\fR specifies a value for the option that
-is not supported. In this case, the function leaves an error message in the
+returns \fBTCL_OK\fR.
+.VS
+It should call \fBTcl_BadChannelOption\fR which itself returns
+\fBTCL_ERROR\fR if the \fIoptionName\fR is
+unrecognized.
+.VE
+If \fIoptionValue\fR specifies a value for the option that
+is not supported or if a system call error occurs,
+the function should leave an error message in the
\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
error code.
@@ -400,6 +444,9 @@ channel. \fIgetOptionProc\fR must match the following prototype:
.CS
typedef int Tcl_DriverGetOptionProc(
ClientData \fIinstanceData\fR,
+.VS
+ Tcl_Interp *\fIinterp\fR,
+.VE
char *\fIoptionName\fR,
Tcl_DString *\fIdsPtr\fR);
.CE
@@ -409,9 +456,16 @@ channel. If the option name is not NULL, the function stores its current
value, as a string, in the Tcl dynamic string \fIdsPtr\fR.
If \fIoptionName\fR is NULL, the function stores in \fIdsPtr\fR an
alternating list of all supported options and their current values.
-On success, the function returns \fBTCL_OK\fR. If an error occurs, the
-function returns \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an
-appropriate POSIX error code.
+On success, the function returns \fBTCL_OK\fR.
+.VS
+It should call \fBTcl_BadChannelOption\fR which itself returns
+\fBTCL_ERROR\fR if the \fIoptionName\fR is
+unrecognized. If a system call error occurs,
+the function should leave an error message in the
+\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
+function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
+error code.
+.VE
.PP
Some options are handled by the generic code and this function is never
called to retrieve their value, e.g. \fB-blockmode\fR. Other options are
@@ -420,8 +474,98 @@ channel driver will get called to implement them. The \fIgetOptionProc\fR
field can be NULL, which indicates that this channel type supports no type
specific options.
+.SH WATCHPROC
+.VS
+.PP
+The \fIwatchProc\fR field contains the address of a function called
+by the generic layer to initialize the event notification mechanism to
+notice events of interest on this channel.
+\fIWatchProc\fR should match the following prototype:
+.PP
+.CS
+typedef void Tcl_DriverWatchProc(
+ ClientData \fIinstanceData\fR,
+ int \fImask\fR);
+.CE
+.VE
+.PP
+The \fIinstanceData\fR is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR
+argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
+and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in
+noticing on this channel.
+.PP
+.VS
+The function should initialize device type specific mechanisms to
+notice when an event of interest is present on the channel. When one
+or more of the designated events occurs on the channel, the channel
+driver is responsible for calling \fBTcl_NotifyChannel\fR to inform
+the generic channel module. The driver should take care not to starve
+other channel drivers or sources of callbacks by invoking
+Tcl_NotifyChannel too frequently. Fairness can be insured by using
+the Tcl event queue to allow the channel event to be scheduled in sequence
+with other events. See the description of \fBTcl_QueueEvent\fR for
+details on how to queue an event.
+
+.SH GETHANDLEPROC
+.PP
+The \fIgetHandleProc\fR field contains the address of a function called by
+the generic layer to retrieve a device-specific handle from the channel.
+\fIGetHandleProc\fR should match the following prototype:
+.PP
+.CS
+typedef int Tcl_DriverGetHandleProc(
+ ClientData \fIinstanceData\fR,
+ int \fIdirection\fR,
+ ClientData *\fIhandlePtr\fR);
+.CE
+.PP
+\fIInstanceData is the same as the value passed to
+\fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR
+argument is either \fBTCL_READABLE\fR to retrieve the handle used
+for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for
+output.
+.PP
+If the channel implementation has device-specific handles, the
+function should retrieve the appropriate handle associated with the
+channel, according the \fIdirection\fR argument. The handle should be
+stored in the location referred to by \fIhandlePtr\fR, and
+\fBTCL_OK\fR should be returned. If the channel is not open for the
+specified direction, or if the channel implementation does not use
+device handles, the function should return \fBTCL_ERROR\fR.
+.VE
+
+.VS
+.SH TCL_BADCHANNELOPTION
+.PP
+This procedure generates a "bad option" error message in an
+(optional) interpreter. It is used by channel drivers when
+a invalid Set/Get option is requested. Its purpose is to concatenate
+the generic options list to the specific ones and factorize
+the generic options error message string.
+.PP
+It always return \fBTCL_ERROR\fR
+.PP
+An error message is generated in interp's result object to
+indicate that a command was invoked with the a bad option
+The message has the form
+.CS
+ bad option "blah": should be one of
+ <...generic options...>+<...specific options...>
+so you get for instance:
+ bad option "-blah": should be one of -blocking,
+ -buffering, -buffersize, -eofchar, -translation,
+ -peername, or -sockname
+when called with optionList="peername sockname"
+.CE
+"blah" is the optionName argument and "<specific options>"
+is a space separated list of specific option words.
+The function takes good care of inserting minus signs before
+each option, commas after, and an "or" before the last option.
+.VE
+
.SH "SEE ALSO"
-Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
+Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3)
.SH KEYWORDS
blocking, channel driver, channel registration, channel type, nonblocking
diff --git a/contrib/tcl/doc/CrtCommand.3 b/contrib/tcl/doc/CrtCommand.3
index 8c27e2fc5619..3da0a30ce094 100644
--- a/contrib/tcl/doc/CrtCommand.3
+++ b/contrib/tcl/doc/CrtCommand.3
@@ -1,41 +1,23 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) CrtCommand.3 1.22 96/03/25 19:58:44
+'\" SCCS: @(#) CrtCommand.3 1.29 97/06/04 17:23:53
'\"
.so man.macros
.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo \- implement new commands in C
+Tcl_CreateCommand \- implement new commands in C
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
-.VS
-.VE
Tcl_Command
\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
-.sp
-int
-\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
-.sp
-.VS
-int
-\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
-.sp
-int
-\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
-.sp
-.VS
-char *
-\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
-.VE
-.VE
.SH ARGUMENTS
.AS Tcl_CmdDeleteProc **deleteProcPtr
.AP Tcl_Interp *interp in
@@ -51,14 +33,6 @@ Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
Procedure to call before \fIcmdName\fR is deleted from the interpreter;
allows for command-specific cleanup. If NULL, then no procedure is
called before the command is deleted.
-.AP Tcl_CmdInfo *infoPtr in/out
-.VS
-Pointer to structure containing various information about a
-Tcl command.
-.AP Tcl_Command token in
-Token for command, returned by previous call to \fBTcl_CreateCommand\fR.
-The command must not have been deleted.
-.VE
.BE
.SH DESCRIPTION
@@ -66,16 +40,41 @@ The command must not have been deleted.
\fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
-will call \fIproc\fR
-to process the command. If there is already a command \fIcmdName\fR
-associated with the interpreter, it is deleted.
-.VS
-\fBTcl_CreateCommand\fR returns a token that may be used to refer
+will call \fIproc\fR to process the command.
+It differs from \fBTcl_CreateObjCommand\fR in that a new string-based
+command is defined;
+that is, a command procedure is defined that takes an array of
+argument strings instead of objects.
+The object-based command procedures registered by \fBTcl_CreateObjCommand\fR
+can execute significantly faster than the string-based command procedures
+defined by \fBTcl_CreateCommand\fR.
+This is because they take Tcl objects as arguments
+and those objects can retain an internal representation that
+can be manipulated more efficiently.
+Also, Tcl's interpreter now uses objects internally.
+In order to invoke a string-based command procedure
+registered by \fBTcl_CreateCommand\fR,
+it must generate and fetch a string representation
+from each argument object before the call
+and create a new Tcl object to hold the string result returned by the
+string-based command procedure.
+New commands should be defined using \fBTcl_CreateObjCommand\fR.
+We support \fBTcl_CreateCommand\fR for backwards compatibility.
+.PP
+The procedures \fBTcl_DeleteCommand\fR, \fBTcl_GetCommandInfo\fR,
+and \fBTcl_SetCommandInfo\fR are used in conjunction with
+\fBTcl_CreateCommand\fR.
+.PP
+\fBTcl_CreateCommand\fR will delete an existing command \fIcmdName\fR,
+if one is already associated with the interpreter.
+It returns a token that may be used to refer
to the command in subsequent calls to \fBTcl_GetCommandName\fR.
+If \fIcmdName\fR contains any \fB::\fR namespace qualifiers,
+then the command is added to the specified namespace;
+otherwise the command is added to the global namespace.
If \fBTcl_CreateCommand\fR is called for an interpreter that is in
the process of being deleted, then it does not create a new command
and it returns NULL.
-.VE
\fIProc\fR should have arguments and result that match the type
\fBTcl_CmdProc\fR:
.CS
@@ -101,24 +100,22 @@ last value is NULL.
\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. See the Tcl overview man page
for details on what these codes mean. Most normal commands will only
return \fBTCL_OK\fR or \fBTCL_ERROR\fR. In addition, \fIproc\fR must set
-\fIinterp->result\fR to point to a string value;
+the interpreter result to point to a string value;
in the case of a \fBTCL_OK\fR return code this gives the result
of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
The \fBTcl_SetResult\fR procedure provides an easy interface for setting
-the return value; for complete details on how the \fIinterp->result\fR
+the return value; for complete details on how the the interpreter result
field is managed, see the \fBTcl_Interp\fR man page.
Before invoking a command procedure,
-\fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
-commands can return an empty result by doing nothing at all.
+\fBTcl_Eval\fR sets the interpreter result to point to an empty string,
+so simple commands can return an empty result by doing nothing at all.
.PP
-.VS
The contents of the \fIargv\fR array belong to Tcl and are not
guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
-not modify them, nor should it set \fIinterp->result\fR to point
+not modify them, nor should it set the interpreter result to point
anywhere within the \fIargv\fR values.
Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
to return something from the \fIargv\fR array.
-.VE
.PP
\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
@@ -133,49 +130,9 @@ typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument passed to \fBTcl_CreateCommand\fR.
.PP
-\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
-Once the call completes, attempts to invoke \fIcmdName\fR in
-\fIinterp\fR will result in errors.
-If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
-\fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise
-it returns 0.
-There are no restrictions on \fIcmdName\fR: it may refer to
-a built-in command, an application-specific command, or a Tcl procedure.
-.PP
-.VS
-\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
-exists as a command in \fIinterp\fR. If not then it returns 0.
-Otherwise it places information about the command in the structure
-pointed to by \fIinfoPtr\fR and returns 1.
-Tcl_CmdInfo structures have fields named \fIproc\fR, \fIclientData\fR,
-and \fIdeleteProc\fR, which have the same meaning as the corresponding
-arguments to \fBTcl_CreateCommand\fR.
-There is also a field \fIdeleteData\fR, which is the ClientData value
-to pass to \fIdeleteProc\fR; it is normally the same as
-\fIclientData\fR but may be set independently using the
-\fBTcl_SetCommandInfo\fR procedure.
-.PP
-\fBTcl_SetCommandInfo\fR is used to modify the procedures and
-ClientData values associated with a command.
-Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
-If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
-Otherwise, it copies the information from \fI*infoPtr\fR to
-Tcl's internal structure for the command and returns 1.
-Note that this procedure allows the ClientData for a command's
-deletion procedure to be given a different value than the ClientData
-for its command procedure.
-.PP
-\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
-that have been renamed. Given a token returned by \fBTcl_CreateCommand\fR
-when the command was created, \fBTcl_GetCommandName\fR returns the
-string name of the command. If the command has been renamed since it
-was created, then \fBTcl_GetCommandName\fR returns the current name.
-The command corresponding to \fItoken\fR must not have been deleted.
-The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
-owned by Tcl and is only guaranteed to retain its value as long as the
-command isn't deleted or renamed; callers should copy the string if
-they need to keep it for a long time.
-.VE
+
+.SH "SEE ALSO"
+Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
.SH KEYWORDS
-bind, command, create, delete, interpreter
+bind, command, create, delete, interpreter, namespace
diff --git a/contrib/tcl/doc/CrtFileHdlr.3 b/contrib/tcl/doc/CrtFileHdlr.3
index 31a5466f8bd9..9b26975d96ab 100644
--- a/contrib/tcl/doc/CrtFileHdlr.3
+++ b/contrib/tcl/doc/CrtFileHdlr.3
@@ -1,29 +1,32 @@
'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) CrtFileHdlr.3 1.6 96/03/25 19:59:08
+'\" SCCS: @(#) CrtFileHdlr.3 1.7 97/04/23 16:11:17
'\"
.so man.macros
-.TH Tcl_CreateFileHandler 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices
+Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only)
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
+.VS
.sp
-\fBTcl_CreateFileHandler\fR(\fIfile, mask, proc, clientData\fR)
+\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
.sp
-\fBTcl_DeleteFileHandler\fR(\fIfile\fR)
+\fBTcl_DeleteFileHandler\fR(\fIfd\fR)
+.VE
.SH ARGUMENTS
.AS Tcl_FileProc clientData
-.AP Tcl_File file in
-Generic file handle for an open file or device (such as returned by
-\fBTcl_GetFile\fR call).
+.VS
+.AP int fd in
+Unix file descriptor for an open file or device.
+.VE
.AP int mask in
Conditions under which \fIproc\fR should be called:
OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
@@ -38,10 +41,12 @@ Arbitrary one-word value to pass to \fIproc\fR.
.SH DESCRIPTION
.PP
+.VS
\fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
invoked in the future whenever I/O becomes possible on a file
or an exceptional condition exists for the file. The file
-is indicated by \fIfile\fR, and the conditions of interest
+is indicated by \fIfd\fR, and the conditions of interest
+.VE
are indicated by \fImask\fR. For example, if \fImask\fR
is \fBTCL_READABLE\fR, \fIproc\fR will be called when
the file is readable.
@@ -70,12 +75,12 @@ to \fBTcl_CreateFileHandler\fR.
.PP
There may exist only one handler for a given file at a given time.
If \fBTcl_CreateFileHandler\fR is called when a handler already
-exists for \fIfile\fR, then the new callback replaces the information
+exists for \fIfd\fR, then the new callback replaces the information
that was previously recorded.
.PP
\fBTcl_DeleteFileHandler\fR may be called to delete the
-file handler for \fIfile\fR; if no handler exists for the
-file given by \fIfile\fR then the procedure has no effect.
+file handler for \fIfd\fR; if no handler exists for the
+file given by \fIfd\fR then the procedure has no effect.
.PP
The purpose of file handlers is to enable an application to respond to
events while waiting for files to become ready for I/O. For this to work
@@ -85,6 +90,11 @@ block if it reads or writes too much data; while waiting for the I/O to
complete the application won't be able to service other events. Use
\fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into
blocking or nonblocking mode as required.
+.PP
+.VS
+Note that these interfaces are only supported by the Unix
+implementation of the Tcl notifier.
+.VE
.SH KEYWORDS
callback, file, handler
diff --git a/contrib/tcl/doc/CrtMathFnc.3 b/contrib/tcl/doc/CrtMathFnc.3
index f3f458dc7823..907df03c3aca 100644
--- a/contrib/tcl/doc/CrtMathFnc.3
+++ b/contrib/tcl/doc/CrtMathFnc.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) CrtMathFnc.3 1.8 96/03/25 19:59:55
+'\" SCCS: @(#) CrtMathFnc.3 1.9 96/08/26 12:59:43
'\"
.so man.macros
.TH Tcl_CreateMathFunc 3 7.0 Tcl "Tcl Library Procedures"
@@ -66,8 +66,6 @@ which describe the actual arguments to the function:
.CS
typedef struct Tcl_Value {
Tcl_ValueType \fItype\fR;
-.VS
-.VE
long \fIintValue\fR;
double \fIdoubleValue\fR;
} Tcl_Value;
diff --git a/contrib/tcl/doc/CrtObjCmd.3 b/contrib/tcl/doc/CrtObjCmd.3
new file mode 100644
index 000000000000..e5108894eeea
--- /dev/null
+++ b/contrib/tcl/doc/CrtObjCmd.3
@@ -0,0 +1,249 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) @(#) CrtObjCmd.3 1.9 97/06/04 17:23:37
+'\"
+.so man.macros
+.TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName \- implement new commands in C
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Command
+\fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
+.sp
+int
+\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
+.sp
+int
+\fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)
+.sp
+int
+\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
+.sp
+int
+\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
+.sp
+char *
+\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
+.SH ARGUMENTS
+.AS Tcl_ObjCmdProc *deleteProc in/out
+.AP Tcl_Interp *interp in
+Interpreter in which to create a new command or that contains a command.
+.AP char *cmdName in
+Name of command.
+.AP Tcl_ObjCmdProc *proc in
+Implementation of the new command: \fIproc\fR will be called whenever
+\fIcmdName\fR is invoked as a command.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
+.AP Tcl_CmdDeleteProc *deleteProc in
+Procedure to call before \fIcmdName\fR is deleted from the interpreter;
+allows for command-specific cleanup. If NULL, then no procedure is
+called before the command is deleted.
+.AP Tcl_Command token in
+Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
+The command must not have been deleted.
+.AP Tcl_CmdInfo *infoPtr in/out
+Pointer to structure containing various information about a
+Tcl command.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
+and associates it with procedure \fIproc\fR
+such that whenever \fIname\fR is
+invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObj\fR)
+the Tcl interpreter will call \fIproc\fR to process the command.
+.PP
+\fBTcl_CreateObjCommand\fR will delete any command \fIname\fR
+already associated with the interpreter.
+It returns a token that may be used to refer
+to the command in subsequent calls to \fBTcl_GetCommandName\fR.
+If \fIname\fR contains any \fB::\fR namespace qualifiers,
+then the command is added to the specified namespace;
+otherwise the command is added to the global namespace.
+If \fBTcl_CreateObjCommand\fR is called for an interpreter that is in
+the process of being deleted, then it does not create a new command
+and it returns NULL.
+\fIproc\fR should have arguments and result that match the type
+\fBTcl_ObjCmdProc\fR:
+.CS
+typedef int Tcl_ObjCmdProc(
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ int \fIobjc\fR,
+.VS
+ Tcl_Obj *CONST \fIobjv\fR[]);
+.CE
+When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
+will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
+\fBTcl_CreateObjCommand\fR. Typically, \fIclientData\fR points to an
+application-specific data structure that describes what to do when the
+command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
+arguments to the command, \fIobjc\fR giving the number of argument objects
+(including the command name) and \fIobjv\fR giving the values of the
+arguments. The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
+the argument objects. Unlike \fIargv\fR[\fIargv\fR] used in a
+string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
+.PP
+Additionally, when \fIproc\fR is invoked, it must not modify the contents
+of the \fIobjv\fR array by assigning new pointer values to any element of the
+array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will
+cause memory to be lost and the runtime stack to be corrupted. The
+\fBCONST\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
+compilers to report any such attempted assignment as an error. However,
+it is acceptable to modify the internal representation of any individual
+object argument. For instance, the user may call
+\fBTcl_GetIntFromObject\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
+representation of that object; that call may change the type of the object
+that \fIobjv\fR[\fB2\fR] points at, but will not change where
+\fIobjv\fR[\fB2\fR] points.
+.VE
+.PP
+\fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
+\fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
+See the Tcl overview man page
+for details on what these codes mean. Most normal commands will only
+return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+In addition, if \fIproc\fR needs to return a non-empty result,
+it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
+In the case of a \fBTCL_OK\fR return code this gives the result
+of the command,
+and in the case of \fBTCL_ERROR\fR this gives an error message.
+Before invoking a command procedure,
+\fBTcl_EvalObj\fR sets interpreter's result to
+point to an object representing an empty string, so simple
+commands can return an empty result by doing nothing at all.
+.PP
+The contents of the \fIobjv\fR array belong to Tcl and are not
+guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
+not modify them.
+Call \fBTcl_SetObjResult\fR if you want
+to return something from the \fIobjv\fR array.
+.PP
+\fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
+This can occur through a call to \fBTcl_DeleteCommand\fR
+or \fBTcl_DeleteInterp\fR,
+or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
+\fIDeleteProc\fR is invoked before the command is deleted, and gives the
+application an opportunity to release any structures associated
+with the command. \fIDeleteProc\fR should have arguments and
+result that match the type \fBTcl_CmdDeleteProc\fR:
+.CS
+typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
+.CE
+The \fIclientData\fR argument will be the same as the \fIclientData\fR
+argument passed to \fBTcl_CreateObjCommand\fR.
+.PP
+\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
+Once the call completes, attempts to invoke \fIcmdName\fR in
+\fIinterp\fR will result in errors.
+If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
+\fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise
+it returns 0.
+There are no restrictions on \fIcmdName\fR: it may refer to
+a built-in command, an application-specific command, or a Tcl procedure.
+If \fIname\fR contains any \fB::\fR namespace qualifiers,
+the command is deleted from the specified namespace.
+.PP
+Given a token returned by \fBTcl_CreateObjCommand\fR
+when the command was created,
+\fBTcl_DeleteCommandFromToken\fR deletes the command
+from a command interpreter.
+Once the call completes, attempts to invoke the command in
+\fIinterp\fR will result in errors.
+If the command corresponding to \fItoken\fR
+has already been deleted from \fIinterp\fR then
+\fBTcl_DeleteCommand\fR does nothing and returns -1;
+otherwise it returns 0.
+.PP
+\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
+exists as a command in \fIinterp\fR.
+\fIcmdName\fR may include \fB::\fR namespace qualifiers
+to identify a command in a particular namespace.
+If the command is not found, then it returns 0.
+Otherwise it places information about the command
+in the \fBTcl_CmdInfo\fR structure
+pointed to by \fIinfoPtr\fR and returns 1.
+A \fBTcl_CmdInfo\fR structure has the following fields:
+.CS
+typedef struct Tcl_CmdInfo {
+ int isNativeObjectProc;
+ Tcl_ObjCmdProc *objProc;
+ ClientData objClientData;
+ Tcl_CmdProc *proc;
+ ClientData clientData;
+ Tcl_CmdDeleteProc *deleteProc;
+ ClientData deleteData;
+ Tcl_Namespace *namespacePtr;
+} Tcl_CmdInfo;
+.CE
+The \fIisNativeObjectProc\fR field has the value 1
+if \fBTcl_CreateObjCommand\fR was called to register the command;
+it is 0 if only \fBTcl_CreateCommand\fR was called.
+It allows a program to determine whether it is faster to
+call \fIobjProc\fR or \fIproc\fR:
+\fIobjProc\fR is normally faster
+if \fIisNativeObjectProc\fR has the value 1.
+The fields \fIobjProc\fR and \fIobjClientData\fR
+have the same meaning as the \fIproc\fR and \fIclientData\fR
+arguments to \fBTcl_CreateObjCommand\fR;
+they hold information about the object-based command procedure
+that the Tcl interpreter calls to implement the command.
+The fields \fIproc\fR and \fIclientData\fR
+hold information about the string-based command procedure
+that implements the command.
+If \fBTcl_CreateCommand\fR was called for this command,
+this is the procedure passed to it;
+otherwise, this is a compatibility procedure
+registered by \fBTcl_CreateObjCommand\fR
+that simply calls the command's
+object-based procedure after converting its string arguments to Tcl objects.
+The field \fIdeleteData\fR is the ClientData value
+to pass to \fIdeleteProc\fR; it is normally the same as
+\fIclientData\fR but may be set independently using the
+\fBTcl_SetCommandInfo\fR procedure.
+The field \fInamespacePtr\fR holds a pointer to the
+Tcl_Namespace that contains the command.
+.PP
+\fBTcl_SetCommandInfo\fR is used to modify the procedures and
+ClientData values associated with a command.
+Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
+\fIcmdName\fR may include \fB::\fR namespace qualifiers
+to identify a command in a particular namespace.
+If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
+Otherwise, it copies the information from \fI*infoPtr\fR to
+Tcl's internal structure for the command and returns 1.
+Note that this procedure allows the ClientData for a command's
+deletion procedure to be given a different value than the ClientData
+for its command procedure.
+Note that \fBTcl_SetCmdInfo\fR will not change a command's namespace;
+you must use \fBTcl_RenameCommand\fR to do that.
+.PP
+\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
+that have been renamed.
+Given a token returned by \fBTcl_CreateObjCommand\fR
+when the command was created, \fBTcl_GetCommandName\fR returns the
+string name of the command. If the command has been renamed since it
+was created, then \fBTcl_GetCommandName\fR returns the current name.
+This name does not include any \fB::\fR namespace qualifiers.
+The command corresponding to \fItoken\fR must not have been deleted.
+The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
+owned by Tcl and is only guaranteed to retain its value as long as the
+command isn't deleted or renamed; callers should copy the string if
+they need to keep it for a long time.
+.PP
+
+.SH "SEE ALSO"
+Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
+
+.SH KEYWORDS
+bind, command, create, delete, namespace, object
diff --git a/contrib/tcl/doc/CrtSlave.3 b/contrib/tcl/doc/CrtSlave.3
index 7979bbb139f8..3b3d7b82f4b9 100644
--- a/contrib/tcl/doc/CrtSlave.3
+++ b/contrib/tcl/doc/CrtSlave.3
@@ -4,14 +4,13 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) CrtSlave.3 1.13 96/03/25 20:00:42
+'\" SCCS: @(#) CrtSlave.3 1.22 97/06/10 17:52:33
'\"
.so man.macros
-.TH Tcl_CreateSlave 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetSlaves, Tcl_GetMaster, Tcl_CreateAlias, Tcl_GetAlias, Tcl_GetAliases \- manage
-multiple Tcl interpreters and aliases.
+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.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -34,20 +33,35 @@ Tcl_Interp *
int
\fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
.sp
+.VS
int
\fBTcl_CreateAlias\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, argc, argv\fR)
.sp
int
+\fBTcl_CreateAliasObj\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, objc, objv\fR)
+.VE
+.sp
+int
\fBTcl_GetAlias\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
+.sp
+.VS
+int
+\fBTcl_GetAliasObj\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr\fR)
+.sp
+int
+\fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
+.sp
+int
+\fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
.SH ARGUMENTS
-.AS Tcl_InterpDeleteProc **delProcPtr
+.AS Tcl_InterpDeleteProc **hiddenCmdName
.AP Tcl_Interp *interp in
Interpreter in which to execute the specified command.
.AP char *slaveName in
Name of slave interpreter to create or manipulate.
.AP int isSafe in
-Zero means the interpreter may have all Tcl functions. Non-zero means the
-new interpreter's functionality should be limited to make it safe.
+If non-zero, a ``safe'' slave that is suitable for running untrusted code
+is created, otherwise a trusted slave is created.
.AP Tcl_Interp *slaveInterp in
Interpreter to use for creating the source command for an alias (see
below).
@@ -62,6 +76,12 @@ Count of additional arguments to pass to the alias command.
.AP char **argv in
Vector of strings, the additional arguments to pass to the alias command.
This storage is owned by the caller.
+.AP int objc in
+Count of additional object arguments to pass to the alias object command.
+.AP Tcl_Object **objv in
+Vector of Tcl_Obj structures, the additional object argumenst to pass to
+the alias object command.
+This storage is owned by the caller.
.AP Tcl_Interp **targetInterpPtr in
Pointer to location to store the address of the interpreter where a target
command is defined for an alias.
@@ -75,6 +95,20 @@ the alias. The location is in storage owned by the caller.
Pointer to location to store a vector of strings, the additional arguments
to pass to an alias. The location is in storage owned by the caller, the
vector of strings is owned by the called function.
+.AP int *objcPtr out
+Pointer to location to store count of additional object arguments to be
+passed to the alias. The location is in storage owned by the caller.
+.AP Tcl_Obj ***objvPtr out
+Pointer to location to store a vector of Tcl_Obj structures, the additional
+arguments to pass to an object alias command. The location is in storage
+owned by the caller, the vector of Tcl_Obj structures is owned by the
+called function.
+.VS
+.AP char *cmdName in
+Name of an exposed command to hide or create.
+.AP char *hiddenCmdName in
+Name of a hidden command to create or expose.
+.VE
.BE
.SH DESCRIPTION
@@ -87,28 +121,31 @@ 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 \fBresult\fR field of the interpreter contains an error message.
.PP
-\fBTcl_CreateSlave\fR creates a new interpreter as a slave of the given
-interpreter. It also creates a slave command in the given interpreter which
-allows the master interpreter to manipulate the slave. The slave
-interpreter and the slave command have the specified name. If \fIisSafe\fR
-is \fB1\fR, the new slave interpreter is made ``safe'' by removing all
-unsafe functionality. If the creation failed, \fBNULL\fR is returned.
+\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
+code has access to all the Tcl commands.
+If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
+has access only to set of Tcl commands defined as ``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.
.PP
-\fBTcl_IsSafe\fR returns \fB1\fR if the given interpreter is ``safe'',
+\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
+with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
\fB0\fR otherwise.
.PP
-\fBTcl_MakeSafe\fR makes the given interpreter ``safe'' by removing all
+\fBTcl_MakeSafe\fR makes \fIinterp\fR ``safe'' by removing all
non-core and core unsafe functionality. Note that if you call this after
adding some extension to an interpreter, all traces of that extension will
-be removed from the interpreter. This operation always succeeds and returns
-\fBTCL_OK\fR.
+be removed from the interpreter.
.PP
-\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of the given
-interpreter. The slave interpreter is identified by the name specified.
+\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.
.PP
-\fBTcl_GetMaster\fR returns a pointer to the master interpreter of the
-given interpreter. If the given interpreter has no master (it is a
+\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
+\fIinterp\fR. If \fIinterp\fR has no master (it is a
top-level interpreter) then \fBNULL\fR is returned.
.PP
\fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
@@ -118,25 +155,66 @@ of the relative path succeeds, \fBTCL_OK\fR is returned, else
\fBTCL_ERROR\fR is returned and the \fIresult\fR field in
\fIaskingInterp\fR contains the error message.
.PP
-\fBTcl_GetAlias\fR returns information about an alias of a specified name
-in a given interpreter. Any of the result fields can be \fBNULL\fR, in
+.VS
+\fBTcl_CreateAlias\fR creates an object command named \fIsrcCmd\fR in
+\fIslaveInterp\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 \fIsrcCmd\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 object result
+of \fIslaveInterp\fR.
+Note that there are no restrictions on the ancestry relationship (as
+created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
+\fItargetInterp\fR. Any two interpreters can be used, without any
+restrictions on how they are related.
+.PP
+\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAliasObj\fR except
+that it takes a vector of objects to pass as additional arguments instead
+of a vector of strings.
+.VE
+.PP
+\fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
+in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
which case the corresponding datum is not returned. If a result field is
non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
pointer to the string containing the name of the target command.
+.VS
+.PP
+\fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
+returns a pointer to a vector of Tcl_Obj structures instead of a vector of
+strings.
+.PP
+\fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
+the set of hidden commands to the set of exposed commands, renaming it to
+\fIcmdName\fR. \fIHiddenCmdName\fR must be the name of an existing hidden
+command, or the operation will return \fBTCL_ERROR\fR and deposit an error
+message in the \fIresult\fR field in \fIinterp\fR.
+If an exposed command named \fIcmdName\fR already exists,
+the operation returns \fBTCL_ERROR\fR and leaves an error message in the
+object result of \fIinterp\fR.
+If the operation succeeds, it returns \fBTCL_OK\fR.
+After executing this command, attempts to use \fIcmdName\fR in a call to
+\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
+.PP
+\fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
+exposed commands to the set of hidden commands, renaming it to
+\fIhiddenCmdName\fR. \fICmdName\fR must be the name of an existing exposed
+command, or the operation will return \fBTCL_ERROR\fR and leave an error
+message in the object result of \fIinterp\fR.
+If a hidden command named \fIhiddenCmdName\fR already
+exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
+field in \fIinterp\fR contains an error message.
+If the operation succeeds, it returns \fBTCL_OK\fR.
+After executing this command, attempts to use \fIcmdName\fR in a call to
+\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
.PP
-In order to map over all slave interpreters, use \fBTcl_Eval\fR with the
-command \fBinterp slaves\fR and use the value (a Tcl list) deposited in the
-\fBresult\fR field of the interpreter. Similarly, to map over all aliases
-whose source commands are defined in an interpreter, use \fBTcl_Eval\fR
-with the command \fBinterp aliases\fR and use the value (a Tcl list)
-deposited in the \fBresult\fR field. Note that the storage of this list
-belongs to Tcl, so you should copy it before invoking any other Tcl
-commands in that interpreter.
.SH "SEE ALSO"
For a description of the Tcl interface to multiple interpreters, see
\fIinterp(n)\fR.
.SH KEYWORDS
-alias, command, interpreter, master, slave
+alias, command, exposed commands, hidden commands, interpreter, invoke,
+master, slave,
diff --git a/contrib/tcl/doc/CrtTimerHdlr.3 b/contrib/tcl/doc/CrtTimerHdlr.3
index 75a13c655d29..14f48a4e2a49 100644
--- a/contrib/tcl/doc/CrtTimerHdlr.3
+++ b/contrib/tcl/doc/CrtTimerHdlr.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) CrtTimerHdlr.3 1.3 96/03/25 20:00:55
+'\" SCCS: @(#) CrtTimerHdlr.3 1.4 96/09/17 10:54:58
'\"
.so man.macros
.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
@@ -67,7 +67,10 @@ previously-created timer handler. It deletes the handler
indicated by \fItoken\fR so that no call to \fIproc\fR
will be made; if that handler no longer exists
(e.g. because the time period has already elapsed and \fIproc\fR
-has been invoked) then \fBTcl_DeleteTimerHandler\fR does nothing.
+has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing.
+The tokens returned by \fBTcl_CreateTimerHandler\fR never have
+a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR
+then the procedure does nothing.
.SH KEYWORDS
callback, clock, handler, timer
diff --git a/contrib/tcl/doc/DString.3 b/contrib/tcl/doc/DString.3
index 330d67d8215e..e6ea142e54f8 100644
--- a/contrib/tcl/doc/DString.3
+++ b/contrib/tcl/doc/DString.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) DString.3 1.19 96/03/25 20:01:32
+'\" SCCS: @(#) DString.3 1.20 96/08/26 12:59:44
'\"
.so man.macros
.TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
@@ -34,17 +34,13 @@ int
char *
\fBTcl_DStringValue\fR(\fIdsPtr\fR)
.sp
-.VS
\fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
-.VE
.sp
\fBTcl_DStringFree\fR(\fIdsPtr\fR)
.sp
\fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
.sp
-.VS
\fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
-.VE
.SH ARGUMENTS
.AS Tcl_DString newLength
.AP Tcl_DString *dsPtr in/out
@@ -114,7 +110,6 @@ of a dynamic string (not including the terminating null character).
\fBTcl_DStringValue\fR is a macro that returns a pointer to the
current contents of a dynamic string.
.PP
-.VS
.PP
\fBTcl_DStringSetLength\fR changes the length of a dynamic string.
If \fInewLength\fR is less than the string's current length, then
@@ -128,7 +123,6 @@ caller to fill in the new space.
\fBTcl_DStringSetLength\fR does not free up the string's storage space
even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
will still need to be called.
-.VE
.PP
\fBTcl_DStringFree\fR should be called when you're finished using
the string. It frees up any memory that was allocated for the string
@@ -141,13 +135,11 @@ This saves the cost of allocating new memory and copying the string.
\fBTcl_DStringResult\fR also reinitializes the dynamic string to
an empty string.
.PP
-.VS
\fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR.
It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and
it clears \fIinterp\fR's result.
If possible it does this by moving a pointer rather than by copying
the string.
-.VE
.SH KEYWORDS
append, dynamic string, free, result
diff --git a/contrib/tcl/doc/DetachPids.3 b/contrib/tcl/doc/DetachPids.3
index 7c14721405ad..153649b0babc 100644
--- a/contrib/tcl/doc/DetachPids.3
+++ b/contrib/tcl/doc/DetachPids.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) DetachPids.3 1.14 96/03/25 20:01:48
+'\" SCCS: @(#) DetachPids.3 1.15 96/08/26 12:59:44
'\"
.so man.macros
.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
@@ -18,9 +18,7 @@ Tcl_DetachPids, Tcl_ReapDetachedProcs \- manage child processes in background
.sp
\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
.sp
-.VS
\fBTcl_ReapDetachedProcs\fR()
-.VE
.SH ARGUMENTS
.AS int *statusPtr
.AP int numPids in
@@ -31,7 +29,6 @@ Address of array containing \fInumPids\fR process ids.
.SH DESCRIPTION
.PP
-.VS
\fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a
mechanism for managing subprocesses that are running in background.
These procedures are needed because the parent of a process must
@@ -60,7 +57,6 @@ However, if you call \fBTcl_DetachPids\fR in situations where the
\fBexec\fR command may never get executed, you may wish to call
\fBTcl_ReapDetachedProcs\fR from time to time so that background
processes can be cleaned up.
-.VE
.SH KEYWORDS
background, child, detach, process, wait
diff --git a/contrib/tcl/doc/DoOneEvent.3 b/contrib/tcl/doc/DoOneEvent.3
index a9e0bc9b778e..fd092c8b8c22 100644
--- a/contrib/tcl/doc/DoOneEvent.3
+++ b/contrib/tcl/doc/DoOneEvent.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) DoOneEvent.3 1.5 96/03/25 20:02:05
+'\" SCCS: @(#) DoOneEvent.3 1.6 97/05/09 18:12:05
'\"
.so man.macros
.TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures"
@@ -46,7 +46,7 @@ If no events are found, \fBTcl_DoOneEvent\fR checks for \fBTcl_DoWhenIdle\fR
callbacks; if any are found, it invokes all of them and returns.
Finally, if no events or idle callbacks have been found, then
\fBTcl_DoOneEvent\fR sleeps until an event occurs; then it adds any
-ew events to the Tcl event queue, calls handlers for the first event,
+new events to the Tcl event queue, calls handlers for the first event,
and returns.
The normal return value is 1 to signify that some event
was processed (see below for other alternatives).
diff --git a/contrib/tcl/doc/DoWhenIdle.3 b/contrib/tcl/doc/DoWhenIdle.3
index 2b43b057385e..c909026d6c96 100644
--- a/contrib/tcl/doc/DoWhenIdle.3
+++ b/contrib/tcl/doc/DoWhenIdle.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) DoWhenIdle.3 1.4 96/03/25 20:02:20
+'\" SCCS: @(#) DoWhenIdle.3 1.6 97/05/09 18:18:33
'\"
.so man.macros
.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
@@ -74,7 +74,6 @@ to defer display updates until all pending commands have
been processed. Without this feature, redundant redisplays
might occur in some situations, such as the processing of
a command file.
-
.SH BUGS
.PP
At present it is not safe for an idle callback to reschedule itself
diff --git a/contrib/tcl/doc/DoubleObj.3 b/contrib/tcl/doc/DoubleObj.3
new file mode 100644
index 000000000000..b4678515a912
--- /dev/null
+++ b/contrib/tcl/doc/DoubleObj.3
@@ -0,0 +1,79 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) @(#) DoubleObj.3 1.6 97/05/08 19:50:07
+'\"
+.so man.macros
+.TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl objects as floating-point values
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewDoubleObj\fR(\fIdoubleValue\fR)
+.sp
+\fBTcl_SetDoubleObj\fR(\fIobjPtr, doubleValue\fR)
+.sp
+int
+\fBTcl_GetDoubleFromObj\fR(\fIinterp, objPtr, doublePtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp doubleValue in/out
+.AP double doubleValue in
+A double-precision floating point value used to initialize or set a double object.
+.AP Tcl_Obj *objPtr in/out
+For \fBTcl_SetDoubleObj\fR, this points to the object to be converted
+to double type.
+For \fBTcl_GetDoubleFromObj\fR, this refers to the object
+from which to get a double value;
+if \fIobjPtr\fR does not already point to a double object,
+an attempt will be made to convert it to one.
+.AP Tcl_Interp *interp in/out
+If an error occurs during conversion,
+an error message is left in the interpreter's result object
+unless \fIinterp\fR is NULL.
+.AP double *doublePtr out
+Points to place to store the double value
+obtained from \fIobjPtr\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures are used to create, modify, and read
+double Tcl objects from C code.
+\fBTcl_NewDoubleObj\fR and \fBTcl_SetDoubleObj\fR
+will create a new object of double type
+or modify an existing object to have double type.
+Both of these procedures set the object to have the
+double-precision floating point value given by \fIdoubleValue\fR;
+\fBTcl_NewDoubleObj\fR returns a pointer to a newly created object
+with reference count zero.
+Both procedures set the object's type to be double
+and assign the double value to the object's internal representation
+\fIdoubleValue\fR member.
+\fBTcl_SetDoubleObj\fR invalidates any old string representation
+and, if the object is not already a double object,
+frees any old internal representation.
+.PP
+\fBTcl_GetDoubleFromObj\fR attempts to return a double value
+from the Tcl object \fIobjPtr\fR.
+If the object is not already a double object,
+it will attempt to convert it to one.
+If an error occurs during conversion, it returns \fBTCL_ERROR\fR
+and leaves an error message in the interpreter's result object
+unless \fIinterp\fR is NULL.
+Otherwise, it returns \fBTCL_OK\fR and stores the double value
+in the address given by \fIdoublePtr\fR.
+If the object is not already a double object,
+the conversion will free any old internal representation.
+
+.SH "SEE ALSO"
+Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
+
+.SH KEYWORDS
+double, double object, double type, internal representation, object, object type, string representation
diff --git a/contrib/tcl/doc/Eval.3 b/contrib/tcl/doc/Eval.3
index f1a78c80f879..f10069760f69 100644
--- a/contrib/tcl/doc/Eval.3
+++ b/contrib/tcl/doc/Eval.3
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) Eval.3 1.17 96/03/25 20:02:33
+'\" SCCS: @(#) Eval.3 1.21 97/01/22 14:22:03
'\"
.so man.macros
.TH Tcl_Eval 3 7.0 Tcl "Tcl Library Procedures"
@@ -17,9 +17,7 @@ Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
\fB#include <tcl.h>\fR
.sp
int
-.VS
\fBTcl_Eval\fR(\fIinterp, cmd\fR)
-.VE
.sp
int
\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
@@ -32,8 +30,8 @@ int
.SH ARGUMENTS
.AS Tcl_Interp **termPtr;
.AP Tcl_Interp *interp in
-Interpreter in which to execute the command. String result will be
-stored in \fIinterp->result\fR.
+Interpreter in which to execute the command.
+A string result will be stored in \fIinterp->result\fR.
.AP char *cmd in
Command (or sequence of commands) to execute. Must be in writable
memory (\fBTcl_Eval\fR makes temporary modifications to the command).
@@ -46,61 +44,71 @@ Name of file containing Tcl command string.
.SH DESCRIPTION
.PP
All four of these procedures execute Tcl commands.
-\fBTcl_Eval\fR is the core procedure: it parses commands
-from \fIcmd\fR and executes them in
-.VS
-order until either an error occurs or it reaches the end of the string.
-.VE
-The return value from \fBTcl_Eval\fR is one
-of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
+\fBTcl_Eval\fR is the core procedure and is used by all the others.
+It executes the commands in the script held by \fIcmd\fR
+until either an error occurs or it reaches the end of the script.
+.PP
+Note that \fBTcl_Eval\fR and \fBTcl_GlobalEval\fR
+have been largely replaced by the
+object-based procedures \fBTcl_EvalObj\fR and \fBTcl_GlobalEvalObj\fR.
+Those object-based procedures evaluate a script held in a Tcl object
+instead of a string.
+The object argument can retain the bytecode instructions for the script
+and so avoid reparsing the script each time it is executed.
+\fBTcl_Eval\fR is implemented using \fBTcl_EvalObj\fR
+but is slower because it must reparse the script each time
+since there is no object to retain the bytecode instructions.
+.PP
+The return value from \fBTcl_Eval\fR is one of the Tcl return codes
+\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
\fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
-a string with additional information (result value or error message).
-This return information corresponds to the last command executed from
-\fIcmd\fR.
+a string with additional information (a result value or error message).
+If an error occurs during compilation, this return information
+describes the error.
+Otherwise, this return information corresponds to the last command
+executed from \fIcmd\fR.
.PP
\fBTcl_VarEval\fR takes any number of string arguments
-of any length, concatenates
-them into a single string, then calls \fBTcl_Eval\fR to
-execute that string as a Tcl command.
+of any length, concatenates them into a single string,
+then calls \fBTcl_Eval\fR to execute that string as a Tcl command.
It returns the result of the command and also modifies
-\fIinterp->result\fR in the usual fashion for Tcl commands. The
-last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
+\fIinterp->result\fR in the usual fashion for Tcl commands.
+The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
of arguments.
.PP
\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
its contents as a Tcl command by calling \fBTcl_Eval\fR. It returns
-a standard Tcl result that reflects the result of evaluating the
-file.
+a standard Tcl result that reflects the result of evaluating the file.
If the file couldn't be read then a Tcl error is returned to describe
why the file couldn't be read.
.PP
-\fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
-processes the command at global level.
-This means that the variable context for the command consists of
-global variables only (it ignores any Tcl procedure that is active).
-This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
-.PP
During the processing of a Tcl command it is legal to make nested
-calls to evaluate other commands (this is how conditionals, loops,
-and procedures are implemented).
-If a code other than
-\fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
-caller should normally return immediately, passing that same
-return code back to its caller, and so on until the top-level application is
-reached. A few commands, like \fBfor\fR, will check for certain
+calls to evaluate other commands (this is how procedures and
+some control structures are implemented).
+If a code other than \fBTCL_OK\fR is returned
+from a nested \fBTcl_Eval\fR invocation,
+then the caller should normally return immediately,
+passing that same return code back to its caller,
+and so on until the top-level application is reached.
+A few commands, like \fBfor\fR, will check for certain
return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
specially without returning.
.PP
-\fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
-in progress for \fIinterp\fR.
+\fBTcl_Eval\fR keeps track of how many nested \fBTcl_Eval\fR
+invocations are in progress for \fIinterp\fR.
If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
-about to be returned from the topmost \fBTcl_Eval\fR invocation for
-\fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
-and sets \fIinterp->result\fR to point to an error message indicating that
+about to be returned from the topmost \fBTcl_Eval\fR
+invocation for \fIinterp\fR,
+it converts the return code to \fBTCL_ERROR\fR
+and sets \fIinterp->result\fR
+to point to an error message indicating that
the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
-invoked in an inappropriate place. This means that top-level
-applications should never see a return code from \fBTcl_Eval\fR other then
-\fBTCL_OK\fR or \fBTCL_ERROR\fR.
+invoked in an inappropriate place.
+This means that top-level applications should never see a return code
+from \fBTcl_Eval\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+
+.SH "SEE ALSO"
+Tcl_EvalObj, Tcl_GlobalEvalObj
.SH KEYWORDS
-command, execute, file, global, interpreter, variable
+command, execute, file, global, object, object result, variable
diff --git a/contrib/tcl/doc/EvalObj.3 b/contrib/tcl/doc/EvalObj.3
new file mode 100644
index 000000000000..8cb8f823c9b0
--- /dev/null
+++ b/contrib/tcl/doc/EvalObj.3
@@ -0,0 +1,91 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) EvalObj.3 1.4 97/01/22 15:18:44
+'\"
+.so man.macros
+.TH Tcl_EvalObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_EvalObj, Tcl_GlobalEvalObj \- execute Tcl commands
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_EvalObj\fR(\fIinterp, objPtr\fR)
+.sp
+int
+\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp **termPtr;
+.AP Tcl_Interp *interp in
+Interpreter in which to execute the command.
+The command's result will be stored in the interpreter's result object
+and can be retrieved using \fBTcl_GetObjResult\fR.
+.AP Tcl_Obj *objPtr in
+A Tcl object containing a command string
+(or sequence of commands in a string) to execute.
+.BE
+
+.SH DESCRIPTION
+.PP
+These two procedures execute Tcl commands.
+\fBTcl_EvalObj\fR is the core procedure
+and is used by \fBTcl_GlobalEvalObj\fR.
+It executes the commands in the script held by \fIobjPtr\fR
+until either an error occurs or it reaches the end of the script.
+If this is the first time \fIobjPtr\fR has been executed,
+its commands are compiled into bytecode instructions
+that are then executed if there are no compilation errors.
+.PP
+The return value from \fBTcl_EvalObj\fR is one of the Tcl return codes
+\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
+\fBTCL_CONTINUE\fR,
+and a result object containing additional information
+(a result value or error message)
+that can be retrieved using \fBTcl_GetObjResult\fR.
+If an error occurs during compilation, this return information
+describes the error.
+Otherwise, this return information corresponds to the last command
+executed from \fIobjPtr\fR.
+.PP
+\fBTcl_GlobalEvalObj\fR is similar to \fBTcl_EvalObj\fR except that it
+processes the command at global level.
+This means that the variable context for the command consists of
+global variables only (it ignores any Tcl procedure that is active).
+This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
+.PP
+During the processing of a Tcl command it is legal to make nested
+calls to evaluate other commands (this is how procedures and
+some control structures are implemented).
+If a code other than \fBTCL_OK\fR is returned
+from a nested \fBTcl_EvalObj\fR invocation,
+then the caller should normally return immediately,
+passing that same return code back to its caller,
+and so on until the top-level application is reached.
+A few commands, like \fBfor\fR, will check for certain
+return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
+specially without returning.
+.PP
+\fBTcl_EvalObj\fR keeps track of how many nested \fBTcl_EvalObj\fR
+invocations are in progress for \fIinterp\fR.
+If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
+about to be returned from the topmost \fBTcl_EvalObj\fR
+invocation for \fIinterp\fR,
+it converts the return code to \fBTCL_ERROR\fR
+and sets the interpreter's result object
+to point to an error message indicating that
+the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
+invoked in an inappropriate place.
+This means that top-level applications should never see a return code
+from \fBTcl_EvalObj\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+
+.SH "SEE ALSO"
+Tcl_GetObjResult, Tcl_SetObjResult
+
+.SH KEYWORDS
+command, execute, file, global, object, object result, variable
diff --git a/contrib/tcl/doc/Exit.3 b/contrib/tcl/doc/Exit.3
index dc370bd4ebe7..1d3e26d14fd0 100644
--- a/contrib/tcl/doc/Exit.3
+++ b/contrib/tcl/doc/Exit.3
@@ -4,19 +4,21 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) Exit.3 1.4 96/03/25 20:02:50
+'\" SCCS: @(#) Exit.3 1.8 96/12/10 07:37:23
'\"
.so man.macros
-.TH Tcl_Exit 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_Exit, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers)
+Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers)
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_Exit\fR(\fIstatus\fR)
.sp
+\fBTcl_Finalize\fR()
+.sp
\fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
.sp
\fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
@@ -24,8 +26,8 @@ Tcl_Exit, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (a
.AS Tcl_ExitProc clientData
.AP int status in
Provides information about why application exited. Exact meaning may
-be platform-specific. 0 usually means a normal exit, 1 means that an
-error occurred.
+be platform-specific. 0 usually means a normal exit, any nonzero value
+usually means that an error occurred.
.AP Tcl_ExitProc *proc in
Procedure to invoke before exiting application.
.AP ClientData clientData in
@@ -34,18 +36,41 @@ Arbitrary one-word value to pass to \fIproc\fR.
.SH DESCRIPTION
.PP
-\fBTcl_Exit\fR is the procedure that is invoked to end a Tcl application.
-It is invoked by the \fBexit\fR command, as well as anyplace else that
-terminates the application.
-No-one should ever invoke the \fBexit\fR procedure directly; always
+The procedures described here provide a graceful mechanism to end the
+execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
+application's state before ending the execution of \fBTcl\fR code.
+.PP
+Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this
+process. This procedure is invoked by the \fBexit\fR command, and can be
+invoked anyplace else to terminate the application.
+No-one should ever invoke the \fBexit\fR system procedure directly; always
invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
+Note that if other code invokes \fBexit\fR system procedure directly, or
+otherwise causes the application to terminate without calling
+\fBTcl_Exit\fR, the exit handlers will not be run.
+\fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
+returns control to its caller.
+.PP
+.VS
+\fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
+exit from the current process.
+It is useful for cleaning up when a process is finished using \fBTcl\fR but
+wishes to continue executing, and when \fBTcl\fR is used in a dynamically
+loaded extension that is about to be unloaded.
+On some systems \fBTcl\fR is automatically notified when it is being
+unloaded, and it calls \fBTcl_Finalize\fR internally; on these systems it
+not necessary for the caller to explicitly call \fBTcl_Finalize\fR.
+However, to ensure portability, your code should always invoke
+\fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
+code will work on all platforms. \fBTcl_Finalize\fR can be safely called
+more than once.
+.VE
.PP
\fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
-by \fBTcl_Exit\fR before it terminates the application.
+by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
This provides a hook for cleanup operations such as flushing buffers
and freeing global memory.
-\fIProc\fR should have arguments and return value that match
-the type \fBTcl_ExitProc\fR:
+\fIProc\fR should match the type \fBTcl_ExitProc\fR:
.CS
typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
.CE
@@ -61,6 +86,18 @@ previously-created exit handler. It removes the handler
indicated by \fIproc\fR and \fIclientData\fR so that no call
to \fIproc\fR will be made. If no such handler exists then
\fBTcl_DeleteExitHandler\fR does nothing.
+.PP
+.VS
+.PP
+\fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
+in reverse order from the order in which they were registered.
+This matches the natural order in which extensions are loaded and unloaded;
+if extension \fBA\fR loads extension \fBB\fR, it usually
+unloads \fBB\fR before it itself is unloaded.
+If extension \fBA\fR registers its exit handlers before loading extension
+\fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
+before the exit handlers for \fBA\fR.
+.VE
.SH KEYWORDS
-callback, end application, exit
+callback, cleanup, dynamic loading, end application, exit, unloading
diff --git a/contrib/tcl/doc/ExprLong.3 b/contrib/tcl/doc/ExprLong.3
index 100bec3361c5..634f3c0039d0 100644
--- a/contrib/tcl/doc/ExprLong.3
+++ b/contrib/tcl/doc/ExprLong.3
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) ExprLong.3 1.17 96/03/25 20:03:03
+'\" SCCS: @(#) ExprLong.3 1.26 97/06/26 13:42:47
'\"
.so man.macros
.TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures"
@@ -30,7 +30,7 @@ int
.SH ARGUMENTS
.AS Tcl_Interp *booleanPtr
.AP Tcl_Interp *interp in
-Interpreter in whose context to evaluate \fIstring\fR.
+Interpreter in whose context to evaluate \fIstring\fR or \fIobjPtr\fR.
.AP char *string in
Expression to be evaluated. Must be in writable memory (the expression
parser makes temporary modifications to the string during parsing, which
@@ -48,20 +48,29 @@ expression.
.SH DESCRIPTION
.PP
-These four procedures all evaluate an expression, returning
-the result in one of four different forms.
-The expression is given by the \fIstring\fR argument, and it
-can have any of the forms accepted by the \fBexpr\fR command.
+These four procedures all evaluate the expression
+given by the \fIstring\fR argument
+and return the result in one of four different forms.
+The expression can have any of the forms accepted by the \fBexpr\fR command.
+Note that these procedures have been largely replaced by the
+object-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
+\fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprStringObj\fR.
+Those object-based procedures evaluate an expression held in a Tcl object
+instead of a string.
+The object argument can retain an internal representation
+that is more efficient to execute.
+.PP
The \fIinterp\fR argument refers to an interpreter used to
evaluate the expression (e.g. for variables and nested Tcl
-commands) and to return error information. \fIInterp->result\fR
-is assumed to be initialized in the standard fashion when any
-of the procedures are invoked.
+commands) and to return error information.
+\fIinterp->result\fR is assumed to be initialized
+in the standard fashion when they are invoked.
.PP
For all of these procedures the return value is a standard
-Tcl result: \fBTCL_OK\fR means the expression was successfully
+Tcl result: \fBTCL_OK\fR means the expression was successfully
evaluated, and \fBTCL_ERROR\fR means that an error occurred while
-evaluating the expression. If \fBTCL_ERROR\fR is returned then
+evaluating the expression.
+If \fBTCL_ERROR\fR is returned then
\fIinterp->result\fR will hold a message describing the error.
If an error occurs while executing a Tcl command embedded in
the expression then that error will be returned.
@@ -83,24 +92,23 @@ an error is returned.
.PP
\fBTcl_ExprBoolean\fR stores a 0/1 integer value at \fI*booleanPtr\fR.
If the expression's actual value is an integer or floating-point
-number, then \fBTcl_ExprBoolean\fR stores 0 at \fI*booleanPtr\fR if
+number, then they store 0 at \fI*booleanPtr\fR if
the value was zero and 1 otherwise.
-.VS
If the expression's actual value is a non-numeric string then
-it must be one of the values accepted by \fBTcl_GetBoolean\fR,
+it must be one of the values accepted by \fBTcl_GetBoolean\fR
such as ``yes'' or ``no'', or else an error occurs.
-.VE
.PP
\fBTcl_ExprString\fR returns the value of the expression as a
string stored in \fIinterp->result\fR.
-.VS
If the expression's actual value is an integer
then \fBTcl_ExprString\fR converts it to a string using \fBsprintf\fR
with a ``%d'' converter.
If the expression's actual value is a floating-point
number, then \fBTcl_ExprString\fR calls \fBTcl_PrintDouble\fR
to convert it to a string.
-.VE
+
+.SH "SEE ALSO"
+Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj
.SH KEYWORDS
-boolean, double, evaluate, expression, integer, string
+boolean, double, evaluate, expression, integer, object, string
diff --git a/contrib/tcl/doc/ExprLongObj.3 b/contrib/tcl/doc/ExprLongObj.3
new file mode 100644
index 000000000000..569dc9364a36
--- /dev/null
+++ b/contrib/tcl/doc/ExprLongObj.3
@@ -0,0 +1,104 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) ExprLongObj.3 1.6 97/06/26 13:41:12
+'\"
+.so man.macros
+.TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj \- evaluate an expression
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_ExprLongObj\fR(\fIinterp, objPtr, longPtr\fR)
+.sp
+int
+\fBTcl_ExprDoubleObj\fR(\fIinterp, objPtr, doublePtr\fR)
+.sp
+int
+\fBTcl_ExprBooleanObj\fR(\fIinterp, objPtr, booleanPtr\fR)
+.sp
+int
+\fBTcl_ExprObj\fR(\fIinterp, objPtr, resultPtrPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *resultPtrPtr out
+.AP Tcl_Interp *interp in
+Interpreter in whose context to evaluate \fIstring\fR or \fIobjPtr\fR.
+.AP Tcl_Obj *objPtr in
+Pointer to an object containing the expression to evaluate.
+.AP long *longPtr out
+Pointer to location in which to store the integer value of the
+expression.
+.AP int *doublePtr out
+Pointer to location in which to store the floating-point value of the
+expression.
+.AP int *booleanPtr out
+Pointer to location in which to store the 0/1 boolean value of the
+expression.
+.AP Tcl_Obj *resultPtrPtr out
+Pointer to location in which to store a pointer to the object
+that is the result of the expression.
+.BE
+
+.SH DESCRIPTION
+.PP
+These four procedures all evaluate an expression, returning
+the result in one of four different forms.
+The expression is given by the \fIobjPtr\fR argument, and it
+can have any of the forms accepted by the \fBexpr\fR command.
+.PP
+The \fIinterp\fR argument refers to an interpreter used to
+evaluate the expression (e.g. for variables and nested Tcl
+commands) and to return error information.
+.PP
+For all of these procedures the return value is a standard
+Tcl result: \fBTCL_OK\fR means the expression was successfully
+evaluated, and \fBTCL_ERROR\fR means that an error occurred while
+evaluating the expression.
+If \fBTCL_ERROR\fR is returned,
+then a message describing the error
+can be retrieved using \fBTcl_GetObjResult\fR.
+If an error occurs while executing a Tcl command embedded in
+the expression then that error will be returned.
+.PP
+If the expression is successfully evaluated, then its value is
+returned in one of four forms, depending on which procedure
+is invoked.
+\fBTcl_ExprLongObj\fR stores an integer value at \fI*longPtr\fR.
+If the expression's actual value is a floating-point number,
+then it is truncated to an integer.
+If the expression's actual value is a non-numeric string then
+an error is returned.
+.PP
+\fBTcl_ExprDoubleObj\fR stores a floating-point value at \fI*doublePtr\fR.
+If the expression's actual value is an integer, it is converted to
+floating-point.
+If the expression's actual value is a non-numeric string then
+an error is returned.
+.PP
+\fBTcl_ExprBooleanObj\fR stores a 0/1 integer value at \fI*booleanPtr\fR.
+If the expression's actual value is an integer or floating-point
+number, then they store 0 at \fI*booleanPtr\fR if
+the value was zero and 1 otherwise.
+If the expression's actual value is a non-numeric string then
+it must be one of the values accepted by \fBTcl_GetBoolean\fR
+such as ``yes'' or ``no'', or else an error occurs.
+.PP
+If \fBTcl_ExprObj\fR successfully evaluates the expression,
+it stores a pointer to the Tcl object
+containing the expression's value at \fI*resultPtrPtr\fR.
+In this case, the caller is responsible for calling
+\fBTcl_DecrRefCount\fR to decrement the object's reference count
+when it is finished with the object.
+
+.SH "SEE ALSO"
+Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
+
+.SH KEYWORDS
+boolean, double, evaluate, expression, integer, object, string
diff --git a/contrib/tcl/doc/FindExec.3 b/contrib/tcl/doc/FindExec.3
index 10342cc71485..b48b225e89c8 100644
--- a/contrib/tcl/doc/FindExec.3
+++ b/contrib/tcl/doc/FindExec.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) FindExec.3 1.3 96/03/25 20:03:17
+'\" SCCS: @(#) FindExec.3 1.4 96/10/09 08:29:29
'\"
.so man.macros
.TH Tcl_FindExecutable 3 7.5 Tcl "Tcl Library Procedures"
@@ -30,7 +30,7 @@ This procedure computes the full path name of the executable file
from which the application was invoked and saves it for Tcl's
internal use.
The executable's path name is needed for several purposes in
-Tcl. For example, is is needed on some platforms in the
+Tcl. For example, it is needed on some platforms in the
implementation of the \fBload\fR command.
It is also returned by the \fBinfo nameofexecutable\fR command.
.PP
diff --git a/contrib/tcl/doc/GetIndex.3 b/contrib/tcl/doc/GetIndex.3
new file mode 100644
index 000000000000..66782576e2f8
--- /dev/null
+++ b/contrib/tcl/doc/GetIndex.3
@@ -0,0 +1,74 @@
+'\"
+'\" 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.
+'\"
+'\" SCCS: @(#) @(#) GetIndex.3 1.2 97/02/11 13:25:45
+'\"
+.so man.macros
+.TH Tcl_GetIndexFromObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_GetIndexFromObj \- lookup string in table of keywords
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags, indexPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp **tablePtr
+.AP Tcl_Interp *interp in
+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 object is used to search through \fItablePtr\fR.
+The internal representation is modified to hold the index of the matching
+table entry.
+.AP char **tablePtr in
+An array of null-terminated strings. The end of the array is marked
+by a NULL string pointer.
+.AP char *msg in
+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.
+.AP int *indexPtr out
+The index of the string in \fItablePtr\fR that matches the value of
+\fIobjPtr\fR is returned here.
+.BE
+
+.SH DESCRIPTION
+.PP
+This procedure provides an efficient way for looking up keywords,
+switch names, option names, and similar things where the value of
+an object must be one of a predefined set of values.
+\fIObjPtr\fR is compared against each of
+the strings in \fItablePtr\fR to find a match. A match occurs if
+\fIobjPtr\fR's string value is identical to one of the strings in
+\fItablePtr\fR, or if it is a unique abbreviation
+for exactly one of the strings in \fItablePtr\fR and the
+\fBTCL_EXACT\fR flag was not specified; in either case
+the index of the matching entry is stored at \fI*indexPtr\fR
+and TCL_OK is returned.
+.PP
+If there is no matching entry,
+TCL_ERROR is returned and an error message is left in \fIinterp\fR's
+result if \fIinterp\fR isn't NULL. \fIMsg\fR is included in the
+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
+\fBbad option "firt": must be first, second, or third\fR.
+.PP
+If \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
+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.
+
+.SH KEYWORDS
+index, object, table lookup
diff --git a/contrib/tcl/doc/GetOpnFl.3 b/contrib/tcl/doc/GetOpnFl.3
index 8f37d1156552..decb9a40d170 100644
--- a/contrib/tcl/doc/GetOpnFl.3
+++ b/contrib/tcl/doc/GetOpnFl.3
@@ -1,15 +1,15 @@
'\"
-'\" Copyright (c) 1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1996-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.
'\"
-'\" SCCS: @(#) GetOpnFl.3 1.2 96/03/26 13:40:26
+'\" SCCS: @(#) GetOpnFl.3 1.3 97/04/23 16:14:43
.so man.macros
-.TH Tcl_GetOpenFile 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_GetOpenFile \- Get a standard IO File * handle from a channel.
+Tcl_GetOpenFile \- Get a standard IO File * handle from a channel. (Unix only)
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -52,6 +52,10 @@ for the access specified by \fIwrite\fR) then TCL_ERROR is returned
and \fIinterp->result\fR will contain an error message.
In the current implementation \fIcheckUsage\fR is ignored and consistency
checks are always performed.
+.VS
+.PP
+Note that this interface is only supported on the Unix platform.
+.VE
.SH KEYWORDS
channel, file handle, permissions, pipeline, read, write
diff --git a/contrib/tcl/doc/IntObj.3 b/contrib/tcl/doc/IntObj.3
new file mode 100644
index 000000000000..a87ac929060f
--- /dev/null
+++ b/contrib/tcl/doc/IntObj.3
@@ -0,0 +1,104 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) @(#) IntObj.3 1.7 97/05/08 19:49:22
+'\"
+.so man.macros
+.TH Tcl_IntObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj \- manipulate Tcl objects as integers
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewIntObj\fR(\fIintValue\fR)
+.sp
+Tcl_Obj *
+\fBTcl_NewLongObj\fR(\fIlongValue\fR)
+.sp
+\fBTcl_SetIntObj\fR(\fIobjPtr, intValue\fR)
+.sp
+\fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
+.sp
+int
+\fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
+.sp
+int
+\fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP int intValue in
+Integer value used to initialize or set an integer object.
+.AP long longValue in
+Long integer value used to initialize or set an integer object.
+.AP Tcl_Obj *objPtr in/out
+For \fBTcl_SetIntObj\fR and \fBTcl_SetLongObj\fR,
+this points to the object to be converted to integer type.
+For \fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR,
+this refers to the object
+from which to get an integer or long integer value;
+if \fIobjPtr\fR does not already point to an integer object,
+an attempt will be made to convert it to one.
+.AP Tcl_Interp *interp in/out
+If an error occurs during conversion,
+an error message is left in the interpreter's result object
+unless \fIinterp\fR is NULL.
+.AP int *intPtr out
+Points to place to store the integer value
+obtained by \fBTcl_GetIntFromObj\fR from \fIobjPtr\fR.
+.AP long *longPtr out
+Points to place to store the long integer value
+obtained by \fBTcl_GetLongFromObj\fR from \fIobjPtr\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures are used to create, modify, and read
+integer Tcl objects from C code.
+\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR,
+\fBTcl_SetIntObj\fR, and \fBTcl_SetLongObj\fR
+create a new object of integer type
+or modify an existing object to have integer type.
+\fBTcl_NewIntObj\fR and \fBTcl_SetIntObj\fR set the object to have the
+integer value given by \fIintValue\fR,
+while \fBTcl_NewLongObj\fR and \fBTcl_SetLongObj\fR
+set the object to have the
+long integer value given by \fIlongValue\fR.
+\fBTcl_NewIntObj\fR and \fBTcl_NewLongObj\fR
+return a pointer to a newly created object with reference count zero.
+These procedures set the object's type to be integer
+and assign the integer value to the object's internal representation
+\fIlongValue\fR member.
+\fBTcl_SetIntObj\fR and \fBTcl_SetLongObj\fR
+invalidate any old string representation and,
+if the object is not already an integer object,
+free any old internal representation.
+.PP
+\fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR
+attempt to return an integer value from the Tcl object \fIobjPtr\fR.
+If the object is not already an integer object,
+they will attempt to convert it to one.
+If an error occurs during conversion, they return \fBTCL_ERROR\fR
+and leave an error message in the interpreter's result object
+unless \fIinterp\fR is NULL.
+Also, if the long integer held in the object's internal representation
+\fIlongValue\fR member can not be represented in a (non-long) integer,
+\fBTcl_GetIntFromObj\fR returns \fBTCL_ERROR\fR
+and leaves an error message in the interpreter's result object
+unless \fIinterp\fR is NULL.
+Otherwise, both procedures return \fBTCL_OK\fR and
+store the integer or the long integer value
+in the address given by \fIintPtr\fR and \fIlongPtr\fR respectively.
+If the object is not already an integer object,
+the conversion will free any old internal representation.
+
+.SH "SEE ALSO"
+Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
+
+.SH KEYWORDS
+integer, integer object, integer type, internal representation, object, object type, string representation
diff --git a/contrib/tcl/doc/LinkVar.3 b/contrib/tcl/doc/LinkVar.3
index 192646037e39..a7a535527e54 100644
--- a/contrib/tcl/doc/LinkVar.3
+++ b/contrib/tcl/doc/LinkVar.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) LinkVar.3 1.13 96/06/05 18:00:14
+'\" SCCS: @(#) LinkVar.3 1.15 96/09/05 17:16:57
'\"
.so man.macros
.TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
@@ -21,16 +21,15 @@ int
.sp
\fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
.sp
-.VS
\fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
-.VE
.SH ARGUMENTS
.AS Tcl_Interp writable
.AP Tcl_Interp *interp in
Interpreter that contains \fIvarName\fR.
Also used by \fBTcl_LinkVar\fR to return error messages.
.AP char *varName in
-Name of global variable.
+Name of global variable. Must be in writable memory: Tcl may make
+temporary modifications to it while parsing the variable name.
.AP char *addr in
Address of C variable that is to be linked to \fIvarName\fR.
.AP int type in
@@ -102,7 +101,6 @@ Attempts to write the variable from Tcl will be rejected with errors.
variable given by \fIvarName\fR. If there does not exist a link
for \fIvarName\fR then the procedure has no effect.
.PP
-.VS
\fBTcl_UpdateLinkedVar\fR may be invoked after the C variable has
changed to force the Tcl variable to be updated immediately.
In many cases this procedure is not needed, since any attempt to
@@ -112,7 +110,6 @@ Tk widget that wishes to display the value of the variable), the
trace will not trigger when the C variable has changed.
\fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl
variable are invoked.
-.VE
.SH KEYWORDS
boolean, integer, link, read-only, real, string, traces, variable
diff --git a/contrib/tcl/doc/ListObj.3 b/contrib/tcl/doc/ListObj.3
new file mode 100644
index 000000000000..1e304297633c
--- /dev/null
+++ b/contrib/tcl/doc/ListObj.3
@@ -0,0 +1,249 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) @(#) ListObj.3 1.9 97/06/03 13:51:42
+'\"
+.so man.macros
+.TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl objects as lists
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_ListObjAppendList\fR(\fIinterp, listPtr, elemListPtr\fR)
+.sp
+int
+\fBTcl_ListObjAppendElement\fR(\fIinterp, listPtr, objPtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_NewListObj\fR(\fIobjc, objv\fR)
+.sp
+\fBTcl_SetListObj\fR(\fIobjPtr, objc, objv\fR)
+.sp
+int
+\fBTcl_ListObjGetElements\fR(\fIinterp, listPtr, objcPtr, objvPtr\fR)
+.sp
+int
+\fBTcl_ListObjLength\fR(\fIinterp, listPtr, intPtr\fR)
+.sp
+int
+\fBTcl_ListObjIndex\fR(\fIinterp, listPtr, index, objPtrPtr\fR)
+.sp
+int
+\fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp "*CONST objv[]" out
+.AP Tcl_Interp *interp in
+If an error occurs while converting an object to be a list object,
+an error message is left in the interpreter's result object
+unless \fIinterp\fR is NULL.
+.AP Tcl_Obj *listPtr in/out
+Points to the list object to be manipulated.
+If \fIlistPtr\fR does not already point to a list object,
+an attempt will be made to convert it to one.
+.AP Tcl_Obj *elemListPtr in/out
+For \fBTcl_ListObjAppendList\fR, this points to a list object
+containing elements to be appended onto \fIlistPtr\fR.
+Each element of *\fIelemListPtr\fR will
+become a new element of \fIlistPtr\fR.
+If *\fIelemListPtr\fR is not NULL and
+does not already point to a list object,
+an attempt will be made to convert it to one.
+.AP Tcl_Obj *objPtr in
+For \fBTcl_ListObjAppendElement\fR,
+points to the Tcl object that will be appended to \fIlistPtr\fR.
+For \fBTcl_SetListObj\fR,
+this points to the Tcl object that will be converted to a list object
+containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR.
+.AP int *objcPtr in
+Points to location where \fBTcl_ListObjGetElements\fR
+stores the number of element objects in \fIlistPtr\fR.
+.AP Tcl_Obj ***objvPtr out
+A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
+of pointers to the element objects of \fIlistPtr\fR.
+.AP int objc in
+The number of Tcl objects that \fBTcl_NewListObj\fR
+will insert into a new list object,
+and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR.
+For \fBTcl_SetListObj\fR,
+the number of Tcl objects to insert into \fIobjPtr\fR.
+.VS
+.TP
+Tcl_Obj *CONST \fIobjv\fR[] (in)
+.
+An array of pointers to objects.
+\fBTcl_NewListObj\fR will insert these objects into a new list object
+and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
+Each object will become a separate list element.
+.VE
+.AP int *intPtr out
+Points to location where \fBTcl_ListObjLength\fR
+stores the length of the list.
+.AP int index in
+Index of the list element that \fBTcl_ListObjIndex\fR
+is to return.
+The first element has index 0.
+.AP Tcl_Obj **objPtrPtr out
+Points to place where \fBTcl_ListObjIndex\fR is to store
+a pointer to the resulting list element object.
+.AP int first in
+Index of the starting list element that \fBTcl_ListObjReplace\fR
+is to replace.
+The list's first element has index 0.
+.AP int last in
+Index of the final list element that \fBTcl_ListObjReplace\fR
+is to replace.
+.BE
+
+.SH DESCRIPTION
+.PP
+Tcl list objects have an internal representation that supports
+the efficient indexing and appending.
+The procedures described in this man page are used to
+create, modify, index, and append to Tcl list objects from C code.
+.PP
+\fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR
+both add one or more objects
+to the end of the list object referenced by \fIlistPtr\fR.
+\fBTcl_ListObjAppendList\fR appends each element of the list object
+referenced by \fIelemListPtr\fR while
+\fBTcl_ListObjAppendElement\fR appends the single object
+referenced by \fIobjPtr\fR.
+Both procedures will convert the object referenced by \fIlistPtr\fR
+to a list object if necessary.
+If an error occurs during conversion,
+both procedures return \fBTCL_ERROR\fR and leave an error message
+in the interpreter's result object if \fIinterp\fR is not NULL.
+Similarly, if \fIelemListPtr\fR does not already refer to a list object,
+\fBTcl_ListObjAppendList\fR will attempt to convert it to one
+and if an error occurs during conversion,
+will return \fBTCL_ERROR\fR
+and leave an error message in the interpreter's result object
+if interp is not NULL.
+Both procedures invalidate any old string representation of \fIlistPtr\fR
+and, if it was converted to a list object,
+free any old internal representation.
+Similarly, \fBTcl_ListObjAppendList\fR frees any old internal representation
+of \fIelemListPtr\fR if it converts it to a list object.
+After appending each element in \fIelemListPtr\fR,
+\fBTcl_ListObjAppendList\fR increments the element's reference count
+since \fIlistPtr\fR now also refers to it.
+For the same reason, \fBTcl_ListObjAppendElement\fR
+increments \fIobjPtr\fR's reference count.
+If no error occurs,
+the two procedures return \fBTCL_OK\fR after appending the objects.
+.PP
+\fBTcl_NewListObj\fR and \fBTcl_SetListObj\fR
+create a new object or modify an existing object to hold
+the \fIobjc\fR elements of the array referenced by \fIobjv\fR
+where each element is a pointer to a Tcl object.
+If \fIobjc\fR is less than or equal to zero,
+they return an empty object.
+The new object's string representation is left invalid.
+The two procedures increment the reference counts
+of the elements in \fIobjc\fR since the list object now refers to them.
+The new list object returned by \fBTcl_NewListObj\fR
+has reference count zero.
+.PP
+\fBTcl_ListObjGetElements\fR returns a count and
+a pointer to an array of the elements in a list object.
+It returns the count by storing it in the address \fIobjcPtr\fR.
+Similarly, it returns the array pointer by storing it
+in the address \fIobjvPtr\fR.
+If \fIlistPtr\fR is not already a list object,
+\fBTcl_ListObjGetElements\fR will attempt to convert it to one;
+if the conversion fails, it returns \fBTCL_ERROR\fR
+and leaves an error message in the interpreter's result object
+if \fIinterp\fR is not NULL.
+Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer.
+.PP
+\fBTcl_ListObjLength\fR returns the number of elements in the list object
+referenced by \fIlistPtr\fR.
+It returns this count by storing an integer in the address \fIintPtr\fR.
+If the object is not already a list object,
+\fBTcl_ListObjLength\fR will attempt to convert it to one;
+if the conversion fails, it returns \fBTCL_ERROR\fR
+and leaves an error message in the interpreter's result object
+if \fIinterp\fR is not NULL.
+Otherwise it returns \fBTCL_OK\fR after storing the list's length.
+.PP
+The procedure \fBTcl_ListObjIndex\fR returns a pointer to the object
+at element \fIindex\fR in the list referenced by \fIlistPtr\fR.
+It returns this object by storing a pointer to it
+in the address \fIobjPtrPtr\fR.
+If \fIlistPtr\fR does not already refer to a list object,
+\fBTcl_ListObjIndex\fR will attempt to convert it to one;
+if the conversion fails, it returns \fBTCL_ERROR\fR
+and leaves an error message in the interpreter's result object
+if \fIinterp\fR is not NULL.
+If the index is out of range,
+that is, \fIindex\fR is negative or
+greater than or equal to the number of elements in the list,
+\fBTcl_ListObjIndex\fR stores a NULL in \fIobjPtrPtr\fR
+and returns \fBTCL_OK\fR.
+Otherwise it returns \fBTCL_OK\fR after storing the element's
+object pointer.
+The reference count for the list element is not incremented;
+the caller must do that if it needs to retain a pointer to the element.
+.PP
+\fBTcl_ListObjReplace\fR replaces zero or more elements
+of the list referenced by \fIlistPtr\fR
+with the \fIobjc\fR objects in the array referenced by \fIobjv\fR.
+If \fIlistPtr\fR does not point to a list object,
+\fBTcl_ListObjReplace\fR will attempt to convert it to one;
+if the conversion fails, it returns \fBTCL_ERROR\fR
+and leaves an error message in the interpreter's result object
+if \fIinterp\fR is not NULL.
+Otherwise, it returns \fBTCL_OK\fR after replacing the objects.
+If \fIobjv\fR is NULL, no new elements are added.
+If the argument \fIfirst\fR is zero or negative,
+it refers to the first element.
+If \fIfirst\fR is greater than or equal to the
+number of elements in the list, then no elements are deleted;
+the new elements are appended to the list.
+\fIcount\fR gives the number of elements to replace.
+If \fIcount\fR is zero or negative then no elements are deleted;
+the new elements are simply inserted before the one
+designated by \fIfirst\fR.
+\fBTcl_ListObjReplace\fR invalidates \fIlistPtr\fR's
+old string representation.
+The reference counts of any elements inserted from \fIobjv\fR
+are incremented since the resulting list now refers to them.
+Similarly, the reference counts for any replaced objects are decremented.
+.PP
+Because \fBTcl_ListObjReplace\fR combines
+both element insertion and deletion,
+it can be used to implement a number of list operations.
+For example, the following code inserts the \fIobjc\fR objects
+referenced by the array of object pointers \fIobjv\fR
+just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR:
+.CS
+result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv);
+.CE
+Similarly, the following code appends the \fIobjc\fR objects
+referenced by the array \fIobjv\fR
+to the end of the list \fIlistPtr\fR:
+.CS
+result = Tcl_ListObjLength(interp, listPtr, &length);
+if (result == TCL_OK) {
+ result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv);
+}
+.CE
+The \fIcount\fR list elements starting at \fIfirst\fR can be deleted
+by simply calling \fBTcl_ListObjReplace\fR
+with a NULL \fIobjvPtr\fR:
+.CS
+result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL);
+.CE
+
+.SH "SEE ALSO"
+Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
+
+.SH KEYWORDS
+append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation
diff --git a/contrib/tcl/doc/Notifier.3 b/contrib/tcl/doc/Notifier.3
index 0d3ff9384017..5016200ab62b 100644
--- a/contrib/tcl/doc/Notifier.3
+++ b/contrib/tcl/doc/Notifier.3
@@ -1,50 +1,63 @@
'\"
-'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1995-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.
'\"
-'\" SCCS: @(#) Notifier.3 1.11 96/06/05 18:00:17
+'\" SCCS: @(#) Notifier.3 1.16 97/05/17 17:03:17
'\"
.so man.macros
-.TH Tcl_CreateEventSource 3 7.5 Tcl "Tcl Library Procedures"
+.TH Notifier 3 8.0 Tcl "Tcl Library Procedures"
.BS
+.VS
.SH NAME
-Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_WatchFile, Tcl_FileReady, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_WaitForEvent \- Event sources, the event notifier, and the event queue
+Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_WaitForEvent, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
+
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
-\fBTcl_CreateEventSource(\fIsetupProc, checkProc, clientData\fB)\fR
+\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
+.sp
+\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
+.sp
+\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fB)\fR
.sp
-\fBTcl_DeleteEventSource(\fIsetupProc, checkProc, clientData\fB)\fR
+\fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
+.VS
+.sp
+\fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
.sp
-\fBTcl_WatchFile(\fIfile, mask\fB)\fR
+int
+\fBTcl_WaitForEvent\fR(\fItimePtr\fR)
.sp
-\fBTcl_SetMaxBlockTime(\fItimePtr\fB)\fR
+\fBTcl_SetTimer\fR(\fItimePtr\fR)
.sp
int
-\fBTcl_FileReady(\fIfile, mask\fB)\fR
+\fBTcl_ServiceAll\fR()
.sp
-\fBTcl_QueueEvent(\fIevPtr, position\fB)\fR
+int
+\fBTcl_ServiceEvent\fR(\fIflags\fR)
.sp
int
-\fBTcl_WaitForEvent(\fItimePtr\fB)\fR
+\fBTcl_GetServiceMode\fR()
+.sp
+int
+\fBTcl_SetServiceMode\fR(\fImode\fR)
+.VE
+
.SH ARGUMENTS
+.AS Tcl_EventDeleteProc milliseconds
.AS Tcl_EventSetupProc *setupProc
.AP Tcl_EventSetupProc *setupProc in
-Procedure to invoke to prepare for event wait in \fBTcl_DoWhenIdle\fR.
+Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
.AP Tcl_EventCheckProc *checkProc in
-Procedure for \fBTcl_DoWhenIdle\fR to invoke after waiting for
+Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
events. Checks to see if any events have occurred and, if so,
queues them.
.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIsetupProc\fR and \fIcheckProc\fR.
-.AP Tcl_File file in
-Generic file handle as returned by \fBTcl_GetFile\fR.
-.AP int mask in
-Indicates the events of interest on \fIfile\fR: an OR'ed combination
-of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR, and \fBTCL_EXCEPTION\fR.
+Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
+\fIdeleteProc\fR.
.AP Tcl_Time *timePtr in
Indicates the maximum amount of time to wait for an event. This
is specified as an interval (how long to wait), not an absolute
@@ -53,59 +66,104 @@ is NULL, it means there is no maximum wait time: wait forever if
necessary.
.AP Tcl_Event *evPtr in
An event to add to the event queue. The storage for the event must
-.VS
have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
-.VE
.AP Tcl_QueuePosition position in
Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR,
\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
.AP int flags in
-A copy of the \fIflags\fR argument passed to \fBTcl_DoOneEvent\fR.
+What types of events to service. These flags are the same as those
+passed to \fBTcl_DoOneEvent\fR.
+.AP Tcl_EventDeleteProc *deleteProc in
+Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
+.VS
+.AP int mode in
+Inidicates whether events should be serviced by \fBTcl_ServiceAll\fR.
+Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
+.VE
.BE
.SH INTRODUCTION
.PP
-The procedures described here are the building blocks out of which
-the Tcl event notifier is constructed. The event notifier is the
-lowest layer in the Tcl event mechanism. It consists of three
-things:
+.VS
+The interfaces described here are used to customize the Tcl event
+loop. The two most common customizations are to add new sources of
+events and to merge Tcl's event loop with some other event loop, such
+as one provided by an application in which Tcl is embedded. Each of
+these tasks is described in a separate section below.
+.VE
+.PP
+The procedures in this manual entry are the building blocks out of which
+the Tcl event notifier is constructed. The event notifier is the lowest
+layer in the Tcl event mechanism. It consists of three things:
.IP [1]
-Event sources: these represent the ways in which events can be
+Event sources: these represent the ways in which events can be
generated. For example, there is a timer event source that implements
-the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR command,
-and there is a file event source that implements the
-\fBTcl_CreateFileHandler\fR procedure. An event source must work
-with the notifier to detect events at the right times, record them
-on the event queue, and eventually notify higher-level software that
-they have occurred.
+the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR
+command, and there is a file event source that implements the
+\fBTcl_CreateFileHandler\fR procedure on Unix systems. An event
+source must work with the notifier to detect events at the right
+times, record them on the event queue, and eventually notify
+higher-level software that they have occurred. The procedures
+\fBTcl_CreateEventSource\fR, \fBTcl_DeleteEventSource\fR,
+and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
+\fBTcl_DeleteEvents\fR are used primarily by event sources.
.IP [2]
-The event queue: there is a single queue for the whole application,
-containing events that have been detected but not yet serviced.
-The event queue guarantees a fair discipline of event handling, so
-that no event source can starve the others. It also allows events
-to be saved for servicing at a future time.
+The event queue: there is a single queue for the whole application,
+containing events that have been detected but not yet serviced. Event
+sources place events onto the queue so that they may be processed in
+order at appropriate times during the event loop. The event queue
+guarantees a fair discipline of event handling, so that no event
+source can starve the others. It also allows events to be saved for
+servicing at a future time.
+.VS
+\fBTcl_QueueEvent\fR is used (primarily
+by event sources) to add events to the event queue and
+\fBTcl_DeleteEvents\fR is used to remove events from the queue without
+processing them.
.IP [3]
-The procedure \fBTcl_DoOneEvent\fR: this is procedure that is invoked
-by the application to service events. It works with the event sources
-and the event queue to detect and handle events, and calls
-\fBTcl_WaitForEvent\fR to actually wait for an event to occur.
+The event loop: in order to detect and process events, the application
+enters a loop that waits for events to occur, places them on the event
+queue, and then processes them. Most applications will do this by
+calling the procedure \fBTcl_DoOneEvent\fR, which is described in a
+separate manual entry.
+.PP
+Most Tcl applications need not worry about any of the internals of
+the Tcl notifier. However, the notifier now has enough flexibility
+to be retargeted either for a new platform or to use an external event
+loop (such as the Motif event loop, when Tcl is embedded in a Motif
+application). The procedures \fBTcl_WaitForEvent\fR and
+\fBTcl_SetTimer\fR are normally implemented by Tcl, but may be
+replaced with new versions to retarget the notifier (the \fBTcl_Sleep\fR,
+\fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must
+also be replaced; see CREATING A NEW NOTIFIER below for details).
+The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
+\fBTcl_GetServiceMode\fR, and \fBTcl_SetServiceMode\fR are provided
+to help connect Tcl's event loop to an external event loop such as
+Motif's.
+.SH "NOTIFIER BASICS"
+.VE
.PP
The easiest way to understand how the notifier works is to consider
what happens when \fBTcl_DoOneEvent\fR is called.
-\fBTcl_DoOneEvent\fR is passed a \fIflags\fR
-argument that indicates what sort of events it is OK to process and
-also whether or not to block if no events are ready.
-\fBTcl_DoOneEvent\fR does the following things:
+\fBTcl_DoOneEvent\fR is passed a \fIflags\fR argument that indicates
+what sort of events it is OK to process and also whether or not to
+block if no events are ready. \fBTcl_DoOneEvent\fR does the following
+things:
.IP [1]
Check the event queue to see if it contains any events that can
be serviced. If so, service the first possible event, remove it
-from the queue, and return.
+.VS
+from the queue, and return. It does this by calling
+\fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
+.VE
.IP [2]
Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR
invokes a \fIsetup procedure\fR in each event source.
-The event source will call procedures like \fBTcl_WatchFile\fR and
-\fBTcl_SetMaxBlockTime\fR to indicate what low-level events to look
-for in \fBTcl_WaitForEvent\fR.
+The event source will perform event-source specific initialization and
+.VS
+possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
+.VE
+\fBTcl_WaitForEvent\fR will block if no new events occur.
.IP [3]
Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently
on different platforms; it waits for an event to occur, based on the
@@ -120,26 +178,17 @@ and \fBTcl_DoOneEvent\fR returns 0.
.IP [4]
Call a \fIcheck procedure\fR in each event source. The check
procedure determines whether any events of interest to this source
-occurred (e.g. by calling \fBTcl_FileReady\fR). If so,
-the events are added to the event queue.
+occurred. If so, the events are added to the event queue.
.IP [5]
Check the event queue to see if it contains any events that can
be serviced. If so, service the first possible event, remove it
from the queue, and return.
.IP [6]
-See if there are idle callbacks pending.
-If so, invoke all of them and return.
+See if there are idle callbacks pending. If so, invoke all of them and
+return.
.IP [7]
Either return 0 to indicate that no events were ready, or go back to
step [2] if blocking was requested by the caller.
-.PP
-The procedures in this file allow you to do two things. First, they
-allow you to create new event sources, such as one for UNIX signals
-or one to notify when subprocesses have exited. Second, the procedures
-can be used to build a new version of \fBTcl_DoOneEvent\fR. This
-might be necessary to support a new operating system with different
-low-level event reporting mechanisms, or it might be necessary to
-merge Tcl's event loop with that of some other toolkit like Xt.
.SH "CREATING A NEW EVENT SOURCE"
.PP
@@ -164,38 +213,34 @@ argument to \fBTcl_CreateEventSource\fR; it is typically used to
point to private information managed by the event source.
The \fIflags\fR argument will be the same as the \fIflags\fR
argument passed to \fBTcl_DoOneEvent\fR except that it will never
-by 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
+be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
\fIFlags\fR indicates what kinds of events should be considered;
if the bit corresponding to this event source isn't set, the event
source should return immediately without doing anything. For
example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
bit.
.PP
-\fISetupProc\fR's job is to provide information to
-\fBTcl_WaitForEvent\fR about how to wait for events.
-It usually does this by calling \fBTcl_WatchFile\fR or
-\fBTcl_SetMaxBlockTime\fR.
-For example, \fIsetupProc\fR can call \fBTcl_WatchFile\fR to indicate
-that \fBTcl_WaitForEvent\fR should return when the conditions
-given by the \fImask\fR argument become true for the file given
-by \fIfile\fR.
-The UNIX version of \fBTcl_WaitForEvent\fR uses the
-information passed to \fBTcl_WatchFile\fR to set the file masks
-for \fBselect\fR, which it uses to wait for events.
-If \fBTcl_WatchFile\fR isn't called by any event sources then
-\fBTcl_WaitForEvent\fR will ignore files while waiting.
-.PP
-\fISetupProc\fR can also invoke \fBTcl_SetMaxBlockTime\fR to set an
-upper bound on how long \fBTcl_WaitForEvent\fR will block.
-If no event source calls \fBTcl_SetMaxBlockTime\fR then
-\fBTcl_WaitForEvent\fR will wait as long as necessary for an event
-to occur; otherwise, it will only wait as long as the shortest
+\fISetupProc\fR's job is to make sure that the application wakes up
+when events of the desired type occur. This is typically done in a
+platform-dependent fashion. For example, under Unix an event source
+might call \fBTcl_CreateFileHandler\fR; under Windows it might
+request notification with a Windows event. For timer-driven event
+sources such as timer events or any polled event, the event source
+can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
+up after a specified time even if no events have occurred.
+.VS
+If no event source calls \fBTcl_SetMaxBlockTime\fR
+then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
+event to occur; otherwise, it will only wait as long as the shortest
interval passed to \fBTcl_SetMaxBlockTime\fR by one of the event
-sources.
-For example, the timer event source uses this procedure to limit the
-wait time to the interval before the next timer event is ready.
-If an event source knows that it already has events ready to report,
-it can request a zero maximum block time.
+sources. If an event source knows that it already has events ready to
+report, it can request a zero maximum block time. For example, the
+setup procedure for the X event source looks to see if there are
+events already queued. If there are, it calls
+\fBTcl_SetMaxBlockTime\fR with a 0 block time so that
+\fBTcl_WaitForEvent\fR does not block if there is no new data on the X
+connection.
+.VE
The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
a structure that describes a time interval in seconds and
microseconds:
@@ -207,17 +252,32 @@ typedef struct Tcl_Time {
.CE
The \fIusec\fR field should be less than 1000000.
.PP
-Information provided to \fBTcl_WatchFile\fR and \fBTcl_SetMaxBlockTime\fR
+.VS
+Information provided to \fBTcl_SetMaxBlockTime\fR
is only used for the next call to \fBTcl_WaitForEvent\fR; it is
discarded after \fBTcl_WaitForEvent\fR returns.
+.VE
The next time an event wait is done each of the event sources'
setup procedures will be called again, and they can specify new
information for that event wait.
.PP
-In addition to the generic procedures \fBTcl_WatchFile\fR and
-\fBTcl_SetMaxBlockTime\fR, other platform-specific procedures may
-also be available for \fIsetupProc\fR, if there is additional
-information needed by \fBTcl_WaitForEvent\fR on that platform.
+.VS
+If the application uses an external event loop rather than
+\fBTcl_DoOneEvent\fR, the event sources may need to call
+\fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event
+handler is registered that needs to poll for events, the event source
+may call \fBTcl_SetMaxBlockTime\fR to set the block time to zero to
+force the external event loop to call Tcl. In this case,
+\fBTcl_SetMaxBlockTime\fR invokes \fBTcl_SetTimer\fR with the shortest
+interval seen since the last call to \fBTcl_DoOneEvent\fR or
+\fBTcl_ServiceAll\fR.
+.PP
+In addition to the generic procedure \fBTcl_SetMaxBlockTime\fR, other
+platform-specific procedures may also be available for
+\fIsetupProc\fR, if there is additional information needed by
+\fBTcl_WaitForEvent\fR on that platform. For example, on Unix systems
+the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
+.VE
.PP
The second procedure provided by each event source is its check
procedure, indicated by the \fIcheckProc\fR argument to
@@ -234,28 +294,18 @@ for events. Presumably at least one event source is now prepared to
queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources
in turn, so they all have a chance to queue any events that are ready.
The check procedure does two things. First, it must see if any events
-have triggered. Different event sources do this in different ways,
-but the procedure \fBTcl_FileReady\fR may be useful for some event
-sources. It takes as arguments a file identifier \fIfile\fR and
-a mask of interesting conditions; it returns another mask indicating
-which of those conditions were found to be present on the file during
-the most recent call to \fBTcl_WaitForEvent\fR.
-\fBTcl_WaitForEvent\fR only checks a file if \fBTcl_WatchFile\fR was
-called by at least one event source, so it is possible for
-\fBTcl_FileReady\fR to return 0 even if the file is ready.
+have triggered. Different event sources do this in different ways.
.PP
-If an event source's check procedure detects that an interesting
-event has occurred, then it must add the event to Tcl's event queue.
-To do this, the event source calls \fBTcl_QueueEvent\fR.
-The \fIevPtr\fR argument is a pointer to a dynamically allocated
-structure containing the event (see below for more information
-on memory management issues).
-Each event source can define its own event structure with
-whatever information is relevant to that event source.
-However, the first element of the structure must be a structure
-of type \fBTcl_Event\fR, and the address of this structure is used when
-communicating between the event source and the rest of the notifier.
-A \fBTcl_Event\fR has the following definition:
+If an event source's check procedure detects an interesting event, it
+must add the event to Tcl's event queue. To do this, the event source
+calls \fBTcl_QueueEvent\fR. The \fIevPtr\fR argument is a pointer to
+a dynamically allocated structure containing the event (see below for
+more information on memory management issues). Each event source can
+define its own event structure with whatever information is relevant
+to that event source. However, the first element of the structure
+must be a structure of type \fBTcl_Event\fR, and the address of this
+structure is used when communicating between the event source and the
+rest of the notifier. A \fBTcl_Event\fR has the following definition:
.CS
typedef struct Tcl_Event {
Tcl_EventProc *\fIproc\fR;
@@ -285,8 +335,10 @@ events at the front of the queue, such as a series of
Enter and Leave events synthesized during a grab or ungrab operation
in Tk.
.PP
-When it is time to handle an event from the queue (steps 1 and 5
-above) \fBTcl_DoOneEvent\fR will invoke the \fIproc\fR specified
+.VS
+When it is time to handle an event from the queue (steps 1 and 4
+above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
+.VE
in the first queued \fBTcl_Event\fR structure.
\fIProc\fR must match the following prototype:
.CS
@@ -298,7 +350,9 @@ The first argument to \fIproc\fR is a pointer to the event, which will
be the same as the first argument to the \fBTcl_QueueEvent\fR call that
added the event to the queue.
The second argument to \fIproc\fR is the \fIflags\fR argument for the
-current call to \fBTcl_DoOneEvent\fR; this is used by the event source
+.VS
+current call to \fBTcl_ServiceEvent\fR; this is used by the event source
+.VE
to return immediately if its events are not relevant.
.PP
It is up to \fIproc\fR to handle the event, typically by invoking
@@ -307,7 +361,9 @@ Once the event source has finished handling the event it returns 1
to indicate that the event can be removed from the queue.
If for some reason the event source decides that the event cannot
be handled at this time, it may return 0 to indicate that the event
-should be deferred for processing later; in this case \fBTcl_DoOneEvent\fR
+.VS
+should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR
+.VE
will go on to the next event in the queue and attempt to service it.
There are several reasons why an event source might defer an event.
One possibility is that events of this type are excluded by the
@@ -318,53 +374,164 @@ Another example of deferring events happens in Tk if
\fBTk_RestrictEvents\fR has been invoked to defer certain kinds
of window events.
.PP
-When \fIproc\fR returns 1, \fBTcl_DoOneEvent\fR will remove the
+.VS
+When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
event from the event queue and free its storage.
Note that the storage for an event must be allocated by
-.VS
the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
-.VE
before calling \fBTcl_QueueEvent\fR, but it
-will be freed by \fBTcl_DoOneEvent\fR, not by the event source.
+will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
+.PP
+\fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
+events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
+for each event in the queue, deleting those for with the procedure
+returns 1. Events for which the procedure returns 0 are left in the
+queue. \fIProc\fR should match the following prototype:
+.CS
+typedef int Tcl_EventDeleteProc(
+ Tcl_Event *\fIevPtr\fR,
+ ClientData \fIclientData\fR);
+.CE
+The \fIclientData\fR argument will be the same as the \fIclientData\fR
+argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
+private information managed by the event source. The \fIevPtr\fR will
+point to the next event in the queue.
+.VE
.SH "CREATING A NEW NOTIFIER"
.PP
-The notifier consists of all the procedures described in this
-manual entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR.
-Most of these procedures are generic, in that they are the
-same for all platforms. However, four of the procedures are
-platform-dependent: \fBTcl_WatchFile\fR,
-\fBTcl_FileReady\fR, \fBTcl_WaitForEvent\fR, and \fBTcl_Sleep\fR.
-To support a new platform, you must write new versions of these
+The notifier consists of all the procedures described in this manual
+entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
+.VS
+available on all platforms, and \fBTcl_CreateFileHandler\fR and
+\fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these
+procedures are generic, in that they are the same for all notifiers.
+However, five of the procedures are notifier-dependent:
+\fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
+\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR. To
+support a new platform or to integrate Tcl with an
+application-specific event loop, you must write new versions of these
procedures.
-\fBTcl_WatchFile\fR and \fBTcl_FileReady\fR have already been
-described previously in this document, and \fBTcl_Sleep\fR
-is described in its own manual entry.
.PP
-\fBTcl_WaitForEvent\fR is the lowest-level procedure in the
-notifier; it is responsible for waiting for an ``interesting''
-event to occur or for a given time to elapse.
-Before \fBTcl_WaitForEvent\fR is invoked, each of the event
-sources' setup procedure will have been invoked; the setup
-procedures will have provided information about what to wait
-for by invoking procedures like \fBTcl_WatchFile\fR.
-The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR gives
-the maximum time to block for an event, based on calls to
-\fBTcl_SetMaxBlockTime\fR made by setup procedures and
-on other information (such as the \fBTCL_DONT_WAIT\fR bit in \fIflags\fR).
-\fBTcl_WaitForEvent\fR uses information saved by \fBTcl_WatchFile\fR,
-plus the \fItimePtr\fR argument to decide what to wait for
-and how long to block.
-It returns TCL_OK as soon as one of the specified events has occurred
-or the given amount of time has elapsed.
-However, if there are no event handlers (neither \fBTcl_WatchFile\fR nor
-\fBTcl_SetMaxBlockTime\fR has been called since the last call to
-\fBTcl_WaitForEvent\fR), so that the procedure would block forever,
-then it returns immediately with a result of TCL_ERROR.
+\fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
+it is responsible for waiting for an ``interesting'' event to occur or
+for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked,
+each of the event sources' setup procedure will have been invoked.
+The \fItimePtr\fR argument to
+\fBTcl_WaitForEvent\fR gives the maximum time to block for an event,
+based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures
+and on other information (such as the \fBTCL_DONT_WAIT\fR bit in
+\fIflags\fR).
+.PP
+Ideally, \fBTcl_WaitForEvent\fR should only wait for an event
+to occur; it should not actually process the event in any way.
+Later on, the
+event sources will process the raw events and create Tcl_Events on
+the event queue in their \fIcheckProc\fR procedures.
+However, on some platforms (such as Windows) this isn't possible;
+events may be processed in \fBTcl_WaitForEvent\fR, including queuing
+Tcl_Events and more (for example, callbacks for native widgets may be
+invoked). The return value from \fBTcl_WaitForEvent\fR must be either
+0, 1, or \-1. On platforms such as Windows where events get processed in
+\fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
+events still pending that haven't been processed. This is a sign to the
+caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
+pending events to be processed. A 0 return value means that calling
+\fBTcl_WaitForEvent\fR again will not have any effect: either this is a
+platform where \fBTcl_WaitForEvent\fR only waits without doing any event
+processing, or \fBTcl_WaitForEvent\fR knows for sure that there are no
+additional events to process (e.g. it returned because the time
+elapsed). Finally, a return value of \-1 means that the event loop is
+no longer operational and the application should probably unwind and
+terminate. Under Windows this happens when a WM_QUIT message is received;
+under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
+forever because there were no active event sources and the timeout was
+infinite.
+.PP
+If the notifier will be used with an external event loop, then it must
+also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is
+invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
+time has been reduced. \fBTcl_SetTimer\fR should arrange for the
+external event loop to invoke \fBTcl_ServiceAll\fR after the specified
+interval even if no events have occurred. This interface is needed
+because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
+event loop. If the
+notifier will only be used from \fBTcl_DoOneEvent\fR, then
+\fBTcl_SetTimer\fR need not do anything.
+.PP
+On Unix systems, the file event source also needs support from the
+notifier. The file event source consists of the
+\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
+procedures, which are described elsewhere.
+.PP
+The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described
+elsewhere.
.PP
The easiest way to create a new notifier is to look at the code
-for an existing notifier, such as the files \fBgeneric/tclNotify.c\fR
-and \fBunix/tclUnixNotfy.c\fR.
+for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
+or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
+
+.SH "EXTERNAL EVENT LOOPS"
+.PP
+The notifier interfaces are designed so that Tcl can be embedded into
+applications that have their own private event loops. In this case,
+the application does not call \fBTcl_DoOneEvent\fR except in the case
+of recursive event loops such as calls to the Tcl commands \fBupdate\fR
+or \fBvwait\fR. Most of the time is spent in the external event loop
+of the application. In this case the notifier must arrange for the
+external event loop to call back into Tcl when something
+happens on the various Tcl event sources. These callbacks should
+arrange for appropriate Tcl events to be placed on the Tcl event queue.
+.PP
+Because the external event loop is not calling \fBTcl_DoOneEvent\fR on
+a regular basis, it is up to the notifier to arrange for
+\fBTcl_ServiceEvent\fR to be called whenever events are pending on the
+Tcl event queue. The easiest way to do this is to invoke
+\fBTcl_ServiceAll\fR at the end of each callback from the external
+event loop. This will ensure that all of the event sources are
+polled, any queued events are serviced, and any pending idle handlers
+are processed before returning control to the application. In
+addition, event sources that need to poll for events can call
+\fBTcl_SetMaxBlockTime\fR to force the external event loop to call
+Tcl even if no events are available on the system event queue.
+.PP
+As a side effect of processing events detected in the main external
+event loop, Tcl may invoke \fBTcl_DoOneEvent\fR to start a recursive event
+loop in commands like \fBvwait\fR. \fBTcl_DoOneEvent\fR will invoke
+the external event loop, which will result in callbacks as described
+in the preceding paragraph, which will result in calls to
+\fBTcl_ServiceAll\fR. However, in these cases it is undesirable to
+service events in \fBTcl_ServiceAll\fR. Servicing events there is
+unnecessary because control will immediately return to the
+external event loop and hence to \fBTcl_DoOneEvent\fR, which can
+service the events itself. Furthermore, \fBTcl_DoOneEvent\fR is
+supposed to service only a single event, whereas \fBTcl_ServiceAll\fR
+normally services all pending events. To handle this situation,
+\fBTcl_DoOneEvent\fR sets a flag for \fBTcl_ServiceAll\fR
+that causes it to return without servicing any events.
+This flag is called the \fIservice mode\fR;
+\fBTcl_DoOneEvent\fR restores it to its previous value before it returns.
+.PP
+In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR
+to service events
+even when it has been invoked from \fBTcl_DoOneEvent\fR. This happens
+when there is yet another recursive event loop invoked via an
+event handler called by \fBTcl_DoOneEvent\fR (such as one that is
+part of a native widget). In this case, \fBTcl_DoOneEvent\fR may not
+have a chance to service events so \fBTcl_ServiceAll\fR must service
+them all. Any recursive event loop that calls an external event
+loop rather than \fBTcl_DoOneEvent\fR must reset the service mode so
+that all events get processed in \fBTcl_ServiceAll\fR. This is done
+by invoking the \fBTcl_SetServiceMode\fR procedure. If
+\fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_NONE\fR, then calls
+to \fBTcl_ServiceAll\fR will return immediately without processing any
+events. If \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_ALL\fR,
+then calls to \fBTcl_ServiceAll\fR will behave normally.
+\fBTcl_SetServiceMode\fR returns the previous value of the service
+mode, which should be restored when the recursive loop exits.
+\fBTcl_GetServiceMode\fR returns the current value of the service
+mode.
+.VE
.SH KEYWORDS
-block time, event notifier, event queue, event sources, file events
+event, notifier, event queue, event sources, file events, timer, idle, service mode
diff --git a/contrib/tcl/doc/ObjSetVar.3 b/contrib/tcl/doc/ObjSetVar.3
new file mode 100644
index 000000000000..49dd82d09acd
--- /dev/null
+++ b/contrib/tcl/doc/ObjSetVar.3
@@ -0,0 +1,162 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) ObjSetVar.3 1.6 97/05/19 17:35:44
+'\"
+.so man.macros
+.TH Tcl_ObjSetVar2 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_ObjSetVar2, Tcl_ObjGetVar2 \- manipulate Tcl variables
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *newValuePtr
+.AP Tcl_Interp *interp in
+Interpreter containing variable.
+.AP Tcl_Obj *part1Ptr in
+Points to a Tcl object containing the variable's name.
+The name may include a series of \fB::\fR namespace qualifiers
+to specify a variable in a particular namespace.
+May refer to a scalar variable or an element of an array variable.
+.AP Tcl_Obj *part2Ptr in
+If non-NULL, points to an object containing the name of an element
+within an array and \fIpart1Ptr\fR must refer to an array variable.
+.AP Tcl_Obj *newValuePtr in
+Points to a Tcl object containing the new value for the variable.
+.AP int flags in
+OR-ed combination of bits providing additional information for
+operation. See below for valid values.
+.BE
+
+.SH DESCRIPTION
+.PP
+These two procedures may be used to read and modify
+Tcl variables from C code.
+\fBTcl_ObjSetVar2\fR will create a new variable or modify an existing one.
+It sets the specified variable to
+the object referenced by \fInewValuePtr\fR
+and returns a pointer to the object which is the variable's new value.
+The returned object may not be the same one
+referenced by \fInewValuePtr\fR;
+this might happen because variable traces may modify the variable's value.
+The reference count for the variable's old value is decremented
+and the reference count for its new value is incremented.
+If the new value for the variable
+is not the same one referenced by \fInewValuePtr\fR
+(perhaps as a result of a variable trace),
+then \fInewValuePtr\fR's reference count is left unchanged.
+The reference count for the returned object is not incremented
+to reflect the returned reference.
+If the caller needs to keep a reference to the object,
+say in a data structure,
+it must increment its reference count using \fBTcl_IncrRefCount\fR.
+If an error occurs in setting the variable
+(e.g. an array variable is referenced
+without giving an index into the array),
+then NULL is returned.
+.PP
+The variable name specified to \fBTcl_ObjSetVar2\fR consists of two parts.
+\fIpart1Ptr\fR contains the name of a scalar or array variable.
+If \fIpart2Ptr\fR is NULL, the variable must be a scalar.
+If \fIpart2Ptr\fR is not NULL,
+it contains the name of an element in the array named by \fIpart2Ptr\fR.
+As a special case, if the flag TCL_PARSE_PART1 is specified,
+\fIpart1Ptr\fR may contain both an array and an element name:
+if the name contains an open parenthesis and ends with a
+close parenthesis, then the value between the parentheses is
+treated as an element name (which can have any string value) and
+the characters before the first open
+parenthesis are treated as the name of an array variable.
+If the flag TCL_PARSE_PART1 is given,
+\fIpart2Ptr\fR should be NULL since the array and element names
+are taken from \fIpart2Ptr\fR.
+.PP
+The \fIflags\fR argument may be used to specify any of several
+options to the procedures.
+It consists of an OR-ed combination of any of the following
+bits:
+.TP
+\fBTCL_GLOBAL_ONLY\fR
+Under normal circumstances the procedures look up variables as follows:
+If a procedure call is active in \fIinterp\fR,
+a variable is looked up at the current level of procedure call.
+Otherwise, a variable is looked up first in the current namespace,
+then in the global namespace.
+However, if this bit is set in \fIflags\fR then the variable
+is looked up only in the global namespace
+even if there is a procedure call active.
+If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
+\fBTCL_GLOBAL_ONLY\fR is ignored.
+.TP
+\fBTCL_NAMESPACE_ONLY\fR
+Under normal circumstances the procedures look up variables as follows:
+If a procedure call is active in \fIinterp\fR,
+a variable is looked up at the current level of procedure call.
+Otherwise, a variable is looked up first in the current namespace,
+then in the global namespace.
+However, if this bit is set in \fIflags\fR then the variable
+is looked up only in the current namespace
+even if there is a procedure call active.
+.TP
+\fBTCL_LEAVE_ERR_MSG\fR
+If an error is returned and this bit is set in \fIflags\fR, then
+an error message will be left in the interpreter's result,
+where it can be retrieved with \fBTcl_GetObjResult\fR
+or \fBTcl_GetStringResult\fR.
+If this flag bit isn't set then no error message is left
+and the interpreter's result will not be modified.
+.TP
+\fBTCL_APPEND_VALUE\fR
+If this bit is set then \fInewValuePtr\fR is appended to the current
+value, instead of replacing it.
+If the variable is currently undefined, then this bit is ignored.
+.TP
+\fBTCL_LIST_ELEMENT\fR
+If this bit is set, then \fInewValuePtr\fR is converted to a valid
+Tcl list element before setting (or appending to) the variable.
+A separator space is appended before the new list element unless
+the list element is going to be the first element in a list or
+sublist (i.e. the variable's current value is empty, or contains
+the single character ``{'', or ends in `` }'').
+.TP
+\fBTCL_PARSE_PART1\fR
+If this bit is set,
+then \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR
+will parse \fIpart1Ptr\fR
+to obtain both an array name and an element name.
+If the name in \fIpart1Ptr\fR contains an open parenthesis
+and ends with a close parenthesis,
+the name is treated as the name of an element of an array;
+otherwise, the name in \fIpart1Ptr\fR
+is interpreted as the name of a scalar variable.
+When this bit is set,
+\fIpart2Ptr\fR is ignored.
+.PP
+\fBTcl_ObjGetVar2\fR returns the value of the specified variable.
+Its arguments are treated the same way as those for \fBTcl_ObjSetVar2\fR.
+It returns a pointer to the object which is the variable's value.
+The reference count for the returned object is not incremented.
+If the caller needs to keep a reference to the object,
+say in a data structure,
+it must increment the reference count using \fBTcl_IncrRefCount\fR.
+If an error occurs in setting the variable
+(e.g. an array variable is referenced
+without giving an index into the array),
+then NULL is returned.
+
+.SH "SEE ALSO"
+Tcl_GetObjResult, Tcl_GetStringResult, Tcl_GetVar, Tcl_GetVar2, Tcl_SetVar, Tcl_SetVar2, Tcl_TraceVar, Tcl_UnsetVar, Tcl_UnsetVar2
+
+.SH KEYWORDS
+array, interpreter, object, scalar, set, unset, variable
diff --git a/contrib/tcl/doc/Object.3 b/contrib/tcl/doc/Object.3
new file mode 100644
index 000000000000..e564de9cd907
--- /dev/null
+++ b/contrib/tcl/doc/Object.3
@@ -0,0 +1,336 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) @(#) Object.3 1.9 97/06/13 18:36:20
+'\"
+.so man.macros
+.TH Tcl_Obj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared \- manipulate Tcl objects
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewObj\fR()
+.sp
+Tcl_Obj *
+\fBTcl_DuplicateObj\fR(\fIobjPtr\fR)
+.sp
+\fBTcl_IncrRefCount\fR(\fIobjPtr\fR)
+.sp
+\fBTcl_DecrRefCount\fR(\fIobjPtr\fR)
+.sp
+int
+\fBTcl_IsShared\fR(\fIobjPtr\fR)
+.sp
+\fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Obj *objPtr in
+.AP Tcl_Obj *objPtr in
+Points to an object;
+must have been the result of a previous call to \fBTcl_NewObj\fR.
+.BE
+
+.SH INTRODUCTION
+.PP
+This man page presents an overview of Tcl objects and how they are used.
+It also describes generic procedures for managing Tcl objects.
+These procedures are used to create and copy objects,
+and increment and decrement the count of references (pointers) to objects.
+The procedures are used in conjunction with ones
+that operate on specific types of objects such as
+\fBTcl_GetIntFromObj\fR and \fBTcl_ListObjAppendElement\fR.
+The individual procedures are described along with the data structures
+they manipulate.
+.PP
+Tcl's \fIdual-ported\fR objects provide a general-purpose mechanism
+for storing and exchanging Tcl values.
+They largely replace the use of strings in Tcl.
+For example, they are used to store variable values,
+command arguments, command results, and scripts.
+Tcl objects behave like strings but also hold an internal representation
+that can be manipulated more efficiently.
+For example, a Tcl list is now represented as an object
+that holds the list's string representation
+as well as an array of pointers to the objects for each list element.
+Dual-ported objects avoid most runtime type conversions.
+They also improve the speed of many operations
+since an appropriate representation is immediately available.
+The compiler itself uses Tcl objects to
+cache the instruction bytecodes resulting from compiling scripts.
+.PP
+The two representations are a cache of each other and are computed lazily.
+That is, each representation is only computed when necessary,
+it is computed from the other representation,
+and, once computed, it is saved.
+In addition, a change in one representation invalidates the other one.
+As an example, a Tcl program doing integer calculations can
+operate directly on a variable's internal machine integer
+representation without having to constantly convert
+between integers and strings.
+Only when it needs a string representing the variable's value,
+say to print it,
+will the program regenerate the string representation from the integer.
+Although objects contain an internal representation,
+their semantics are defined in terms of strings:
+an up-to-date string can always be obtained,
+and any change to the object will be reflected in that string
+when the object's string representation is fetched.
+Because of this representation invalidation and regeneration,
+it is dangerous for extension writers to access
+\fBTcl_Obj\fR fields directly.
+It is better to access Tcl_Obj information using
+procedures like \fBTcl_GetStringFromObj\fR.
+.PP
+Objects are allocated on the heap
+and are referenced using a pointer to their \fBTcl_Obj\fR structure.
+Objects are shared as much as possible.
+This significantly reduces storage requirements
+because some objects such as long lists are very large.
+Also, most Tcl values are only read and never modified.
+This is especially true for procedure arguments,
+which can be shared between the caller and the called procedure.
+Assignment and argument binding is done by
+simply assigning a pointer to the value.
+Reference counting is used to determine when it is safe to
+reclaim an object's storage.
+.PP
+Tcl objects are typed.
+An object's internal representation is controlled by its type.
+Seven types are predefined in the Tcl core
+including integer, double, list, and bytecode.
+Extension writers can extend the set of types
+by using the procedure \fBTcl_RegisterObjType\fR .
+
+.SH "THE TCL_OBJ STRUCTURE"
+.PP
+Each Tcl object is represented by a \fBTcl_Obj\fR structure
+which is defined as follows.
+.CS
+typedef struct Tcl_Obj {
+ int \fIrefCount\fR;
+ char *\fIbytes\fR;
+ int \fIlength\fR;
+ Tcl_ObjType *\fItypePtr\fR;
+ union {
+ long \fIlongValue\fR;
+ double \fIdoubleValue\fR;
+ VOID *\fIotherValuePtr\fR;
+ struct {
+ VOID *\fIptr1\fR;
+ VOID *\fIptr2\fR;
+ } \fItwoPtrValue\fR;
+ } \fIinternalRep\fR;
+} Tcl_Obj;
+.CE
+The \fIbytes\fR and the \fIlength\fR members together hold
+an object's string representation,
+which is a \fIcounted\fR or \fIbinary string\fR
+that may contain binary data with embedded null bytes.
+\fIbytes\fR points to the first byte of the string representation.
+The \fIlength\fR member gives the number of bytes.
+The byte array must always have a null after the last byte,
+at offset \fIlength\fR;
+this allows string representations that do not contain nulls
+to be treated as conventional null-terminated C strings.
+C programs use \fBTcl_GetStringFromObj\fR to get
+an object's string representation.
+If \fIbytes\fR is NULL,
+the string representation is invalid.
+.PP
+An object's type manages its internal representation.
+The member \fItypePtr\fR points to the Tcl_ObjType structure
+that describes the type.
+If \fItypePtr\fR is NULL,
+the internal representation is invalid.
+.PP
+The \fIinternalRep\fR union member holds
+an object's internal representation.
+This is either a (long) integer, a double-precision floating point number,
+a pointer to a value containing additional information
+needed by the object's type to represent the object,
+or two arbitrary pointers.
+.PP
+The \fIrefCount\fR member is used to tell when it is safe to free
+an object's storage.
+It holds the count of active references to the object.
+Maintaining the correct reference count is a key responsibility
+of extension writers.
+Reference counting is discussed below
+in the section \fBSTORAGE MANAGEMENT OF OBJECTS\fR.
+.PP
+Although extension writers can directly access
+the members of a Tcl_Obj structure,
+it is much better to use the appropriate procedures and macros.
+For example, extension writers should never
+read or update \fIrefCount\fR directly;
+they should use macros such as
+\fBTcl_IncrRefCount\fR and \fBTcl_IsShared\fR instead.
+.PP
+A key property of Tcl objects is that they hold two representations.
+An object typically starts out containing only a string representation:
+it is untyped and has a NULL \fItypePtr\fR.
+An object containing an empty string or a copy of a specified string
+is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively.
+An object's string value is gotten with \fBTcl_GetStringFromObj\fR
+and changed with \fBTcl_SetStringObj\fR.
+If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR
+that requires a specific internal representation,
+the procedure will create one and set the object's \fItypePtr\fR.
+The internal representation is computed from the string representation.
+An object's two representations are duals of each other:
+changes made to one are reflected in the other.
+For example, \fBTcl_ListObjReplace\fR will modify an object's
+internal representation and the next call to \fBTcl_GetStringFromObj\fR
+will reflect that change.
+.PP
+Representations are recomputed lazily for efficiency.
+A change to one representation made by a procedure
+such as \fBTcl_ListObjReplace\fR is not reflected immediately
+in the other representation.
+Instead, the other representation is marked invalid
+so that it is only regenerated if it is needed later.
+Most C programmers never have to be concerned with how this is done
+and simply use procedures such as \fBTcl_GetBooleanFromObj\fR or
+\fBTcl_ListObjIndex\fR.
+Programmers that implement their own object types
+must check for invalid representations
+and mark representations invalid when necessary.
+The procedure \fBTcl_InvalidateStringRep\fR is used
+to mark an object's string representation invalid and to
+free any storage associated with the old string representation.
+.PP
+Objects usually remain one type over their life,
+but occasionally an object must be converted from one type to another.
+For example, a C program might build up a string in an object
+with repeated calls to \fBTcl_StringObjAppend\fR,
+and then call \fBTcl_ListObjIndex\fR to extract a list element from
+the object.
+The same object holding the same string value
+can have several different internal representations
+at different times.
+Extension writers can also force an object to be converted from one type
+to another using the \fBTcl_ConvertToType\fR procedure.
+Only programmers that create new object types need to be concerned
+about how this is done.
+A procedure defined as part of the object type's implementation
+creates a new internal representation for an object
+and changes its \fItypePtr\fR.
+See the man page for \fBTcl_RegisterObjType\fR
+to see how to create a new object type.
+
+.SH "EXAMPLE OF THE LIFETIME OF AN OBJECT"
+.PP
+As an example of the lifetime of an object,
+consider the following sequence of commands:
+.CS
+\fBset x 123\fR
+.CE
+This assigns to \fIx\fR an untyped object whose
+\fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3.
+The object's \fItypePtr\fR member is NULL.
+.CS
+\fBputs "x is $x"\fR
+.CE
+\fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL)
+and is fetched for the command.
+.CS
+\fBincr x\fR
+.CE
+The \fBincr\fR command first gets an integer from \fIx\fR's object
+by calling \fBTcl_GetIntFromObj\fR.
+This procedure checks whether the object is already an integer object.
+Since it is not, it converts the object
+by setting the object's \fIinternalRep.longValue\fR member
+to the integer \fB123\fR
+and setting the object's \fItypePtr\fR
+to point to the integer Tcl_ObjType structure.
+Both representations are now valid.
+\fBincr\fR increments the object's integer internal representation
+then invalidates its string representation
+(by calling \fBTcl_InvalidateStringRep\fR)
+since the string representation
+no longer corresponds to the internal representation.
+.CS
+\fBputs "x is now $x"\fR
+.CE
+The string representation of \fIx\fR's object is needed
+and is recomputed.
+The string representation is now \fB124\fR.
+and both representations are again valid.
+
+.SH "STORAGE MANAGEMENT OF OBJECTS"
+.PP
+Tcl objects are allocated on the heap and are shared as much as possible
+to reduce storage requirements.
+Reference counting is used to determine when an object is
+no longer needed and can safely be freed.
+An object just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
+has \fIrefCount\fR 0.
+The macro \fBTcl_IncrRefCount\fR increments the reference count
+when a new reference to the object is created.
+The macro \fBTcl_DecrRefCount\fR decrements the count
+when a reference is no longer needed and,
+if the object's reference count drops to zero, frees its storage.
+An object shared by different code or data structures has
+\fIrefCount\fR greater than 1.
+Incrementing an object's reference count ensures that
+it won't be freed too early or have its value change accidently.
+.PP
+As an example, the bytecode interpreter shares argument objects
+between calling and called Tcl procedures to avoid having to copy objects.
+It assigns the call's argument objects to the procedure's
+formal parameter variables.
+In doing so, it calls \fBTcl_IncrRefCount\fR to increment
+the reference count of each argument since there is now a new
+reference to it from the formal parameter.
+When the called procedure returns,
+the interpreter calls \fBTcl_DecrRefCount\fR to decrement
+each argument's reference count.
+When an object's reference count drops to zero,
+\fBTcl_DecrRefCount\fR reclaims its storage.
+Most command procedures do not have to be concerned about
+reference counting since they use an object's value immediately
+and don't retain a pointer to the object after they return.
+However, if they do retain a pointer to an object in a data structure,
+they must be careful to increment its reference count
+since the retained pointer is a new reference.
+.PP
+Command procedures that directly modify objects
+such as those for \fBlappend\fR and \fBlinsert\fR must be careful to
+copy a shared object before changing it.
+They must first check whether the object is shared
+by calling \fBTcl_IsShared\fR.
+If the object is shared they must copy the object
+by using \fBTcl_DuplicateObj\fR;
+this returns a new duplicate of the original object
+that has \fIrefCount\fR 1.
+If the object is not shared,
+the command procedure "owns" the object and can safely modify it directly.
+For example, the following code appears in the command procedure
+that implements \fBlinsert\fR.
+This procedure modifies the list object passed to it in \fIobjv[1]\fR
+by inserting \fIobjc-3\fR new elements before \fIindex\fR.
+.CS
+listPtr = objv[1];
+if (Tcl_IsShared(listPtr)) {
+ listPtr = Tcl_DuplicateObj(listPtr);
+}
+result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3]));
+.CE
+As another example, \fBincr\fR's command procedure
+must check whether the variable's object is shared before
+incrementing the integer in its internal representation.
+If it is shared, it needs to duplicate the object
+in order to avoid accidently changing values in other data structures.
+
+.SH "SEE ALSO"
+Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType
+
+.SH KEYWORDS
+internal representation, object, object creation, object type, reference counting, string representation, type conversion
diff --git a/contrib/tcl/doc/ObjectType.3 b/contrib/tcl/doc/ObjectType.3
new file mode 100644
index 000000000000..515d85c66a51
--- /dev/null
+++ b/contrib/tcl/doc/ObjectType.3
@@ -0,0 +1,198 @@
+'\"
+'\" Copyright (c) 1996-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.
+'\"
+'\" SCCS: @(#) ObjectType.3 1.8 97/04/30 15:42:29
+'\"
+.so man.macros
+.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl object types
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_RegisterObjType\fR(\fItypePtr\fR)
+.sp
+Tcl_ObjType *
+\fBTcl_GetObjType\fR(\fItypeName\fR)
+.sp
+int
+\fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR)
+.sp
+int
+\fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
+.SH ARGUMENTS
+.AS Tcl_ObjType *typeName in
+.AP Tcl_ObjType *typePtr in
+Points to the structure containing information about the Tcl object type.
+This storage must must live forever,
+typically by being statically allocated.
+.AP char *typeName in
+The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tcl_Obj *objPtr in
+For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which
+it appends the name of each object type as a list element.
+For \fBTcl_ConvertToType\fR, this points to an object that
+must have been the result of a previous call to \fBTcl_NewObj\fR.
+.BE
+
+.SH DESCRIPTION
+.PP
+The procedures in this man page manage Tcl object types.
+The are used to register new object types,
+look up types,
+and force conversions from one type to another.
+.PP
+\fBTcl_RegisterObjType\fR registers a new Tcl object type
+in the table of all object types supported by Tcl.
+The argument \fItypePtr\fR points to a Tcl_ObjType structure that
+describes the new type by giving its name
+and by supplying pointers to four procedures
+that implement the type.
+If the type table already containes a type
+with the same name as in \fItypePtr\fR,
+it is replaced with the new type.
+The Tcl_ObjType structure is described
+in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
+.PP
+\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
+with name \fItypeName\fR.
+It returns NULL if no type with that name is registered.
+.PP
+\fBTcl_AppendAllObjTypes\fR appends the name of each object type
+as a list element onto the Tcl object referenced by \fIobjPtr\fR.
+The return value is \fBTCL_OK\fR unless there was an error
+converting \fIobjPtr\fR to a list object;
+in that case \fBTCL_ERROR\fR is returned.
+.PP
+\fBTcl_ConvertToType\fR converts an object from one type to another
+if possible.
+It creates a new internal representation for \fIobjPtr\fR
+appropriate for the target type \fItypePtr\fR
+and sets its \fItypePtr\fR member to that type.
+Any internal representation for \fIobjPtr\fR's old type is freed.
+If an error occurs during conversion, it returns \fBTCL_ERROR\fR
+and leaves an error message in the result object for \fIinterp\fR
+unless \fIinterp\fR is NULL.
+Otherwise, it returns \fBTCL_OK\fR.
+Passing a NULL \fIinterp\fR allows this procedure to be used
+as a test whether the conversion can be done (and in fact was done).
+
+.SH "THE TCL_OBJTYPE STRUCTURE"
+.PP
+Extension writers can define new object types by defining four
+procedures,
+initializing a Tcl_ObjType structure to describe the type,
+and calling \fBTcl_RegisterObjType\fR.
+The \fBTcl_ObjType\fR structure is defined as follows:
+.CS
+typedef struct Tcl_ObjType {
+ char *\fIname\fR;
+ Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
+ Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
+ Tcl_UpdateStringProc *\fIupdateStringProc\fR;
+ Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
+} Tcl_ObjType;
+.CE
+.PP
+The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
+Extension writers can look up an object type using its name
+with the \fBTcl_GetObjType\fR procedure.
+The remaining four members are pointers to procedures
+called by the generic Tcl object code:
+.PP
+The \fIsetFromAnyProc\fR member contains the address of a function
+called to create a valid internal representation
+from an object's string representation.
+.CS
+typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
+.CE
+If an internal representation can't be created from the string,
+it returns \fBTCL_ERROR\fR and puts a message
+describing the error in the result object for \fIinterp\fR
+unless \fIinterp\fR is NULL.
+If \fIsetFromAnyProc\fR is successful,
+it stores the new internal representation,
+sets \fIobjPtr\fR's \fItypePtr\fR member to point to
+\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
+Before setting the new internal representation,
+the \fIsetFromAnyProc\fR must free any internal representation
+of \fIobjPtr\fR's old type;
+it does this by calling the old type's \fIfreeIntRepProc\fR
+if it is not NULL.
+As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type
+gets an up-to-date string representation for \fIobjPtr\fR
+by calling \fBTcl_GetStringFromObj\fR.
+It parses the string to obtain an integer and,
+if this succeeds,
+stores the integer in \fIobjPtr\fR's internal representation
+and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
+Tcl_ObjType structure.
+.PP
+The \fIupdateStringProc\fR member contains the address of a function
+called to create a valid string representation
+from an object's internal representation.
+.CS
+typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
+.CE
+\fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
+It must always set \fIbytes\fR non-NULL before returning.
+We require the string representation's byte array
+to have a null after the last byte, at offset \fIlength\fR;
+this allows string representations that do not contain null bytes
+to be treated as conventional null character-terminated C strings.
+Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR.
+Note that \fIupdateStringProc\fRs must allocate
+enough storage for the string's bytes and the terminating null byte.
+The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
+builds an array of strings for each element object
+and then calls \fBTcl_Merge\fR
+to construct a string with proper Tcl list structure.
+It stores this string as the list object's string representation.
+.PP
+The \fIdupIntRepProc\fR member contains the address of a function
+called to copy an internal representation from one object to another.
+.CS
+typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
+.CE
+\fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
+internal representation.
+Before the call,
+\fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
+\fIsrcPtr\fR's object type determines what
+copying its internal representation means.
+For example, the \fIdupIntRepProc\fR for the Tcl integer type
+simply copies an integer.
+The builtin list type's \fIdupIntRepProc\fR
+allocates a new array that points at the original element objects;
+the elements are shared between the two lists
+(and their reference counts are incremented to reflect the new references).
+.PP
+The \fIfreeIntRepProc\fR member contains the address of a function
+that is called when an object is freed.
+.CS
+typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
+.CE
+The \fIfreeIntRepProc\fR function can deallocate the storage
+for the object's internal representation
+and do other type-specific processing necessary when an object is freed.
+For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
+that points to an array of pointers to each element in the list.
+The list type's \fIfreeIntRepProc\fR decrements
+the reference count for each element object
+(since the list will no longer refer to those objects),
+then deallocates the storage for the array of pointers.
+The \fIfreeIntRepProc\fR member can be set to NULL
+to indicate that the internal representation does not require freeing.
+
+.SH "SEE ALSO"
+Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
+
+.SH KEYWORDS
+internal representation, object, object type, string representation, type conversion
diff --git a/contrib/tcl/doc/OpenFileChnl.3 b/contrib/tcl/doc/OpenFileChnl.3
index c17cc64d16fa..09768d931223 100644
--- a/contrib/tcl/doc/OpenFileChnl.3
+++ b/contrib/tcl/doc/OpenFileChnl.3
@@ -1,16 +1,16 @@
'\"
-'\" Copyright (c) 1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1996-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.
'\"
-'\" SCCS: @(#) OpenFileChnl.3 1.27 96/03/22 14:55:07
+'\" SCCS: @(#) OpenFileChnl.3 1.39 97/05/09 18:14:49
.so man.macros
-.TH Tcl_OpenFileChannel 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_GetChannelOption, Tcl_SetChannelOption \- buffered I/O facilities using channels
+Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_GetChannelOption, Tcl_SetChannelOption \- buffered I/O facilities using channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -22,9 +22,11 @@ Tcl_Channel
.sp
Tcl_Channel
\fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR)
+.VS
.sp
Tcl_Channel
-\fBTcl_MakeFileChannel\fR(\fIinOsFile, outOsFile, readOrWrite\fR)
+\fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR)
+.VE
.sp
Tcl_Channel
\fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
@@ -45,6 +47,9 @@ int
\fBTcl_Gets\fR(\fIchannel, lineRead\fR)
.sp
int
+\fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
+.sp
+int
\fBTcl_Write\fR(\fIchannel, buf, toWrite\fR)
.sp
int
@@ -102,14 +107,14 @@ as the standard input of the invoking process; likewise for
then the pipe can redirect stdio handles to override the stdio handles for
which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.
If it is set, then such redirections cause an error.
-.AP ClientData inOsFile in
-Operating system specific handle for input from a file. For Unix this is a
-file descriptor, for Windows it is a HANDLE, etc.
-.AP ClientData outOsFile in
-Operating system specific handle for output to a file.
+.VS
+.AP ClientData handle in
+Operating system specific handle for I/O to a file. For Unix this is a
+file descriptor, for Windows it is a HANDLE.
.AP int readOrWrite in
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
-which of \fIinOsFile\fR and \fIoutOsFile\fR contains a valid value.
+what operations are valid on \fIhandle\fR.
+.VE
.AP int *modePtr out
Points at an integer variable that will receive an OR-ed combination of
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
@@ -120,11 +125,21 @@ from a procedure such as \fBTcl_OpenFileChannel\fR.
.AP char *buf in
An array of bytes in which to store channel input, or from which
to read channel output.
+.AP int len in
+The length of the input or output.
+.AP int atEnd in
+If nonzero, store the input at the end of the input queue, otherwise store
+it at the head of the input queue.
.AP int toRead in
The number of bytes to read from the channel.
.AP Tcl_DString *lineRead in
A pointer to a Tcl dynamic string in which to store the line read from the
-channel. Must have been initialized by the caller.
+channel. Must have been initialized by the caller. The line read
+will be appended to any data already in the dynamic string.
+.AP Tcl_Obj *linePtrObj in
+A pointer to a Tcl object in which to store the line read from the
+channel. The line read will be appended to the current value of the
+object.
.AP int toWrite in
The number of bytes to read from \fIbuf\fR and output to the channel.
.AP int offset in
@@ -176,6 +191,12 @@ returns NULL and records a POSIX error code that can be
retrieved with \fBTcl_GetErrno\fR.
In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
leaves an error message in \fIinterp->result\fR after any error.
+.PP
+The newly created channel is not registered in the supplied interpreter; to
+register it, use \fBTcl_RegisterChannel\fR, described below.
+If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+previously closed, the act of creating the new channel also assigns it as a
+replacement for the standard channel.
.SH TCL_OPENCOMMANDCHANNEL
.PP
@@ -208,11 +229,22 @@ returns NULL and records a POSIX error code that can be retrieved with
\fBTcl_GetErrno\fR.
In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
\fIinterp->result\fR if \fIinterp\fR is not NULL.
+.PP
+The newly created channel is not registered in the supplied interpreter; to
+register it, use \fBTcl_RegisterChannel\fR, described below.
+If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+previously closed, the act of creating the new channel also assigns it as a
+replacement for the standard channel.
.SH TCL_MAKEFILECHANNEL
.PP
\fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
platform-specific, file handle.
+The newly created channel is not registered in the supplied interpreter; to
+register it, use \fBTcl_RegisterChannel\fR, described below.
+If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+previously closed, the act of creating the new channel also assigns it as a
+replacement for the standard channel.
.SH TCL_GETCHANNEL
.PP
@@ -228,41 +260,46 @@ open for reading and writing.
.PP
\fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
in \fIinterp\fR. After this call, Tcl programs executing in that
-interpreter can refer to the channel in input or output operations using the
-name given in the call to \fBTcl_CreateChannel\fR.
-After this call the channel becomes the property of the interpreter.
-The caller should not call \fBTcl_Close\fR for the channel; the
-channel will be closed automatically when it is unregistered from
-the interpreter.
-Furthermore, it is not generally safe to reference the channel
-anymore, since it could be deleted at any time by a \fBclose\fR
-command in the interpreter.
+interpreter can refer to the channel in input or output operations using
+the name given in the call to \fBTcl_CreateChannel\fR. After this call,
+the channel becomes the property of the interpreter, and the caller should
+not call \fBTcl_Close\fR for the channel; the channel will be closed
+automatically when it is unregistered from the interpreter.
+.PP
+Code executing outside of any Tcl interpreter can call
+\fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
+wishes to hold a reference to this channel. Subsequently, the channel can
+be registered in a Tcl interpreter and it will only be closed when the
+matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
+This allows code executing outside of any interpreter to safely hold a
+reference to a channel that is also registered in a Tcl interpreter.
.SH TCL_UNREGISTERCHANNEL
.PP
\fBTcl_UnregisterChannel\fR removes a channel from the set of channels
-accessible in \fIinterp\fR. After this call, Tcl programs will no longer
-be able to use the channel's name to refer to the channel in that
-interpreter. If this operation removed the last registration of the channel
-in any interpreter, the channel is also closed and destroyed.
+accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
+able to use the channel's name to refer to the channel in that interpreter.
+If this operation removed the last registration of the channel in any
+interpreter, the channel is also closed and destroyed.
+.PP
+Code not associated with a Tcl interpreter can call
+\fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
+that it no longer holds a reference to that channel. If this is the last
+reference to the channel, it will now be closed.
.SH TCL_CLOSE
.PP
\fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
-currently open channel.
-The channel should not be registered in any interpreter when
-\fBTcl_Close\fR is called; see the manual entry for \fBTcl_CreateChannel\fR
-for a description of \fBTcl_RegisterChannel\fR and \fBTcl_UnregisterChannel\fR.
-Buffered output is flushed to the channel's output device prior to
-destroying the channel, and any buffered input is discarded.
-If this is a blocking channel, the call does not return until all
-buffered data is successfully sent to the channel's output device.
-If this is a nonblocking channel and there is buffered output that
-cannot be written without blocking, the call
-returns immediately; output is flushed in the background and
-the channel will be closed once all of the buffered data has
-been output.
-In this case errors during flushing are not reported.
+currently open channel. The channel should not be registered in any
+interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to
+the channel's output device prior to destroying the channel, and any
+buffered input is discarded. If this is a blocking channel, the call does
+not return until all buffered data is successfully sent to the channel's
+output device. If this is a nonblocking channel and there is buffered
+output that cannot be written without blocking, the call returns
+immediately; output is flushed in the background and the channel will be
+closed once all of the buffered data has been output. In this case errors
+during flushing are not reported.
.PP
If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR.
If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
@@ -271,9 +308,13 @@ If the channel is being closed synchronously and an error occurs during
closing of the channel and \fIinterp\fR is not NULL, an error message is
left in \fIinterp->result\fR.
.PP
-Note: it is not safe to call \fBTcl_Close\fR on a channel that has
-been registered in an interpreter using \fBTcl_RegisterChannel\fR;
-see the documentation for \fBTcl_RegisterChannel\fR for details.
+Note: it is not safe to call \fBTcl_Close\fR on a channel that has been
+registered using \fBTcl_RegisterChannel\fR; see the documentation for
+\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been
+given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR,
+you should instead use \fBTcl_UnregisterChannel\fR, which will internally
+call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been
+matched by corresponding calls to \fBTcl_UnregisterChannel\fR.
.SH TCL_READ
.PP
@@ -307,7 +348,7 @@ current end-of-line recognition mode. End-of-line recognition and the
various platform-specific modes are described in the manual entry for the
Tcl \fBfconfigure\fR command.
-.SH TCL_GETS
+.SH TCL_GETS AND TCL_GETSOBJ
.PP
\fBTcl_Gets\fR reads a line of input from a channel and appends all of
the characters of the line except for the terminating end-of-line character(s)
@@ -329,7 +370,10 @@ did not contain an end-of-line character.
When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be
invoked to determine if the channel is blocked because of input
unavailability.
-
+.PP
+\fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting
+characters are appended to a Tcl object \fBlineObjPtr\fR rather than a
+dynamic string.
.SH TCL_WRITE
.PP
\fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output
@@ -433,6 +477,20 @@ The call always returns zero if the channel is in blocking mode.
buffered in the internal buffers for a channel. If the channel is not open
for reading, this function always returns zero.
+.VS
+.SH "PLATFORM ISSUES"
+.PP
+The handles returned from \fBTcl_GetChannelHandle\fR depend on the
+platform and the channel type. On Unix platforms, the handle is
+always a Unix file descriptor as returned from the \fBopen\fR system
+call. On Windows platforms, the handle is a file \fBHANDLE\fR when
+the channel was created with \fBTcl_OpenFileChannel\fR,
+\fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other
+channel types may return a different type of handle on Windows
+platforms. On the Macintosh platform, the handle is a file reference
+number as returned from \fBHOpenDF\fR.
+.VE
+
.SH "SEE ALSO"
DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3)
diff --git a/contrib/tcl/doc/OpenTcp.3 b/contrib/tcl/doc/OpenTcp.3
index 3f6d1d321cd0..8f7c7d027cb8 100644
--- a/contrib/tcl/doc/OpenTcp.3
+++ b/contrib/tcl/doc/OpenTcp.3
@@ -1,16 +1,16 @@
'\"
-'\" Copyright (c) 1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1996-7 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) OpenTcp.3 1.16 96/03/17 09:51:18
+'\" SCCS: @(#) OpenTcp.3 1.19 97/06/25 14:44:00
.so man.macros
-.TH Tcl_OpenTcpClient 3 7.5 Tcl "Tcl Library Procedures"
+.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Tcl_OpenTcpClient, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
+Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
.SH SYNOPSIS
.nf
\fB#include <tcl.h> \fR
@@ -92,11 +92,23 @@ NULL and records a POSIX error code that can be retrieved
with \fBTcl_GetErrno\fR.
In addition, if \fIinterp\fR is non-NULL, an error message
is left in \fIinterp->result\fR.
+.PP
+The newly created channel is not registered in the supplied interpreter; to
+register it, use \fBTcl_RegisterChannel\fR.
+If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+previously closed, the act of creating the new channel also assigns it as a
+replacement for the standard channel.
.SH TCL_MAKETCPCLIENTCHANNEL
.PP
\fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an
existing, platform specific, handle for a client TCP socket.
+.PP
+The newly created channel is not registered in the supplied interpreter; to
+register it, use \fBTcl_RegisterChannel\fR.
+If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+previously closed, the act of creating the new channel also assigns it as a
+replacement for the standard channel.
.SH TCL_OPENTCPSERVER
.PP
@@ -144,9 +156,24 @@ TCP server channels operate correctly only in applications that dispatch
events through \fBTcl_DoOneEvent\fR or through Tcl commands such as
\fBvwait\fR; otherwise Tcl will never notice that a connection request from
a remote client is pending.
+.PP
+The newly created channel is not registered in the supplied interpreter; to
+register it, use \fBTcl_RegisterChannel\fR.
+If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
+previously closed, the act of creating the new channel also assigns it as a
+replacement for the standard channel.
+
+.VS
+.SH "PLATFORM ISSUES"
+.PP
+On Unix platforms, the socket handle is a Unix file descriptor as
+returned by the \fBsocket\fR system call. On the Windows platform, the
+socket handle is a \fBSOCKET\fR as defined in the WinSock API. On the
+Macintosh platform, the socket handle is a \fBStreamPtr\fR.
+.VE
.SH "SEE ALSO"
-Tcl_OpenFileChannel(3), vwait(n)
+Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
.SH KEYWORDS
client, server, TCP
diff --git a/contrib/tcl/doc/PrintDbl.3 b/contrib/tcl/doc/PrintDbl.3
index 413e2b71473e..e4a4c7eba050 100644
--- a/contrib/tcl/doc/PrintDbl.3
+++ b/contrib/tcl/doc/PrintDbl.3
@@ -1,14 +1,14 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) PrintDbl.3 1.6 96/03/25 20:05:45
+'\" SCCS: @(#) PrintDbl.3 1.8 97/02/18 16:34:51
'\"
.so man.macros
-.TH Tcl_PrintDouble 3 7.0 Tcl "Tcl Library Procedures"
+.TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_PrintDouble \- Convert floating value to string
@@ -20,7 +20,11 @@ Tcl_PrintDouble \- Convert floating value to string
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
-Interpreter that controls the conversion.
+.VS
+Before Tcl 8.0, the \fBtcl_precision\fR variable in this interpreter
+controlled the conversion. As of Tcl 8.0, this argument is ignored and
+17 digits of precision are always used for conversion.
+.VE
.AP double value in
Floating-point value to be converted.
.AP char *dst out
@@ -32,14 +36,11 @@ least TCL_DOUBLE_SPACE characters of storage.
.PP
\fBTcl_PrintDouble\fR generates a string that represents the value
of \fIvalue\fR and stores it in memory at the location given by
-\fIdst\fR. It uses %g format to generate the string, with two
-special twists. First, the string is guaranteed to contain either
-a ``.'' or an ``e'' so that it doesn't look like an integer (where
-%g would generate an integer with no decimal point, \fBTcl_PrintDouble\fR
-adds ``.0''). Second, the number of significant digits printed at
-\fIdst\fR is controlled by the \fBtcl_precision\fR variable in
-\fIinterp\fR; if \fBtcl_precision\fR is undefined then 6 significant
-digits are printed.
+\fIdst\fR. It uses \fB%g\fR format to generate the string, with one
+special twist: the string is guaranteed to contain either
+a ``.'' or an ``e'' so that it doesn't look like an integer. Where
+\fB%g\fR would generate an integer with no decimal point, \fBTcl_PrintDouble\fR
+adds ``.0''.
.SH KEYWORDS
conversion, double-precision, floating-point, string
diff --git a/contrib/tcl/doc/RecordEval.3 b/contrib/tcl/doc/RecordEval.3
index 36567d96dfcf..6e6fb27e67dd 100644
--- a/contrib/tcl/doc/RecordEval.3
+++ b/contrib/tcl/doc/RecordEval.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) RecordEval.3 1.16 96/03/25 20:06:06
+'\" SCCS: @(#) RecordEval.3 1.17 96/08/26 12:59:47
'\"
.so man.macros
.TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures"
@@ -25,20 +25,16 @@ Tcl interpreter in which to evaluate command.
.AP char *cmd in
Command (or sequence of commands) to execute.
.AP int flags in
-.VS
An OR'ed combination of flag bits. TCL_NO_EVAL means record the
command but don't evaluate it. TCL_EVAL_GLOBAL means evaluate
the command at global level instead of the current stack level.
-.VE
.BE
.SH DESCRIPTION
.PP
\fBTcl_RecordAndEval\fR is invoked to record a command as an event
on the history list and then execute it using \fBTcl_Eval\fR
-.VS
(or \fBTcl_GlobalEval\fR if the TCL_EVAL_GLOBAL bit is set in \fIflags\fR).
-.VE
It returns a completion code such as TCL_OK just like \fBTcl_Eval\fR
and it leaves information in \fIinterp->result\fR.
If you don't want the command recorded on the history list then
diff --git a/contrib/tcl/doc/RegExp.3 b/contrib/tcl/doc/RegExp.3
index eea3f42a5639..fef92457eefa 100644
--- a/contrib/tcl/doc/RegExp.3
+++ b/contrib/tcl/doc/RegExp.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) RegExp.3 1.8 96/02/15 20:01:42
+'\" SCCS: @(#) RegExp.3 1.9 96/08/26 12:59:48
'\"
.so man.macros
.TH Tcl_RegExpMatch 3 7.4 Tcl "Tcl Library Procedures"
@@ -19,7 +19,6 @@ Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern m
int
\fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
.sp
-.VS
Tcl_RegExp
\fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
.sp
@@ -27,7 +26,6 @@ int
\fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
.sp
\fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
-.VE
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
@@ -37,7 +35,6 @@ String to check for a match with a regular expression.
.AP char *pattern in
String in the form of a regular expression pattern.
.AP Tcl_RegExp regexp in
-.VS
Compiled regular expression. Must have been returned previously
by \fBTcl_RegExpCompile\fR.
.AP char *start in
@@ -55,7 +52,6 @@ NULL if there is no such range.
.AP char **endPtr out
The address of the character just after the last one in the range
is stored here, or NULL if there is no such range.
-.VE
.BE
.SH DESCRIPTION
@@ -70,7 +66,6 @@ If an error occurs in the matching process (e.g. \fIpattern\fR
is not a valid regular expression) then \fBTcl_RegExpMatch\fR
returns \-1 and leaves an error message in \fIinterp->result\fR.
.PP
-.VS
\fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
provide lower-level access to the regular expression pattern matcher.
\fBTcl_RegExpCompile\fR compiles a regular expression string into
@@ -80,11 +75,9 @@ used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
If an error occurs while compiling the regular expression then
\fBTcl_RegExpCompile\fR returns NULL and leaves an error message
in \fIinterp->result\fR.
-.VS
Note: the return value from \fBTcl_RegExpCompile\fR is only valid
up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to
retain these values for long periods of time.
-.VE
.PP
\fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
It returns 1 if \fIstring\fR contains a range of characters that
@@ -118,7 +111,6 @@ information is returned about the range of characters that matched the
\fIindex\fR'th parenthesized subexpression within the pattern.
If there is no range corresponding to \fIindex\fR then NULL
is stored in \fI*firstPtr\fR and \fI*lastPtr\fR.
-.VE
.SH KEYWORDS
match, pattern, regular expression, string, subexpression
diff --git a/contrib/tcl/doc/SetResult.3 b/contrib/tcl/doc/SetResult.3
index b70977d4cfcd..5616de85f5c1 100644
--- a/contrib/tcl/doc/SetResult.3
+++ b/contrib/tcl/doc/SetResult.3
@@ -1,28 +1,34 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) SetResult.3 1.19 96/06/05 18:00:15
+'\" SCCS: @(#) SetResult.3 1.23 97/06/26 14:05:57
'\"
.so man.macros
.TH Tcl_SetResult 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string
+Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
+\fBTcl_SetObjResult\fR(\fIinterp, objPtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetObjResult\fR(\fIinterp\fR)
+.sp
\fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
.sp
-\fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
+char *
+\fBTcl_GetStringResult\fR(\fIinterp\fR)
+.sp
+\fBTcl_AppendResult\fR(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
.sp
-.VS
\fBTcl_AppendElement\fR(\fIinterp, string\fR)
-.VE
.sp
\fBTcl_ResetResult\fR(\fIinterp\fR)
.sp
@@ -30,10 +36,12 @@ Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulat
.SH ARGUMENTS
.AS Tcl_FreeProc freeProc
.AP Tcl_Interp *interp out
-Interpreter whose result is to be modified.
+Interpreter whose result is to be modified or read.
+.AP Tcl_Obj *objPtr in
+Object value to become result for \fIinterp\fR.
.AP char *string in
String value to become result for \fIinterp\fR or to be
-appended to existing result.
+appended to the existing result.
.AP Tcl_FreeProc *freeProc in
Address of procedure to call to release storage at
\fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
@@ -42,51 +50,75 @@ Address of procedure to call to release storage at
.SH DESCRIPTION
.PP
-The procedures described here are utilities for setting the
-result/error string in a Tcl interpreter.
+The procedures described here are utilities for manipulating the
+result value in a Tcl interpreter.
+The interpreter result may be either a Tcl object or a string.
+For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
+set the interpreter result to, respectively, an object and a string.
+Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
+return the interpreter result as an object and as a string.
+The procedures always keep the string and object forms
+of the interpreter result consistent.
+For example, if \fBTcl_SetObjResult\fR is called to set
+the result to an object,
+then \fBTcl_GetStringResult\fR is called,
+it will return the object's string value.
.PP
-\fBTcl_SetResult\fR
-arranges for \fIstring\fR to be the return string for the current Tcl
-command in \fIinterp\fR, replacing any existing result.
-If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
-refers to an area of static storage that is guaranteed not to be
-modified until at least the next call to \fBTcl_Eval\fR.
-.VS
-If \fIfreeProc\fR
-is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
-to \fBTcl_Alloc\fR and is now the property of the Tcl system.
-\fBTcl_SetResult\fR will arrange for the string's storage to be
-released by calling \fBTcl_Free\fR when it is no longer needed.
-.VE
-If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
-points to an area of memory that is likely to be overwritten when
-\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
-In this case \fBTcl_SetResult\fR will make a copy of the string in
-dynamically allocated storage and arrange for the copy to be the
-return string for the current Tcl command.
+\fBTcl_SetObjResult\fR
+arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
+replacing any existing result.
+The result is left pointing to the object
+referenced by \fIobjPtr\fR.
+\fIobjPtr\fR's reference count is incremented
+since there is now a new reference to it from \fIinterp\fR.
+The reference count for any old result object
+is decremented and the old result object is freed if no
+references to it remain.
.PP
-If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
-\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
-of a procedure that Tcl should call to free the string.
-This allows applications to use non-standard storage allocators.
-When Tcl no longer needs the storage for the string, it will
-call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
-result that match the type \fBTcl_FreeProc\fR:
-.CS
-typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
-.CE
-When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
-the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
+\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object.
+The object's reference count is not incremented;
+if the caller needs to retain a long-term pointer to the object
+they should use \fBTcl_IncrRefCount\fR to increment its reference count
+in order to keep it from being freed too early or accidently changed.
.PP
+\fBTcl_SetResult\fR
+arranges for \fIstring\fR to be the result for the current Tcl
+command in \fIinterp\fR, replacing any existing result.
+The \fIfreeProc\fR argument specifies how to manage the storage
+for the \fIstring\fR argument;
+it is discussed in the section
+\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.
If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
and \fBTcl_SetResult\fR
-re-initializes \fIinterp\fR's result to point to the pre-allocated result
-area, with an empty string in the result area.
+re-initializes \fIinterp\fR's result to point to an empty string.
+.PP
+\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as an string.
+If the result was set to an object by a \fBTcl_SetObjResult\fR call,
+the object form will be converted to a string and returned.
+If the object's string representation contains null bytes,
+this conversion will lose information.
+For this reason, programmers are encouraged to
+write their code to use the new object API procedures
+and to call \fBTcl_GetObjResult\fR instead.
.PP
-If \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a
-result, \fBTcl_SetResult\fR does whatever is necessary to dispose
-of the old result (see the \fBTcl_Interp\fR manual entry for details
-on this).
+\fBTcl_ResetResult\fR clears the result for \fIinterp\fR
+and leaves the result in its normal empty initialized state.
+If the result is an object,
+its reference count is decremented and the result is left
+pointing to an unshared object representing an empty string.
+If the result is a dynamically allocated string, its memory is free*d
+and the result is left as a empty string.
+\fBTcl_ResetResult\fR also clears the error state managed by
+\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR,
+and \fBTcl_SetErrorCode\fR.
+
+.SH OLD STRING PROCEDURES
+.PP
+Use of the following procedures is deprecated
+since they manipulate the Tcl result as a string.
+Procedures such as \fBTcl_SetObjResult\fR
+that manipulate the result as an object
+can be significantly more efficient.
.PP
\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
It takes each of its \fIstring\fR arguments and appends them in order
@@ -100,8 +132,10 @@ of the result are produced.
\fBTcl_AppendResult\fR takes care of all the
storage management issues associated with managing \fIinterp\fR's
result, such as allocating a larger result area if necessary.
+It also converts the current interpreter result from an object
+to a string, if necessary, before appending the argument strings.
Any number of \fIstring\fR arguments may be passed in a single
-call; the last argument in the list must be a NULL pointer.
+call; the last argument in the list must be a NULL pointer.
.PP
\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
that it allows results to be built up in pieces.
@@ -115,33 +149,69 @@ Under normal conditions, \fBTcl_AppendElement\fR will add a space
character to \fIinterp\fR's result just before adding the new
list element, so that the list elements in the result are properly
separated.
-.VS
However if the new list element is the first in a list or sub-list
(i.e. \fIinterp\fR's current result is empty, or consists of the
single character ``{'', or ends in the characters `` {'') then no
space is added.
-.VE
-.PP
-\fBTcl_ResetResult\fR clears the result for \fIinterp\fR,
-freeing the memory associated with it if the current result was
-dynamically allocated.
-It leaves the result in its normal initialized state with
-\fIinterp->result\fR pointing to a static buffer containing
-\fBTCL_RESULT_SIZE\fR characters, of which the first character
-is zero.
-\fBTcl_ResetResult\fR also clears the error state managed by
-\fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR.
.PP
-\fBTcl_FreeResult\fR is a macro that performs part of the work
+\fBTcl_FreeResult\fR performs part of the work
of \fBTcl_ResetResult\fR.
-It frees up the memory associated with \fIinterp\fR's result
-and sets \fIinterp->freeProc\fR to zero, but it doesn't
+It frees up the memory associated with \fIinterp\fR's result.
+It also sets \fIinterp->freeProc\fR to zero, but doesn't
change \fIinterp->result\fR or clear error state.
\fBTcl_FreeResult\fR is most commonly used when a procedure
is about to replace one result value with another.
+.SH DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED
+.PP
+It used to be legal for programs to
+directly read and write \fIinterp->result\fR
+to manipulate the interpreter result.
+Direct access to \fIinterp->result\fR is now strongly deprecated
+because it can make the result's string and object forms inconsistent.
+Programs should always read the result
+using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR,
+and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR.
+
+.SH THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT
+.PP
+\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
+the Tcl system is to manage the storage for the \fIstring\fR argument.
+If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
+at a time when \fIinterp\fR holds a string result,
+they do whatever is necessary to dispose of the old string result
+(see the \fBTcl_Interp\fR manual entry for details on this).
+.PP
+If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
+refers to an area of static storage that is guaranteed not to be
+modified until at least the next call to \fBTcl_Eval\fR.
+If \fIfreeProc\fR
+is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
+to \fBTcl_Alloc\fR and is now the property of the Tcl system.
+\fBTcl_SetResult\fR will arrange for the string's storage to be
+released by calling \fBTcl_Free\fR when it is no longer needed.
+If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
+points to an area of memory that is likely to be overwritten when
+\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
+In this case \fBTcl_SetResult\fR will make a copy of the string in
+dynamically allocated storage and arrange for the copy to be the
+result for the current Tcl command.
+.PP
+If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
+\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
+of a procedure that Tcl should call to free the string.
+This allows applications to use non-standard storage allocators.
+When Tcl no longer needs the storage for the string, it will
+call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
+result that match the type \fBTcl_FreeProc\fR:
+.CS
+typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
+.CE
+When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
+the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
+
.SH "SEE ALSO"
-Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
+Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
.SH KEYWORDS
-append, command, element, list, result, return value, interpreter
+append, command, element, list, object, result, return value, interpreter
diff --git a/contrib/tcl/doc/SetVar.3 b/contrib/tcl/doc/SetVar.3
index 8d1696fb4dc9..10850ae4d29d 100644
--- a/contrib/tcl/doc/SetVar.3
+++ b/contrib/tcl/doc/SetVar.3
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) SetVar.3 1.22 96/03/25 20:07:08
+'\" SCCS: @(#) SetVar.3 1.29 97/05/19 17:35:05
'\"
.so man.macros
.TH Tcl_SetVar 3 7.4 Tcl "Tcl Library Procedures"
@@ -38,13 +38,14 @@ int
.AP Tcl_Interp *interp in
Interpreter containing variable.
.AP char *varName in
-Name of variable. May refer to a scalar variable or an element of
+Name of variable.
+May include a series of \fB::\fR namespace qualifiers
+to specify a variable in a particular namespace.
+May refer to a scalar variable or an element of
an array variable.
-.VS
If the name references an element of an array, then it
must be in writable memory: Tcl will make temporary modifications
to it while looking up the name.
-.VE
.AP char *newValue in
New value for variable.
.AP int flags in
@@ -53,6 +54,8 @@ operation. See below for valid values.
.AP char *name1 in
Name of scalar variable, or name of array variable if \fIname2\fR
is non-NULL.
+May include a series of \fB::\fR namespace qualifiers
+to specify a variable in a particular namespace.
.AP char *name2 in
If non-NULL, gives name of element within array and \fIname1\fR
must refer to an array variable.
@@ -62,8 +65,19 @@ must refer to an array variable.
.PP
These procedures may be used to create, modify, read, and delete
Tcl variables from C code.
-\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR will create a new variable
-or modify an existing one.
+.PP
+Note that \fBTcl_GetVar\fR and \fBTcl_SetVar\fR
+have been largely replaced by the
+object-based procedures \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR.
+Those object-based procedures read, modify, and create
+a variable whose name is held in a Tcl object instead of a string.
+They also return a pointer to the object
+which is the variable's value instead of returning a string.
+Operations on objects can be faster since objects
+hold an internal representation that can be manipulated more efficiently.
+.PP
+\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR
+will create a new variable or modify an existing one.
Both of these procedures set the given variable to the value
given by \fInewValue\fR, and they return a pointer to a
copy of the variable's new value, which is stored in Tcl's
@@ -73,9 +87,10 @@ may change \fInewValue\fR after these procedures return without
affecting the value of the variable.
If an error occurs in setting the variable (e.g. an array
variable is referenced without giving an index into the array),
-then NULL is returned.
+they return NULL.
.PP
-The name of the variable may be specified in either of two ways.
+The name of the variable may be specified to
+\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR in either of two ways.
If \fBTcl_SetVar\fR is called, the variable name is given as
a single string, \fIvarName\fR.
If \fIvarName\fR contains an open parenthesis and ends with a
@@ -96,18 +111,34 @@ It consists of an OR-ed combination of any of the following
bits:
.TP
\fBTCL_GLOBAL_ONLY\fR
-Under normal circumstances the procedures look up variables
-at the current level of procedure call for \fIinterp\fR, or
-at global level if there is no call active.
+Under normal circumstances the procedures look up variables as follows:
+If a procedure call is active in \fIinterp\fR,
+a variable is looked up at the current level of procedure call.
+Otherwise, a variable is looked up first in the current namespace,
+then in the global namespace.
+However, if this bit is set in \fIflags\fR then the variable
+is looked up only in the global namespace
+even if there is a procedure call active.
+If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
+\fBTCL_GLOBAL_ONLY\fR is ignored.
+.TP
+\fBTCL_NAMESPACE_ONLY\fR
+Under normal circumstances the procedures look up variables as follows:
+If a procedure call is active in \fIinterp\fR,
+a variable is looked up at the current level of procedure call.
+Otherwise, a variable is looked up first in the current namespace,
+then in the global namespace.
However, if this bit is set in \fIflags\fR then the variable
-is looked up at global level even if there is a procedure
-call active.
+is looked up only in the current namespace
+even if there is a procedure call active.
.TP
\fBTCL_LEAVE_ERR_MSG\fR
If an error is returned and this bit is set in \fIflags\fR, then
-an error message will be left in \fI\%interp->result\fR. If this
-flag bit isn't set then no error message is left (\fI\%interp->result\fR
-will not be modified).
+an error message will be left in the interpreter's result,
+where it can be retrieved with \fBTcl_GetObjResult\fR
+or \fBTcl_GetStringResult\fR.
+If this flag bit isn't set then no error message is left
+and the interpreter's result will not be modified.
.TP
\fBTCL_APPEND_VALUE\fR
If this bit is set then \fInewValue\fR is appended to the current
@@ -118,14 +149,12 @@ If the variable is currently undefined, then this bit is ignored.
If this bit is set, then \fInewValue\fR is converted to a valid
Tcl list element before setting (or appending to) the variable.
A separator space is appended before the new list element unless
-.VS
the list element is going to be the first element in a list or
sublist (i.e. the variable's current value is empty, or contains
the single character ``{'', or ends in `` }'').
-.VE
.PP
-\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR return the current value
-of a variable.
+\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR
+return the current value of a variable.
The arguments to these procedures are treated in the same way
as the arguments to \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR.
Under normal circumstances, the return value is a pointer
@@ -145,18 +174,16 @@ a variable, so that future calls to \fBTcl_GetVar\fR or \fBTcl_GetVar2\fR
for the variable will return an error.
The arguments to these procedures are treated in the same way
as the arguments to \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR.
-.VS
If the variable is successfully removed then TCL_OK is returned.
If the variable cannot be removed because it doesn't exist then
TCL_ERROR is returned.
-.VE
If an array element is specified, the given element is removed
but the array remains.
If an array name is specified without an index, then the entire
array is removed.
.SH "SEE ALSO"
-Tcl_TraceVar
+Tcl_GetObjResult, Tcl_GetStringResult, Tcl_ObjGetVar2, Tcl_ObjSetVar2, Tcl_TraceVar
.SH KEYWORDS
-array, interpreter, scalar, set, unset, variable
+array, interpreter, object, scalar, set, unset, variable
diff --git a/contrib/tcl/doc/SplitList.3 b/contrib/tcl/doc/SplitList.3
index a1364502a055..a250c8fb335f 100644
--- a/contrib/tcl/doc/SplitList.3
+++ b/contrib/tcl/doc/SplitList.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) SplitList.3 1.20 96/06/05 18:00:16
+'\" SCCS: @(#) SplitList.3 1.21 97/04/29 14:07:10
'\"
.so man.macros
.TH Tcl_SplitList 3 7.5 Tcl "Tcl Library Procedures"
@@ -24,9 +24,19 @@ char *
.sp
int
\fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
+.VS
+.sp
+int
+\fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR)
+.VE
.sp
int
\fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
+.VS
+.sp
+int
+\fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR)
+.VE
.SH ARGUMENTS
.AS Tcl_Interp ***argvPtr
.AP Tcl_Interp *interp out
@@ -53,6 +63,10 @@ String that is to become an element of a list.
.AP int *flagsPtr in
Pointer to word to fill in with information about \fIsrc\fR.
The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
+.VS
+.AP int length in
+Number of bytes in string \fIsrc\fR.
+.VE
.AP char *dst in
Place to copy converted list element. Must contain enough characters
to hold converted string.
@@ -165,6 +179,13 @@ special situations, such as when \fBTcl_ConvertElement\fR is being
used to generate a portion of an argument for a Tcl command.
In this case, surrounding \fIsrc\fR with curly braces would cause
the command not to be parsed correctly.
+.PP
+.VS
+\fBTcl_ScanCountedElement\fR and \fBTcl_ConvertCountedElement\fR are
+the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except
+the length of string \fIsrc\fR is specified by the \fIlength\fR
+argument, and the string may contain embedded nulls.
+.VE
.SH KEYWORDS
backslash, convert, element, list, merge, split, strings
diff --git a/contrib/tcl/doc/SplitPath.3 b/contrib/tcl/doc/SplitPath.3
index abfffb500abd..f98a78b75905 100644
--- a/contrib/tcl/doc/SplitPath.3
+++ b/contrib/tcl/doc/SplitPath.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) SplitPath.3 1.3 96/07/31 17:04:33
+'\" SCCS: @(#) SplitPath.3 1.4 96/08/19 14:59:35
'\"
.so man.macros
.TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
@@ -59,11 +59,11 @@ responsibility to free all of this storage.
For example, suppose that you have called \fBTcl_SplitPath\fR with the
following code:
.CS
-int argc, code;
+int argc;
char *path;
char **argv;
\&...
-code = Tcl_SplitPath(interp, string, &argc, &argv);
+Tcl_SplitPath(string, &argc, &argv);
.CE
Then you should eventually free the storage with a call like the
following:
diff --git a/contrib/tcl/doc/StaticPkg.3 b/contrib/tcl/doc/StaticPkg.3
index 729e91cd4afd..ccb1a694ed70 100644
--- a/contrib/tcl/doc/StaticPkg.3
+++ b/contrib/tcl/doc/StaticPkg.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) StaticPkg.3 1.3 96/03/15 08:29:37
+'\" SCCS: @(#) StaticPkg.3 1.4 96/09/04 11:21:26
'\"
.so man.macros
.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
@@ -38,12 +38,15 @@ can't be used in safe interpreters.
.SH DESCRIPTION
.PP
This procedure may be invoked to announce that a package has been
-linked statically with a Tcl application and, optionally, that it
+linked statically with a Tcl application and, optionally, that it
has already been loaded into an interpreter.
-\fBTcl_StaticPackage\fR is typically invoked by the \fBTcl_AppInit\fR
-procedure for the application.
Once \fBTcl_StaticPackage\fR has been invoked for a package, it
may be loaded into interpreters using the \fBload\fR command.
+\fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR
+procedure for the application, not by packages for themselves
+(\fBTcl_StaticPackage\fR should only be invoked for statically
+loaded packages, and code in the package itself should not need
+to know whether the package is dynamically or statically loaded).
.PP
When the \fBload\fR command is used later to load the package into
an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will
diff --git a/contrib/tcl/doc/StringObj.3 b/contrib/tcl/doc/StringObj.3
new file mode 100644
index 000000000000..a98fc46d13d5
--- /dev/null
+++ b/contrib/tcl/doc/StringObj.3
@@ -0,0 +1,132 @@
+'\"
+'\" Copyright (c) 1994-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.
+'\"
+'\" SCCS: @(#) @(#) StringObj.3 1.13 97/06/25 13:40:25
+'\"
+.so man.macros
+.TH Tcl_StringObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_AppendToObj, Tcl_AppendStringsToObj, Tcl_SetObjLength, TclConcatObj \- manipulate Tcl objects as strings
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewStringObj\fR(\fIbytes, length\fR)
+.sp
+\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
+.sp
+char *
+\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
+.sp
+\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
+.sp
+\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
+.sp
+\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *lengthPtr out
+.AP char *bytes in
+Points to the first byte of an array of bytes
+used to set or append to a string object.
+This byte array may contain embedded null bytes
+unless \fIlength\fR is negative.
+.AP int length in
+The number of bytes to copy from \fIbytes\fR when
+initializing, setting, or appending to a string object.
+If negative, all bytes up to the first null are used.
+.AP Tcl_Obj *objPtr in/out
+Points to an object to manipulate.
+.AP int *lengthPtr out
+If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
+the the length of an object's string representation.
+.AP char *string in
+Null-terminated string value to append to \fIobjPtr\fR.
+.AP int newLength in
+New length for the string value of \fIobjPtr\fR, not including the
+final NULL character.
+.AP int objc in
+The number of elements to concatenate.
+.AP Tcl_Obj *objv[] in
+The array of objects to concatenate.
+.BE
+
+.SH DESCRIPTION
+.PP
+The procedures described in this manual entry allow Tcl objects to
+be manipulated as string values. They use the internal representation
+of the object to store additional information to make the string
+manipulations more efficient. In particular, they make a series of
+append operations efficient by allocating extra storage space for the
+string so that it doesn't have to be copied for each append.
+.PP
+\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
+or modify an existing object to hold a copy of
+the string given by \fIbytes\fR and \fIlength\fR.
+\fBTcl_NewStringObj\fR returns a pointer to a newly created object
+with reference count zero.
+Both procedures set the object to hold a copy of the specified string.
+\fBTcl_SetStringObj\fR frees any old string representation
+as well as any old internal representation of the object.
+.PP
+\fBTcl_GetStringFromObj\fR returns an object's string representation.
+This is given by the returned byte pointer
+and length, which is stored in \fIlengthPtr\fR if it is non-NULL.
+If the object's string representation is invalid
+(its byte pointer is NULL),
+the string representation is regenerated from the
+object's internal representation.
+The storage referenced by the returned byte pointer
+is owned by the object manager and should not be modified by the caller.
+.PP
+\fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
+\fIlength\fR to the object specified by \fIobjPtr\fR. It does this
+in a way that handles repeated calls relatively efficiently (it
+overallocates the string space to avoid repeated reallocations
+and copies of object's string value).
+.PP
+\fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
+except that it can be passed more than one value to append and
+each value must be a null-terminated string (i.e. none of the
+values may contain internal null characters). Any number of
+\fIstring\fR arguments may be provided, but the last argument
+must be a NULL pointer to indicate the end of the list.
+.PP
+The \fBTcl_SetObjLength\fR procedure changes the length of the
+string value of its \fIobjPtr\fR argument. If the \fInewLength\fR
+argument is greater than the space allocated for the object's
+string, then the string space is reallocated and the old value
+is copied to the new space; the bytes between the old length of
+the string and the new length may have arbitrary values.
+If the \fInewLength\fR argument is less than the current length
+of the object's string, with \fIobjPtr->length\fR is reduced without
+reallocating the string space; the original allocated size for the
+string is recorded in the object, so that the string length can be
+enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
+reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves
+a null character at \fIobjPtr->bytes[newLength]\fR.
+.PP
+The \fBTcl_ConcatObj\fR function returns a new string object whose
+value is the space-separated concatenation of the string
+representations of all of the objects in the \fIobjv\fR
+array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
+as it copies the string representations of the \fIobjv\fR array to the
+result. If an element of the \fIobjv\fR array consists of nothing but
+white space, then that object is ignored entirely. This white-space
+removal was added to make the output of the \fBconcat\fR command
+cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
+newly-created object whose ref count is zero.
+
+.SH "SEE ALSO"
+Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
+
+.SH KEYWORDS
+append, internal representation, object, object type, string object,
+string type, string representation, concat, concatenate
diff --git a/contrib/tcl/doc/Tcl.n b/contrib/tcl/doc/Tcl.n
index d0b60e591ed0..610fe1bbb070 100644
--- a/contrib/tcl/doc/Tcl.n
+++ b/contrib/tcl/doc/Tcl.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) Tcl.n 1.127 96/03/25 20:08:20
+'\" SCCS: @(#) Tcl.n 1.128 96/08/26 12:59:50
'
.so man.macros
.TH Tcl n "" Tcl "Tcl Built-In Commands"
@@ -102,22 +102,18 @@ Variable substitution is not performed on words enclosed in braces.
.IP [8]
If a backslash (``\e'') appears within a word then
\fIbackslash substitution\fR occurs.
-.VS
In all cases but those described below the backslash is dropped and
the following character is treated as an ordinary
character and included in the word.
-.VE
This allows characters such as double quotes, close brackets,
and dollar signs to be included in words without triggering
special processing.
The following table lists the backslash sequences that are
handled specially, along with the value that replaces each sequence.
.RS
-.VS
.TP 6
\e\fBa\fR
Audible alert (bell) (0x7).
-.VE
.TP 6
\e\fBb\fR
Backspace (0x8).
@@ -138,7 +134,6 @@ Tab (0x9).
Vertical tab (0xb).
.TP 6
\e\fB<newline>\fIwhiteSpace\fR
-.VS
A single space character replaces the backslash, newline, and all
spaces and tabs after the newline.
This backslash sequence is unique in that it is replaced in a separate
@@ -146,7 +141,6 @@ pre-pass before the command is actually parsed.
This means that it will be replaced even when it occurs between
braces, and the resulting space will be treated as a word separator
if it isn't in braces or quotes.
-.VE
.TP 6
\e\e
Backslash (``\e'').
@@ -156,10 +150,8 @@ The digits \fIooo\fR (one, two, or three of them) give the octal value of
the character.
.TP 6
\e\fBx\fIhh\fR
-.VS
The hexadecimal digits \fIhh\fR give the hexadecimal value of
the character. Any number of digits may be present.
-.VE
.LP
Backslash substitution is not performed on words enclosed in braces,
except for backslash-newline as described above.
diff --git a/contrib/tcl/doc/TraceVar.3 b/contrib/tcl/doc/TraceVar.3
index ecfdc3e5b2ac..665a3a7d2b2e 100644
--- a/contrib/tcl/doc/TraceVar.3
+++ b/contrib/tcl/doc/TraceVar.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) TraceVar.3 1.25 96/03/25 20:08:44
+'\" SCCS: @(#) TraceVar.3 1.26 96/08/26 12:59:52
'\"
.so man.macros
.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
@@ -39,11 +39,9 @@ Interpreter containing variable.
Name of variable. May refer to a scalar variable, to
an array variable with no index, or to an array variable
with a parenthesized index.
-.VS
If the name references an element of an array, then it
must be in writable memory: Tcl will make temporary modifications
to it while looking up the name.
-.VE
.AP int flags in
OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and
TCL_TRACE_UNSETS, and TCL_GLOBAL_ONLY. Not all flags are used by all
@@ -195,10 +193,8 @@ for the variable, so that calls to \fBTcl_GetVar2\fR and
to be invoked again.
Disabling only occurs for the variable whose trace procedure
is active; accesses to other variables will still be traced.
-.VS
However, if a variable is unset during a read or write trace then unset
traces will be invoked.
-.VE
.PP
During unset traces the variable has already been completely
expunged.
@@ -222,10 +218,8 @@ and \fBTcl_GetVar2\fR procedures.
returned.
It may modify the value of the variable to affect what
is returned by the traced access.
-.VS
If it unsets the variable then the access will return an error
just as if the variable never existed.
-.VE
.PP
When write tracing has been specified for a variable, the
trace procedure will be invoked whenever the variable's value
@@ -239,10 +233,8 @@ returned.
It may modify the value of the variable to override the change
and to determine the value actually returned by the traced
access.
-.VS
If it deletes the variable then the traced access will return
an empty string.
-.VE
.PP
When unset tracing has been specified, the trace procedure
will be invoked whenever the variable is destroyed.
@@ -270,11 +262,9 @@ access, in order from most-recently-created to least-recently-created.
When there exist whole-array traces for an array as well as
traces on individual elements, the whole-array traces are invoked
before the individual-element traces.
-.VS
If a read or write trace unsets the variable then all of the unset
traces will be invoked but the remainder of the read and write traces
will be skipped.
-.VE
.SH "ERROR RETURNS"
.PP
diff --git a/contrib/tcl/doc/Translate.3 b/contrib/tcl/doc/Translate.3
index 81a16dae2a45..6330ee9e2c63 100644
--- a/contrib/tcl/doc/Translate.3
+++ b/contrib/tcl/doc/Translate.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) Translate.3 1.21 96/03/25 20:08:58
+'\" SCCS: @(#) Translate.3 1.22 96/08/26 12:59:51
'\"
.so man.macros
.TH Tcl_TranslateFileName 3 7.5 Tcl "Tcl Library Procedures"
@@ -17,9 +17,7 @@ Tcl_TranslateFileName \- convert file name to native form and replace tilde with
\fB#include <tcl.h>\fR
.sp
char *
-.VS
\fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
-.VE
.SH ARGUMENTS
.AS Tcl_DString *bufferPtr
.AP Tcl_Interp *interp in
@@ -27,17 +25,14 @@ Interpreter in which to report an error, if any.
.AP char *name in
File name, which may start with a ``~''.
.AP Tcl_DString *bufferPtr in/out
-.VS
If needed, this dynamic string is used to store the new file name.
At the time of the call it should be uninitialized or empty. The
caller must eventually call \fBTcl_DStringFree\fR to free up
anything stored here.
-.VE
.BE
.SH DESCRIPTION
.PP
-.VS
This utility procedure translates a file name to a form suitable for
passing to the local operating system. It converts network names into
native form and does tilde substitution.
@@ -53,24 +48,19 @@ placed in \fI*bufferPtr\fR. The caller need not know whether or
not \fBTcl_TranslateFileName\fR actually used the string; \fBTcl_TranslateFileName\fR
initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to
\fBTcl_DStringFree\fR will be safe in either case.
-.VE
.PP
If an error occurs (e.g. because there was no user by the given
name) then NULL is returned and an error message will be left
at \fIinterp->result\fR.
-.VS
When an error occurs, \fBTcl_TranslateFileName\fR
frees the dynamic string itself so that the caller need not call
\fBTcl_DStringFree\fR.
-.VE
.PP
The caller is responsible for making sure that \fIinterp->result\fR
has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
-.VS
.SH "SEE ALSO"
filename
-.VE
.SH KEYWORDS
file name, home directory, tilde, translate, user
diff --git a/contrib/tcl/doc/WrongNumArgs.3 b/contrib/tcl/doc/WrongNumArgs.3
new file mode 100644
index 000000000000..528ebc827511
--- /dev/null
+++ b/contrib/tcl/doc/WrongNumArgs.3
@@ -0,0 +1,59 @@
+'\"
+'\" Copyright (c) 1994-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.
+'\"
+'\" SCCS: @(#) @(#) WrongNumArgs.3 1.3 97/03/18 11:53:25
+'\"
+.so man.macros
+.TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_WrongNumArgs \- generate standard error message for wrong number of arguments
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_WrongNumArgs\fR(\fIinterp, objc, objv, message\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp "*CONST objv[]"
+.AP Tcl_Interp interp in
+Interpreter in which error will be reported: error message gets stored
+in its result object.
+.AP int objc in
+Number of leading arguments from \fIobjv\fR to include in error
+message.
+.TP
+Tcl_Obj *CONST \fIobjv\fR[] (in)
+Arguments to command that had the wrong number of arguments.
+.AP char *message in
+Additional error information to print after leading arguments
+from \fIobjv\fR. This typically gives the acceptable syntax
+of the command.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by
+command procedures when they discover that they have received the
+wrong number of arguments. \fBTcl_WrongNumArgs\fR generates a
+standard error message and stores it in the result object of
+\fIinterp\fR. The message includes the \fIobjc\fR initial
+elements of \fIobjv\fR plus \fImessage\fR. For example, if
+\fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR,
+\fIobjc\fR is 1, and \fImessage\fR is ``\fBfileName count\fR''
+then \fIinterp\fR's result object will be set to the following
+string:
+.CS
+wrong # args: should be "foo fileName count"
+.CE
+If \fIobjc\fR is 2, the result will be set to the following string:
+.CS
+wrong # args: should be "foo bar fileName count"
+.CE
+\fIObjc\fR is usually 1, but may be 2 or more for commands like \fBstring\fR
+and the Tk widget commands, which use the first argument as a subcommand.
+
+.SH KEYWORDS
+command, error message, wrong number of arguments
diff --git a/contrib/tcl/doc/array.n b/contrib/tcl/doc/array.n
index 37265f1f8dce..a6e88172b7ca 100644
--- a/contrib/tcl/doc/array.n
+++ b/contrib/tcl/doc/array.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) array.n 1.7 96/03/25 20:09:58
+'\" SCCS: @(#) array.n 1.8 96/08/26 12:59:53
'\"
.so man.macros
.TH array n 7.4 Tcl "Tcl Built-In Commands"
@@ -47,31 +47,24 @@ been the return value from a previous invocation of
\fBarray startsearch\fR. Returns an empty string.
.TP
\fBarray exists \fIarrayName\fR
-.VS
Returns 1 if \fIarrayName\fR is an array variable, 0 if there
is no variable by that name or if it is a scalar variable.
-.VE
.TP
\fBarray get \fIarrayName\fR ?\fIpattern\fR?
-.VS
Returns a list containing pairs of elements. The first
element in each pair is the name of an element in \fIarrayName\fR
and the second element of each pair is the value of the
array element. The order of the pairs is undefined.
-.VS
If \fIpattern\fR is not specified, then all of the elements of the
array are included in the result.
If \fIpattern\fR is specified, then only those elements whose names
match \fIpattern\fR (using the glob-style matching rules of
\fBstring match\fR) are included.
-.VE
If \fIarrayName\fR isn't the name of an array variable, or if
the array contains no elements, then an empty list is returned.
-.VE
.TP
\fBarray names \fIarrayName\fR ?\fIpattern\fR?
Returns a list containing the names of all of the elements in
-.VS
the array that match \fIpattern\fR (using the glob-style matching
rules of \fBstring match\fR).
If \fIpattern\fR is omitted then the command returns all of
@@ -79,7 +72,6 @@ the element names in the array.
If there are no (matching) elements in the array, or if \fIarrayName\fR
isn't the name of an array variable, then an empty string is
returned.
-.VE
.TP
\fBarray nextelement \fIarrayName searchId\fR
Returns the name of the next element in \fIarrayName\fR, or
@@ -93,21 +85,17 @@ then all searches are automatically terminated just as if
\fBarray nextelement\fR operations to fail for those searches.
.TP
\fBarray set \fIarrayName list\fR
-.VS
Sets the values of one or more elements in \fIarrayName\fR.
\fIlist\fR must have a form like that returned by \fBarray get\fR,
consisting of an even number of elements.
Each odd-numbered element in \fIlist\fR is treated as an element
name within \fIarrayName\fR, and the following element in \fIlist\fR
is used as a new value for that array element.
-.VE
.TP
\fBarray size \fIarrayName\fR
Returns a decimal string giving the number of elements in the
array.
-.VS
If \fIarrayName\fR isn't the name of an array then 0 is returned.
-.VE
.TP
\fBarray startsearch \fIarrayName\fR
This command initializes an element-by-element search through the
diff --git a/contrib/tcl/doc/binary.n b/contrib/tcl/doc/binary.n
new file mode 100644
index 000000000000..17d938071b83
--- /dev/null
+++ b/contrib/tcl/doc/binary.n
@@ -0,0 +1,532 @@
+'\"
+'\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" SCCS: @(#) binary.n 1.5 97/06/10 17:52:46
+'\"
+.so man.macros
+.TH binary n 8.0 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+binary \- Insert and extract fields from binary strings
+.SH SYNOPSIS
+\fBbinary format \fIformatString \fR?\fIarg arg ...\fR?
+.br
+\fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+This command provides facilities for manipulating binary data. The
+first form, \fBbinary format\fR, creates a binary string from normal
+Tcl values. For example, given the values 16 and 22, it might produce
+an 8-byte binary string consisting of two 4-byte integers, one for
+each of the numbers. The second form of the command,
+\fBbinary scan\fR, does the opposite: it extracts data from a binary
+string and returns it as ordinary Tcl string values.
+
+.SH "BINARY FORMAT"
+.PP
+The \fBbinary format\fR command generates a binary string whose layout
+is specified by the \fIformatString\fR and whose contents come from
+the additional arguments. The resulting binary value is returned.
+.PP
+The \fIformatString\fR consists of a sequence of zero or more field
+specifiers separated by zero or more spaces. Each field specifier is
+a single type character followed by an optional numeric \fIcount\fR.
+Most field specifiers consume one argument to obtain the value to be
+formatted. The type character specifies how the value is to be
+formatted. The \fIcount\fR typically indicates how many items of the
+specified type are taken from the value. If present, the \fIcount\fR
+is a non-negative decimal integer or \fB*\fR, which normally indicates
+that all of the items in the value are to be used. If the number of
+arguments does not match the number of fields in the format string
+that consume arguments, then an error is generated.
+.PP
+Each type-count pair moves an imaginary cursor through the binary
+data, storing bytes at the current position and advancing the cursor
+to just after the last byte stored. The cursor is initially at
+position 0 at the beginning of the data. The type may be any one of
+the following characters:
+.IP \fBa\fR 5
+Stores a character string of length \fIcount\fR in the output string.
+If \fIarg\fR has fewer than \fIcount\fR bytes, then additional zero
+bytes are used to pad out the field. If \fIarg\fR is longer than the
+specified length, the extra characters will be ignored. If
+\fIcount\fR is \fB*\fR, then all of the bytes in \fIarg\fR will be
+formatted. If \fIcount\fR is omitted, then one character will be
+formatted. For example,
+.RS
+.CS
+\fBbinary format a7a*a alpha bravo charlie\fR
+.CE
+will return a string equivalent to \fBalpha\\000\\000bravoc\fR.
+.RE
+.IP \fBA\fR 5
+This form is the same as \fBa\fR except that spaces are used for
+padding instead of nulls. For example,
+.RS
+.CS
+\fBbinary format A6A*A alpha bravo charlie\fR
+.CE
+will return \fBalpha bravoc\fR.
+.RE
+.IP \fBb\fR 5
+Stores a string of \fIcount\fR binary digits in low-to-high order
+within each byte in the output string. \fIArg\fR must contain a
+sequence of \fB1\fR and \fB0\fR characters. The resulting bytes are
+emitted in first to last order with the bits being formatted in
+low-to-high order within each byte. If \fIarg\fR has fewer than
+\fIcount\fR digits, then zeros will be used for the remaining bits.
+If \fIarg\fR has more than the specified number of digits, the extra
+digits will be ignored. If \fIcount\fR is \fB*\fR, then all of the
+digits in \fIarg\fR will be formatted. If \fIcount\fR is omitted,
+then one digit will be formatted. If the number of bits formatted
+does not end at a byte boundary, the remaining bits of the last byte
+will be zeros. For example,
+.RS
+.CS
+\fBbinary format b5b* 11100 111000011010\fR
+.CE
+will return a string equivalent to \fB\\x07\\x87\\x05\fR.
+.RE
+.IP \fBB\fR 5
+This form is the same as \fBb\fR except that the bits are stored in
+high-to-low order within each byte. For example,
+.RS
+.CS
+\fBbinary format B5B* 11100 111000011010\fR
+.CE
+will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR.
+.RE
+.IP \fBh\fR 5
+Stores a string of \fIcount\fR hexadecimal digits in low-to-high
+within each byte in the output string. \fIArg\fR must contain a
+sequence of characters in the set ``0123456789abcdefABCDEF''. The
+resulting bytes are emitted in first to last order with the hex digits
+being formatted in low-to-high order within each byte. If \fIarg\fR
+has fewer than \fIcount\fR digits, then zeros will be used for the
+remaining digits. If \fIarg\fR has more than the specified number of
+digits, the extra digits will be ignored. If \fIcount\fR is
+\fB*\fR, then all of the digits in \fIarg\fR will be formatted. If
+\fIcount\fR is omitted, then one digit will be formatted. If the
+number of digits formatted does not end at a byte boundary, the
+remaining bits of the last byte will be zeros. For example,
+.RS
+.CS
+\fBbinary format h3h* AB def\fR
+.CE
+will return a string equivalent to \fB\\xba\\xed\\x0f\fR.
+.RE
+.IP \fBH\fR 5
+This form is the same as \fBh\fR except that the digits are stored in
+high-to-low order within each byte. For example,
+.RS
+.CS
+\fBbinary format H3H* ab DEF\fR
+.CE
+will return a string equivalent to \fB\\xab\\xde\\xf0\fR.
+.RE
+.IP \fBc\fR 5
+Stores one or more 8-bit integer values in the output string. If no
+\fIcount\fR is specified, then \fIarg\fR must consist of an integer
+value; otherwise \fIarg\fR must consist of a list containing at least
+\fIcount\fR integer elements. The low-order 8 bits of each integer
+are stored as a one-byte value at the cursor position. If \fIcount\fR
+is \fB*\fR, then all of the integers in the list are formatted. If
+the number of elements in the list is fewer than \fIcount\fR, then an
+error is generated. If the number of elements in the list is greater
+than \fIcount\fR, then the extra elements are ignored. For example,
+.RS
+.CS
+\fBbinary format c3cc* {3 -3 128 1} 257 {2 5}\fR
+.CE
+will return a string equivalent to
+\fB\\x03\\xfd\\x80\\x01\\x02\\x05\fR, whereas
+.CS
+\fBbinary format c {2 5}\fR
+.CE
+will generate an error.
+.RE
+.IP \fBs\fR 5
+This form is the same as \fBc\fR except that it stores one or more
+16-bit integers in little-endian byte order in the output string. The
+low-order 16-bits of each integer are stored as a two-byte value at
+the cursor position with the least significant byte stored first. For
+example,
+.RS
+.CS
+\fBbinary format s3 {3 -3 258 1}\fR
+.CE
+will return a string equivalent to
+\fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR.
+.RE
+.IP \fBS\fR 5
+This form is the same as \fBs\fR except that it stores one or more
+16-bit integers in big-endian byte order in the output string. For
+example,
+.RS
+.CS
+\fBbinary format S3 {3 -3 258 1}\fR
+.CE
+will return a string equivalent to
+\fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR.
+.RE
+.IP \fBi\fR 5
+This form is the same as \fBc\fR except that it stores one or more
+32-bit integers in little-endian byte order in the output string. The
+low-order 32-bits of each integer are stored as a four-byte value at
+the cursor position with the least significant byte stored first. For
+example,
+.RS
+.CS
+\fBbinary format i3 {3 -3 65536 1}\fR
+.CE
+will return a string equivalent to
+\fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x10\\x00\fR.
+.RE
+.IP \fBI\fR 5
+This form is the same as \fBi\fR except that it stores one or more one
+or more 32-bit integers in big-endian byte order in the output string.
+For example,
+.RS
+.CS
+\fBbinary format I3 {3 -3 65536 1}\fR
+.CE
+will return a string equivalent to
+\fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x10\\x00\\x00\fR.
+.RE
+.IP \fBf\fR 5
+This form is the same as \fBc\fR except that it stores one or more one
+or more single-precision floating in the machine's native
+representation in the output string. This representation is not
+portable across architectures, so it should not be used to communicate
+floating point numbers across the network. The size of a floating
+point number may vary across architectures, so the number of bytes
+that are generated may vary. If the value is out of range for the
+machine's native representation, then the value of FLT_MIN or FLT_MAX
+as defined by the system will be used instead. Because Tcl uses
+double-precision floating-point numbers internally, there may be some
+loss of precision in the conversion to single-precision. For example,
+on a Windows system running on an Intel Pentium processor,
+.RS
+.CS
+\fBbinary format f2 {1.6 3.4}\fR
+.CE
+will return a string equivalent to
+\fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR.
+.RE
+.IP \fBd\fR 5
+This form is the same as \fBf\fR except that it stores one or more one
+or more double-precision floating in the machine's native
+representation in the output string. For example, on a
+Windows system running on an Intel Pentium processor,
+.RS
+.CS
+\fBbinary format d1 {1.6}\fR
+.CE
+will return a string equivalent to
+\fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR.
+.RE
+.IP \fBx\fR 5
+Stores \fIcount\fR null bytes in the output string. If \fIcount\fR is
+not specified, stores one null byte. If \fIcount\fR is \fB*\fR,
+generates an error. This type does not consume an argument. For
+example,
+.RS
+.CS
+\fBbinary format a3xa3x2a3 abc def ghi\fR
+.CE
+will return a string equivalent to \fBabc\\000def\\000\\000ghi\fR.
+.RE
+.IP \fBX\fR 5
+Moves the cursor back \fIcount\fR bytes in the output string. If
+\fIcount\fR is \fB*\fR or is larger than the current cursor position,
+then the cursor is positioned at location 0 so that the next byte
+stored will be the first byte in the result string. If \fIcount\fR is
+omitted then the cursor is moved back one byte. This type does not
+consume an argument. For example,
+.RS
+.CS
+\fBbinary format a3X*a3X2a3 abc def ghi\fR
+.CE
+will return \fBdghi\fR.
+.RE
+.IP \fB@\fR 5
+Moves the cursor to the absolute location in the output string
+specified by \fIcount\fR. Position 0 refers to the first byte in the
+output string. If \fIcount\fR refers to a position beyond the last
+byte stored so far, then null bytes will be placed in the unitialized
+locations and the cursor will be placed at the specified location. If
+\fIcount\fR is \fB*\fR, then the cursor is moved to the current end of
+the output string. If \fIcount\fR is omitted, then an error will be
+generated. This type does not consume an argument. For example,
+.RS
+.CS
+\fBbinary format a5@2a1@*a3@10a1 abcde f ghi j\fR
+.CE
+will return \fBabfdeghi\\000\\000j\fR.
+.RE
+
+.SH "BINARY SCAN"
+.PP
+The \fBbinary scan\fR command parses fields from a binary string,
+returning the number of conversions performed. \fIString\fR gives the
+input to be parsed and \fIformatString\fR indicates how to parse it.
+Each \fIvarName\fR gives the name of a variable; when a field is
+scanned from \fIstring\fR the result is assigned to the corresponding
+variable.
+.PP
+As with \fBbinary format\fR, the \fIformatString\fR consists of a
+sequence of zero or more field specifiers separated by zero or more
+spaces. Each field specifier is a single type character followed by
+an optional numeric \fIcount\fR. Most field specifiers consume one
+argument to obtain the variable into which the scanned values should
+be placed. The type character specifies how the binary data is to be
+interpreted. The \fIcount\fR typically indicates how many items of
+the specified type are taken from the data. If present, the
+\fIcount\fR is a non-negative decimal integer or \fB*\fR, which
+normally indicates that all of the remaining items in the data are to
+be used. If there are not enough bytes left after the current cursor
+position to satisfy the current field specifier, then the
+corresponding variable is left untouched and \fBbinary scan\fR returns
+immediately with the number of variables that were set. If there are
+not enough arguments for all of the fields in the format string that
+consume arguments, then an error is generated.
+.PP
+Each type-count pair moves an imaginary cursor through the binary data,
+reading bytes from the current position. The cursor is initially
+at position 0 at the beginning of the data. The type may be any one of
+the following characters:
+.IP \fBa\fR 5
+The data is a character string of length \fIcount\fR. If \fIcount\fR
+is \fB*\fR, then all of the remaining bytes in \fIstring\fR will be
+scanned into the variable. If \fIcount\fR is omitted, then one
+character will be scanned. For example,
+.RS
+.CS
+\fBbinary scan abcde\\000fghi a6a10 var1 var2\fR
+.CE
+will return \fB1\fR with the string equivalent to \fBabcde\\000\fR
+stored in \fBvar1\fR and \fBvar2\fR left unmodified.
+.RE
+.IP \fBA\fR 5
+This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from
+the scanned value before it is stored in the variable. For example,
+.RS
+.CS
+\fBbinary scan "abc efghi \\000" a* var1\fR
+.CE
+will return \fB1\fR with \fBabc efghi\fR stored in \fBvar1\fR.
+.RE
+.IP \fBb\fR 5
+The data is turned into a string of \fIcount\fR binary digits in
+low-to-high order represented as a sequence of ``1'' and ``0''
+characters. The data bytes are scanned in first to last order with
+the bits being taken in low-to-high order within each byte. Any extra
+bits in the last byte are ignored. If \fIcount\fR is \fB*\fR, then
+all of the remaining bits in \fBstring\fR will be scanned. If
+\fIcount\fR is omitted, then one bit will be scanned. For example,
+.RS
+.CS
+\fBbinary scan \\x07\\x87\\x05 b5b* var1 var2\fR
+.CE
+will return \fB2\fR with \fB11100\fR stored in \fBvar1\fR and
+\fB1110000110100000\fR stored in \fBvar2\fR.
+.RE
+.IP \fBB\fR 5
+This form is the same as \fBB\fR, except the bits are taken in
+high-to-low order within each byte. For example,
+.RS
+.CS
+\fBbinary scan \\x70\\x87\\x05 b5b* var1 var2\fR
+.CE
+will return \fB2\fR with \fB01110\fR stored in \fBvar1\fR and
+\fB1000011100000101\fR stored in \fBvar2\fR.
+.RE
+.IP \fBh\fR 5
+The data is turned into a string of \fIcount\fR hexadecimal digits in
+low-to-high order represented as a sequence of characters in the set
+``0123456789abcdef''. The data bytes are scanned in first to last
+order with the hex digits being taken in low-to-high order within each
+byte. Any extra bits in the last byte are ignored. If \fIcount\fR
+is \fB*\fR, then all of the remaining hex digits in \fBstring\fR will be
+scanned. If \fIcount\fR is omitted, then one hex digit will be
+scanned. For example,
+.RS
+.CS
+\fBbinary scan \\x07\\x86\\x05 h3h* var1 var2\fR
+.CE
+will return \fB2\fR with \fB706\fR stored in \fBvar1\fR and
+\fB50\fR stored in \fBvar2\fR.
+.RE
+.IP \fBH\fR 5
+This form is the same as \fBh\fR, except the digits are taken in
+low-to-high order within each byte. For example,
+.RS
+.CS
+\fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR
+.CE
+will return \fB2\fR with \fB078\fR stored in \fBvar1\fR and
+\fB05\fR stored in \fBvar2\fR.
+.RE
+.IP \fBc\fR 5
+The data is turned into \fIcount\fR 8-bit signed integers and stored
+in the corresponding variable as a list. If \fIcount\fR is \fB*\fR,
+then all of the remaining bytes in \fBstring\fR will be scanned. If
+\fIcount\fR is omitted, then one 8-bit integer will be scanned. For
+example,
+.RS
+.CS
+\fBbinary scan \\x07\\x86\\x05 c2c* var1 var2\fR
+.CE
+will return \fB2\fR with \fB7 -122\fR stored in \fBvar1\fR and \fB5\fR
+stored in \fBvar2\fR. Note that the integers returned are signed, but
+they can be converted to unsigned 8-bit quantities using an expression
+like:
+.CS
+\fBexpr ( $num + 0x100 ) % 0x100\fR
+.CE
+.RE
+.IP \fBs\fR 5
+The data is interpreted as \fIcount\fR 16-bit signed integers
+represented in little-endian byte order. The integers are stored in
+the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then
+all of the remaining bytes in \fBstring\fR will be scanned. If
+\fIcount\fR is omitted, then one 16-bit integer will be scanned. For
+example,
+.RS
+.CS
+\fBbinary scan \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2\fR
+.CE
+will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
+stored in \fBvar2\fR. Note that the integers returned are signed, but
+they can be converted to unsigned 16-bit quantities using an expression
+like:
+.CS
+\fBexpr ( $num + 0x10000 ) % 0x10000\fR
+.CE
+.RE
+.IP \fBS\fR 5
+This form is the same as \fBs\fR except that the data is interpreted
+as \fIcount\fR 16-bit signed integers represented in big-endian byte
+order. For example,
+.RS
+.CS
+\fBbinary scan \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2\fR
+.CE
+will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
+stored in \fBvar2\fR.
+.RE
+.IP \fBi\fR 5
+The data is interpreted as \fIcount\fR 32-bit signed integers
+represented in little-endian byte order. The integers are stored in
+the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then
+all of the remaining bytes in \fBstring\fR will be scanned. If
+\fIcount\fR is omitted, then one 32-bit integer will be scanned. For
+example,
+.RS
+.CS
+\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff i2i* var1 var2\fR
+.CE
+will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
+stored in \fBvar2\fR. Note that the integers returned are signed and
+cannot be represented by Tcl as unsigned values.
+.RE
+.IP \fBI\fR 5
+This form is the same as \fBI\fR except that the data is interpreted
+as \fIcount\fR 32-bit signed integers represented in big-endian byte
+order. For example,
+.RS
+.CS
+\fBbinary \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 I2I* var1 var2\fR
+.CE
+will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
+stored in \fBvar2\fR.
+.RE
+.IP \fBf\fR 5
+The data is interpreted as \fIcount\fR single-precision floating point
+numbers in the machine's native representation. The floating point
+numbers are stored in the corresponding variable as a list. If
+\fIcount\fR is \fB*\fR, then all of the remaining bytes in
+\fBstring\fR will be scanned. If \fIcount\fR is omitted, then one
+single-precision floating point number will be scanned. The size of a
+floating point number may vary across architectures, so the number of
+bytes that are scanned may vary. If the data does not represent a
+valid floating point number, the resulting value is undefined and
+compiler dependent. For example, on a Windows system running on an
+Intel Pentium processor,
+.RS
+.CS
+\fBbinary scan \\x3f\\xcc\\xcc\\xcd f var1\fR
+.CE
+will return \fB1\fR with \fB1.6000000238418579\fR stored in
+\fBvar1\fR.
+.RE
+.IP \fBd\fR 5
+This form is the same as \fBf\fR except that the data is interpreted
+as \fIcount\fR double-precision floating point numbers in the
+machine's native representation. For example, on a Windows system
+running on an Intel Pentium processor,
+.RS
+.CS
+\fBbinary scan \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1\fR
+.CE
+will return \fB1\fR with \fB1.6000000000000001\fR
+stored in \fBvar1\fR.
+.RE
+.IP \fBx\fR 5
+Moves the cursor forward \fIcount\fR bytes in \fIstring\fR. If
+\fIcount\fR is \fB*\fR or is larger than the number of bytes after the
+current cursor cursor position, then the cursor is positioned after
+the last byte in \fIstring\fR. If \fIcount\fR is omitted, then the
+cursor is moved forward one byte. Note that this type does not
+consume an argument. For example,
+.RS
+.CS
+\fBbinary scan \\x01\\x02\\x03\\x04 x2H* var1\fR
+.CE
+will return \fB1\fR with \fB0304\fR stored in \fBvar1\fR.
+.RE
+.IP \fBX\fR 5
+Moves the cursor back \fIcount\fR bytes in \fIstring\fR. If
+\fIcount\fR is \fB*\fR or is larger than the current cursor position,
+then the cursor is positioned at location 0 so that the next byte
+scanned will be the first byte in \fIstring\fR. If \fIcount\fR
+is omitted then the cursor is moved back one byte. Note that this
+type does not consume an argument. For example,
+.RS
+.CS
+\fBbinary scan \\x01\\x02\\x03\\x04 c2XH* var1 var2\fR
+.CE
+will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
+stored in \fBvar2\fR.
+.RE
+.IP \fB@\fR 5
+Moves the cursor to the absolute location in the data string specified
+by \fIcount\fR. Note that position 0 refers to the first byte in
+\fIstring\fR. If \fIcount\fR refers to a position beyond the end of
+\fIstring\fR, then the cursor is positioned after the last byte. If
+\fIcount\fR is omitted, then an error will be generated. For example,
+.RS
+.CS
+\fBbinary scan \\x01\\x02\\x03\\x04 c2@1H* var1 var2\fR
+.CE
+will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
+stored in \fBvar2\fR.
+.RE
+
+.SH "PLATFORM ISSUES"
+Sometimes it is desirable to format or scan integer values in the
+native byte order for the machine. Refer to the \fBbyteOrder\fR
+element of the \fBtcl_platform\fR array to decide which type character
+to use when formatting or scanning integers.
+
+.SH "SEE ALSO"
+format, scan, tclvars
+
+.SH KEYWORDS
+binary, format, scan
diff --git a/contrib/tcl/doc/break.n b/contrib/tcl/doc/break.n
index 6b3a47bd3a6d..391ba910bbe9 100644
--- a/contrib/tcl/doc/break.n
+++ b/contrib/tcl/doc/break.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) break.n 1.6 96/03/25 20:10:27
+'\" SCCS: @(#) break.n 1.7 96/10/09 08:29:26
'\"
.so man.macros
.TH break n "" Tcl "Tcl Built-In Commands"
@@ -24,7 +24,7 @@ such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
It returns a TCL_BREAK code, which causes a break exception
to occur.
The exception causes the current script to be aborted
-out to the the innermost containing loop command, which then
+out to the innermost containing loop command, which then
aborts its execution and returns normally.
Break exceptions are also handled in a few other situations, such
as the \fBcatch\fR command, Tk event bindings, and the outermost
diff --git a/contrib/tcl/doc/clock.n b/contrib/tcl/doc/clock.n
index 548ffc060392..c7777a63cd7f 100644
--- a/contrib/tcl/doc/clock.n
+++ b/contrib/tcl/doc/clock.n
@@ -1,6 +1,6 @@
'\"
'\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans.
-'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
'\"
'\" This documentation is derived from the time and date facilities of
'\" TclX, by Mark Diekhans and Karl Lehenbauer.
@@ -8,7 +8,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) clock.n 1.13 96/05/03 14:40:37
+'\" SCCS: @(#) clock.n 1.17 97/02/03 16:34:17
'\"
.so man.macros
.TH clock n 7.4 Tcl "Tcl Built-In Commands"
@@ -150,7 +150,10 @@ A specific month and day with optional year. The
acceptable formats are \fImm/dd\fR?\fI/yy\fR?, \fImonthname dd\fR
?, \fIyy\fR?, \fIdd monthname \fR?\fIyy\fR? and \fIday, dd monthname
yy\fR. The default year is the current year. If the year is less
-then 100, then 1900 is added to it.
+then 100, we treat the years 00-38 as 2000-2038 and the years 70-99
+as 1970-1999. The years 39-70 are undefined and may not be valid on
+certain platforms. (For thos platforms where it is defined then the
+years 69-99 match to 1969-1999.)
.TP
\fIrelative time\fR
A specification relative to the current time. The format is \fInumber
@@ -170,7 +173,8 @@ Next, relative specifications are used. If a date or day is
specified, and no absolute or relative time is given, midnight is
used. Finally, a correction is applied so that the correct hour of
the day is produced after allowing for daylight savings time
-differences.
+differences and the correct date is given when going from the end
+of a long month to a short month.
.RE
.TP
\fBclock seconds\fR
diff --git a/contrib/tcl/doc/concat.n b/contrib/tcl/doc/concat.n
index f24833592b5a..3a1e7a47cd4d 100644
--- a/contrib/tcl/doc/concat.n
+++ b/contrib/tcl/doc/concat.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) concat.n 1.7 96/03/25 20:11:56
+'\" SCCS: @(#) concat.n 1.8 96/08/26 12:59:54
'\"
.so man.macros
.TH concat n "" Tcl "Tcl Built-In Commands"
@@ -14,9 +14,7 @@
.SH NAME
concat \- Join lists together
.SH SYNOPSIS
-.VS
\fBconcat\fI \fR?\fIarg arg ...\fR?
-.VE
.BE
.SH DESCRIPTION
@@ -36,9 +34,7 @@ will return
.CE
as its result.
.PP
-.VS
If no \fIarg\fRs are supplied, the result is an empty string.
-.VE
.SH KEYWORDS
concatenate, join, lists
diff --git a/contrib/tcl/doc/continue.n b/contrib/tcl/doc/continue.n
index 75434a89e7df..104b89d6ee8b 100644
--- a/contrib/tcl/doc/continue.n
+++ b/contrib/tcl/doc/continue.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) continue.n 1.6 96/03/25 20:12:09
+'\" SCCS: @(#) continue.n 1.7 96/10/09 08:29:27
'\"
.so man.macros
.TH continue n "" Tcl "Tcl Built-In Commands"
@@ -24,7 +24,7 @@ such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
It returns a TCL_CONTINUE code, which causes a continue exception
to occur.
The exception causes the current script to be aborted
-out to the the innermost containing loop command, which then
+out to the innermost containing loop command, which then
continues with the next iteration of the loop.
Catch exceptions are also handled in a few other situations, such
as the \fBcatch\fR command and the outermost scripts of procedure
diff --git a/contrib/tcl/doc/exec.n b/contrib/tcl/doc/exec.n
index 6b731e2a614d..22caf805b48d 100644
--- a/contrib/tcl/doc/exec.n
+++ b/contrib/tcl/doc/exec.n
@@ -5,10 +5,10 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) exec.n 1.12 96/03/25 20:13:20
+'\" SCCS: @(#) exec.n 1.17 96/09/18 15:21:17
'\"
.so man.macros
-.TH exec n 7.0 Tcl "Tcl Built-In Commands"
+.TH exec n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -26,7 +26,6 @@ where each \fIarg\fR becomes one word of a command, and
each distinct command becomes a subprocess.
.PP
If the initial arguments to \fBexec\fR start with \fB\-\fR then
-.VS
they are treated as command-line switches and are not part
of the pipeline specification. The following switches are
currently supported:
@@ -38,17 +37,14 @@ Normally a trailing newline will be deleted.
\fB\-\|\-\fR
Marks the end of switches. The argument following this one will
be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
-.VE
.PP
If an \fIarg\fR (or pair of \fIarg\fR's) has one of the forms
described below then it is used by \fBexec\fR to control the
flow of input and output among the subprocess(es).
Such arguments will not be passed to the subprocess(es). In forms
-.VS
such as ``< \fIfileName\fR'' \fIfileName\fR may either be in a
separate argument from ``<'' or in the same argument with no
intervening space (i.e. ``<\fIfileName\fR'').
-.VE
.TP 15
|
Separates distinct commands in the pipeline. The standard output
@@ -66,12 +62,10 @@ The file named by \fIfileName\fR is opened and used as the standard
input for the first command in the pipeline.
.TP 15
<@\0\fIfileId\fR
-.VS
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
It is used as the standard input for the first command in the pipeline.
\fIFileId\fR must have been opened for reading.
-.VE
.TP 15
<<\0\fIvalue\fR
\fIValue\fR is passed to the first command as its standard input.
@@ -81,7 +75,6 @@ Standard output from the last command is redirected to the file named
\fIfileName\fR, overwriting its previous contents.
.TP 15
2>\0\fIfileName\fR
-.VS
Standard error from all commands in the pipeline is redirected to the
file named \fIfileName\fR, overwriting its previous contents.
.TP 15
@@ -89,7 +82,6 @@ file named \fIfileName\fR, overwriting its previous contents.
Both standard output from the last command and standard error from all
commands are redirected to the file named \fIfileName\fR, overwriting
its previous contents.
-.VE
.TP 15
>>\0\fIfileName\fR
Standard output from the last command is
@@ -97,7 +89,6 @@ redirected to the file named \fIfileName\fR, appending to it rather
than overwriting it.
.TP 15
2>>\0\fIfileName\fR
-.VS
Standard error from all commands in the pipeline is
redirected to the file named \fIfileName\fR, appending to it rather
than overwriting it.
@@ -126,7 +117,6 @@ value from a previous call to \fBopen\fR.
Both standard output from the last command and standard error from
all commands are redirected to \fIfileId\fR's file.
The file must have been opened for writing.
-.VE
.PP
If standard output has not been redirected then the \fBexec\fR
command returns the standard output from the last command
@@ -149,10 +139,8 @@ is a newline then that character is normally deleted
from the result or error message.
This is consistent with other Tcl return values, which don't
normally end with newlines.
-.VS
However, if \fB\-keepnewline\fR is specified then the trailing
newline is retained.
-.VE
.PP
If standard input isn't redirected with ``<'' or ``<<''
or ``<@'' then the standard input for the first command in the
@@ -160,11 +148,9 @@ pipeline is taken from the application's current standard input.
.PP
If the last \fIarg\fR is ``&'' then the pipeline will be
executed in background.
-.VS
In this case the \fBexec\fR command will return a list whose
elements are the process identifiers for all of the subprocesses
in the pipeline.
-.VE
The standard output from the last command in the pipeline will
go to the application's standard output if it hasn't been
redirected, and error output from all of
@@ -181,5 +167,191 @@ reachable from the current directory.
No ``glob'' expansion or other shell-like substitutions
are performed on the arguments to commands.
+.VS
+.SH "PORTABILITY ISSUES"
+.TP
+\fBWindows\fR (all versions)
+.
+Reading from or writing to a socket, using the ``\fB@\0\fIfileId\fR''
+notation, does not work. When reading from a socket, a 16-bit DOS
+application will hang and a 32-bit application will return immediately with
+end-of-file. When either type of application writes to a socket, the
+information is instead sent to the console, if one is present, or is
+discarded.
+.sp
+The Tk console text widget does not provide real standard IO capabilities.
+Under Tk, when redirecting from standard input, all applications will see an
+immediate end-of-file; information redirected to standard output or standard
+error will be discarded.
+.sp
+Either forward or backward slashes are accepted as path separators for
+arguments to Tcl commands. When executing an application, the path name
+specified for the application may also contain forward or backward slashes
+as path separators. Bear in mind, however, that most Windows applications
+accept arguments with forward slashes only as option delimiters and
+backslashes only in paths. Any arguments to an application that specify a
+path name with forward slashes will not automatically be converted to use
+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.
+.sp
+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 ``applba~1.def''
+instead of ``applbakery.default'').
+.sp
+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
+\fBc://windows/system\fR (two slashes together), which refers to the
+directory \fB/system\fR on the machine \fBwindows\fR (and the \fBc:/\fR is
+ignored), and is not equivalent to \fBc:/windows/system\fR, which describes
+a directory on the current computer.
+.TP
+\fBWindows NT\fR
+.
+When attempting to execute an application, \fBexec\fR first searches for the
+name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR
+are appended to the end of the specified name and it searches for
+the longer name. If a directory name was not specified as part of the
+application name, the following directories are automatically searched in
+order when attempting to locate the application:
+.sp
+.RS
+.RS
+The directory from which the Tcl executable was loaded.
+.br
+The current directory.
+.br
+The Windows NT 32-bit system directory.
+.br
+The Windows NT 16-bit system directory.
+.br
+The Windows NT home directory.
+.br
+The directories listed in the path.
+.RE
+.sp
+In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
+the caller must prepend ``\fBcmd.exe /c\0\fR'' to the desired command.
+.sp
+.RE
+.TP
+\fBWindows 95\fR
+.
+When attempting to execute an application, \fBexec\fR first searches for the
+name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR
+are appended to the end of the specified name and it searches for
+the longer name. If a directory name was not specified as part of the
+application name, the following directories are automatically searched in
+order when attempting to locate the application:
+.sp
+.RS
+.RS
+The directory from which the Tcl executable was loaded.
+.br
+The current directory.
+.br
+The Windows 95 system directory.
+.br
+The Windows 95 home directory.
+.br
+The directories listed in the path.
+.RE
+.sp
+In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
+the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command.
+.sp
+Once a 16-bit DOS application has read standard input from a console and
+then quit, all subsequently run 16-bit DOS applications will see the
+standard input as already closed. 32-bit applications do not have this
+problem and will run correctly even after a 16-bit DOS application thinks
+that standard input is closed. There is no known workaround for this bug
+at this time.
+.sp
+Redirection between the \fBNUL:\fR device and a 16-bit application does not
+always work. When redirecting from \fBNUL:\fR, some applications may hang,
+others will get an infinite stream of ``0x01'' bytes, and some will actually
+correctly get an immediate end-of-file; the behavior seems to depend upon
+something compiled into the application itself. When redirecting greater than
+4K or so to \fBNUL:\fR, some applications will hang. The above problems do not
+happen with 32-bit applications.
+.sp
+All DOS 16-bit applications are run synchronously. All standard input from
+a pipe to a 16-bit DOS application is collected into a temporary file; the
+other end of the pipe must be closed before the 16-bit DOS application
+begins executing. All standard output or error from a 16-bit DOS
+application to a pipe is collected into temporary files; the application
+must terminate before the temporary files are redirected to the next stage
+of the pipeline. This is due to a workaround for a Windows 95 bug in the
+implementation of pipes, and is how the Windows 95 command line interpreter
+handles pipes itself.
+.sp
+Certain applications, such as \fBcommand.com\fR, should not be executed
+interactively. Applications which directly access the console window,
+rather than reading from their standard input and writing to their standard
+output may fail, hang Tcl, or even hang the system if their own private
+console window is not available to them.
+.RE
+.TP
+\fBWindows 3.X\fR
+.
+When attempting to execute an application, \fBexec\fR first searches for the
+name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR
+are appended to the end of the specified name and it searches for
+the longer name. If a directory name was not specified as part of the
+application name, the following directories are automatically searched in
+order when attempting to locate the application:
+.sp
+.RS
+.RS
+The directory from which the Tcl executable was loaded.
+.br
+The current directory.
+.br
+The Windows 3.X system directory.
+.br
+The Windows 3.X home directory.
+.br
+The directories listed in the path.
+.RE
+.sp
+In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
+the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command.
+.sp
+16-bit and 32-bit DOS and Windows applications may be executed. However,
+redirection and piping of standard IO only works with 16-bit DOS
+applications. 32-bit applications always see standard input as already
+closed, and any standard output or error is discarded, no matter where in the
+pipeline the application occurs or what redirection symbols are used by the
+caller. Additionally, for 16-bit applications, standard error is always
+sent to the same place as standard output; it cannot be redirected to a
+separate location. In order to achieve pseudo-redirection for 32-bit
+applications, the 32-bit application must instead be written to take command
+line arguments that specify the files that it should read from and write to
+and open those files itself.
+.sp
+All applications, both 16-bit and 32-bit, run synchronously; each application
+runs to completion before the next one in the pipeline starts. Temporary files
+are used to simulate piping between applications. The \fBexec\fR
+command cannot be used to start an application in the background.
+.sp
+When standard input is redirected from an open file using the
+``\fB@\0\fIfileId\fR'' notation, the open file is completely read up to its
+end. This is slightly different than under Windows 95 or NT, where the child
+application consumes from the open file only as much as it wants.
+Redirecting to an open file is supported as normal.
+.RE
+.TP
+\fBMacintosh\fR
+The \fBexec\fR command is not implemented and does not exist under Macintosh.
+.TP
+\fBUnix\fR\0\0\0\0\0\0\0
+The \fBexec\fR command is fully functional and works as described.
+
+.SH "SEE ALSO"
+open(n)
+.VE
+
.SH KEYWORDS
execute, pipeline, redirection, subprocess
+
diff --git a/contrib/tcl/doc/expr.n b/contrib/tcl/doc/expr.n
index e8a80e98e4c0..e7dda17681fd 100644
--- a/contrib/tcl/doc/expr.n
+++ b/contrib/tcl/doc/expr.n
@@ -1,14 +1,14 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) expr.n 1.17 96/03/14 10:54:40
+'\" SCCS: @(#) expr.n 1.25 97/04/29 10:11:52
'\"
.so man.macros
-.TH expr n 7.4 Tcl "Tcl Built-In Commands"
+.TH expr n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -19,10 +19,8 @@ expr \- Evaluate an expression
.SH DESCRIPTION
.PP
-.VS
Concatenates \fIarg\fR's (adding separator spaces between them),
evaluates the result as a Tcl expression, and returns the value.
-.VE
The operators permitted in Tcl expressions are a subset of
the operators permitted in C expressions, and they have the
same meaning and precedence as the corresponding C operators.
@@ -41,7 +39,7 @@ non-numeric operands and string comparisons.
A Tcl expression consists of a combination of operands, operators,
and parentheses.
White space may be used between the operands and operators and
-parentheses; it is ignored by the expression processor.
+parentheses; it is ignored by the expression's instructions.
Where possible, operands are interpreted as integer values.
Integer values may be specified in decimal (the normal case), in octal (if the
first character of the operand is \fB0\fR), or in hexadecimal (if the first
@@ -50,7 +48,7 @@ If an operand does not have one of the integer formats given
above, then it is treated as a floating-point number if that is
possible. Floating-point numbers may be specified in any of the
ways accepted by an ANSI-compliant C compiler (except that the
-``f'', ``F'', ``l'', and ``L'' suffixes will not be permitted in
+\fBf\fR, \fBF\fR, \fBl\fR, and \fBL\fR suffixes will not be permitted in
most installations). For example, all of the
following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.
If no numeric interpretation is possible, then an operand is left
@@ -77,14 +75,12 @@ As a Tcl command enclosed in brackets.
The command will be executed and its result will be used as
the operand.
.IP [6]
-.VS
As a mathematical function whose arguments have any of the above
-forms for operands, such as ``\fBsin($x)\fR''. See below for a list of defined
+forms for operands, such as \fBsin($x)\fR. See below for a list of defined
functions.
-.VE
.LP
Where substitutions occur above (e.g. inside quoted strings), they
-are performed by the expression processor.
+are performed by the expression's instructions.
However, an additional layer of substitution may already have
been performed by the command parser before the expression
processor was called.
@@ -110,9 +106,7 @@ The valid operators are listed below, grouped in decreasing order
of precedence:
.TP 20
\fB\-\0\0+\0\0~\0\0!\fR
-.VS
Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
-.VE
may be applied to string operands, and bit-wise NOT may be
applied only to integers.
.TP 20
@@ -120,10 +114,8 @@ applied only to integers.
Multiply, divide, remainder. None of these operands may be
applied to string operands, and remainder may be applied only
to integers.
-.VS
The remainder will always have the same sign as the divisor and
an absolute value smaller than the divisor.
-.VE
.TP 20
\fB+\0\0\-\fR
Add and subtract. Valid for any numeric operands.
@@ -188,7 +180,6 @@ the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before
invoking the \fBexpr\fR command.
.SH "MATH FUNCTIONS"
.PP
-.VS
Tcl supports the following mathematical functions in expressions:
.DS
.ta 3c 6c 9c
@@ -201,7 +192,8 @@ Tcl supports the following mathematical functions in expressions:
Each of these functions invokes the math library function of the same
name; see the manual entries for the library functions for details
on what they do. Tcl also implements the following functions for
-conversion between integers and floating-point numbers:
+conversion between integers and floating-point numbers and the
+generation of random numbers:
.TP
\fBabs(\fIarg\fB)\fR
Returns the absolute value of \fIarg\fR. \fIArg\fR may be either
@@ -215,13 +207,23 @@ If \fIarg\fR is a floating value, returns \fIarg\fR, otherwise converts
If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts
\fIarg\fR to integer by truncation and returns the converted value.
.TP
+\fBrand()\fR
+Returns a floating point number from zero to just less than one or,
+in mathematical terms, the range [0,1). The seed comes from the
+internal clock of the machine or may be set manual with the srand
+function.
+.TP
\fBround(\fIarg\fB)\fR
If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts
\fIarg\fR to integer by rounding and returns the converted value.
+.TP
+\fBsrand(\fIarg\fB)\fR
+The \fIarg\fR, which must be an integer, is used to reset the seed for
+the random number generator. Returns the first random number from
+that seed. Each interpreter has it's own seed.
.PP
In addition to these predefined functions, applications may
define additional functions using \fBTcl_CreateMathFunc\fR().
-.VE
.SH "TYPES, OVERFLOW, AND PRECISION"
.PP
All internal computations involving integers are done with the C type
@@ -251,24 +253,13 @@ returns 1, while
\fBexpr 5 / ( [string length "abcd"] + 0.0 )\fR
.CE
both return 1.25.
-.VS
-Floating-point values are always returned with a ``.''
-or an ``e'' so that they will not look like integer values. For
+Floating-point values are always returned with a ``\fB.\fR''
+or an \fBe\fR so that they will not look like integer values. For
example,
.CS
\fBexpr 20.0/5.0\fR
.CE
-returns ``4.0'', not ``4''. The global variable \fBtcl_precision\fR
-determines the the number of significant digits that are retained
-when floating values are converted to strings (except that trailing
-zeroes are omitted). If \fBtcl_precision\fR
-is unset then 6 digits of precision are used.
-To retain all of the significant bits of an IEEE floating-point
-number set \fBtcl_precision\fR to 17; if a value is converted to
-string with 17 digits of precision and then converted back to binary
-for some later calculation, the resulting binary value is guaranteed
-to be identical to the original one.
-.VE
+returns \fB4.0\fR, not \fB4\fR.
.SH "STRING OPERATIONS"
.PP
@@ -286,14 +277,44 @@ For example, the commands
.CE
both return 1. The first comparison is done using integer
comparison, and the second is done using string comparison after
-the second operand is converted to the string ``18''.
-.VS
+the second operand is converted to the string \fB18\fR.
Because of Tcl's tendency to treat values as numbers whenever
possible, it isn't generally a good idea to use operators like \fB==\fR
when you really want string comparison and the values of the
operands could be arbitrary; it's better in these cases to use the
\fBstring compare\fR command instead.
-.VE
+
+.SH "PERFORMANCE CONSIDERATIONS"
+.PP
+Enclose expressions in braces for the best speed and the smallest
+storage requirements.
+This allows the Tcl bytecode compiler to generate the best code.
+.PP
+As mentioned above, expressions are substituted twice:
+once by the Tcl parser and once by the \fBexpr\fR command.
+For example, the commands
+.CS
+\fBset a 3\fR
+\fBset b {$a + 2}\fR
+\fBexpr $b*4\fR
+.CE
+return 11, not a multiple of 4.
+This is because the Tcl parser will first substitute \fB$a + 2\fR for
+the variable \fBb\fR,
+then the \fBexpr\fR command will evaluate the expression \fB$a + 2*4\fR.
+.PP
+Most expressions do not require a second round of substitutions.
+Either they are enclosed in braces or, if not,
+their variable and command substitutions yield numbers or strings
+that don't themselves require substitutions.
+However, because a few unbraced expressions
+need two rounds of substitutions,
+the bytecode compiler must emit
+additional instructions to handle this situation.
+The most expensive code is required for
+unbraced expressions that contain command substitutions.
+These expressions must be implemented by generating new code
+each time the expression is executed.
.SH KEYWORDS
arithmetic, boolean, compare, expression
diff --git a/contrib/tcl/doc/fcopy.n b/contrib/tcl/doc/fcopy.n
new file mode 100644
index 000000000000..cea50664114d
--- /dev/null
+++ b/contrib/tcl/doc/fcopy.n
@@ -0,0 +1,127 @@
+'\"
+'\" Copyright (c) 1993 The Regents of the University of California.
+'\" Copyright (c) 1994-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.
+'\"
+'\" SCCS: @(#) fcopy.n 1.4 97/06/19 11:10:07
+'\"
+.so man.macros
+.TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+fcopy \- Copy data from one channel to another.
+.SH SYNOPSIS
+\fBfcopy \fIinchan\fR \fIoutchan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBfcopy\fP command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR.
+The \fBfcopy\fP command leverages the buffering in the Tcl I/O system to
+avoid extra copies and to avoid buffering too much data in
+main memory when copying large files to slow destinations like
+network sockets.
+.PP
+The \fBfcopy\fP
+command transfers data from \fIinchan\fR until end of file
+or \fIsize\fP bytes have been
+transferred. If no \fB\-size\fP argument is given,
+then the copy goes until end of file.
+All the data read from \fIinchan\fR is copied to \fIoutchan\fR.
+Without the \fB\-command\fP option, \fBfcopy\fP blocks until the copy is complete
+and returns the number of bytes written to \fIoutchan\fR.
+.PP
+The \fB\-command\fP argument makes \fBfcopy\fP work in the background.
+In this case it returns immediately and the \fIcallback\fP is invoked
+later when the copy completes.
+The \fIcallback\fP is called with
+one or two additional
+arguments that indicates how many bytes were written to \fIoutchan\fR.
+If an error occurred during the background copy, the second argument is the
+error string associated with the error.
+With a background copy,
+it is not necessary to put \fIinchan\fR or \fIoutchan\fR into
+non-blocking mode; the \fBfcopy\fP command takes care of that automatically.
+However, it is necessary to enter the event loop by using
+the \fBvwait\fP command or by using Tk.
+.PP
+You are not allowed to do other I/O operations with
+\fIinchan\fR or \fIoutchan\fR during a background fcopy.
+If either \fIinchan\fR or \fIoutchan\fR get closed
+while the copy is in progress, the current copy is stopped
+and the command callback is \fInot\fP made.
+If \fIinchan\fR is closed,
+then all data already queued for \fIoutchan\fR is written out.
+.PP
+Note that \fIinchan\fR can become readable during a background copy.
+You should turn off any \fBfileevent\fP handlers during a background
+copy so those handlers do not interfere with the copy.
+Any I/O attempted by a \fBfileevent\fP handler will get a "channel busy" error.
+.PP
+\fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR
+according to the \fB\-translation\fR option
+for these channels.
+See the manual entry for \fBfconfigure\fR for details on the
+\fB\-translation\fR option.
+The translations mean that the number of bytes read from \fIinchan\fR
+can be different than the number of bytes written to \fIoutchan\fR.
+Only the number of bytes written to \fIoutchan\fR is reported,
+either as the return value of a synchronous \fBfcopy\fP or
+as the argument to the callback for an asynchronous \fBfcopy\fP.
+
+.SH EXAMPLE
+.PP
+This first example shows how the callback gets
+passed the number of bytes transferred.
+It also uses vwait to put the application into the event loop.
+Of course, this simplified example could be done without the command
+callback.
+.DS
+proc Cleanup {in out bytes {error {}}} {
+ global total
+ set total $bytes
+ close $in
+ close $out
+ if {[string length $error] != 0} {
+ # error occurred during the copy
+ }
+}
+set in [open $file1]
+set out [socket $server $port]
+fcopy $in $out -command [list Cleanup $in $out]
+vwait total
+
+.DE
+.PP
+The second example copies in chunks and tests for end of file
+in the command callback
+.DS
+proc CopyMore {in out chunk bytes {error {}}} {
+ global total done
+ incr total $bytes
+ if {([string length $error] != 0) || [eof $in] {
+ set done $total
+ close $in
+ close $out
+ } else {
+ fcopy $in $out -command [list CopyMore $in $out $chunk] \\
+ -size $chunk
+ }
+}
+set in [open $file1]
+set out [socket $server $port]
+set chunk 1024
+set total 0
+fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
+vwait done
+
+.DE
+
+.SH "SEE ALSO"
+eof(n), fblocked(n), fconfigure(n)
+
+.SH KEYWORDS
+blocking, channel, end of line, end of file, nonblocking, read, translation
diff --git a/contrib/tcl/doc/file.n b/contrib/tcl/doc/file.n
index 1451fc300c64..5b3a1f5fa222 100644
--- a/contrib/tcl/doc/file.n
+++ b/contrib/tcl/doc/file.n
@@ -5,10 +5,10 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) file.n 1.13 96/04/11 17:03:13
+'\" SCCS: @(#) file.n 1.23 97/04/30 11:37:10
'\"
.so man.macros
-.TH file n 7.5 Tcl "Tcl Built-In Commands"
+.TH file n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -19,25 +19,92 @@ file \- Manipulate file names and attributes
.SH DESCRIPTION
.PP
-.VS
This command provides several operations on a file's name or attributes.
-\fIName\fR is the name of a file;
-if it starts with a tilde, then tilde substitution is done before
-executing the command (see the manual entry for \fBfilename\fR
-for details).
-.VE
-\fIOption\fR indicates what to do with the file name. Any unique
-abbreviation for \fIoption\fR is acceptable. The valid options are:
+\fIName\fR is the name of a file; if it starts with a tilde, then tilde
+substitution is done before executing the command (see the manual entry for
+\fBfilename\fR for details). \fIOption\fR indicates what to do with the
+file name. Any unique abbreviation for \fIoption\fR is acceptable. The
+valid options are:
.TP
\fBfile atime \fIname\fR
+.
Returns a decimal string giving the time at which file \fIname\fR
was last accessed. The time is measured in the standard POSIX
fashion as seconds from a fixed starting time (often January 1, 1970).
If the file doesn't exist or its access time cannot be queried then an
error is generated.
+.VS
+.TP
+\fBfile attributes \fIname\fR
+.br
+\fBfile attributes \fIname\fR ?\fBoption\fR?
+.br
+\fBfile attributes \fIname\fR ?\fBoption value option value...\fR?
+.RS
+This subcommand returns or sets platform specific values associated
+with a file. The first form returns a list of the platform specific
+flags and their values. The second form returns the value for the
+specific option. The third form sets one or more of the values. The
+values are as follows:
+.PP
+On Unix, \fB-group\fR gets or sets the group name for the file. A group id can
+be given to the command, but it returns a group name. \fB-owner\fR
+gets or sets the user name of the owner of the file. The command
+returns the owner name, but the numerical id can be passed when
+setting the owner. \fB-permissions\fR sets or retrieves the octal code
+that chmod(1) uses. This command does not support the symbolic
+attributes for chmod(1) at this time.
+.PP
+On Windows, \fB-archive\fR gives the value or sets or clears the
+archive attribute of the file. \fB-hidden\fR gives the value or sets
+or clears the hidden attribute of the file. \fB-longname\fR will
+expand each path element to its long version. This attribute cannot be
+set. \fB-readonly\fR gives the value or sets or clears the readonly
+attribute of the file. \fB-shortname\fR gives a string where every
+path element is replaced with its short (8.3) version of the
+name. This attribute cannot be set. \fB-system\fR gives or sets or
+clears the value of the system attribute of the file.
+.PP
+On Macintosh, \fB-creator\fR gives or sets the Finder creator type of
+the file. \fB-hidden\fR gives or sets or clears the hidden attribute
+of the file. \fB-readonly\fR gives or sets or clears the readonly
+attribute of the file. Note that directories can only be locked if
+File Sharing is turned on. \fB-type\fR gives or sets the Finder file
+type for the file.
+.RE
+.VE
+.PP
+\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
+.br
+\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
+.RS
+The first form makes a copy of the file or directory \fIsource\fR under
+the pathname \fItarget\fR. If \fItarget\fR is an existing directory,
+then the second form is used. The second form makes a copy inside
+\fItargetDir\fR of each \fIsource\fR file listed. If a directory is
+specified as a \fIsource\fR, then the contents of the directory will be
+recursively copied into \fItargetDir\fR. Existing files will not be
+overwritten unless the \fB\-force\fR option is specified. Trying to
+overwrite a non-empty directory, overwrite a directory with a file, or a
+file with a directory will all result in errors even if \fI\-force\fR was
+specified. Arguments are processed in the order specified, halting at the
+first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument
+following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it
+starts with a \fB\-\fR.
+.RE
+.TP
+\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?
+.
+Removes the file or directory specified by each \fIpathname\fR argument.
+Non-empty directories will be removed only if the \fB\-force\fR option is
+specified. Trying to delete a non-existant file is not considered an
+error. Trying to delete a read-only file will cause the file to be deleted,
+even if the \fB\-force\fR flags is not specified. Arguments are processed
+in the order specified, halting at the first error, if any. A \fB\-\|\-\fR
+marks the end of switches; the argument following the \fB\-\|\-\fR will be
+treated as a \fIpathname\fR even if it starts with a \fB\-\fR.
.TP
\fBfile dirname \fIname\fR
-.VS
Returns a name comprised of all of the path components in \fIname\fR
excluding the last element. If \fIname\fR is a relative file name and
only contains one path element, then returns ``\fB.\fR'' (or ``\fB:\fR''
@@ -50,7 +117,7 @@ root directory is returned. For example,
returns \fBc:/\fR.
.PP
Note that tilde substitution will only be
-performed if it is necessary to complete the command. For example,
+performed if it is necessary to complete the command. For example,
.CS
\fBfile dirname ~/src/foo.c\fR
.CE
@@ -60,36 +127,35 @@ returns \fB~/src\fR, whereas
.CE
returns \fB/home\fR (or something similar).
.RE
-.VE
.TP
\fBfile executable \fIname\fR
-Returns \fB1\fR if file \fIname\fR is executable by
-the current user, \fB0\fR otherwise.
-Under UNIX this command uses the real user and group identifiers,
-not the effective ones.
+.
+Returns \fB1\fR if file \fIname\fR is executable by the current user,
+\fB0\fR otherwise.
.TP
\fBfile exists \fIname\fR
+.
Returns \fB1\fR if file \fIname\fR exists and the current user has
search privileges for the directories leading to it, \fB0\fR otherwise.
.TP
\fBfile extension \fIname\fR
-Returns all of the characters in \fIname\fR after and including the
-last dot in the last element of \fIname\fR. If there is no dot in
-the last element of \fIname\fR then returns
-the empty string.
+.
+Returns all of the characters in \fIname\fR after and including the last
+dot in the last element of \fIname\fR. If there is no dot in the last
+element of \fIname\fR then returns the empty string.
.TP
\fBfile isdirectory \fIname\fR
-Returns \fB1\fR if file \fIname\fR is a directory,
-\fB0\fR otherwise.
+.
+Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise.
.TP
\fBfile isfile \fIname\fR
-Returns \fB1\fR if file \fIname\fR is a regular file,
-\fB0\fR otherwise.
-.VS br
+.
+Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise.
.TP
\fBfile join \fIname\fR ?\fIname ...\fR?
-Takes one or more file names and combines them, using the correct
-path separator for the current platform. If a particular \fIname\fR is
+.
+Takes one or more file names and combines them, using the correct path
+separator for the current platform. If a particular \fIname\fR is
relative, then it will be joined to the previous file name argument.
Otherwise, any earlier arguments will be discarded, and joining will
proceed from the current argument. For example,
@@ -103,9 +169,9 @@ Note that any of the names can contain separators, and that the result
is always canonical for the current platform: \fB/\fR for Unix and
Windows, and \fB:\fR for Macintosh.
.RE
-.VE
.TP
\fBfile lstat \fIname varName\fR
+.
Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
kernel call instead of \fIstat\fR. This means that if \fIname\fR
refers to a symbolic link the information returned in \fIvarName\fR
@@ -113,19 +179,38 @@ is for the link rather than the file it refers to. On systems that
don't support symbolic links this option behaves exactly the same
as the \fBstat\fR option.
.TP
+\fBfile mkdir \fIdir\fR ?\fIdir\fR ...?
+.
+Creates each directory specified. For each pathname \fIdir\fR specified,
+this command will create all non-existing parent directories as
+well as \fIdir\fR itself. If an existing directory is specified, then
+no action is taken and no error is returned. Trying to overwrite an existing
+file with a directory will result in an error. Arguments are processed in
+the order specified, halting at the first error, if any.
+.TP
\fBfile mtime \fIname\fR
-Returns a decimal string giving the time at which file \fIname\fR
-was last modified. The time is measured in the standard POSIX
-fashion as seconds from a fixed starting time (often January 1, 1970).
-If the file doesn't exist or its modified time cannot be queried then an
-error is generated.
+.
+Returns a decimal string giving the time at which file \fIname\fR was
+last modified. The time is measured in the standard POSIX fashion as
+seconds from a fixed starting time (often January 1, 1970). If the file
+doesn't exist or its modified time cannot be queried then an error is
+generated.
+.VS
.TP
-\fBfile owned \fIname\fR
-Returns \fB1\fR if file \fIname\fR is owned by the current user,
-\fB0\fR otherwise.
-.VS br
+\fBfile nativename \fIname\fR
+.
+Returns the platform-specific name of the file. This is useful if the
+filename is needed to pass to a platform-specific call, such as exec
+under Windows or AppleScript on the Macintosh.
+.VE
+.TP
+\fBfile owned \fIname\fR
+.
+Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR
+otherwise.
.TP
\fBfile pathtype \fIname\fR
+.
Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If
\fIname\fR refers to a specific file on a specific volume, the path type
will be \fBabsolute\fR. If \fIname\fR refers to a file relative to the
@@ -133,37 +218,55 @@ current working directory, then the path type will be \fBrelative\fR. If
\fIname\fR refers to a file relative to the current working directory on
a specified volume, or to a specific file on the current working volume, then
the file type is \fBvolumerelative\fR.
-.VE
.TP
\fBfile readable \fIname\fR
-Returns \fB1\fR if file \fIname\fR is readable by
-the current user, \fB0\fR otherwise.
-Under UNIX this command uses the real user and group identifiers,
-not the effective ones.
+.
+Returns \fB1\fR if file \fIname\fR is readable by the current user,
+\fB0\fR otherwise.
.TP
\fBfile readlink \fIname\fR
-Returns the value of the symbolic link given by \fIname\fR (i.e. the
-name of the file it points to). If
-\fIname\fR isn't a symbolic link or its value cannot be read, then
-an error is returned. On systems that don't support symbolic links
-this option is undefined.
+.
+Returns the value of the symbolic link given by \fIname\fR (i.e. the name
+of the file it points to). If \fIname\fR isn't a symbolic link or its
+value cannot be read, then an error is returned. On systems that don't
+support symbolic links this option is undefined.
+.PP
+\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
+.br
+\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
+.RS
+The first form takes the file or directory specified by pathname
+\fIsource\fR and renames it to \fItarget\fR, moving the file if the
+pathname \fItarget\fR specifies a name in a different directory. If
+\fItarget\fR is an existing directory, then the second form is used. The
+second form moves each \fIsource\fR file or directory into the directory
+\fItargetDir\fR. Existing files will not be overwritten unless the
+\fB\-force\fR option is specified. Trying to overwrite a non-empty
+directory, overwrite a directory with a file, or a file with a directory
+will all result in errors. Arguments are processed in the order specified,
+halting at the first error, if any. A \fB\-\|\-\fR marks the end of
+switches; the argument following the \fB\-\|\-\fR will be treated as a
+\fIsource\fR even if it starts with a \fB\-\fR.
+.RE
.TP
\fBfile rootname \fIname\fR
-Returns all of the characters in \fIname\fR up to but not including
-the last ``.'' character in the last component of name. If the last
+.
+Returns all of the characters in \fIname\fR up to but not including the
+last ``.'' character in the last component of name. If the last
component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
.TP
\fBfile size \fIname\fR
-Returns a decimal string giving the size of file \fIname\fR in bytes.
-If the file doesn't exist or its size cannot be queried then an
-error is generated.
-.VS br
+.
+Returns a decimal string giving the size of file \fIname\fR in bytes. If
+the file doesn't exist or its size cannot be queried then an error is
+generated.
.TP
\fBfile split \fIname\fR
+.
Returns a list whose elements are the path components in \fIname\fR. The
first element of the list will have the same path type as \fIname\fR.
All other elements will be relative. Path separators will be discarded
-unless they are needed ensure that an element is unambiguously relative.
+unless they are needed ensure that an element is unambiguously relative.
For example, under Unix
.RS
.CS
@@ -173,45 +276,56 @@ returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands
that use the third component do not attempt to perform tilde
substitution.
.RE
-.VE
.TP
\fBfile stat \fIname varName\fR
-Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the
-variable given by \fIvarName\fR to hold information returned from
-the kernel call.
-\fIVarName\fR is treated as an array variable,
-and the following elements of that variable are set: \fBatime\fR,
-\fBctime\fR, \fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, \fBmtime\fR,
-\fBnlink\fR, \fBsize\fR, \fBtype\fR, \fBuid\fR.
-Each element except \fBtype\fR is a decimal string with the value of
-the corresponding field from the \fBstat\fR return structure; see the
-manual entry for \fBstat\fR for details on the meanings of the values.
-The \fBtype\fR element gives the type of the file in the same form
-returned by the command \fBfile type\fR.
-This command returns an empty string.
+.
+Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable
+given by \fIvarName\fR to hold information returned from the kernel call.
+\fIVarName\fR is treated as an array variable, and the following elements
+of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR,
+\fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR,
+\fBuid\fR. Each element except \fBtype\fR is a decimal string with the
+value of the corresponding field from the \fBstat\fR return structure;
+see the manual entry for \fBstat\fR for details on the meanings of the
+values. The \fBtype\fR element gives the type of the file in the same
+form returned by the command \fBfile type\fR. This command returns an
+empty string.
.TP
\fBfile tail \fIname\fR
-.VS
+.
Returns all of the characters in \fIname\fR after the last directory
separator. If \fIname\fR contains no separators then returns
\fIname\fR.
-.VE
.TP
\fBfile type \fIname\fR
-Returns a string giving the type of file \fIname\fR, which will be
-one of \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR,
-\fBblockSpecial\fR, \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
+.
+Returns a string giving the type of file \fIname\fR, which will be one of
+\fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR,
+\fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
+.TP
+\fBfile volume\fR
+.
+Returns the absolute paths to the volumes mounted on the system, as a proper
+Tcl list. On the Macintosh, this will be a list of the mounted drives,
+both local and network. N.B. if two drives have the same name, they will
+both appear on the volume list, but there is currently no way, from Tcl, to
+access any but the first of these drives. On UNIX, the command will always return
+"/", since all filesystems are locally mounted. On Windows, it will return
+a list of the available local drives (e.g. {a:/ c:/}).
.TP
\fBfile writable \fIname\fR
-Returns \fB1\fR if file \fIname\fR is writable by
-the current user, \fB0\fR otherwise.
-Under UNIX this command uses the real user and group identifiers,
-not the effective ones.
+.
+Returns \fB1\fR if file \fIname\fR is writable by the current user,
+\fB0\fR otherwise.
+.SH "PORTABILITY ISSUES"
+.TP
+\fBUnix\fR\0\0\0\0\0\0\0
+.
+These commands always operate using the real user and group identifiers,
+not the effective ones.
-.VS
.SH "SEE ALSO"
filename
-.VE
.SH KEYWORDS
-attributes, directory, file, name, stat
+attributes, copy files, delete files, directory, file, move files, name, rename files, stat
diff --git a/contrib/tcl/doc/flush.n b/contrib/tcl/doc/flush.n
index 4a224a85590a..f69354a5e0e8 100644
--- a/contrib/tcl/doc/flush.n
+++ b/contrib/tcl/doc/flush.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) flush.n 1.9 96/02/15 20:02:05
+'\" SCCS: @(#) flush.n 1.10 96/08/26 12:59:57
'\"
.so man.macros
.TH flush n 7.5 Tcl "Tcl Built-In Commands"
@@ -22,13 +22,11 @@ flush \- Flush buffered output for a channel
Flushes any output that has been buffered for \fIchannelId\fR.
\fIChannelId\fR must be a channel identifier such as returned by a previous
\fBopen\fR or \fBsocket\fR command, and it must have been opened for writing.
-.VS
If the channel is in blocking mode the command does not return until all the
buffered output has been flushed to the channel. If the channel is in
nonblocking mode, the command may return before all buffered output has been
flushed; the remainder will be flushed in the background as fast as the
underlying file or device is able to absorb it.
-.VE
.SH "SEE ALSO"
open(n), socket(n)
diff --git a/contrib/tcl/doc/for.n b/contrib/tcl/doc/for.n
index 11e5d017e9a4..3680cf44f598 100644
--- a/contrib/tcl/doc/for.n
+++ b/contrib/tcl/doc/for.n
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) for.n 1.5 96/03/25 20:15:01
+'\" SCCS: @(#) for.n 1.6 97/04/08 17:13:49
'\"
.so man.macros
.TH for n "" Tcl "Tcl Built-In Commands"
@@ -39,6 +39,22 @@ return immediately.
The operation of \fBbreak\fR and \fBcontinue\fR are similar to the
corresponding statements in C.
\fBFor\fR returns an empty string.
+.PP
+Note: \fItest\fR should almost always be enclosed in braces. If not,
+variable substitutions will be made before the \fBfor\fR
+command starts executing, which means that variable changes
+made by the loop body will not be considered in the expression.
+This is likely to result in an infinite loop. If \fItest\fR is
+enclosed in braces, variable substitutions are delayed until the
+expression is evaluated (before
+each loop iteration), so changes in the variables will be visible.
+For an example, try the following script with and without the braces
+around \fB$x<10\fR:
+.CS
+for {set x 0} {$x<10} {incr x} {
+ puts "x is $x"
+}
+.CE
.SH KEYWORDS
for, iteration, looping
diff --git a/contrib/tcl/doc/format.n b/contrib/tcl/doc/format.n
index a207fa308f0c..57c97d6dd01c 100644
--- a/contrib/tcl/doc/format.n
+++ b/contrib/tcl/doc/format.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) format.n 1.10 96/03/25 20:15:25
+'\" SCCS: @(#) format.n 1.11 96/08/26 12:59:57
'\"
.so man.macros
.TH format n "" Tcl "Tcl Built-In Commands"
@@ -44,16 +44,13 @@ The \fBformat\fR command must be given enough \fIarg\fRs to meet the needs
of all of the conversion specifiers in \fIformatString\fR.
.PP
Each conversion specifier may contain up to six different parts:
-.VS
an XPG3 position specifier,
-.VE
a set of flags, a minimum field width, a precision, a length modifier,
and a conversion character.
Any of these fields may be omitted except for the conversion character.
The fields that are present must appear in the order given above.
The paragraphs below discuss each of these fields in turn.
.PP
-.VS
If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in
``\fB%2$d\fR'', then the value to convert is not taken from the
next sequential argument.
@@ -66,7 +63,6 @@ given by the number.
This follows the XPG3 conventions for positional specifiers.
If there are any positional specifiers in \fIformatString\fR
then all of the specifiers must be positional.
-.VE
.PP
The second portion of a conversion specifier may contain any of the
following flag characters, in any order:
@@ -196,25 +192,21 @@ the conversion specifier.
.SH "DIFFERENCES FROM ANSI SPRINTF"
.PP
-.VS
The behavior of the format command is the same as the
ANSI C \fBsprintf\fR procedure except for the following
differences:
.IP [1]
\fB%p\fR and \fB%n\fR specifiers are not currently supported.
-.VE
.IP [2]
For \fB%c\fR conversions the argument must be a decimal string,
which will then be converted to the corresponding character value.
.IP [3]
-.VS
The \fBl\fR modifier is ignored; integer values are always converted
as if there were no modifier present and real values are always
converted as if the \fBl\fR modifier were present (i.e. type
\fBdouble\fR is used for the internal representation).
If the \fBh\fR modifier is specified then integer values are truncated
to \fBshort\fR before conversion.
-.VE
.SH KEYWORDS
conversion specifier, format, sprintf, string, substitution
diff --git a/contrib/tcl/doc/gets.n b/contrib/tcl/doc/gets.n
index 175a831f4239..025f76dacf0a 100644
--- a/contrib/tcl/doc/gets.n
+++ b/contrib/tcl/doc/gets.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) gets.n 1.12 96/02/15 20:02:08
+'\" SCCS: @(#) gets.n 1.13 96/08/26 12:59:58
'\"
.so man.macros
.TH gets n 7.5 Tcl "Tcl Built-In Commands"
@@ -28,7 +28,6 @@ If \fIvarName\fR is specified then the line is placed in the variable by
that name and the return value is a count of the number of characters
returned.
.PP
-.VS
If end of file occurs while scanning for an end of
line, the command returns whatever input is available up to the end of file.
If \fIchannelId\fR is in nonblocking mode and there is not a full
@@ -43,7 +42,6 @@ produce the same results as if there were an input line consisting
only of the end-of-line character(s).
The \fBeof\fR and \fBfblocked\fR commands can be used to distinguish
these three cases.
-.VE
.SH "SEE ALSO"
eof(n), fblocked(n)
diff --git a/contrib/tcl/doc/glob.n b/contrib/tcl/doc/glob.n
index 11c6cc7e5009..2097534fceac 100644
--- a/contrib/tcl/doc/glob.n
+++ b/contrib/tcl/doc/glob.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) glob.n 1.10 96/03/25 20:15:48
+'\" SCCS: @(#) glob.n 1.11 96/08/26 12:59:59
'\"
.so man.macros
.TH glob n 7.5 Tcl "Tcl Built-In Commands"
@@ -24,7 +24,6 @@ the csh shell. It returns a list of the files whose names match any
of the \fIpattern\fR arguments.
.LP
If the initial arguments to \fBglob\fR start with \fB\-\fR then
-.VS
they are treated as switches. The following switches are
currently supported:
.TP 15
@@ -35,7 +34,6 @@ switch an error is returned if the result list would be empty.
\fB\-\|\-\fR
Marks the end of switches. The argument following this one will
be treated as a \fIpattern\fR even if it starts with a \fB\-\fR.
-.VE
.PP
The \fIpattern\fR arguments may contain any of the following
special characters:
@@ -69,7 +67,6 @@ the HOME environment variable is used.
The \fBglob\fR command differs from csh globbing in two ways.
First, it does not sort its result list (use the \fBlsort\fR
command if you want the list sorted).
-.VS
Second, \fBglob\fR only returns the names of files that actually
exist; in csh no check for existence is made unless a pattern
contains a ?, *, or [] construct.
@@ -82,7 +79,6 @@ native and network names are specified), the \fBglob\fR command only
accepts native names. Also, for Windows UNC names, the servername and
sharename components of the path may not contain ?, *, or []
constructs.
-.VE
.SH KEYWORDS
exist, file, glob, pattern
diff --git a/contrib/tcl/doc/global.n b/contrib/tcl/doc/global.n
index 17ac62f823d7..a89cbef37783 100644
--- a/contrib/tcl/doc/global.n
+++ b/contrib/tcl/doc/global.n
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) global.n 1.5 96/03/25 20:16:10
+'\" SCCS: @(#) global.n 1.6 97/05/18 15:23:09
'\"
.so man.macros
.TH global n "" Tcl "Tcl Built-In Commands"
@@ -21,10 +21,15 @@ global \- Access global variables
.PP
This command is ignored unless a Tcl procedure is being interpreted.
If so then it declares the given \fIvarname\fR's to be global variables
-rather than local ones. For the duration of the current procedure
-(and only while executing in the current procedure), any reference to
-any of the \fIvarname\fRs will refer to the global variable by the same
-name.
+rather than local ones.
+Global variables are variables in the global namespace.
+For the duration of the current procedure
+(and only while executing in the current procedure),
+any reference to any of the \fIvarname\fRs
+will refer to the global variable by the same name.
+
+.SH "SEE ALSO"
+namespace(n), variable(n)
.SH KEYWORDS
-global, procedure, variable
+global, namespace, procedure, variable
diff --git a/contrib/tcl/doc/http.n b/contrib/tcl/doc/http.n
new file mode 100644
index 000000000000..5a5b2d28b246
--- /dev/null
+++ b/contrib/tcl/doc/http.n
@@ -0,0 +1,359 @@
+'\"
+'\" Copyright (c) 1995-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.
+'\"
+'\" SCCS: @(#) http.n 1.10 97/06/24 17:15:09
+'\"
+.so man.macros
+.TH "Http" n 8.0 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+Http \- Client-side implementation of the HTTP/1.0 protocol.
+.SH SYNOPSIS
+\fBpackage require http ?1.0?\fP
+.sp
+\fBhttp_config \fI?options?\fR
+.sp
+\fBhttp_get \fIurl ?options?\fR
+.sp
+\fBhttp_formatQuery \fIlist\fR
+.sp
+\fBhttp_reset \fItoken\fR
+.sp
+\fBhttp_wait \fItoken\fR
+.sp
+\fBhttp_status \fItoken\fR
+.sp
+\fBhttp_size \fItoken\fR
+.sp
+\fBhttp_code \fItoken\fR
+.sp
+\fBhttp_data \fItoken\fR
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBhttp\fR package provides the client side of the HTTP/1.0
+protocol. The package implements the GET, POST, and HEAD operations
+of HTTP/1.0. It allows configuration of a proxy host to get through
+firewalls. The package is compatible with the \fBSafesock\fR security
+policy, so it can be used by untrusted applets to do URL fetching from
+a restricted set of hosts.
+.PP
+The \fBhttp_get\fR procedure does a HTTP transaction.
+Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction
+is performed.
+The return value of \fBhttp_get\fR is a token for the transaction.
+The value is also the name of a global array that contains state
+information about the transaction. The elements of this array are
+described in the STATE ARRAY section.
+.PP
+If the \fB-command\fP option is specified, then
+the HTTP operation is done in the background.
+\fBhttp_get\fR returns immediately after generating the
+HTTP request and the callback is invoked
+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 \fBhttp_wait\fR after calling
+\fBhttp_get\fR to start the event loop.
+.SH COMMANDS
+.TP
+\fBhttp_config\fP ?\fIoptions\fR?
+The \fBhttp_config\fR command is used to set and query the name of the
+proxy server and port, and the User-Agent name used in the HTTP
+requests. If no options are specified, then the current configuration
+is returned. If a single argument is specified, then it should be one
+of the flags described below. In this case the current value of
+that setting is returned. Otherwise, the options should be a set of
+flags and values that define the configuration:
+.RS
+.TP
+\fB\-accept\fP \fImimetypes\fP
+The Accept header of the request. The default is */*, which means that
+all types of documents are accepted. Otherwise you can supply a
+comma separated list of mime type patterns that you are
+willing to receive. For example, "image/gif, image/jpeg, text/*".
+.TP
+\fB\-proxyhost\fP \fIhostname\fP
+The name of the proxy host, if any. If this value is the
+empty string, the URL host is contacted directly.
+.TP
+\fB\-proxyport\fP \fInumber\fP
+The proxy port number.
+.TP
+\fB\-proxyfilter\fP \fIcommand\fP
+The command is a callback that is made during
+\fBhttp_get\fR
+to determine if a proxy is required for a given host. One argument, a
+host name, is added to \fIcommand\fR when it is invoked. If a proxy
+is required, the callback should return a two element list containing
+the proxy server and proxy port. Otherwise the filter should return
+an empty list. The default filter returns the values of the
+\fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
+non-empty.
+.TP
+\fB\-useragent\fP \fIstring\fP
+The value of the User-Agent header in the HTTP request. The default
+is \fB"Tcl http client package 1.0."\fR
+.RE
+.TP
+\fBhttp_get\fP \fIurl\fP ?\fIoptions\fP?
+The \fBhttp_get \fR command is the main procedure in the package.
+The \fB\-query\fR option causes a POST operation and
+the \fB\-validate\fR option causes a HEAD operation;
+otherwise, a GET operation is performed. The \fBhttp_get\fR command
+returns a \fItoken\fR value that can be used to get
+information about the transaction. See the STATE ARRAY section for
+details. The \fBhttp_get\fR command blocks until the operation
+completes, unless the \fB\-command\fR option specifies a callback
+that is invoked when the HTTP transaction completes.
+\fBhttp_get\fR takes several options:
+.RS
+.TP
+\fB\-blocksize\fP \fIsize\fP
+The blocksize used when reading the URL.
+At most
+\fIsize\fR
+bytes are read at once. After each block, a call to the
+\fB\-progress\fR
+callback is made.
+.TP
+\fB\-channel\fP \fIname\fP
+Copy the URL contents to channel \fIname\fR instead of saving it in
+\fBstate(body)\fR.
+.TP
+\fB\-command\fP \fIcallback\fP
+Invoke \fIcallback\fP after the HTTP transaction completes.
+This option causes \fBhttp_get\fP to return immediately.
+The \fIcallback\fP gets an additional argument that is the \fItoken\fR returned
+from \fBhttp_get\fR. This token is the name of a global array that is
+described in the STATE ARRAY section. Here is a template for the
+callback:
+.RS
+.CS
+proc httpCallback {token} {
+ upvar #0 $token state
+ # Access state as a Tcl array
+}
+.CE
+.RE
+.TP
+\fB\-handler\fP \fIcallback\fP
+Invoke \fIcallback\fP whenever HTTP data is available; if present, nothing
+else will be done with the HTTP data. This procedure gets two additional
+arguments: the socket for the HTTP data and the \fItoken\fR returned from
+\fBhttp_get\fR. The token is the name of a global array that is described
+in the STATE ARRAY section. The procedure is expected to return the number
+of bytes read from the socket. Here is a template for the callback:
+.RS
+.CS
+proc httpHandlerCallback {socket token} {
+ upvar #0 $token state
+ # Access socket, and state as a Tcl array
+ ...
+ (example: set data [read $socket 1000];set nbytes [string length $data])
+ ...
+ return nbytes
+}
+.CE
+.RE
+.TP
+\fB\-headers\fP \fIkeyvaluelist\fP
+This option is used to add extra headers to the HTTP request. The
+\fIkeyvaluelist\fR argument must be a list with an even number of
+elements that alternate between keys and values. The keys become
+header field names. Newlines are stripped from the values so the
+header cannot be corrupted. For example, if \fIkeyvaluelist\fR is
+\fBPragma no-cache\fR then the following header is included in the
+HTTP request:
+.CS
+Pragma: no-cache
+.CE
+.TP
+\fB\-progress\fP \fIcallback\fP
+The \fIcallback\fR is made after each transfer of data from the URL.
+The callback gets three additional arguments: the \fItoken\fR from
+\fBhttp_get\fR, the expected total size of the contents from the
+\fBContent-Length\fR meta-data, and the current number of bytes
+transferred so far. The expected total size may be unknown, in which
+case zero is passed to the callback. Here is a template for the
+progress callback:
+.RS
+.CS
+proc httpProgress {token total current} {
+ upvar #0 $token state
+}
+.CE
+.RE
+.TP
+\fB\-query\fP \fIquery\fP
+This flag causes \fBhttp_get\fR to do a POST request that passes the
+\fIquery\fR to the server. The \fIquery\fR must be a x-url-encoding
+formatted query. The \fBhttp_formatQuery\fR procedure can be used to
+do the formatting.
+.TP
+\fB\-timeout\fP \fImilliseconds\fP
+If \fImilliseconds\fR is non-zero, then \fBhttp_get\fR sets up a timeout
+to occur after the specified number of milliseconds.
+A timeout results in a call to \fBhttp_reset\fP and to
+the \fB-command\fP callback, if specified.
+The return value of \fBhttp_status\fP is \fBtimeout\fP
+after a timeout has occurred.
+.TP
+\fB\-validate\fP \fIboolean\fP
+If \fIboolean\fR is non-zero, then \fBhttp_get\fR does an HTTP HEAD
+request. This request returns meta information about the URL, but the
+contents are not returned. The meta information is available in the
+\fBstate(meta) \fR variable after the transaction. See the STATE
+ARRAY section for details.
+.RE
+.TP
+\fBhttp_formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
+This procedure does x-url-encoding of query data. It takes an even
+number of arguments that are the keys and values of the query. It
+encodes the keys and values, and generates one string that has the
+proper & and = separators. The result is suitable for the
+\fB\-query\fR value passed to \fBhttp_get\fR.
+.TP
+\fBhttp_reset\fP \fItoken\fP ?\fIwhy\fP?
+This command resets the HTTP transaction identified by \fItoken\fR, if
+any. This sets the \fBstate(status)\fP value to \fIwhy\fP, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback.
+.TP
+\fBhttp_wait\fP \fItoken\fP
+This is a convenience procedure that blocks and waits for the
+transaction to complete. This only works in trusted code because it
+uses \fBvwait\fR.
+.TP
+\fBhttp_data\fP \fItoken\fP
+This is a convenience procedure that returns the \fBbody\fP element
+(i.e., the URL data) of the state array.
+.TP
+\fBhttp_status\fP \fItoken\fP
+This is a convenience procedure that returns the \fBstatus\fP element of
+the state array.
+.TP
+\fBhttp_code\fP \fItoken\fP
+This is a convenience procedure that returns the \fBhttp\fP element of the
+state array.
+.TP
+\fBhttp_size\fP \fItoken\fP
+This is a convenience procedure that returns the \fBcurrentsize\fP
+element of the state array.
+.SH "STATE ARRAY"
+The \fBhttp_get\fR procedure returns a \fItoken\fR that can be used to
+get to the state of the HTTP transaction in the form of a Tcl array.
+Use this construct to create an easy-to-use array variable:
+.CS
+upvar #0 $token state
+.CE
+The following elements of the array are supported:
+.RS
+.TP
+\fBbody\fR
+The contents of the URL. This will be empty if the \fB\-channel\fR
+option has been specified. This value is returned by the \fBhttp_data\fP command.
+.TP
+\fBcurrentsize\fR
+The current number of bytes fetched from the URL.
+This value is returned by the \fBhttp_size\fP command.
+.TP
+\fBerror\fR
+If defined, this is the error string seen when the HTTP transaction
+was aborted.
+.TP
+\fBhttp\fR
+The HTTP status reply from the server. This value
+is returned by the \fBhttp_code\fP command. The format of this value is:
+.RS
+.CS
+\fIcode string\fP
+.CE
+The \fIcode\fR is a three-digit number defined in the HTTP standard.
+A code of 200 is OK. Codes beginning with 4 or 5 indicate errors.
+Codes beginning with 3 are redirection errors. In this case the
+\fBLocation\fR meta-data specifies a new URL that contains the
+requested information.
+.RE
+.TP
+\fBmeta\fR
+The HTTP protocol returns meta-data that describes the URL contents.
+The \fBmeta\fR element of the state array is a list of the keys and
+values of the meta-data. This is in a format useful for initializing
+an array that just contains the meta-data:
+.RS
+.CS
+array set meta $state(meta)
+.CE
+Some of the meta-data keys are listed below, but the HTTP standard defines
+more, and servers are free to add their own.
+.TP
+\fBContent-Type\fR
+The type of the URL contents. Examples include \fBtext/html\fR,
+\fBimage/gif,\fR \fBapplication/postscript\fR and
+\fBapplication/x-tcl\fR.
+.TP
+\fBContent-Length\fR
+The advertised size of the contents. The actual size obtained by
+\fBhttp_get\fR is available as \fBstate(size)\fR.
+.TP
+\fBLocation\fR
+An alternate URL that contains the requested data.
+.RE
+.TP
+\fBstatus\fR
+Either \fBok\fR, for successful completion, \fBreset\fR for
+user-reset, or \fBerror\fR for an error condition. During the
+transaction this value is the empty string.
+.TP
+\fBtotalsize\fR
+A copy of the \fBContent-Length\fR meta-data value.
+.TP
+\fBtype\fR
+A copy of the \fBContent-Type\fR meta-data value.
+.TP
+\fBurl\fR
+The requested URL.
+.RE
+.SH EXAMPLE
+.DS
+# Copy a URL to a file and print meta-data
+proc Http_Copy { url file {chunk 4096} } {
+ set out [open $file w]
+ set token [http_get $url -channel $out -progress HttpProgress \\
+ -blocksize $chunk]
+ close $out
+ # This ends the line started by HttpProgress
+ puts stderr ""
+ upvar #0 $token state
+ set max 0
+ foreach {name value} $state(meta) {
+ if {[string length $name] > $max} {
+ set max [string length $name]
+ }
+ if {[regexp -nocase ^location$ $name]} {
+ # Handle URL redirects
+ puts stderr "Location:$value"
+ return [Http_Copy [string trim $value] $file $chunk]
+ }
+ }
+ incr max
+ foreach {name value} $state(meta) {
+ puts [format "%-*s %s" $max $name: $value]
+ }
+
+ return $token
+}
+proc HttpProgress {args} {
+ puts -nonewline stderr . ; flush stderr
+}
+
+.DE
+.SH "SEE ALSO"
+safe(n), socket(n), safesock(n)
+.SH KEYWORDS
+security policy, socket
+
+
diff --git a/contrib/tcl/doc/if.n b/contrib/tcl/doc/if.n
index f76d8d963bd8..9e8621447305 100644
--- a/contrib/tcl/doc/if.n
+++ b/contrib/tcl/doc/if.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) if.n 1.6 96/03/25 20:16:42
+'\" SCCS: @(#) if.n 1.7 96/08/26 13:00:00
'\"
.so man.macros
.TH if n "" Tcl "Tcl Built-In Commands"
@@ -22,11 +22,9 @@ if \- Execute scripts conditionally
The \fIif\fR command evaluates \fIexpr1\fR as an expression (in the
same way that \fBexpr\fR evaluates its argument). The value of the
expression must be a boolean
-.VS
(a numeric value, where 0 is false and
anything is true, or a string value such as \fBtrue\fR or \fByes\fR
for true and \fBfalse\fR or \fBno\fR for false);
-.VE
if it is true then \fIbody1\fR is executed by passing it to the
Tcl interpreter.
Otherwise \fIexpr2\fR is evaluated as an expression and if it is true
diff --git a/contrib/tcl/doc/info.n b/contrib/tcl/doc/info.n
index a84509cf3196..a0c2001fac97 100644
--- a/contrib/tcl/doc/info.n
+++ b/contrib/tcl/doc/info.n
@@ -1,11 +1,12 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) info.n 1.13 96/07/20 16:07:40
+'\" SCCS: @(#) info.n 1.17 97/05/19 14:48:52
'\"
.so man.macros
.TH info n 7.5 Tcl "Tcl Built-In Commands"
@@ -37,12 +38,21 @@ Returns a count of the total number of commands that have been invoked
in this interpreter.
.TP
\fBinfo commands \fR?\fIpattern\fR?
-If \fIpattern\fR isn't specified, returns a list of names of all the
-Tcl commands, including both the built-in commands written in C and
+If \fIpattern\fR isn't specified,
+returns a list of names of all the Tcl commands in the current namespace,
+including both the built-in commands written in C and
the command procedures defined using the \fBproc\fR command.
-If \fIpattern\fR is specified, only those names matching \fIpattern\fR
-are returned. Matching is determined using the same rules as for
-\fBstring match\fR.
+If \fIpattern\fR is specified,
+only those names matching \fIpattern\fR are returned.
+Matching is determined using the same rules as for \fBstring match\fR.
+\fIpattern\fR can be a qualified name like \fBFoo::print*\fR.
+That is, it may specify a particular namespace
+using a sequence of namespace names separated by \fB::\fRs,
+and may have pattern matching special characters
+at the end to specify a set of commands in that namespace.
+If \fIpattern\fR is a qualified name,
+the resulting list of command names has each one qualified with the name
+of the specified namespace.
.TP
\fBinfo complete \fIcommand\fR
Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of
@@ -68,15 +78,14 @@ otherwise.
\fBinfo globals \fR?\fIpattern\fR?
If \fIpattern\fR isn't specified, returns a list of all the names
of currently-defined global variables.
+Global variables are variables in the global namespace.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
are returned. Matching is determined using the same rules as for
\fBstring match\fR.
-.VS br
.TP
\fBinfo hostname\fR
Returns the name of the computer on which this invocation is being
executed.
-.VE
.TP
\fBinfo level\fR ?\fInumber\fR?
If \fInumber\fR is not specified, this command returns a number
@@ -94,7 +103,6 @@ levels mean.
\fBinfo library\fR
Returns the name of the library directory in which standard Tcl
scripts are stored.
-.VS
This is actually the value of the \fBtcl_library\fR
variable and may be changed by setting \fBtcl_library\fR.
See the \fBtclvars\fR manual entry for more information.
@@ -110,7 +118,6 @@ If \fIinterp\fR is omitted then information is returned for all packages
loaded in any interpreter in the process.
To get a list of just the packages in the current interpreter, specify
an empty string for the \fIinterp\fR argument.
-.VE
.TP
\fBinfo locals \fR?\fIpattern\fR?
If \fIpattern\fR isn't specified, returns a list of all the names
@@ -121,7 +128,6 @@ will not be returned.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
are returned. Matching is determined using the same rules as for
\fBstring match\fR.
-.VS br
.TP
\fBinfo nameofexecutable\fR
Returns the full path name of the binary file from which the application
@@ -131,13 +137,14 @@ string is returned.
\fBinfo patchlevel\fR
Returns the value of the global variable \fBtcl_patchLevel\fR; see
the \fBtclvars\fR manual entry for more information.
-.VE
.TP
\fBinfo procs \fR?\fIpattern\fR?
If \fIpattern\fR isn't specified, returns a list of all the
-names of Tcl command procedures.
-If \fIpattern\fR is specified, only those names matching \fIpattern\fR
-are returned. Matching is determined using the same rules as for
+names of Tcl command procedures in the current namespace.
+If \fIpattern\fR is specified,
+only those procedure names in the current namespace
+matching \fIpattern\fR are returned.
+Matching is determined using the same rules as for
\fBstring match\fR.
.TP
\fBinfo script\fR
@@ -146,7 +153,6 @@ call to \fBTcl_EvalFile\fR active or there is an active invocation
of the \fBsource\fR command), then this command returns the name
of the innermost file being processed. Otherwise the command returns an
empty string.
-.VS br
.TP
\fBinfo sharedlibextension\fR
Returns the extension used on this platform for the names of files
@@ -157,15 +163,23 @@ string is returned.
\fBinfo tclversion\fR
Returns the value of the global variable \fBtcl_version\fR; see
the \fBtclvars\fR manual entry for more information.
-.VE
.TP
\fBinfo vars\fR ?\fIpattern\fR?
If \fIpattern\fR isn't specified,
-returns a list of all the names of currently-visible variables, including
-both locals and currently-visible globals.
+returns a list of all the names of currently-visible variables.
+This includes locals and currently-visible globals.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
are returned. Matching is determined using the same rules as for
\fBstring match\fR.
+\fIpattern\fR can be a qualified name like \fBFoo::option*\fR.
+That is, it may specify a particular namespace
+using a sequence of namespace names separated by \fB::\fRs,
+and may have pattern matching special characters
+at the end to specify a set of variables in that namespace.
+If \fIpattern\fR is a qualified name,
+the resulting list of variable names
+has each matching namespace variable qualified with the name
+of its namespace.
.SH KEYWORDS
-command, information, interpreter, level, procedure, variable
+command, information, interpreter, level, namespace, procedure, variable
diff --git a/contrib/tcl/doc/interp.n b/contrib/tcl/doc/interp.n
index 05615f640652..a7dda337b0b8 100644
--- a/contrib/tcl/doc/interp.n
+++ b/contrib/tcl/doc/interp.n
@@ -4,10 +4,10 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) interp.n 1.19 96/05/10 16:36:44
+'\" SCCS: @(#) interp.n 1.29 97/03/06 17:41:39
'\"
.so man.macros
-.TH interp n 7.5 Tcl "Tcl Built-In Commands"
+.TH interp n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -15,6 +15,7 @@ interp \- Create and manipulate Tcl interpreters
.SH SYNOPSIS
\fBinterp \fIoption \fR?\fIarg arg ...\fR?
.BE
+
.SH DESCRIPTION
.PP
This command makes it possible to create one or more new Tcl
@@ -43,32 +44,45 @@ The \fBinterp\fR command also provides support for \fIsafe\fR
interpreters. A safe interpreter is a slave 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 commands
-and subprocess creation commands are removed from safe interpreters.
-See SAFE INTERPRETERS below for more information on what features
-are present in a safe interpreter. The alias mechanism can be
-used for protected communication (analogous to a kernel call)
-between a slave interpreter and its master.
+application's environment. For example, all IO channel creation
+commands and subprocess creation commands are made inaccessible to safe
+interpreters.
+.VS
+See SAFE INTERPRETERS below for more information on
+what features are present in a safe interpreter.
+The dangerous functionality is not removed from the safe interpreter;
+instead, it is \fIhidden\fR, so that only trusted interpreters can obtain
+access to it. For a detailed explanation of hidden commands, see
+HIDDEN COMMANDS, below.
+The alias mechanism can be used for protected communication (analogous to a
+kernel call) between a slave interpreter and its master. See ALIAS
+INVOCATION, below, for more details on how the alias mechanism works.
+.VE
.PP
A qualified interpreter name is a proper Tcl lists 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 which they are used. For example, if \fIa\fR is a slave of
-the current interpreter and it has a slave \fIa1\fR, which in turn has a
-slave \fIa11\fR, the qualified name of \fIa11\fR in \fIa\fR is the list
-\fI{a1 a11}\fR.
+interpreter in which they are used. For example, if \fBa\fR is a slave of
+the current interpreter and it has a slave \fBa1\fR, which in turn has a
+slave \fBa11\fR, the qualified name of \fBa11\fR in \fBa\fR is the list
+\fBa1 a11\fR.
.PP
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 \fI{}\fR (the empty list or string). Note that
+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
which one can refer to the first interpreter created in an application.
Both restrictions are motivated by safety concerns.
+
+.VS
+.SH "THE INTERP COMMAND"
.PP
+.VE
The \fBinterp\fR command is used to create, delete, and manipulate
-slave interpreters. It can have any of several forms, depending on
-the \fIoption\fR argument:
+slave interpreters, and to share or transfer
+channels between interpreters. It can have any of several forms, depending
+on the \fIoption\fR argument:
.TP
\fBinterp \fBalias \fIsrcPath \fIsrcCmd\fR
Returns a Tcl list whose elements are the \fItargetCmd\fR and
@@ -117,9 +131,9 @@ 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
are created in the interpreter identified by the path obtained by removing
-the last component from \fIpath\fR. For example, if \fIpath is ``\fBa b
-c\fR'' then a new slave interpreter and slave command named ``\fBc\fR'' are
-created in the interpreter identified by the path ``\fBa b\fR''.
+the last component from \fIpath\fR. For example, if \fIpath is \fBa b
+c\fR then a new slave interpreter and slave 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
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
@@ -153,10 +167,49 @@ invoking interpreter.
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
invoking interpreter is used.
+.VS BR
+.TP
+\fBinterp \fBexpose \fIpath\fR \fIhiddenCmdName\fR ?\fIexposedCmdName\fR?
+Makes the hidden command \fIhiddenCmdName\fR exposed, potentially renaming
+it to \fIexposedCmdName\fR, in the interpreter denoted by \fIpath\fR.
+If an exposed command with the targetted name already exists, this command
+fails.
+Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+.TP
+\fBinterp \fBhide \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
+Makes the exposed command \fIexposedCmdName\fR hidden, potentially renaming
+it to \fIhiddenCmdName\fR, in the interpreter denoted by \fIpath\fR.
+If a hidden command with the targetted name already exists, this command
+fails.
+Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+.TP
+\fBinterp \fBhidden \fIpath\fR
+Returns a list of the names of all hidden commands in the interpreter
+identified by \fIpath\fR.
+.TP
+\fBinterp \fBinvokehidden\fR \fIpath\fR ?\fB-global\fR \fIhiddenCmdName\fR ?\fIarg ...\fR?
+Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied
+in the interpreter denoted by \fIpath\fR. No substitutions or evaluation
+are applied to the arguments.
+If the \fB-global\fR flag is present, the hidden command is invoked at the
+global level in the target interpreter; otherwise it is invoked at the
+current call frame and can access local variables in that and outer call
+frames.
+Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+.VE
.TP
\fBinterp \fBissafe\fR ?\fIpath\fR?
Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR
is safe, \fB0\fR otherwise.
+.VS BR
+.TP
+\fBinterp \fBmarktrusted\fR \fIpath\fR
+Marks the interpreter identified by \fIpath\fR as trusted. Does
+not expose the hidden commands. This command can only be invoked from a
+trusted interpreter.
+The command has no effect if the interpreter identified by \fIpath\fR is
+already trusted.
+.VE
.TP
\fBinterp \fBshare\fR \fIsrcPath channelId destPath\fR
Causes the IO channel identified by \fIchannelId\fR to become shared
@@ -186,6 +239,7 @@ 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"
.PP
For each slave interpreter created with the \fBinterp\fR command, a
@@ -235,50 +289,46 @@ the resulting string as a Tcl script in \fIslave\fR.
The result of this evaluation (including error information
such as the \fBerrorInfo\fR and \fBerrorCode\fR variables, if an
error occurs) is returned to the invoking interpreter.
+.VS BR
+.TP
+\fIslave \fBexpose \fIhiddenCmdName \fR?\fIexposedCmdName\fR?
+This command exposes the hidden command \fIhiddenCmdName\fR, potentially
+renaming it to \fIexposedCmdName\fR, in \fIslave\fR.
+If an exposed command with the targeted name already exists, this command
+fails.
+For more details on hidden commands, see HIDDEN COMMANDS, below.
+.TP
+\fIslave \fBhide \fIexposedCmdName \fR?\fIhiddenCmdName\fR?
+This command hides the exposed command \fIexposedCmdName\fR, potentially
+renaming it to \fIhiddenCmdName\fR, in \fIslave\fR.
+If a hidden command with the targeted name already exists, this command
+fails.
+For more details on hidden commands, see HIDDEN COMMANDS, below.
+.TP
+\fIslave \fBhidden\fR
+Returns a list of the names of all hidden commands in \fIslave\fR.
+.TP
+\fIslave \fBinvokehidden\fR ?\fB-global\fR \fIhiddenCmdName \fR?\fIarg ..\fR?
+This command invokes the hidden command \fIhiddenCmdName\fR with the
+supplied arguments, in \fIslave\fR. No substitutions or evaluations are
+applied to the arguments.
+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
+can access local variables in that or outer call frames.
+For more details on hidden commands, see HIDDEN
+COMMANDS, below.
+.VE
.TP
\fIslave \fBissafe\fR
Returns \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise.
-
-.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
-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.
-The command procedure for the source command takes its arguments
-and merges them with the \fItargetCmd\fR and \fIarg\fRs for the
-alias to create a new array of arguments. If the words
-of \fIsrcCmd\fR were ``\fIsrcCmd arg1 arg2 ... argN\fR'',
-the new set of words will be
-``\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR'',
-where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the
-alias was created. \fITargetCmd\fR is then used to locate a command
-procedure in the target interpreter, and that command procedure
-is invoked with the new set of arguments. An error occurs if
-there is no command named \fItargetCmd\fR in the target interpreter.
-No additional substitutions are performed on the words: the
-target command procedure is invoked directly, without
-going through the normal Tcl evaluation mechanism.
-Substitutions are thus performed on each word exactly once:
-\fItargetCmd\fR and \fIargs\fR were substituted when parsing the command
-that created the alias, and \fIarg1 - argN\fR are substituted when
-the alias's source command is parsed in the source interpreter.
-.PP
-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
-of the system.
+.VS BR
+.TP
+\fIslave \fBmarktrusted\fR
+Marks the slave 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
+is already trusted.
+.VE
.SH "SAFE INTERPRETERS"
.PP
@@ -321,9 +371,18 @@ split string subst switch
tell trace unset update
uplevel upvar vwait while\fR
.DE
-All commands not on this list are removed from the interpreter by
-the \fBinterp create\fR command. Of course, the missing commands
-can be recreated later as Tcl procedures or aliases.
+.VS BR
+The following commands are hidden by \fBinterp create\fR when it
+creates a safe interpreter:
+.DS
+.ta 1.2i 2.4i 3.6i
+\fBcd exec exit fconfigure
+file glob load open
+pwd socket source vwait\fR
+.DE
+These commands can be recreated later as Tcl procedures or aliases, or
+re-exposed by \fBinterp expose\fR.
+.VE
.PP
In addition, the \fBenv\fR variable is not present in a safe interpreter,
so it cannot share environment variables with other interpreters. The
@@ -336,15 +395,118 @@ security risk.
.PP
If extensions are loaded into a safe interpreter, they may also restrict
their own functionality to eliminate unsafe commands. For a discussion of
-management of extensions for safety see the manual entries for the
-\fBpackage\fR and \fBload\fR Tcl commands.
+management of extensions for safety see the manual entries for
+\fBSafe\-Tcl\fR and the \fBload\fR Tcl command.
+
+.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
+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.
+The command procedure for the source command takes its arguments
+and merges them with the \fItargetCmd\fR and \fIarg\fRs for the
+alias to create a new array of arguments. If the words
+of \fIsrcCmd\fR were ``\fIsrcCmd arg1 arg2 ... argN\fR'',
+the new set of words will be
+``\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR'',
+where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the
+alias was created. \fITargetCmd\fR is then used to locate a command
+procedure in the target interpreter, and that command procedure
+is invoked with the new set of arguments. An error occurs if
+there is no command named \fItargetCmd\fR in the target interpreter.
+No additional substitutions are performed on the words: the
+target command procedure is invoked directly, without
+going through the normal Tcl evaluation mechanism.
+Substitutions are thus performed on each word exactly once:
+\fItargetCmd\fR and \fIargs\fR were substituted when parsing the command
+that created the alias, and \fIarg1 - argN\fR are substituted when
+the alias's source command is parsed in the source interpreter.
+.PP
+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
+of the system.
+
+.VS
+.SH "HIDDEN COMMANDS"
+.PP
+Safe interpreters greatly restrict the functionality available to Tcl
+programs executing within them.
+Allowing the untrusted Tcl program to have direct access to this
+functionality is unsafe, because it can be used for a variety of
+attacks on the environment.
+However, there are times when there is a legitimate need to use the
+dangerous functionality in the context of the safe interpreter. For
+example, sometimes a program must be \fBsource\fRd into the interpreter.
+Another example is Tk, where windows are bound to the hierarchy of windows
+for a specific interpreter; some potentially dangerous functions, e.g.
+window management, must be performed on these windows within the
+interpreter context.
+.PP
+The \fBinterp\fR command provides a solution to this problem in the form of
+\fIhidden commands\fR. Instead of removing the dangerous commands entirely
+from a safe interpreter, these commands are hidden so they become
+unavailable to Tcl scripts executing in the interpreter. However, such
+hidden commands can be invoked by any trusted ancestor of the safe
+interpreter, in the context of the safe interpreter, using \fBinterp
+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
+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
+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
+the hidden command.
+.PP
+Because a master 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
+interpreter to execute dangerous commands on their behalf. See the section
+on ALIAS INVOCATION 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
+hidden functionality in themselves or their descendants.
+.PP
+The set of hidden commands in an interpreter can be manipulated by a trusted
+interpreter using \fBinterp expose\fR and \fBinterp hide\fR. The \fBinterp
+expose\fR command moves a hidden command to the
+set of exposed commands in the interpreter identified by \fIpath\fR,
+potentially renaming the command in the process. If an exposed command by
+the targeted name already exists, the operation fails. Similarly,
+\fBinterp hide\fR moves an exposed command to the set of hidden commands in
+that interpreter. Safe interpreters are not allowed to move commands
+between the set of hidden and exposed commands, in either themselves or
+their descendants.
+.VE
.SH CREDITS
.PP
This mechanism is based on the Safe-Tcl prototype implemented
by Nathaniel Borenstein and Marshall Rose.
.SH "SEE ALSO"
-load(n), package(n) Tcl_CreateSlave(3)
+load(n), safe(n), Tcl_CreateSlave(3)
.SH KEYWORDS
alias, master interpreter, safe interpreter, slave interpreter
diff --git a/contrib/tcl/doc/library.n b/contrib/tcl/doc/library.n
index 232c799cbdad..215a5691b7c8 100644
--- a/contrib/tcl/doc/library.n
+++ b/contrib/tcl/doc/library.n
@@ -5,9 +5,9 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) library.n 1.20 96/03/25 20:18:29
+'\" SCCS: @(#) library.n 1.23 96/11/20 14:07:04
.so man.macros
-.TH library n "" Tcl "Tcl Built-In Commands"
+.TH library n "8.0" Tcl "Tcl Built-In Commands"
.BS
.SH NAME
library \- standard library of Tcl procedures
@@ -18,6 +18,13 @@ library \- standard library of Tcl procedures
\fBauto_mkindex \fIdir pattern pattern ...\fR
\fBauto_reset\fR
\fBparray \fIarrayName\fR
+.VS
+\fBtcl_endOfWord \fIstr start\fR
+\fBtcl_startOfNextWord \fIstr start\fR
+\fBtcl_startOfPreviousWord \fIstr start\fR
+\fBtcl_wordBreakAfter \fIstr start\fR
+\fBtcl_wordBreakBefore \fIstr start\fR
+.VE
.BE
.SH INTRODUCTION
@@ -38,7 +45,7 @@ To access the procedures in the Tcl library, an application should
source the file \fBinit.tcl\fR in the library, for example with
the Tcl command
.CS
-\fBsource [info library]/init.tcl\fR
+\fBsource [file join [info library] init.tcl]\fR
.CE
If the library procedure \fBTcl_Init\fR is invoked from an application's
\fBTcl_AppInit\fR procedure, this happens automatically.
@@ -74,14 +81,12 @@ variable is used, if it exists.
Otherwise the auto-load path consists of just the Tcl library directory.
Within each directory in the auto-load path there must be a file
\fBtclIndex\fR that describes one
-.VS
or more commands defined in that directory
and a script to evaluate to load each of the commands.
The \fBtclIndex\fR file should be generated with the
\fBauto_mkindex\fR command.
If \fIcmd\fR is found in an index file, then the appropriate
script is evaluated to create the command.
-.VE
The \fBauto_load\fR command returns 1 if \fIcmd\fR was successfully
created.
The command returns 0 if there was no index entry for \fIcmd\fR
@@ -99,11 +104,9 @@ This will force the next \fBauto_load\fR command to reload the
index database from disk.
.TP
\fBauto_mkindex \fIdir pattern pattern ...\fR
-.VS
Generates an index suitable for use by \fBauto_load\fR.
The command searches \fIdir\fR for all files whose names match
any of the \fIpattern\fR arguments
-.VE
(matching is done with the \fBglob\fR command),
generates an index of all the Tcl command
procedures defined in all the matching files, and stores the
@@ -141,6 +144,45 @@ Prints on standard output the names and values of all the elements
in the array \fIarrayName\fR.
\fBArrayName\fR must be an array accessible to the caller of \fBparray\fR.
It may be either local or global.
+.TP
+\fBtcl_endOfWord \fIstr start\fR
+.VS
+Returns the index of the first end-of-word location that occurs after
+a starting index \fIstart\fR in the string \fIstr\fR. An end-of-word
+location is defined to be the first non-word character following the
+first word character after the starting point. Returns -1 if there
+are no more end-of-word locations after the starting point. See the
+description of \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR below
+for more details on how Tcl determines which characters are word
+characters.
+.TP
+\fBtcl_startOfNextWord \fIstr start\fR
+Returns the index of the first start-of-word location that occurs
+after a starting index \fIstart\fR in the string \fIstr\fR. A
+start-of-word location is defined to be the first word character
+following a non-word character. Returns \-1 if there are no more
+start-of-word locations after the starting point.
+.TP
+\fBtcl_startOfPreviousWord \fIstr start\fR
+Returns the index of the first start-of-word location that occurs
+before a starting index \fIstart\fR in the string \fIstr\fR. Returns
+\-1 if there are no more start-of-word locations before the starting
+point.
+.TP
+\fBtcl_wordBreakAfter \fIstr start\fR
+Returns the index of the first word boundary after the starting index
+\fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more
+boundaries after the starting point in the given string. The index
+returned refers to the second character of the pair that comprises a
+boundary.
+.TP
+\fBtcl_wordBreakBefore \fIstr start\fR
+Returns the index of the first word boundary before the starting index
+\fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more
+boundaries before the starting point in the given string. The index
+returned refers to the second character of the pair that comprises a
+boundary.
+.VE
.SH "VARIABLES"
.PP
@@ -178,6 +220,25 @@ If set, then it must contain a valid Tcl list giving directories to
search during auto-load operations.
This variable is only used if \fBauto_path\fR is not defined.
.TP
+\fBtcl_nonwordchars\fR
+.VS
+This variable contains a regular expression that is used by routines
+like \fBtcl_endOfWord\fR to identify whether a character is part of a
+word or not. If the pattern matches a character, the character is
+considered to be a non-word character. On Windows platforms, spaces,
+tabs, and newlines are considered non-word characters. Under Unix,
+everything but numbers, letters and underscores are considered
+non-word characters.
+.TP
+\fBtcl_wordchars\fR
+This variable contains a regular expression that is used by routines
+like \fBtcl_endOfWord\fR to identify whether a character is part of a
+word or not. If the pattern matches a character, the character is
+considered to be a word character. On Windows platforms, words are
+comprised of any character that is not a space, tab, or newline. Under
+Unix, words are comprised of numbers, letters or underscores.
+.VE
+.TP
\fBunknown_active\fR
This variable is set by \fBunknown\fR to indicate that it is active.
It is used to detect errors where \fBunknown\fR recurses on itself
@@ -185,4 +246,4 @@ infinitely.
The variable is unset before \fBunknown\fR returns.
.SH KEYWORDS
-auto-exec, auto-load, library, unknown
+auto-exec, auto-load, library, unknown, word, whitespace
diff --git a/contrib/tcl/doc/lindex.n b/contrib/tcl/doc/lindex.n
index 794d128ce547..cf0979cd8a67 100644
--- a/contrib/tcl/doc/lindex.n
+++ b/contrib/tcl/doc/lindex.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) lindex.n 1.7 96/03/25 20:18:43
+'\" SCCS: @(#) lindex.n 1.8 96/08/26 13:00:02
'\"
.so man.macros
.TH lindex n 7.4 Tcl "Tcl Built-In Commands"
@@ -28,10 +28,8 @@ substitution and command substitution do not occur.
If \fIindex\fR is negative or greater than or equal to the number
of elements in \fIvalue\fR, then an empty
string is returned.
-.VS
If \fIindex\fR has the value \fBend\fR, it refers to the last element
in the list.
-.VE
.SH KEYWORDS
element, index, list
diff --git a/contrib/tcl/doc/linsert.n b/contrib/tcl/doc/linsert.n
index 17c7538a590a..7d62b5f570bf 100644
--- a/contrib/tcl/doc/linsert.n
+++ b/contrib/tcl/doc/linsert.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) linsert.n 1.7 96/03/25 20:18:57
+'\" SCCS: @(#) linsert.n 1.8 96/08/26 13:00:03
'\"
.so man.macros
.TH linsert n 7.4 Tcl "Tcl Built-In Commands"
@@ -25,9 +25,7 @@ element of \fIlist\fR. Each \fIelement\fR argument will become
a separate element of the new list. If \fIindex\fR is less than
or equal to zero, then the new elements are inserted at the
beginning of the list. If \fIindex\fR
-.VS
has the value \fBend\fR,
-.VE
or if it is greater than or equal to the number of elements in the list,
then the new elements are appended to the list.
diff --git a/contrib/tcl/doc/list.n b/contrib/tcl/doc/list.n
index f89b203a0972..5a688cba5a1d 100644
--- a/contrib/tcl/doc/list.n
+++ b/contrib/tcl/doc/list.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) list.n 1.8 96/03/25 20:19:13
+'\" SCCS: @(#) list.n 1.9 96/08/26 13:00:04
'\"
.so man.macros
.TH list n "" Tcl "Tcl Built-In Commands"
@@ -14,17 +14,13 @@
.SH NAME
list \- Create a list
.SH SYNOPSIS
-.VS
\fBlist \fR?\fIarg arg ...\fR?
-.VE
.BE
.SH DESCRIPTION
.PP
This command returns a list comprised of all the \fIarg\fRs,
-.VS
or an empty string if no \fIarg\fRs are specified.
-.VE
Braces and backslashes get added as necessary, so that the \fBindex\fR command
may be used on the result to re-extract the original arguments, and also
so that \fBeval\fR may be used to execute the resulting list, with
diff --git a/contrib/tcl/doc/load.n b/contrib/tcl/doc/load.n
index 73a3f167cf7e..096081f47cc7 100644
--- a/contrib/tcl/doc/load.n
+++ b/contrib/tcl/doc/load.n
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) load.n 1.5 96/03/25 20:19:39
+'\" SCCS: @(#) load.n 1.8 96/12/20 09:23:23
'\"
.so man.macros
.TH load n 7.5 Tcl "Tcl Built-In Commands"
@@ -52,6 +52,10 @@ be \fBFoo_Init\fR.
If the target interpreter is a safe interpreter, then the name
of the initialization procedure will be \fIpkg\fB_SafeInit\fR
instead of \fIpkg\fB_Init\fR.
+The \fIpkg\fB_SafeInit\fR function should be written carefully, so that it
+initializes the safe interpreter only with partial functionality provided
+by the package that is safe for use by untrusted code. For more information
+on Safe\-Tcl, see the \fBsafe\fR manual entry.
.PP
The initialization procedure must match the following prototype:
.CS
@@ -75,10 +79,7 @@ The \fBload\fR command also supports packages that are statically
linked with the application, if those packages have been registered
by calling the \fBTcl_StaticPackage\fR procedure.
If \fIfileName\fR is an empty string, then \fIpackageName\fR must
-be specified and it must give the name of a statically loaded
-package.
-The appropriate initialization procedure for that package will then
-be invoked to incorporate the package into the target interpreter.
+be specified.
.PP
If \fIpackageName\fR is omitted or specified as an empty string,
Tcl tries to guess the name of the package.
@@ -86,10 +87,24 @@ This may be done differently on different platforms.
The default guess, which is used on most UNIX platforms, is to
take the last element of \fIfileName\fR, strip off the first
three characters if they are \fBlib\fR, and use any following
-alphabetic characters as the module name.
+.VS
+alphabetic and underline characters as the module name.
+.VE
For example, the command \fBload libxyz4.2.so\fR uses the module
name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the
module name \fBlast\fR.
+.VS br
+.PP
+If \fIfileName\fR is an empty string, then \fIpackageName\fR must
+be specified.
+The \fBload\fR command first searches for a statically loaded package
+(one that has been registered by calling the \fBTcl_StaticPackage\fR
+procedure) by that name; if one is found, it is used.
+Otherwise, the \fBload\fR command searches for a dynamically loaded
+package by that name, and uses it if it is found. If several
+different files have been \fBload\fRed with different versions of
+the package, Tcl picks the file that was loaded first.
+.VE
.SH BUGS
.PP
@@ -99,7 +114,7 @@ behavior of this varies from system to system (some systems may
detect the redundant loads, others may not).
.SH "SEE ALSO"
-\fBinfo sharedlibextension\fR, Tcl_StaticPackage
+\fBinfo sharedlibextension\fR, Tcl_StaticPackage, safe(n)
.SH KEYWORDS
-binary code, loading, shared library
+binary code, loading, safe interpreter, shared library
diff --git a/contrib/tcl/doc/lrange.n b/contrib/tcl/doc/lrange.n
index 1dbc01222a0e..8a5d98c50f72 100644
--- a/contrib/tcl/doc/lrange.n
+++ b/contrib/tcl/doc/lrange.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) lrange.n 1.8 96/03/25 20:19:51
+'\" SCCS: @(#) lrange.n 1.9 96/08/26 13:00:05
'\"
.so man.macros
.TH lrange n 7.4 Tcl "Tcl Built-In Commands"
@@ -22,9 +22,7 @@ lrange \- Return one or more adjacent elements from a list
\fIList\fR must be a valid Tcl list. This command will
return a new list consisting of elements
\fIfirst\fR through \fIlast\fR, inclusive.
-.VS
\fIFirst\fR or \fIlast\fR
-.VE
may be \fBend\fR (or any abbreviation of it) to refer to the last
element of the list.
If \fIfirst\fR is less than zero, it is treated as if it were zero.
diff --git a/contrib/tcl/doc/lreplace.n b/contrib/tcl/doc/lreplace.n
index 6ee666453247..0065da5d1c6a 100644
--- a/contrib/tcl/doc/lreplace.n
+++ b/contrib/tcl/doc/lreplace.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) lreplace.n 1.8 96/03/25 20:20:05
+'\" SCCS: @(#) lreplace.n 1.9 96/08/26 13:00:07
'\"
.so man.macros
.TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
@@ -28,11 +28,9 @@ element of \fIlist\fR; the element indicated by \fIfirst\fR
must exist in the list.
\fILast\fR gives the index in \fIlist\fR of the last element
to be replaced.
-.VS
If \fIlast\fR is less than \fIfirst\fR then no elements are deleted;
the new elements are simply inserted before \fIfirst\fR.
\fIFirst\fR or \fIlast\fR may be \fBend\fR
-.VE
(or any abbreviation of it) to refer to the last element of the list.
The \fIelement\fR arguments specify zero or more new arguments to
be added to the list in place of those that were deleted.
diff --git a/contrib/tcl/doc/lsearch.n b/contrib/tcl/doc/lsearch.n
index a411c96f2473..aca019d22ea2 100644
--- a/contrib/tcl/doc/lsearch.n
+++ b/contrib/tcl/doc/lsearch.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) lsearch.n 1.6 96/03/25 20:20:16
+'\" SCCS: @(#) lsearch.n 1.7 96/08/26 13:00:05
'\"
.so man.macros
.TH lsearch n 7.0 Tcl "Tcl Built-In Commands"
@@ -24,7 +24,6 @@ of them matches \fIpattern\fR.
If so, the command returns the index of the first matching
element.
If not, the command returns \fB\-1\fR.
-.VS
The \fImode\fR argument indicates how the elements of the list are to
be matched against \fIpattern\fR and it must have one of the following
values:
@@ -41,7 +40,6 @@ element using the same rules as the \fBstring match\fR command.
each list element using the same rules as the \fBregexp\fR command.
.PP
If \fImode\fR is omitted then it defaults to \fB\-glob\fR.
-.VE
.SH KEYWORDS
list, match, pattern, regular expression, search, string
diff --git a/contrib/tcl/doc/lsort.n b/contrib/tcl/doc/lsort.n
index e6cf40f49ff3..8184663093ff 100644
--- a/contrib/tcl/doc/lsort.n
+++ b/contrib/tcl/doc/lsort.n
@@ -5,16 +5,16 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) lsort.n 1.6 96/03/25 20:20:27
+'\" SCCS: @(#) lsort.n 1.9 97/03/24 20:51:09
'\"
.so man.macros
-.TH lsort n 7.0 Tcl "Tcl Built-In Commands"
+.TH lsort n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
lsort \- Sort the elements of a list
.SH SYNOPSIS
-\fBlsort \fR?\fIswitches\fR? \fIlist\fR
+\fBlsort \fR?\fIoptions\fR? \fIlist\fR
.BE
.SH DESCRIPTION
@@ -22,14 +22,23 @@ lsort \- Sort the elements of a list
This command sorts the elements of \fIlist\fR, returning a new
list in sorted order. By default ASCII sorting is used with
the result returned in increasing order.
-.VS
However, any of the
-following switches may be specified before \fIlist\fR to
+following options may be specified before \fIlist\fR to
control the sorting process (unique abbreviations are accepted):
.TP 20
\fB\-ascii\fR
Use string comparison with ASCII collation order. This is
the default.
+.VS br
+.TP 20
+\fB\-dictionary\fR
+Use dictionary-style comparison. This is the same as \fB\-ascii\fR
+except (a) case is ignored except as a tie-breaker and (b) if two
+strings contain embedded numbers, the numbers compare as integers,
+not characters. For example, in \fB\-dictionary\fR mode, \fBbigBoy\fR
+sorts between \fBbigbang\fR and \fBbigboy\fR, and \fBx10y\fR
+sorts between \fBx9y\fR and \fBx11y\fR.
+.VE
.TP 20
\fB\-integer\fR
Convert list elements to integers and use integer comparison.
@@ -53,7 +62,24 @@ This is the default.
.TP 20
\fB\-decreasing\fR
Sort the list in decreasing order (``largest'' items first).
+.VS br
+.TP 20
+\fB\-index\0\fIindex\fR
+If this option is specified, each of the elements of \fIlist\fR must
+itself be a proper Tcl sublist. Instead of sorting based on whole sublists,
+\fBlsort\fR will extract the \fIindex\fR'th element from each sublist
+and sort based on the given element. The keyword \fBend\fP is allowed
+for the \fIindex\fP to sort on the last sublist element. For example,
+.RS
+.CS
+lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
+.CE
+returns \fB{Second 18} {First 24} {Third 30}\fR.
+This option is much more efficient than using \fB\-command\fR
+to achieve the same effect.
+.RE
.VE
+
.SH KEYWORDS
element, list, order, sort
diff --git a/contrib/tcl/doc/namespace.n b/contrib/tcl/doc/namespace.n
new file mode 100644
index 000000000000..4be685a7527c
--- /dev/null
+++ b/contrib/tcl/doc/namespace.n
@@ -0,0 +1,663 @@
+'\"
+'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
+'\" 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.
+'\"
+'\" SCCS: @(#) namespace.n 1.8 97/06/20 16:48:18
+'\"
+.so man.macros
+.TH namespace n 8.0 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+namespace \- create and manipulate contexts for commands and variables
+.SH SYNOPSIS
+\fBnamespace ?\fIsubcommand\fR? ?\fIarg ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBnamespace\fR command lets you create, access, and destroy
+separate contexts for commands and variables.
+See the section \fBWHAT IS A NAMESPACE?\fR below
+for a brief overview of namespaces.
+The legal \fIsubcommand\fR's are listed below.
+Note that you can abbreviate the names of subcommands.
+.TP
+\fBnamespace children \fR?\fIname\fR? ?\fIpattern\fR?
+Returns a list of all child namespaces that belong to the
+namespace \fIname\fR.
+If \fIname\fR is not specified,
+then the children are returned for the current namespace.
+This command returns fully-qualified names which start with \fB::\fR.
+If the optional \fIpattern\fR is given,
+then this command returns only the names that match the glob-style pattern.
+The actual pattern used is determined as follows:
+a pattern that starts with \fB::\fR is used directly,
+otherwise the namespace \fIname\fR
+(or the fully-qualified name of the current namespace)
+is prepended onto the the pattern.
+.TP
+\fBnamespace code \fIarg\fR
+Captures the current namespace context for later execution
+of the script \fIarg\fR.
+It returns a new Tcl scoped command that can be evaluated later
+to execute \fIarg\fR in the current namespace.
+It is typically used to create callback scripts,
+where the \fIarg\fR argument is a list containing a script.
+The command it produces is equivalent to that produced by
+\fBlist namespace inscope [namespace current] $arg\fR
+If \fIarg\fR is itself a scoped command starting with
+\fBnamespace inscope\fR,
+the result is just \fIarg\fR.
+.br
+.sp
+Extensions like Tk normally execute callback scripts
+in the global namespace.
+A scoped command captures a command together with its namespace context
+in a way that allows it to be executed properly later.
+See the section \fBSCOPED VALUES\fR for some examples
+of how this is used to create callback scripts.
+.TP
+\fBnamespace current\fR
+Returns the fully-qualified name for the current namespace.
+The actual name of the global namespace is ``''
+(i.e., an empty string),
+but this command returns \fB::\fR for the global namespace
+as a convenience to programmers.
+Tcl treats ``'' and \fB::\fR as synonyms
+for the name of the global namespace.
+This make it easier to manipulate namespace names
+and ensures that commands like
+\fBset [namespace current]::x\fR
+always work.
+.TP
+\fBnamespace delete \fR?\fIname name ...\fR?
+Each namespace \fIname\fR is deleted
+and all variables, procedures, and child namespaces
+contained in the namespace are deleted.
+\fIname\fR may include a sequence of namespace qualifiers
+separated by \fB::\fRs.
+If a procedure is currently executing inside the namespace,
+the namespace will be kept alive until the procedure returns;
+however, the namespace is marked to prevent other code from
+looking it up by name.
+If a namespace doesn't exist, this command returns an error.
+If no namespace names are given, this command does nothing.
+.TP
+\fBnamespace eval\fR \fIname arg\fR ?\fIarg ...\fR?
+Activates a namespace called \fIname\fR and evaluates some code
+in that context.
+If the namespace does not already exist, it is created.
+This command is normally used to define the
+commands and variables in a namespace.
+If more than one \fIarg\fR argument is specified,
+the arguments are concatenated together with a space between each one
+in the same fashion as the \fBconcat\fR command,
+and the result is evaluated.
+.br
+.sp
+If a \fBnamespace eval\fR command creates a new namespace \fIname\fR,
+then \fIname\fR determines its parent namespace and
+the new namespace's position in the hierarchy of namespaces.
+If \fIname\fR includes a sequence of namespace qualifiers
+separated by \fB::\fRs,
+it is created as a child of the specified parent namespace;
+otherwise, the namespace is created as a child of the current namespace.
+If \fIname\fR has leading namespace qualifiers
+and any leading namespaces do not exist,
+they are automatically created.
+.br
+.sp
+\fBnamespace eval\fR is another way (besides procedure calls)
+that the Tcl naming context can change.
+It adds a call frame to the stack to represent the namespace context.
+This means each \fBnamespace eval\fR command
+counts as another call level for \fBuplevel\fR and \fBupvar\fR commands.
+For example, \fBinfo level 1\fR will return a list
+describing a command that is either
+the outermost procedure call or the outermost \fBnamespace eval\fR command.
+Also, \fBuplevel #0\fR evaluates a script
+at top-level in the outermost namespace (the global namespace).
+.TP
+\fBnamespace export \fR?\fB-clear\fR? ?\fIpattern pattern ...\fR?
+Specifies which commands are exported from a namespace.
+The exported commands are those that can be later imported
+into another namespace using a \fBnamespace import\fR command.
+Both commands defined in a namespace and
+commands the namespace has previously imported
+can be exported by a namespace.
+The commands do not have to be defined
+at the time the \fBnamespace export\fR command is executed.
+Each \fIpattern\fR may contain glob-style special characters,
+but it may not include any namespace qualifiers.
+That is, the pattern can only specify commands
+in the current (exporting) namespace.
+Each \fIpattern\fR is appended onto the namespace's list of export patterns.
+If the \fB-clear\fR flag is given,
+the namespace's export pattern list is reset to empty before any
+\fIpattern\fR arguments are appended.
+If no \fIpattern\fRs are given and the \fB-clear\fR flag isn't given,
+this command returns the namespace's current export list.
+.TP
+\fBnamespace forget \fR?\fIpattern pattern ...\fR?
+Removes previously imported commands from a namespace.
+Each \fIpattern\fR is a \fIqualified name\fR like
+\fBfoo::x\fR or \fBa::b::p*\fR.
+Qualified names contain \fB::\fRs and qualify a name
+with the name of one or more namespaces.
+Each \fIpattern\fR is qualified with the name of an exporting namespace
+and may have glob-style special characters in the command name
+at the end of the qualified name.
+Glob characters may not appear in a namespace name.
+This command first finds the matching exported commands.
+It then checks whether any of those those commands
+were previously imported by the current namespace.
+If so, this command deletes the corresponding imported command.
+In effect, this un-does the action of a \fBnamespace import\fR command.
+.TP
+\fBnamespace import \fR?\fB-force\fR? ?\fIpattern\fR \fIpattern ...\fR?
+Imports commands into a namespace.
+Each \fIpattern\fR is a qualified name like
+\fBfoo::x\fR or \fBa::p*\fR.
+That is, it includes the name of an exporting namespace
+and may have glob-style special characters in the command name
+at the end of the qualified name.
+Glob characters may not appear in a namespace name.
+All the commands that match a \fIpattern\fR string
+and which are exported from their namespace
+are added to the current namespace.
+This is done by creating a new command in the current namespace
+that points to the exported command in its original namespace;
+when the new imported command is called, it invokes the exported command.
+This command normally returns an error
+if an imported command conflicts with an existing command.
+However, if the \fB-force\fR option is given,
+imported commands will silently replace existing commands.
+.TP
+\fBnamespace inscope\fR \fIname arg\fR ?\fIarg ...\fR?
+Executes a script in the context of a particular namespace.
+This command is not expected to be used directly by programmers;
+calls to it are generated implicitly when applications
+use \fBnamespace code\fR commands to create callback scripts
+that the applications then register with, e.g., Tk widgets.
+The \fBnamespace inscope\fR command is much like the \fBnamespace eval\fR
+command except that it has \fBlappend\fR semantics
+and the namespace must already exist.
+It treats the first argument as a list,
+and appends any arguments after the first
+onto the end as proper list elements.
+\fBnamespace inscope ::foo a x y z\fR
+is equivalent to
+\fBnamespace eval ::foo [concat a [list x y z]]\fR
+This \fBlappend\fR semantics is important because many callback scripts
+are actually prefixes.
+.TP
+\fBnamespace origin name\fR
+Returns the fully-qualified name of the original command
+to which the imported command \fIname\fR refers.
+When a command is imported into a namespace,
+a new command is created in that namespace
+that points to the actual command in the exporting namespace.
+If a command is imported into a sequence of namespaces
+\fIa, b,...,n\fR where each successive namespace
+just imports the command from the previous namespace,
+this command returns the fully-qualified name of the original command
+in the first namespace, \fIa\fR.
+If \fIname\fR does not refer to an imported command,
+the command's own fully-qualified name is returned.
+.TP
+\fBnamespace parent\fR ?\fIname\fR?
+Returns the fully-qualified name of the parent namespace
+for namespace \fIname\fR.
+If \fIname\fR is not specified,
+the fully-qualified name of the current namespace's parent is returned.
+.TP
+\fBnamespace qualifiers\fR \fIstring\fR
+Returns any leading namespace qualifiers for \fIstring\fR.
+Qualifiers are namespace names separated by \fB::\fRs.
+For the \fIstring\fR \fB::foo::bar::x\fR,
+this command returns \fB::foo::bar\fR,
+and for \fB::\fR it returns \fB``''\fR (an empty string).
+This command is the complement of the \fBnamespace tail\fR command.
+Note that it does not check whether the
+namespace names are, in fact,
+the names of currently defined namespaces.
+.TP
+\fBnamespace tail\fR \fIstring\fR
+Returns the simple name at the end of a qualified string.
+Qualifiers are namespace names separated by \fB::\fRs.
+For the \fIstring\fR \fB::foo::bar::x\fR,
+this command returns \fBx\fR,
+and for \fB::\fR it returns \fB``''\fR (an empty string).
+This command is the complement of the \fBnamespace qualifiers\fR command.
+It does not check whether the namespace names are, in fact,
+the names of currently defined namespaces.
+.TP
+\fBnamespace which\fR ?\fB-command\fR? ?\fB-variable\fR? \fIname\fR
+Looks up \fIname\fR as either a command or variable
+and returns its fully-qualified name.
+For example, if \fIname\fR does not exist in the current namespace
+but does exist in the global namespace,
+this command returns a fully-qualified name in the global namespace.
+If the command or variable does not exist,
+this command returns an empty string.
+If no flag is given, \fIname\fR is treated as a command name.
+See the section \fBNAME RESOLUTION\fR below for an explanation of
+the rules regarding name resolution.
+
+.SH "WHAT IS A NAMESPACE?"
+.PP
+A namespace is a collection of commands and variables.
+It encapsulates the commands and variables to ensure that they
+won't interfere with the commands and variables of other namespaces.
+Tcl has always had one such collection,
+which we refer to as the \fIglobal namespace\fR.
+The global namespace holds all global variables and commands.
+The \fBnamespace eval\fR command lets you create new namespaces.
+For example,
+.CS
+\fBnamespace eval Counter {
+ namespace export Bump
+ variable num 0
+
+ proc Bump {} {
+ variable num
+ incr num
+ }
+}\fR
+.CE
+creates a new namespace containing the variable \fBnum\fR and
+the procedure \fBBump\fR.
+The commands and variables in this namespace are separate from
+other commands and variables in the same program.
+If there is a command named \fBBump\fR in the global namespace,
+for example, it will not interfere with the command \fBBump\fR
+in the \fBCounter\fR namespace.
+.PP
+Namespace variables resemble global variables in Tcl.
+They exist outside of the procedures in a namespace
+but can be accessed in a procedure via the \fBvariable\fR command,
+as shown in the example above.
+.PP
+Namespaces are dynamic.
+You can add and delete commands and variables at any time.
+So you can build up the contents of a
+namespace over time using a series of \fBnamespace eval\fR commands.
+For example, the following series of commands has the same effect
+as the namespace definition shown above:
+.CS
+\fBnamespace eval Counter {
+ variable num 0
+ proc Bump {} {
+ variable num
+ return [incr num]
+ }
+}
+namespace eval Counter {
+ proc test {args} {
+ return $args
+ }
+}
+namespace eval Counter {
+ rename test ""
+}\fR
+.CE
+Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace,
+and later removed via the \fBrename\fR command.
+.PP
+Namespaces can have other namespaces within them,
+so they nest hierarchically.
+A nested namespace is encapsulated inside its parent namespace
+and can not interfere with other namespaces.
+If namespaces are used to represent packages,
+this feature lets one package contain its own copy of another package.
+
+.SH "QUALIFIED NAMES"
+Procedures execute in the context of the namespace that contains them.
+So in the following namespace,
+.CS
+\fBnamespace eval Counter {
+ namespace export Bump Reset
+ variable num 0
+
+ proc Bump {{by 1}} {
+ variable num
+ return [incr num $by]
+ }
+ proc Reset {} {
+ variable num
+ set num 0
+ }
+}\fR
+.CE
+procedures like \fBBump\fR and \fBReset\fR execute in the context of
+namespace \fBCounter\fR.
+.PP
+In this context, you can access the commands and variables that
+reside in the namespace using simple names.
+In the example above,
+we access the \fBnum\fR variable with the command \fBvariable num\fR.
+(We can't use \fBglobal num\fR since that would only
+look up \fBnum\fR in the global namespace.)
+We can access the \fBBump\fR and \fBReset\fR procedures in
+another procedure like this:
+.CS
+\fBnamespace eval Counter {
+ namespace export Rebump
+ proc Rebump {{by 1}} {
+ Reset
+ Bump $by
+ }
+}\fR
+.CE
+This is the real benefit of namespaces.
+The commands and variables in a namespace fit together as a module.
+.PP
+If you want to access commands and variables from another namespace,
+you must use some extra syntax.
+Names must be qualified by the namespace that contains them.
+The \fB::\fR string acts as a separator
+between the various qualifiers in a name.
+From the global namespace,
+we might access the \fBCounter\fR procedures like this:
+.CS
+\fBCounter::Bump 5
+Counter::Reset
+Counter::Rebump 10\fR
+.CE
+We could access the current count like this:
+.CS
+\fBputs "count = $Counter::num"
+set Counter::num 35\fR
+.CE
+When one namespace contains another, you may need more than one
+qualifier to reach its elements.
+If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR,
+you could invoke its \fBBump\fR procedure
+from the global namespace like this:
+.CS
+\fBFoo::Counter::Bump 3\fR
+.CE
+You can think of namespaces like directories in a file system.
+When you are sitting in a particular directory context,
+you can access files with simple names.
+But from another context, you must use a proper path name.
+A name like \fBFoo::Counter::Bump\fR
+is just like a file name \fBFoo/Counter/Bump\fR,
+except that we have used \fB::\fR instead of \fB/\fR as the separator.
+Just as the file system has a root directory \fB/\fR,
+all namespaces are rooted in the global namespace named \fB::\fR.
+So all names can be given with an absolute path that begins with \fB::\fR.
+For example, we can say:
+.CS
+\fB::Foo::Counter::Bump 3\fR
+.CE
+With this name, you can be sure that you'll get the \fBBump\fR procedure
+in the \fBCounter\fR namespace, in the \fBFoo\fR namespace, in the global
+namespace\-no matter what the current namespace context may be.
+.PP
+You can also use qualified names when you create and rename commands.
+For example, you could add a procedure to the \fBFoo\fR
+namespace like this:
+.CS
+\fBproc Foo::Test {args} {return $args}\fR
+.CE
+And you could move the same procedure to another namespace like this:
+.CS
+\fBrename Foo::Test Bar::Test\fR
+.CE
+.PP
+There are a few remaining points about qualified names
+that we should cover.
+\fB::\fR is disallowed in both simple command and variable names except
+as a namespace separator.
+Extra \fB:\fRs in a qualified name are ignored;
+that is, two or more \fB:\fRs are treated as a namespace separator.
+A trailing \fB::\fR in a qualified variable or command name
+refers to the variable or command named {}.
+However, a trailing \fB::\fR in a qualified namespace name is ignored.
+
+.SH "NAME RESOLUTION"
+.PP
+In general, all Tcl commands that take variable and command names
+support qualified names.
+This means you can give qualified names to such commands as
+\fBset\fR, \fBproc\fR, \fBrename\fR, and \fBinterp alias\fR.
+If you provide a fully-qualified name that starts with a \fB::\fR,
+there is no question about what command, variable, or namespace
+you mean.
+However, if the name does not start with a \fB::\fR
+(i.e., is \fIrelative\fR),
+Tcl follows a fixed rule for looking it up:
+Command and variable names are always resolved
+by looking first in the current namespace,
+and then in the global namespace.
+Namespace names, on the other hand, are always resolved
+by looking in only the current namespace.
+.PP
+In the following example,
+.CS
+\fBset traceLevel 0
+namespace eval Debug {
+ printTrace $traceLevel
+}\fR
+.CE
+Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR
+and then in the global namespace.
+It looks up the command \fBprintTrace\fR in the same way.
+If a variable or command name is not found in either context,
+the name is undefined.
+To make this point absolutely clear, consider the following example:
+.CS
+\fBset traceLevel 0
+namespace eval Foo {
+ variable traceLevel 3
+
+ namespace eval Debug {
+ printTrace $traceLevel
+ }
+}\fR
+.CE
+Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR.
+Since it is not found there, Tcl then looks for it
+in the global namespace.
+The variable \fBFoo::traceLevel\fR is completely ignored
+during the name resolution process.
+.PP
+You can use the \fBnamespace which\fR command to clear up any question
+about name resolution.
+For example, the command:
+.CS
+\fBnamespace eval Foo::Debug {namespace which -variable traceLevel}\fR
+.CE
+returns \fB::traceLevel\fR.
+On the other hand, the command,
+.CS
+\fBnamespace eval Foo {namespace which -variable traceLevel}\fR
+.CE
+returns \fB::Foo::traceLevel\fR.
+.PP
+Although Tcl always follows the
+``look in the current then in the global namespace''
+rule for variables and commands,
+there is a question of how to resolve a
+qualified name like \fBfoo::bar::cmd\fR.
+A relative name like this might resolve to either
+\fB[namespace current]::foo::bar::cmd\fR
+or to \fB::foo::bar::cmd\fR.
+If \fBcmd\fR does not appear in \fB[namespace current]::foo::bar\fR
+but does appear in \fB::foo::bar\fR,
+Tcl assumes it refers to the latter command.
+.PP
+As mentioned above,
+namespace names are looked up differently
+than the names of variables and commands.
+Namespace names are always resolved in the current namespace.
+This means, for example,
+that a \fBnamespace eval\fR command that creates a new namespace
+always creates a child of the current namespace
+unless the new namespace name begins with a \fB::\fR.
+.PP
+Tcl has no access control to limit what variables, commands,
+or namespaces you can reference.
+If you provide a qualified name that resolves to an element
+by the name resolution rule above,
+you can access the element.
+.PP
+You can access a namespace variable
+within a procedure in the same namespace
+by using the \fBvariable\fR command.
+Much like the \fBglobal\fR command,
+this creates a local link to the namespace variable.
+If necessary, it also creates the variable in the current namespace
+and initializes it.
+Note that the \fBglobal\fR command only creates links
+to variables in the global namespace.
+It is not necessary to use a \fBvariable\fR command
+if you always refer to the namespace variable using an
+appropriate qualified name.
+
+.SH "IMPORTING COMMANDS"
+.PP
+Namespaces are often used to represent libraries.
+Some library commands are used so frequently
+that it is a nuisance to type their qualified names.
+For example, suppose that all of the commands in a package
+like BLT are contained in a namespace called \fBBlt\fR.
+Then you might access these commands like this:
+.CS
+\fBBlt::graph .g -background red
+Blt::table . .g 0,0\fR
+.CE
+If you use the \fBgraph\fR and \fBtable\fR commands frequently,
+you may want to access them without the \fBBlt::\fR prefix.
+You can do this by importing the commands into the current namespace,
+like this:
+.CS
+\fBnamespace import Blt::*\fR
+.CE
+This adds all commands from the \fBBlt\fR namespace into the current
+namespace context, so you can write code like this:
+.CS
+\fBgraph .g -background red
+table . .g 0,0\fR
+.CE
+Importing \fIevery\fR command from a namespace is generally
+a bad idea since you don't know what you will get.
+It is better to import just the specific commands you need.
+For example, the command
+.CS
+\fBnamespace import Blt::graph Blt::table\fR
+.CE
+imports only the \fBgraph\fR and \fBtable\fR commands into the
+current context.
+.PP
+The \fBnamespace import\fR command has snapshot semantics:
+that is, only requested commands that are currently defined
+in the exporting namespace are imported.
+In other words, you can import only the commands that are in a namespace
+like \fBBlt\fR at the time when the \fBnamespace import\fR command is
+executed. If another command appears in this namespace later on, it
+will not be imported.
+.PP
+If you try to import a command that already exists, you will get an
+error. This prevents you from importing the same command from two
+different packages. But from time to time (perhaps when debugging),
+you may want to get around this restriction. You may want to
+reissue the \fBnamespace import\fR command to pick up new commands
+that have appeared in a namespace. In that case, you can use the
+\fB-force\fR option, and existing commands will be silently overwritten:
+.CS
+\fBnamespace import -force Blt::graph Blt::table\fR
+.CE
+If for some reason, you want to stop using the imported commands,
+you can remove them with an \fBnamespace forget\fR command, like this:
+.CS
+\fBnamespace forget Blt::*\fR
+.CE
+This searches the current namespace for any commands imported from \fBBlt\fR.
+If it finds any, it removes them. Otherwise, it does nothing.
+After this, the \fBBlt\fR commands must be accessed with the \fBBlt::\fR
+prefix.
+.PP
+When you delete a command from the exporting namespace like this:
+.CS
+\fBrename Blt::graph ""\fR
+.CE
+the command is automatically removed from all namespaces that import it.
+
+.SH "EXPORTING COMMANDS"
+You can export commands from a namespace like this:
+.CS
+\fBnamespace eval Counter {
+ namespace export Bump Reset
+ variable num 0
+ variable max 100
+
+ proc Bump {{by 1}} {
+ variable num
+ incr num $by
+ check
+ return $num
+ }
+ proc Reset {} {
+ variable num
+ set num 0
+ }
+ proc check {} {
+ variable num
+ variable max
+ if {$num > $max} {
+ error "too high!"
+ }
+ }
+}\fR
+.CE
+The procedures \fBBump\fR and \fBReset\fR are exported,
+so they are included when you import from the \fBCounter\fR namespace,
+like this:
+.CS
+\fBnamespace import Counter::*\fR
+.CE
+However, the \fBcheck\fR procedure is not exported,
+so it is ignored by the import operation.
+.PP
+The \fBnamespace import\fR command only imports commands
+that were declared as exported by their namespace.
+The \fBnamespace export\fR command specifies what commands
+may be imported by other namespaces.
+If a \fBnamespace import\fR command specifies a command
+that is not exported, the command is not imported.
+
+.SH "SCOPED VALUES"
+.PP
+Extensions like Tk execute ordinary code fragments in the global
+namespace.
+A scoped command captures a script together with
+its namespace in a way that allows it to be executed properly later.
+It is needed, for example, to wrap up script
+when a Tk widget is used within a namespace.
+It is also needed for commands such as \fBafter\fR that
+execute a script at the global level at some future time.
+If a \fBafter\fR command is executed in a namespace,
+a \fBnamespace code\fR command is needed to ensure
+its script executes in the correct context:
+.CS
+\fBnamespace eval Foo {
+ variable v 123
+ proc report {msg} {
+ puts "$msg"
+ }
+
+ after 2000 [namespace code {report "Hello World, v = $v"}]
+}\fR
+.CE
+
+.SH "SEE ALSO"
+variable(n)
+
+.SH KEYWORDS
+exported, internal, variable
diff --git a/contrib/tcl/doc/open.n b/contrib/tcl/doc/open.n
index 8e6f1d3a4e29..feb7b61a4e6d 100644
--- a/contrib/tcl/doc/open.n
+++ b/contrib/tcl/doc/open.n
@@ -5,10 +5,10 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) open.n 1.11 96/02/15 20:02:25
+'\" SCCS: @(#) open.n 1.16 97/01/14 18:00:35
'\"
.so man.macros
-.TH open n 7.5 Tcl "Tcl Built-In Commands"
+.TH open n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -24,8 +24,10 @@ open \- Open a file-based or command pipeline channel
.SH DESCRIPTION
.PP
-This command opens a file or command pipeline and returns a channel
-identifier that may be used in future invocations of commands like
+.VS
+This command opens a file, serial port, or command pipeline and returns a
+.VE
+channel identifier that may be used in future invocations of commands like
\fBread\fR, \fBputs\fR, and \fBclose\fR.
If the first character of \fIfileName\fR is not \fB|\fR then
the command opens a file:
@@ -90,7 +92,6 @@ If the file is a terminal device, this flag prevents the file from
becoming the controlling terminal of the process.
.TP 15
\fBNONBLOCK\fR
-.VS
Prevents the process from blocking while opening the file, and
possibly in subsequent I/O operations. The exact behavior of
this flag is system- and device-dependent; its use is discouraged
@@ -98,7 +99,6 @@ this flag is system- and device-dependent; its use is discouraged
in nonblocking mode).
For details refer to your system documentation on the \fBopen\fR system
call's \fBO_NONBLOCK\fR flag.
-.VE
.TP 15
\fBTRUNC\fR
If the file exists it is truncated to zero length.
@@ -122,10 +122,128 @@ output unless overridden by the command.
If read-only access is used (e.g. \fIaccess\fR is \fBr\fR),
standard input for the pipeline is taken from the current standard
input unless overridden by the command.
+.SH "SERIAL COMMUNICATIONS"
+.VS
+.PP
+If \fIfileName\fR refers to a serial port, then the specified serial port
+is opened and initialized in a platform-dependent manner. Acceptable
+values for the \fIfileName\fR to use to open a serial port are described in
+the PORTABILITY ISSUES section.
-.SH "SEE ALSO"
-close(n), filename(n), gets(n), read(n), puts(n)
+.SH "CONFIGURATION OPTIONS"
+The \fBfconfigure\fR command can be used to query and set the following
+configuration option for open serial ports:
+.TP
+\fB\-mode \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR
+.
+This option is a set of 4 comma-separated values: the baud rate, parity,
+number of data bits, and number of stop bits for this serial port. The
+\fIbaud\fR rate is a simple integer that specifies the connection speed.
+\fIParity\fR is one of the following letters: \fBn\fR, \fBo\fR, \fBe\fR,
+\fBm\fR, \fBs\fR; respectively signifying the parity options of ``none'',
+``odd'', ``even'', ``mark'', or ``space''. \fIData\fR is the number of
+data bits and should be an integer from 5 to 8, while \fIstop\fR is the
+number of stop bits and should be the integer 1 or 2.
+.VE
+.VS
+.SH "PORTABILITY ISSUES"
+.sp
+.TP
+\fBWindows \fR(all versions)
+.
+Valid values for \fIfileName\fR to open a serial port are of the form
+\fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4. An
+attempt to open a serial port that does not exist will fail.
+.TP
+\fBWindows NT\fR
+.
+When running Tcl interactively, there may be some strange interactions
+between the real console, if one is present, and a command pipeline that uses
+standard input or output. If a command pipeline is opened for reading, some
+of the lines entered at the console will be sent to the command pipeline and
+some will be sent to the Tcl evaluator. If a command pipeline is opened for
+writing, keystrokes entered into the console are not visible until the the
+pipe is closed. This behavior occurs whether the command pipeline is
+executing 16-bit or 32-bit applications. These problems only occur because
+both Tcl and the child application are competing for the console at
+the same time. If the command pipeline is started from a script, so that Tcl
+is not accessing the console, or if the command pipeline does not use
+standard input or output, but is redirected from or to a file, then the
+above problems do not occur.
+.TP
+\fBWindows 95\fR
+.
+A command pipeline that executes a 16-bit DOS application cannot be opened
+for both reading and writing, since 16-bit DOS applications that receive
+standard input from a pipe and send standard output to a pipe run
+synchronously. Command pipelines that do not execute 16-bit DOS
+applications run asynchronously and can be opened for both reading and
+writing.
+.sp
+When running Tcl interactively, there may be some strange interactions
+between the real console, if one is present, and a command pipeline that uses
+standard input or output. If a command pipeline is opened for reading from
+a 32-bit application, some of the keystrokes entered at the console will be
+sent to the command pipeline and some will be sent to the Tcl evaluator. If
+a command pipeline is opened for writing to a 32-bit application, no output
+is visible on the console until the the pipe is closed. These problems only
+occur because both Tcl and the child application are competing for the
+console at the same time. If the command pipeline is started from a script,
+so that Tcl is not accessing the console, or if the command pipeline does
+not use standard input or output, but is redirected from or to a file, then
+the above problems do not occur.
+.sp
+Whether or not Tcl is running interactively, if a command pipeline is opened
+for reading from a 16-bit DOS application, the call to \fBopen\fR will not
+return until end-of-file has been received from the command pipeline's
+standard output. If a command pipeline is opened for writing to a 16-bit DOS
+application, no data will be sent to the command pipeline's standard output
+until the pipe is actually closed. This problem occurs because 16-bit DOS
+applications are run synchronously, as described above.
+.TP
+\fBWindows 3.X\fR
+.
+A command pipeline can execute 16-bit or 32-bit DOS or Windows
+applications, but the call to \fBopen\fR will not return until the last
+program in the pipeline has finished executing; command pipelines run
+synchronously. If the pipeline is opened with write access (either just
+writing or both reading and writing) the first application in the
+pipeline will instead see an immediate end-of-file; any data the caller
+writes to the open pipe will instead be discarded.
+.sp
+Since Tcl cannot be run with a real console under Windows 3.X, there are
+no interactions between command pipelines and the console.
+.TP
+\fBMacintosh\fR
+.
+Opening a serial port is not currently implemented under Macintosh.
+.sp
+Opening a command pipeline is not supported under Macintosh, since
+applications do not support the concept of standard input or output.
+.TP
+\fBUnix\fR\0\0\0\0\0\0\0
+.
+Valid values for \fIfileName\fR to open a serial port are generally of the
+form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name
+of any pseudo-file that maps to a serial port may be used.
+.sp
+When running Tcl interactively, there may be some strange interactions
+between the console, if one is present, and a command pipeline that uses
+standard input. If a command pipeline is opened for reading, some
+of the lines entered at the console will be sent to the command pipeline and
+some will be sent to the Tcl evaluator. This problem only occurs because
+both Tcl and the child application are competing for the console at the
+same time. If the command pipeline is started from a script, so that Tcl is
+not accessing the console, or if the command pipeline does not use standard
+input, but is redirected from a file, then the above problem does not occur.
+.LP
+See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
+information not specific to command pipelines about executing
+applications on the various platforms
+.SH "SEE ALSO"
+close(n), filename(n), gets(n), read(n), puts(n), exec(n)
+.VE
.SH KEYWORDS
access mode, append, create, file, non-blocking, open, permissions,
-pipeline, process
+pipeline, process, serial
diff --git a/contrib/tcl/doc/pkgMkIndex.n b/contrib/tcl/doc/pkgMkIndex.n
index 251c033e95f1..a0f32fd42ce1 100644
--- a/contrib/tcl/doc/pkgMkIndex.n
+++ b/contrib/tcl/doc/pkgMkIndex.n
@@ -4,10 +4,10 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) pkgMkIndex.n 1.2 96/02/15 20:03:23
+'\" SCCS: @(#) pkgMkIndex.n 1.6 96/10/04 11:31:53
'\"
.so man.macros
-.TH pkg_mkIndex n 7.5 Tcl "Tcl Built-In Commands"
+.TH pkg_mkIndex n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -46,22 +46,42 @@ It does this by loading each file 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
in the files, as described above).
+.VS br
.IP [3]
-Make sure that the directory is in the \fBauto_path\fR global variable.
+Install the package as a subdirectory of one of the directories given by
+the \fBtcl_pkgPath\fR variable. If \fB$tcl_pkgPath\fR contains more
+than one directory, machine-dependent packages (e.g., those that
+contain binary shared libraries) should normally be installed
+under the first directory and machine-independent packages (e.g.,
+those that contain only Tcl scripts) should be installed under the
+second directory.
+The subdirectory should include
+the package's script and/or binary files as well as the \fBpkgIndex.tcl\fR
+file. As long as the package is installed as a subdirectory of a
+directory in \fB$tcl_pkgPath\fR it will automatically be found during
+\fBpackage require\fR commands.
+.RS
+.LP
+If you install the package anywhere else, then you must ensure that
+the directory contaiingn the package is in the \fBauto_path\fR global variable
+or an immediate subdirectory of one of the directories in \fBauto_path\fR.
\fBAuto_path\fR contains a list of directories that are searched
-by both the auto-loader and the package loader.
-If you want access to files described by a \fBpkgIndex.tcl\fR file
-in a directory, that directory must be present in \fBauto_path\fR.
-You can add the directory to \fBauto_path\fR explicitly in your
+by both the auto-loader and the package loader; by default it
+includes \fB$tcl_pkgPath\fR.
+The package loader also checks all of the subdirectories of the
+directories in \fBauto_path\fR.
+.VE
+You can add a directory to \fBauto_path\fR explicitly in your
application, or you can add the directory to your \fBTCLLIBPATH\fR
environment variable: if this environment variable is present,
Tcl initializes \fBauto_path\fR from it during application startup.
+.RE
.IP [4]
Once the above steps have been taken, all you need to do to use a
package is to invoke \fBpackage require\fR.
For example, if versions 2.1, 2.3, and 3.1 of package \fBTest\fR
have been indexed by \fBpkg_mkIndex\fR, the command
-\fBpackage require Test\fR will make vesion 3.1 available
+\fBpackage require Test\fR will make version 3.1 available
and the command \fBpackage require \-exact Test 2.1\fR will
make version 2.1 available.
There may be many versions of a package in the various index files
diff --git a/contrib/tcl/doc/proc.n b/contrib/tcl/doc/proc.n
index 85ee2dac346c..6615a4bbaa87 100644
--- a/contrib/tcl/doc/proc.n
+++ b/contrib/tcl/doc/proc.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) proc.n 1.5 96/03/25 20:21:12
+'\" SCCS: @(#) proc.n 1.6 97/05/18 15:49:45
'\"
.so man.macros
.TH proc n "" Tcl "Tcl Built-In Commands"
@@ -24,6 +24,11 @@ The \fBproc\fR command creates a new Tcl procedure named
any existing command or procedure there may have been by that name.
Whenever the new command is invoked, the contents of \fIbody\fR will
be executed by the Tcl interpreter.
+Normally, \fIname\fR is unqualified
+(does not include the names of any containing namespaces),
+and the new procedure is created in the current namespace.
+If \fIname\fR includes any namespace qualifiers,
+the procedure is created in the specified namespace.
\fIArgs\fR specifies the formal arguments to the
procedure. It consists of a list, possibly empty, each of whose
elements specifies
@@ -54,6 +59,8 @@ deleted when the procedure returns. One local variable is automatically
created for each of the procedure's arguments.
Global variables can only be accessed by invoking
the \fBglobal\fR command or the \fBupvar\fR command.
+Namespace variables can only be accessed by invoking
+the \fBvariable\fR command or the \fBupvar\fR command.
.PP
The \fBproc\fR command returns an empty string. When a procedure is
invoked, the procedure's return value is the value specified in a
diff --git a/contrib/tcl/doc/puts.n b/contrib/tcl/doc/puts.n
index 61599c1f8aa0..e455071feaef 100644
--- a/contrib/tcl/doc/puts.n
+++ b/contrib/tcl/doc/puts.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) puts.n 1.10 96/02/15 20:02:28
+'\" SCCS: @(#) puts.n 1.11 96/08/26 13:00:09
'\"
.so man.macros
.TH puts n 7.5 Tcl "Tcl Built-In Commands"
@@ -28,7 +28,6 @@ for output. If no \fIchannelId\fR is specified then it defaults to
\fIstring\fR, but this feature may be suppressed by specifying the
\fB\-nonewline\fR switch.
.PP
-.VS
Newline characters in the output are translated by \fBputs\fR to
platform-specific end-of-line sequences according to the current
value of the \fB\-translation\fR option for the channel (for example,
@@ -37,7 +36,6 @@ sequences; on Macintoshes newlines are normally replaced with
carriage-returns).
See the \fBfconfigure\fR manual entry for a discussion of end-of-line
translations.
-.VE
.PP
Tcl buffers output internally, so characters written with \fBputs\fR
may not appear immediately on the output file or device; Tcl will
@@ -46,7 +44,6 @@ closed.
You can force output to appear immediately with the \fBflush\fR
command.
.PP
-.VS
When the output buffer fills up, the \fBputs\fR command will normally
block until all the buffered data has been accepted for output by the
operating system.
@@ -64,7 +61,6 @@ To avoid wasting memory, nonblocking I/O should normally
be used in an event-driven fashion with the \fBfileevent\fR command
(don't invoke \fBputs\fR unless you have recently been notified
via a file event that the channel is ready for more output data).
-.VE
.SH "SEE ALSO"
fileevent(n)
diff --git a/contrib/tcl/doc/read.n b/contrib/tcl/doc/read.n
index c56d8db23524..20206fe78a93 100644
--- a/contrib/tcl/doc/read.n
+++ b/contrib/tcl/doc/read.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) read.n 1.14 96/02/15 20:02:29
+'\" SCCS: @(#) read.n 1.15 96/08/26 13:00:09
'\"
.so man.macros
.TH read n 7.5 Tcl "Tcl Built-In Commands"
@@ -30,7 +30,6 @@ read. Exactly that many bytes will be read and returned, unless
there are fewer than \fInumBytes\fR left in the file; in this case
all the remaining bytes are returned.
.PP
-.VS
If \fIchannelId\fR is in nonblocking mode, the command may not read
as many bytes as requested: once all available input has been read,
the command will return the data that is available rather than blocking
@@ -43,7 +42,6 @@ newline characters according to the \fB\-translation\fR option
for the channel.
See the manual entry for \fBfconfigure\fR for details on the
\fB\-translation\fR option.
-.VE
.SH "SEE ALSO"
eof(n), fblocked(n), fconfigure(n)
diff --git a/contrib/tcl/doc/regexp.n b/contrib/tcl/doc/regexp.n
index f4e3fab1b70f..f3951eece3e6 100644
--- a/contrib/tcl/doc/regexp.n
+++ b/contrib/tcl/doc/regexp.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) regexp.n 1.11 96/03/25 20:21:48
+'\" SCCS: @(#) regexp.n 1.12 96/08/26 13:00:10
'\"
.so man.macros
.TH regexp n "" Tcl "Tcl Built-In Commands"
@@ -33,7 +33,6 @@ contain the characters that matched the next parenthesized
subexpression to the right in \fIexp\fR, and so on.
.LP
If the initial arguments to \fBregexp\fR start with \fB\-\fR then
-.VS
they are treated as switches. The following switches are
currently supported:
.TP 10
@@ -52,7 +51,6 @@ range of characters.
\fB\-\|\-\fR
Marks the end of switches. The argument following this one will
be treated as \fIexp\fR even if it starts with a \fB\-\fR.
-.VE
.LP
If there are more \fIsubMatchVar\fR's than parenthesized
subexpressions within \fIexp\fR, or if a particular subexpression
diff --git a/contrib/tcl/doc/registry.n b/contrib/tcl/doc/registry.n
new file mode 100644
index 000000000000..6e35f2dab528
--- /dev/null
+++ b/contrib/tcl/doc/registry.n
@@ -0,0 +1,162 @@
+'\"
+'\" Copyright (c) 1997 by Sun Microsystems, Inc. All rights reserved.
+'\"
+'\" SCCS: @(#) registry.n 1.3 97/06/23 14:41:04
+'\"
+.so man.macros
+.TH registry n 8.0 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+registry \- Manipulate the Windows registry
+.SH SYNOPSIS
+.sp
+\fBpackage require registry 1.0\fR
+.sp
+\fBregistry \fIoption\fR \fIkeyName\fR ?\fIarg arg ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBregistry\fR package provides a general set of operations for
+manipulating the Windows registry. The package implements the
+\fBregistry\fR Tcl command. This command is only supported on the
+Windows platform. Warning: this command should be used with caution
+as a corrupted registry can leave your system in an unusable state.
+.PP
+\fIKeyName\fR is the name of a registry key. Registry keys must be
+one of the following forms:
+.IP
+\fB\e\e\fIhostname\fB\e\fIrootname\fB\e\fIkeypath\fR
+.IP
+\fIrootname\fB\e\fIkeypath\fR
+.IP
+\fIrootname\fR
+.PP
+\fIHostname\fR specifies the name of any valid Windows
+host that exports its registry. The \fIrootname\fR component must be
+one of \fBHKEY_LOCAL_MACHINE\fR, \fBHKEY_USERS\fR,
+\fBHKEY_CLASSES_ROOT\fR, \fBHKEY_CURRENT_USER\fR, or
+\fBHKEY_CURRENT_CONFIG\fR. The \fIkeypath\fR can be one or more
+registry key names separated by backslash (\fB\e\fR) characters.
+.PP
+\fIOption\fR indicates what to do with the registry key name. Any
+unique abbreviation for \fIoption\fR is acceptable. The valid options
+are:
+.TP
+\fBregistry delete \fIkeyName\fR ?\fIvalueName\fR?
+.
+If the optional \fIvalueName\fR argument is present, the specified
+value under \fIkeyName\fR will be deleted from the registry. If the
+optional \fIvalueName\fR is omitted, the specified key and any subkeys
+or values beneath it in the registry heirarchy will be deleted. If
+the key could not be deleted then an error is generated. If the key
+did not exist, the command has no effect.
+.TP
+\fBregistry get \fIkeyName valueName\fR
+.
+Returns the data associated with the value \fIvalueName\fR under the key
+\fIkeyName\fR. If either the key or the value does not exist, then an
+error is generated. For more details on the format of the returned
+data, see SUPPORTED TYPES, below.
+.TP
+\fBregistry keys \fIkeyName\fR ?\fIpattern\fR?
+.
+If \fIpattern\fR isn't specified, returns a list of names of all the
+subkeys of \fIkeyName\fR. If \fIpattern\fR is specified, only those
+names matching \fIpattern\fR are returned. Matching is determined
+using the same rules as for \fBstring\fR \fBmatch\fR.
+.TP
+\fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR??
+.
+If \fIvalueName\fR isn't specified, creates the key \fIkeyName\fR if
+it doesn't already exist. If \fIvalueName\fR is specified, creates
+the key \fIkeyName\fR and value \fIvalueName\fR if necessary. The
+contents of \fIvalueName\fR are set to \fIdata\fR with the type
+indicated by \fItype\fR. If \fItype\fR isn't specified, the type
+\fBsz\fR is assumed. For more details on the data and type arguments,
+see SUPPORTED TYPES below.
+.TP
+\fBregistry type \fIkeyName valueName\fR
+.
+Returns the type of the value \fIvalueName\fR in the key
+\fIkeyName\fR. For more information on the possible types, see
+SUPPORTED TYPES, below.
+.TP
+\fBregistry values \fIkeyName\fR ?\fIpattern\fR?
+.
+If \fIpattern\fR isn't specified, returns a list of names of all the
+values of \fIkeyName\fR. If \fIpattern\fR is specified, only those
+names matching \fIpattern\fR are returned. Matching is determined
+using the same rules as for \fBstring\fR \fBmatch\fR.
+
+.SH "SUPPORTED TYPES"
+Each value under a key in the registry contains some data of a
+particular type in a type-specific representation. The \fBregistry\fR
+command converts between this internal representation and one that can
+be manipulated by Tcl scripts. In most cases, the data is simply
+returned as a Tcl string. The type indicates the intended use for the
+data, but does not actually change the representation. For some
+types, the \fBregistry\fR command returns the data in a different form to
+make it easier to manipulate. The following types are recognized by the
+registry command:
+.TP 17
+\fBbinary\fR
+.
+The registry value contains arbitrary binary data. The data is represented
+exactly in Tcl, including any embedded nulls.
+Tcl
+.TP
+\fBnone\fR
+.
+The registry value contains arbitrary binary data with no defined
+type. The data is represented exactly in Tcl, including any embedded
+nulls.
+.TP
+\fBsz\fR
+.
+The registry value contains a null-terminated string. The data is
+represented in Tcl as a string.
+.TP
+\fBexpand_sz\fR
+.
+The registry value contains a null-terminated string that contains
+unexpanded references to environment variables in the normal Windows
+style (for example, "%PATH%"). The data is represented in Tcl as a
+string.
+.TP
+\fBdword\fR
+.
+The registry value contains a little-endian 32-bit number. The data is
+represented in Tcl as a decimal string.
+.TP
+\fBdword_big_endian\fR
+.
+The registry value contains a big-endian 32-bit number. The data is
+represented in Tcl as a decimal string.
+.TP
+\fBlink\fR
+.
+The registry value contains a symbolic link. The data is represented
+exactly in Tcl, including any embedded nulls.
+.TP
+\fBmulti_sz\fR
+.
+The registry value contains an array of null-terminated strings. The
+data is represented in Tcl as a list of strings.
+.TP
+\fBresource_list\fR
+.
+The registry value contains a device-driver resource list. The data
+is represented exactly in Tcl, including any embedded nulls.
+.PP
+In addition to the symbolically named types listed above, unknown
+types are identified using a 32-bit integer that corresponds to the
+type code returned by the system interfaces. In this case, the data
+is represented exactly in Tcl, including any embedded nulls.
+
+.SH "PORTABILITY ISSUES"
+The registry command is only available on Windows.
+
+.SH KEYWORDS
+registry
diff --git a/contrib/tcl/doc/regsub.n b/contrib/tcl/doc/regsub.n
index efa7b748247b..62720ac5f2ba 100644
--- a/contrib/tcl/doc/regsub.n
+++ b/contrib/tcl/doc/regsub.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) regsub.n 1.8 96/03/25 20:22:01
+'\" SCCS: @(#) regsub.n 1.9 96/08/26 13:00:11
'\"
.so man.macros
.TH regsub n 7.4 Tcl "Tcl Built-In Commands"
@@ -21,12 +21,10 @@ regsub \- Perform substitutions based on regular expression pattern matching
.PP
This command matches the regular expression \fIexp\fR against
\fIstring\fR,
-.VS
and it copies \fIstring\fR to the variable whose name is
given by \fIvarName\fR.
If there is a match, then while copying \fIstring\fR to \fIvarName\fR
the portion of \fIstring\fR that
-.VE
matched \fIexp\fR is replaced with \fIsubSpec\fR.
If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
in the substitution with the portion of \fIstring\fR that
@@ -44,7 +42,6 @@ safest to enclose \fIsubSpec\fR in braces if it includes
backslashes.
.LP
If the initial arguments to \fBregexp\fR start with \fB\-\fR then
-.VS
they are treated as switches. The following switches are
currently supported:
.TP 10
@@ -65,12 +62,9 @@ by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
\fB\-\|\-\fR
Marks the end of switches. The argument following this one will
be treated as \fIexp\fR even if it starts with a \fB\-\fR.
-.VE
.PP
-.VS
The command returns a count of the number of matching ranges that
were found and replaced.
-.VE
See the manual entry for \fBregexp\fR for details on the interpretation
of regular expressions.
diff --git a/contrib/tcl/doc/return.n b/contrib/tcl/doc/return.n
index e2c0d5d41448..fdf783b13417 100644
--- a/contrib/tcl/doc/return.n
+++ b/contrib/tcl/doc/return.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) return.n 1.12 96/03/25 20:22:26
+'\" SCCS: @(#) return.n 1.13 96/08/26 13:00:12
'\"
.so man.macros
.TH return n 7.0 Tcl "Tcl Built-In Commands"
@@ -27,7 +27,6 @@ an empty string will be returned as result.
.SH "EXCEPTIONAL RETURNS"
.PP
In the usual case where the \fB\-code\fR option isn't
-.VS
specified the procedure will return normally (its completion
code will be TCL_OK).
However, the \fB\-code\fR option may be used to generate an
@@ -85,7 +84,6 @@ If the \fB\-errorcode\fR option is specified then \fIcode\fR provides
a value for the \fBerrorCode\fR variable.
If the option is not specified then \fBerrorCode\fR will
default to \fBNONE\fR.
-.VE
.SH KEYWORDS
break, continue, error, procedure, return
diff --git a/contrib/tcl/doc/safe.n b/contrib/tcl/doc/safe.n
new file mode 100644
index 000000000000..acc50ed7a18e
--- /dev/null
+++ b/contrib/tcl/doc/safe.n
@@ -0,0 +1,303 @@
+'\"
+'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" SCCS: @(#) safe.n 1.10 97/03/24 09:21:12
+'\"
+.so man.macros
+.TH "Safe Tcl" n 7.7 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+Safe Tcl \- A mechanism for managing security policies.
+.SH SYNOPSIS
+.nf
+\fBtcl_safeCreateInterp\fR \fIslave\fR
+.sp
+\fBtcl_safeInitInterp\fR \fIslave\fR
+.sp
+\fBtcl_safeDeleteInterp\fR \fIslave\fR
+.sp
+\fIpolicy\fB_policyInit\fR \fIslave\fR
+.sp
+\fIpolicy\fB_policyFinalize\fR \fIslave\fR
+.fi
+.BE
+
+.SH DESCRIPTION
+.PP
+This manual entry describes \fBSafe Tcl\fR, a mechanism and collection of
+library procedures for managing security policies. \fBSafe Tcl\fR is used
+in \fBapplications\fR that want to provide a flexible, extensible safe
+hosting environment for untrusted guest scripts, \fBtclets\fR. It
+provides a mechanism to ensure that tclets cannot harm the hosting
+application, and a way to extend limited degrees of trust to such tclets,
+to allow them to have access to unsafe features.
+.PP
+The content of this manual entry is of interest to four different
+audiences: authors of tclets will primarily be interested in the sections
+on the \fBSAFE BASE\fR and on \fBUSING SAFE TCL IN TCLETS\fR.
+Application authors will find relevant information in the section on
+\fBUSING SAFE TCL IN APPLICATIONS\fR. To create a new security
+policy, e.g. to enable tclets to have access to a new feature, read the
+section on \fBWRITING SECURITY POLICIES\fB. Finally, system administrators
+and people installing \fBSafe Tcl\fR will find useful information in the
+section on \fBINSTALLING SECURITY POLICIES\fR.
+.PP
+\fBSecurity policies\fR are collections of procedures, aliases, hidden
+commands and variable settings that together implement a controlled way for
+an application to allow a tclet to have restricted access to unsafe features.
+For a complete description of aliases, hidden commands and how to use
+multiple interpreters in an application, see the manual entry for the
+\fBinterp\fR command.
+.PP
+Packaging collections of features into security policies has several
+advantages: First, it allows these collections to have names. This
+facilitates the formation of a common, agreed upon, understanding of what
+features are included in each policy. Second, it enables a reasoned
+approach to developing extensions that make restricted features available
+to untrusted tclets.
+Third, because the feature set is delineated clearly, a security policy can
+be subjected to analysis to determine what risks it exposes its user to.
+.PP
+The \fBSafe Tcl\fR approach to safe execution of untrusted code is further
+discussed in \fBThe Safe\-Tcl Security Model\fR
+(http://www.sunlabs.com/people/john.ousterhout/SafeTcl.ps).
+This paper provides a detailed discussion of the underlying
+motivations and philosophy, and compares the \fBSafe Tcl\fR model with
+other current efforts.
+
+.SH "SAFE BASE"
+.PP
+This section describes the environment in which tclets start execution in
+an application using \fBSafe Tcl\fR. This environment is known as the
+\fBSafe Base\fR, as it provides the basis on which further security
+policies are built.
+.PP
+When a tclet starts execution in an environment using \fBSafe Tcl\fR,
+its interpreter will contain aliases for the following commands:
+.DS
+.ta 1.2i 2.4i 3.6i
+\fBexit file load source
+tclPkgUnknown\fR
+.DE
+The \fBexit\fR alias terminates the execution of the
+invoking slave.
+\fBFile\fR allows access to a subset of the sub\-commands of the full
+\fBfile\fR command.
+\fBload\fR and \fBsource\fR make extensions available to the tclet in a
+controlled manner.
+The \fBtclPkgUnknown\fR alias allows the application to interpose on
+\fBpackage require\fR invocations by the tclet.
+.PP
+The following \fBTcl\fR commands are hidden in the Safe Base:
+.DS
+.ta 1.2i 2.4i 3.6i
+\fBcd exec exit fconfigure
+file glob load open
+pwd socket source vwait\fR
+.DE
+.PP
+A tclet can also request to load packages using \fBpackage require\fR.
+Please read the manual page on the \fBpackage\fR and \fBload\fR commands
+for a discussion of package loading and special restrictions on loading
+into safe interpreters.
+.PP
+Tclets can use auto-loading to obtain the definitions for procedures as
+needed. The auto-loading mechanism in the Safe Base supports tclIndex files
+generated by \fBauto_mkindex\fR Version 2 and later.
+
+.SH "USING SAFE TCL IN TCLETS"
+.PP
+Tclets start executing in the environment described in the previous
+section, on the \fBSAFE BASE\fR. If they need access to unsafe features,
+tclets can request to use a named security policy by invoking \fBpackage
+require\fR with the policy name. If the request is denied by the
+application's master interpreter, an error is returned.
+A tclet can \fBcatch\fR the error and request to use a different named
+policy, until a request is granted.
+.PP
+A tclet can only use one security policy during its lifetime. Once an
+invocation of \fBpackage require\fR to load a security policy succeeds,
+Safe Tcl prevents subsequent invocations of \fBpackage require\fR from
+succeeding if the requested package is a security policy. There is also no
+mechanism for a tclet to stop using a security policy, once it is loaded.
+Invocations of \fBpackage require\fR to load other packages unrelated to
+security policies will still succeed.
+.PP
+These restrictions are designed to prevent a tclet from composing security
+policies either concurrently or sequentially, in ways not supported or
+forseen by the authors of the policies. Allowing such composition would
+expose the application to unknown security risks, because a security policy
+that is safe in isolation is not necessarily safe when used in conjunction
+with other security policies.
+For example, a security policy that allows read\-only access to the local
+file system can not disclose private data belonging to the application if
+it does not have access to network communication commands such as
+\fBsocket\fR. However, when used in conjunction with another security
+policy that enables the \fBsocket\fR command, this policy is no longer
+safe.
+
+.SH "USING SAFE TCL IN APPLICATIONS"
+.PP
+An application using Safe Tcl is usually structured as one or more unsafe
+interpreters in which trusted code belonging to the application is
+executed. Each such \fBmaster interpreter\fR controls one or more safe
+\fBslave interpreters\fR in which tclets are executed.
+Tclets communicate with their master interpreter via the aliases provided
+by the Safe Base and via additional mechanisms installed by each security
+policy.
+This section describes the procedures an application invokes to use Safe
+Tcl and to manage slave interpreters.
+.PP
+An application invokes \fBtcl_safeCreateInterp\fR \fIslave\fR to create a
+new slave interpreter; this new interpreter will contain the aliases
+provided by the Safe Base. A new command named \fBslave\fR is also created
+in the invoking interpreter, to allow the application to manipulate the new
+slave interpreter.
+.PP
+An application can use \fBtcl_safeInitInterp\fR \fIslave\fR to initialize
+an existing slave interpreter with the Safe-Tcl security policy mechanism.
+This procedure is useful when an application already has a safe slave
+interpreter created with \fBinterp create -safe\fR and wishes to enable it
+to use security policies.
+.PP
+An application should invoke \fBtcl_safeDeleteInterp\fR \fIslave\fR to
+delete an interpreter previously created by \fBtcl_safeCreateInterp\fR. This
+procedure terminates the execution of the tclet in the \fIslave\fR
+interpreter and cleans up associated state maintained by the Safe Tcl
+mechanism.
+.PP
+Security policies are installed on the file system of the system on which
+the application is executing. Security policies are found in the
+\fIpolicies\fR sub-directories of directories mentioned in the
+application's \fBauto_path\fR, and in sub-directories of these
+\fIpolicies\fR directories.
+.PP
+Safe Tcl will invoke, on behalf of an application, additional procedures
+provided by individual security policies to manage the lifecycle of those
+policies. These additional procedures are described in the next section.
+
+.SH "WRITING SECURITY POLICIES"
+.PP
+Writing a security policy is a complex effort that should not be undertaken
+lightly. It involves careful design, exhaustive testing, public review and
+analysis and continuous debugging.
+In addition to considering what features a security policy should provide,
+the implementer has to constantly keep in mind the security risks to which
+an application using the policy may be exposed.
+Actively considering each feature to see if it can be used to compromise an
+application will help to minimize the chance of a security mishap later on.
+.PP
+A security policy is a Tcl script or a shared library that is loaded into
+an unsafe master interpreter.
+A security policy consists of two parts: a \fBmanagement\fR part, concerned
+with installing the policy into safe slaves and cleaning up after a slave
+is destroyed, and a \fBruntime\fR part, concerned with actually
+implementing the features of the policy.
+.PP
+The management part of a security policy consists of two Tcl procedures or
+commands, one for installing the security policy features into a safe
+slave, and the other for cleaning up any associated state when a slave is
+destroyed.
+The names of these procedures or commands are \fIpolicy\fB_policyInit\fR
+and \fIpolicy\fB_policyFinalize, where \fIpolicy\fR is the name of the
+policy as used by the slave interpreter in the \fBpackage require\fR
+invocation.
+.PP
+The policy initialization procedure \fIpolicy\fB_policyInit\fR called in
+the master interpreter with one argument, the name of the slave
+interpreter, when a slave requests to use the \fIpolicy\fR security policy.
+Error returns indicate that the slave was denied permission to use this
+policy; the error is propagated back to the slave interpreter. Successful
+return indicates that the policy is now available in the requesting slave.
+If it decides to allow the slave to use the requested policy,
+\fIpolicy\fB_policyInit\fR should install new aliases and command into the
+slave, initialize variables both in the master interpreter and in the
+slave, and do any other initialization work to make the policy features
+available in the slave.
+Policy initialization procedures may also perform other tasks, such as
+creating policy specific state data for the new slave using this policy.
+.PP
+Policy initialization procedures should be careful to leave a clean state
+in the slave interpreter if a failure occurs during initialization; the
+rule is that if an error is returned, no changes in any variables,
+procedures or aliases should be detectable in the slave.
+For example, if use of a security policy requires creation
+of a socket to a remote host at initialization time, and if that host is
+not accessible, all aliases created in the slave to use the policy
+should be removed. Otherwise, these aliases might open security holes when
+used in conjunction with another security policy subsequently requested by
+the slave. Without this, a malicious tclet could purposely cause a failure
+during initialization in one security policy and compose features provided
+by that policy in an unsafe manner with another security policy requested
+later.
+.PP
+When an application invokes \fBtcl_safeDeleteInterp\fR to delete a slave
+interpreter, the policy finalization procedure
+\fIpolicy\fB_policyFinalize\fR for the policy in use by the slave is called.
+It receives one argument, the name of the slave interpreter being deleted.
+This procedure should ensure that subsequently if a slave by the
+same name is re\-created, the new slave will be able to use this policy.
+It may also wish to remove any policy specific state data created by
+\fIpolicy\fB_policyInit\fR.
+.PP
+During initialization, a number of aliases may be created in the slave;
+when these aliases are invoke, they cause commands defined in the master to
+execute. The runtime part of a security policy consists of implementations
+of all the target commands that handle the invocation of aliases in the
+slave. Because these commands execute in a trusted interpreter, they have
+full access to all the capabilities of Tcl and any extensions loaded into
+the master interpreter.
+.PP
+A security policy must provide a \fBtclIndex\fR file in addition to files
+containing Tcl procedures and shared libraries implementing the policy.
+To generate a \fBtclIndex\fR file, use the Tcl command \fBauto_mkindex\fR
+which is described in the manual page for the Tcl library.
+
+.SH "INSTALLING SECURITY POLICIES"
+.PP
+Safe Tcl uses a platform dependent mechanism for obtaining the initial
+setting for the search path for finding security policies.
+On \fBUnix\fR, the environment variable \fBTCL_POLICY_PATH\fR is consulted.
+On \fBWin32\fR systems and on \fBMacOS\fR there is currently no mechanism
+provided to obtain the initial value; each application should provide its
+own mechanism for obtaining the initial search path. Such mechanisms will
+be provided shortly.
+.PP
+The search path is searched in reverse order of the order in which entries
+appear. Thus, if two or more policies by the same name occur in the path,
+the last policy by that name will be used by Safe Tcl.
+This enable system administrators to install system wide security policies
+in a centralized directory and then require users to include that directory
+as the last component in the search path. Doing so will ensure that system
+wide policies are used in preference of policies installed by individual
+users.
+.PP
+To install a policy, create a sub\-directory of one of the directories
+mentioned in the policy search path, and copy all the files comprising the
+policy into the new directory.
+Applications should be able, in most situations, to use the newly available
+policy immediately, without having to restart.
+If a security policy uses the same name as a regular package, a \fBpackage
+require\fR invocation in a slave interpreter will preferentially use the
+security policy over the regular package.
+However, if a security policy is installed after the first invocation of
+\fBpackage require\fR in an application, and a regular package exists by
+the same name, the security policy will not be available for use in that
+application. In this case you must restart the application for the policy
+to become available.
+
+.SH CREDITS
+.PP
+The security policy mechanism extends and expands on the Safe-Tcl prototype
+first implemented by Nathaniel Borenstein and Marshall Rose.
+
+.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, security
+policy, safe interpreter, slave interpreter, source
diff --git a/contrib/tcl/doc/scan.n b/contrib/tcl/doc/scan.n
index bdc3230c5ae4..96121f8495c6 100644
--- a/contrib/tcl/doc/scan.n
+++ b/contrib/tcl/doc/scan.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) scan.n 1.11 96/03/25 20:22:44
+'\" SCCS: @(#) scan.n 1.12 96/08/26 13:00:13
'\"
.so man.macros
.TH scan n "" Tcl "Tcl Built-In Commands"
@@ -21,10 +21,8 @@ scan \- Parse string using conversion specifiers in the style of sscanf
.PP
This command parses fields from an input string in the same fashion
as the ANSI C \fBsscanf\fR procedure and returns a count of the number
-.VS
of conversions performed, or -1 if the end of the input string is
reached before any conversions have been performed.
-.VE
\fIString\fR gives the input to be parsed and \fIformat\fR indicates
how to parse it, using \fB%\fR conversion specifiers as in \fBsscanf\fR.
Each \fIvarName\fR gives the name of a variable; when a field is
@@ -118,23 +116,19 @@ then no variable is assigned and the next scan argument is not consumed.
The behavior of the \fBscan\fR command is the same as the behavior of
the ANSI C \fBsscanf\fR procedure except for the following differences:
.IP [1]
-.VS
\fB%p\fR and \fB%n\fR conversion specifiers are not currently
supported.
-.VE
.IP [2]
For \fB%c\fR conversions a single character value is
converted to a decimal string, which is then assigned to the
corresponding \fIvarName\fR;
no field width may be specified for this conversion.
.IP [3]
-.VS
The \fBl\fR, \fBh\fR, and \fBL\fR modifiers are ignored; integer
values are always converted as if there were no modifier present
and real values are always converted as if the \fBl\fR modifier
were present (i.e. type \fBdouble\fR is used for the internal
representation).
-.VE
.SH KEYWORDS
conversion specifier, parse, scan
diff --git a/contrib/tcl/doc/seek.n b/contrib/tcl/doc/seek.n
index d31cf15e5af1..ac796e695af2 100644
--- a/contrib/tcl/doc/seek.n
+++ b/contrib/tcl/doc/seek.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) seek.n 1.9 96/02/15 20:02:34
+'\" SCCS: @(#) seek.n 1.10 96/08/26 13:00:14
'\"
.so man.macros
.TH seek n 7.5 Tcl "Tcl Built-In Commands"
@@ -45,10 +45,7 @@ position after the end of file.
The \fIorigin\fR argument defaults to \fBstart\fR.
.PP
The command flushes all buffered output for the channel before the command
-returns,
-.VS
-even if the channel is in nonblocking mode.
-.VE
+returns, even if the channel is in nonblocking mode.
It also discards any buffered and unread input.
This command returns an empty string.
An error occurs if this command is applied to channels whose underlying
diff --git a/contrib/tcl/doc/set.n b/contrib/tcl/doc/set.n
index 84f63ee8fd1c..caf6cc28936e 100644
--- a/contrib/tcl/doc/set.n
+++ b/contrib/tcl/doc/set.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) set.n 1.5 96/03/25 20:23:07
+'\" SCCS: @(#) set.n 1.6 97/05/18 15:56:26
'\"
.so man.macros
.TH set n "" Tcl "Tcl Built-In Commands"
@@ -25,14 +25,24 @@ the value of \fIvarName\fR to \fIvalue\fR, creating a new variable
if one doesn't already exist, and return its value.
If \fIvarName\fR contains an open parenthesis and ends with a
close parenthesis, then it refers to an array element: the characters
-before the first open parenthesis are the name of the array, and the characters
-between the parentheses are the index within the array.
+before the first open parenthesis are the name of the array,
+and the characters between the parentheses are the index within the array.
Otherwise \fIvarName\fR refers to a scalar variable.
-If no procedure is active, then \fIvarName\fR refers to a global
-variable.
+Normally, \fIvarName\fR is unqualified
+(does not include the names of any containing namespaces),
+and the variable of that name in the current namespace is read or written.
+If \fIvarName\fR includes namespace qualifiers
+(in the array name if it refers to an array element),
+the variable in the specified namespace is read or written.
+.PP
+If no procedure is active,
+then \fIvarName\fR refers to a namespace variable
+(global variable if the current namespace is the global namespace).
If a procedure is active, then \fIvarName\fR refers to a parameter
-or local variable of the procedure unless the \fIglobal\fR command
-has been invoked to declare \fIvarName\fR to be global.
+or local variable of the procedure unless the \fBglobal\fR command
+was invoked to declare \fIvarName\fR to be global,
+or unless a \fBvariable\fR command
+was invoked to declare \fIvarName\fR to be a namespace variable.
.SH KEYWORDS
read, write, variable
diff --git a/contrib/tcl/doc/string.n b/contrib/tcl/doc/string.n
index bed040db035d..0bccf30e755e 100644
--- a/contrib/tcl/doc/string.n
+++ b/contrib/tcl/doc/string.n
@@ -5,10 +5,10 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) string.n 1.7 96/03/25 20:24:06
+'\" SCCS: @(#) string.n 1.9 96/08/26 13:00:14
'\"
.so man.macros
-.TH string n 7.4 Tcl "Tcl Built-In Commands"
+.TH string n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -77,9 +77,10 @@ avoiding the special interpretation of the characters
\fBstring range \fIstring first last\fR
Returns a range of consecutive characters from \fIstring\fR, starting
with the character whose index is \fIfirst\fR and ending with the
-character whose index is \fIlast\fR. An index of 0 refers to the
-first character of the string. \fILast\fR may be \fBend\fR (or any
-abbreviation of it) to refer to the last character of the string.
+character whose index is \fIlast\fR. An index of 0 refers to the
+first character of the string.
+An index of \fBend\fR (or any
+abbreviation of it) refers to the last character of the string.
If \fIfirst\fR is less than zero then it is treated as if it were zero, and
if \fIlast\fR is greater than or equal to the length of the string then
it is treated as if it were \fBend\fR. If \fIfirst\fR is greater than
@@ -115,7 +116,6 @@ If \fIchars\fR is not specified then white space is removed
(spaces, tabs, newlines, and carriage returns).
.TP
\fBstring wordend \fIstring index\fR
-.VS
Returns the index of the character just after the last one in the
word containing character \fIindex\fR of \fIstring\fR.
A word is considered to be any contiguous range of alphanumeric
@@ -126,7 +126,6 @@ Returns the index of the first character in the
word containing character \fIindex\fR of \fIstring\fR.
A word is considered to be any contiguous range of alphanumeric
or underscore characters, or any single character other than these.
-.VE
.SH KEYWORDS
case conversion, compare, index, match, pattern, string, word
diff --git a/contrib/tcl/doc/tclsh.1 b/contrib/tcl/doc/tclsh.1
index 228a9a4ce72b..2922d81786bf 100644
--- a/contrib/tcl/doc/tclsh.1
+++ b/contrib/tcl/doc/tclsh.1
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) tclsh.1 1.12 96/03/25 20:25:06
+'\" SCCS: @(#) tclsh.1 1.13 96/08/26 13:00:15
'\"
.so man.macros
.TH tclsh 1 "" Tcl "Tcl Applications"
@@ -50,7 +50,6 @@ you mark the file as executable.
This assumes that \fBtclsh\fR has been installed in the default
location in /usr/local/bin; if it's installed somewhere else
then you'll have to modify the above line to match.
-.VS
Many UNIX systems do not allow the \fB#!\fR line to exceed about
30 characters in length, so be sure that the \fBtclsh\fR
executable can be accessed with a short file name.
@@ -80,7 +79,6 @@ instead to start up \fBtclsh\fR to reprocess the entire script.
When \fBtclsh\fR starts up, it treats all three lines as comments,
since the backslash at the end of the second line causes the third
line to be treated as part of the comment on the second line.
-.VE
.SH "VARIABLES"
.PP
diff --git a/contrib/tcl/doc/tclvars.n b/contrib/tcl/doc/tclvars.n
index 47f1b1599156..9270fcf0c899 100644
--- a/contrib/tcl/doc/tclvars.n
+++ b/contrib/tcl/doc/tclvars.n
@@ -1,14 +1,14 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) tclvars.n 1.15 96/04/12 08:28:20
+'\" SCCS: @(#) tclvars.n 1.30 97/05/02 13:06:45
'\"
.so man.macros
-.TH tclvars n 7.5 Tcl "Tcl Built-In Commands"
+.TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
@@ -36,6 +36,14 @@ passed to children by commands like \fBexec\fR.
If the entire \fBenv\fR array is unset then Tcl will stop
monitoring \fBenv\fR accesses and will not update environment
variables.
+.RS
+Under Windows, the environment variables PATH, COMSPEC, and WINDIR in any
+capitalization are converted automatically to upper case. For instance, the
+PATH variable could be exported by the operating system as ``path'',
+``Path'', ``PaTh'', etc., causing otherwise simple Tcl code to have to
+support many special cases. All other environment variables inherited by
+Tcl are left unmodified.
+.RE
.TP
\fBerrorCode\fR
After an error has occurred, this variable will be set to hold
@@ -49,7 +57,6 @@ Tcl core; individual applications may define additional formats.
.RS
.TP
\fBARITH\fI code msg\fR
-.VS
This format is used when an arithmetic error occurs (e.g. an attempt
to divide by zero in the \fBexpr\fR command).
\fICode\fR identifies the precise error and \fImsg\fR provides a
@@ -59,7 +66,6 @@ DOMAIN (if an argument is outside the domain of a function, such as acos(\-3)),
IOVERFLOW (for integer overflow),
OVERFLOW (for a floating-point overflow),
or UNKNOWN (if the cause of the error cannot be determined).
-.VE
.TP
\fBCHILDKILLED\fI pid sigName msg\fR
This format is used when a child process has been killed because of
@@ -97,10 +103,8 @@ error. In these cases \fBerrorCode\fR will consist of a list
containing a single element whose contents are \fBNONE\fR.
.TP
\fBPOSIX \fIerrName msg\fR
-.VS
If the first element of \fBerrorCode\fR is \fBPOSIX\fR, then
the error occurred during a POSIX kernel call.
-.VE
The second element of the list will contain the symbolic name
of the error that occurred, such as \fBENOENT\fR; this will
be one of the values defined in the include file errno.h.
@@ -109,10 +113,7 @@ message corresponding to \fIerrName\fR, such as
``no such file or directory'' for the \fBENOENT\fR case.
.PP
To set \fBerrorCode\fR, applications should use library
-procedures such as \fBTcl_SetErrorCode\fR and
-.VS
-\fBTcl_PosixError\fR,
-.VE
+procedures such as \fBTcl_SetErrorCode\fR and \fBTcl_PosixError\fR,
or they may invoke the \fBerror\fR command.
If one of these methods hasn't been used, then the Tcl
interpreter will reset the variable to \fBNONE\fR after
@@ -127,12 +128,11 @@ Its contents take the form of a stack trace showing the various
nested Tcl commands that had been invoked at the time of the error.
.TP
\fBtcl_library\fR
-.VS
-This variable holds the network name of a directory containing the
+This variable holds the name of a directory containing the
system library of Tcl scripts, such as those used for auto-loading.
The value of this variable is returned by the \fBinfo library\fR command.
See the \fBlibrary\fR manual entry for details of the facilities
-rovided by the Tcl script library.
+provided by the Tcl script library.
Normally each application or package will have its own application-specific
script library in addition to the Tcl script library;
each application should set a global variable with a name like
@@ -147,7 +147,6 @@ If \fBTCL_LIBRARY\fR isn't set or doesn't refer to an appropriate
directory, then Tcl checks several other directories based on a
compiled-in default location, the location of the binary containing
the application, and the current working directory.
-.VE
.TP
\fBtcl_patchLevel\fR
When an interpreter is created Tcl initializes this variable to
@@ -158,6 +157,24 @@ The value of this variable is returned by the \fBinfo patchlevel\fR
command.
.VS br
.TP
+\fBtcl_pkgPath\fR
+This variable holds a list of directories indicating where packages are
+normally installed. It typically contains either one or two entries;
+if it contains two entries, the first is normally a directory for
+platform-dependent packages (e.g., shared library binaries) and the
+second is normally a directory for platform-independent packages (e.g.,
+script files). Typically a package is installed as a subdirectory of one
+of the entries in \fB$tcl_pkgPath\fR. The directories in
+\fB$tcl_pkgPath\fR are included by default in the \fBauto_path\fR
+variable, so they and their immediate subdirectories are automatically
+searched for packages during \fBpackage require\fR commands. Note:
+\fBtcl_pkgPath\fR it not intended to be modified by the application.
+Its value is added to \fBauto_path\fR at startup; changes to
+\fBtcl_pkgPath\fR are not reflected in \fBauto_path\fR. If you
+want Tcl to search additional directories for packages you should add
+the names of those directories to \fBauto_path\fR, not \fBtcl_pkgPath\fR.
+.VE
+.TP
\fBtcl_platform\fR
This is an associative array whose elements contain information about
the platform on which the application is running, such as the name of
@@ -168,16 +185,22 @@ retrieve any relevant information. In addition, extensions
and applications may add additional values to the array. The
predefined elements are:
.RS
+.VS
+.TP
+\fBbyteOrder\fR
+The native byte order of this machine: either \fBlittleEndian\fR or
+\fBbigEndian\fR.
+.VE
.TP
\fBmachine\fR
The instruction set executed by this machine, such as
-\fBPPC\fR, \fB68k\fR, or \fBsun4m\fR. On UNIX machines, this
+\fBintel\fR, \fBPPC\fR, \fB68k\fR, or \fBsun4m\fR. On UNIX machines, this
is the value returned by \fBuname -m\fR.
.TP
-\fBos\fR
-The name of the operating system running on this machine, such
-as \fBWin95\fR, \fBMacOS\fR, or \fBSunOS\fR. On UNIX machines,
-this is the value returned by \fBuname -s\fR.
+\fBos\fR
+The name of the operating system running on this machine,
+such as \fBWin32s\fR, \fBWindows NT\fR, \fBMacOS\fR, or \fBSunOS\fR.
+On UNIX machines, this is the value returned by \fBuname -s\fR.
.TP
\fBosVersion\fR
The version number for the operating system running on this machine.
@@ -187,25 +210,72 @@ On UNIX machines, this is the value returned by \fBuname -r\fR.
Either \fBwindows\fR, \fBmacintosh\fR, or \fBunix\fR. This identifies the
general operating environment of the machine.
.RE
-.VE
.TP
\fBtcl_precision\fR
-If this variable is set, it must contain a decimal number giving the
+.VS
+In Tcl versions before 8.0, this variable controlled the
number of significant digits to include when converting floating-point
values to strings.
-If this variable is not set then 6 digits are included.
+If the variable was not set then 6 digits were included.
17 digits is ``perfect'' for IEEE floating-point in that it allows
double-precision values to be converted to strings and back to
binary with no loss of precision.
-.VS br
+As of Tcl 8.0 this variable is ignored and all conversions use the
+full 17 digits.
+.VE
.TP
\fBtcl_rcFileName\fR
This variable is used during initialization to indicate the name of a
user-specific startup file. If it is set by application-specific
initialization, then the Tcl startup code will check for the existence
of this file and \fBsource\fR it if it exists. For example, for \fBwish\fR
-the variable is set to \fB~/.wishrc\fR.
-.VE
+the variable is set to \fB~/.wishrc\fR for Unix and \fB~/wishrc.tcl\fR
+for Windows.
+.TP
+\fBtcl_rcRsrcName\fR
+This variable is only used on Macintosh systems. The variable is used
+during initialization to indicate the name of a user-specific
+\fBTEXT\fR resource located in the application or extension resource
+forks. If it is set by application-specific initialization, then the
+Tcl startup code will check for the existence of this resource and
+\fBsource\fR it if it exists. For example, the Macintosh \fBwish\fR
+application has the variable is set to \fBtclshrc\fR.
+.TP
+\fBtcl_traceCompile\fR
+The value of this variable can be set to control
+how much tracing information
+is displayed during bytecode compilation.
+By default, tcl_traceCompile is zero and no information is displayed.
+Setting tcl_traceCompile to 1 generates a one line summary in stdout
+whenever a procedure or top level command is compiled.
+Setting it to 2 generates a detailed listing in stdout of the
+bytecode instructions emitted during every compilation.
+This variable is useful in
+tracking down suspected problems with the Tcl compiler.
+It is also occasionally useful when converting
+existing code to use Tcl8.0.
+.TP
+\fBtcl_traceExec\fR
+The value of this variable can be set to control
+how much tracing information
+is displayed during bytecode execution.
+By default, tcl_traceExec is zero and no information is displayed.
+Setting tcl_traceExec to 1 generates a one line trace in stdout
+on each call to a Tcl procedure.
+Setting it to 2 generates a line of output
+whenever any Tcl command is invoked
+that contains the name of the command and its arguments.
+Setting it to 3 produces a detailed trace showing the result of
+executing each bytecode instruction.
+Note that when tcl_traceExec is 2 or 3,
+commands such as set and incr
+that have been entirely replaced by a sequence
+of bytecode instructions are not shown.
+Setting this variable is useful in
+tracking down suspected problems with the bytecode compiler
+and interpreter.
+It is also occasionally useful when converting
+code to use Tcl8.0.
.TP
\fBtcl_version\fR
When an interpreter is created Tcl initializes this variable to
@@ -217,4 +287,4 @@ The value of this variable is returned by the \fBinfo tclversion\fR
command.
.SH KEYWORDS
-arithmetic, error, environment, POSIX, precision, subprocess, variables
+arithmetic, bytecode, compiler, error, environment, POSIX, precision, subprocess, variables
diff --git a/contrib/tcl/doc/tell.n b/contrib/tcl/doc/tell.n
index 9edf7d2f6d5e..b2c0ec1193d0 100644
--- a/contrib/tcl/doc/tell.n
+++ b/contrib/tcl/doc/tell.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) tell.n 1.8 96/02/15 20:02:42
+'\" SCCS: @(#) tell.n 1.9 96/08/26 13:00:17
'\"
.so man.macros
.TH tell n 7.5 Tcl "Tcl Built-In Commands"
@@ -21,10 +21,8 @@ tell \- Return current access position for an open channel
.PP
Returns a decimal string giving the current access position in
\fIchannelId\fR.
-.VS
The value returned is -1 for channels that do not support
seeking.
-.VE
.SH KEYWORDS
access position, channel, seeking
diff --git a/contrib/tcl/doc/trace.n b/contrib/tcl/doc/trace.n
index 7832d2f563e7..cabf495eb7d5 100644
--- a/contrib/tcl/doc/trace.n
+++ b/contrib/tcl/doc/trace.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) trace.n 1.11 96/03/25 20:25:42
+'\" SCCS: @(#) trace.n 1.12 96/08/26 13:00:18
'\"
.so man.macros
.TH trace n "" Tcl "Tcl Built-In Commands"
@@ -92,9 +92,7 @@ result of the traced operation.
The return value from \fIcommand\fR is ignored except that
if it returns an error of any sort then the traced operation
also returns an error with
-.VS
the same error message returned by the trace command
-.VE
(this mechanism can be used to implement read-only variables, for
example).
For write traces, \fIcommand\fR is invoked after the variable's
@@ -108,10 +106,8 @@ on the variable are temporarily disabled.
This means that reads and writes invoked by
\fIcommand\fR will occur directly, without invoking \fIcommand\fR
(or any other traces) again.
-.VS
However, if \fIcommand\fR unsets the variable then unset traces
will be invoked.
-.VE
.PP
When an unset trace is invoked, the variable has already been
deleted: it will appear to be undefined with no traces.
@@ -122,9 +118,7 @@ will no longer exist.
Traces are not disabled during unset traces, so if an unset trace
command creates a new trace and accesses the variable, the
trace will be invoked.
-.VS
Any errors in unset traces are ignored.
-.VE
.PP
If there are multiple traces on a variable they are invoked
in order of creation, most-recent first.
diff --git a/contrib/tcl/doc/unknown.n b/contrib/tcl/doc/unknown.n
index 6f2fd65bcf9a..a7be9421078d 100644
--- a/contrib/tcl/doc/unknown.n
+++ b/contrib/tcl/doc/unknown.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) unknown.n 1.7 96/03/25 20:26:05
+'\" SCCS: @(#) unknown.n 1.8 96/10/09 08:29:28
'\"
.so man.macros
.TH unknown n "" Tcl "Tcl Built-In Commands"
@@ -52,7 +52,7 @@ If so, it invokes the Tcl \fBexec\fR command
with \fIcmd\fR and all the \fIargs\fR as arguments.
If \fIcmd\fR can't be auto-executed, \fBunknown\fR checks to
see if the command was invoked at top-level and outside of any
-script. If so, then \fBunknown\fR takes takes two additional steps.
+script. If so, then \fBunknown\fR takes two additional steps.
First, it sees if \fIcmd\fR has one of the following three forms:
\fB!!\fR, \fB!\fIevent\fR, or \fB^\fIold\fB^\fInew\fR?\fB^\fR?.
If so, then \fBunknown\fR carries out history substitution
diff --git a/contrib/tcl/doc/upvar.n b/contrib/tcl/doc/upvar.n
index 37baf4c35583..e6e47ce0e5b0 100644
--- a/contrib/tcl/doc/upvar.n
+++ b/contrib/tcl/doc/upvar.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) upvar.n 1.14 96/03/25 20:27:03
+'\" SCCS: @(#) upvar.n 1.15 96/08/26 13:00:19
'\"
.so man.macros
.TH upvar n "" Tcl "Tcl Built-In Commands"
@@ -34,13 +34,11 @@ The variable named by \fIotherVar\fR need not exist at the time of the
call; it will be created the first time \fImyVar\fR is referenced, just like
an ordinary variable. There must not exist a variable by the
name \fImyVar\fR at the time \fBupvar\fR is invoked.
-.VS
\fIMyVar\fR is always treated as the name of a variable, not an
array element. Even if the name looks like an array element,
such as \fBa(b)\fR, a regular variable is created.
\fIOtherVar\fR may refer to a scalar variable, an array,
or an array element.
-.VE
\fBUpvar\fR returns an empty string.
.PP
The \fBupvar\fR command simplifies the implementation of call-by-name
diff --git a/contrib/tcl/doc/variable.n b/contrib/tcl/doc/variable.n
new file mode 100644
index 000000000000..1475d47b5976
--- /dev/null
+++ b/contrib/tcl/doc/variable.n
@@ -0,0 +1,67 @@
+'\"
+'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
+'\" 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.
+'\"
+'\" SCCS: @(#) variable.n 1.2 97/05/18 15:20:28
+'\"
+.so man.macros
+.TH variable n 8.0 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+variable \- create and initialize a namespace variable
+.SH SYNOPSIS
+\fBvariable \fR?\fIname value...\fR? \fIname \fR?\fIvalue\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+This command is normally used within a
+\fBnamespace eval\fR command to create one or more variables
+within a namespace.
+Each variable \fIname\fR is initialized with \fIvalue\fR.
+The \fIvalue\fR for the last variable is optional.
+.PP
+If a variable \fIname\fR does not exist,
+it is created and given the optional \fIvalue\fR.
+If it already exists, it is simply set to the optional \fIvalue\fR.
+Normally, \fIname\fR is unqualified
+(does not include the names of any containing namespaces),
+and the variable is created in the current namespace.
+If \fIname\fR includes any namespace qualifiers,
+the variable is created in the specified namespace.
+.PP
+If the \fBvariable\fR command is executed inside a Tcl procedure,
+it creates local variables
+linked to the corresponding namespace variables.
+In this way the \fBvariable\fR command resembles the \fBglobal\fR command,
+although the \fBglobal\fR command
+only links to variables in the global namespace.
+If any \fIvalue\fRs are given,
+they are used to modify the values of the associated namespace variables.
+If a namespace variable does not exist,
+it is created and optionally initialized.
+.PP
+A \fIname\fR argument cannot reference an element within an array.
+Instead, \fIname\fR should reference the entire array,
+and the initialization \fIvalue\fR should be left off.
+After the variable has been declared,
+elements within the array can be set using ordinary
+\fBset\fR or \fBarray\fR commands.
+.PP
+It is generally best to provide a \fIvalue\fR to initialize each variable,
+or to initialize it immediately after the \fBvariable\fR command.
+This is because a namespace variable declared by a \fBvariable\fR command
+is not actually created until it is given a value.
+A declared but not yet initialized namespace variable
+will not appear in the output of an \fBinfo vars\fR command,
+for example.
+
+.SH "SEE ALSO"
+global(n), namespace(n)
+
+.SH KEYWORDS
+global, namespace, procedure, variable
diff --git a/contrib/tcl/doc/while.n b/contrib/tcl/doc/while.n
index 8703684d518b..326d18f76e65 100644
--- a/contrib/tcl/doc/while.n
+++ b/contrib/tcl/doc/while.n
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-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.
'\"
-'\" SCCS: @(#) while.n 1.6 96/03/25 20:27:35
+'\" SCCS: @(#) while.n 1.7 97/04/08 17:13:50
'\"
.so man.macros
.TH while n "" Tcl "Tcl Built-In Commands"
@@ -19,7 +19,7 @@ while \- Execute script repeatedly as long as a condition is met
.SH DESCRIPTION
.PP
-The \fIwhile\fR command evaluates \fItest\fR as an expression
+The \fBwhile\fR command evaluates \fItest\fR as an expression
(in the same way that \fBexpr\fR evaluates its argument).
The value of the expression must a proper boolean
value; if it is a true value
@@ -32,6 +32,24 @@ iteration of the loop, and \fBbreak\fR
commands may be executed inside \fIbody\fR to cause immediate
termination of the \fBwhile\fR command. The \fBwhile\fR command
always returns an empty string.
+.PP
+Note: \fItest\fR should almost always be enclosed in braces. If not,
+variable substitutions will be made before the \fBwhile\fR
+command starts executing, which means that variable changes
+made by the loop body will not be considered in the expression.
+This is likely to result in an infinite loop. If \fItest\fR is
+enclosed in braces, variable substitutions are delayed until the
+expression is evaluated (before
+each loop iteration), so changes in the variables will be visible.
+For an example, try the following script with and without the braces
+around \fB$x<10\fR:
+.CS
+set x 0
+while {$x<10} {
+ puts "x is $x"
+ incr x
+}
+.CE
.SH KEYWORDS
boolean value, loop, test, while