diff options
author | Kevin B Kenny <kennykb@acm.org> | 2001-05-31 23:45:44 (GMT) |
---|---|---|
committer | Kevin B Kenny <kennykb@acm.org> | 2001-05-31 23:45:44 (GMT) |
commit | f16a9d29ec4b0f401338397dee7f5d24f9acffb5 (patch) | |
tree | fdd7e6cc3e4c627755440c7f60e6ebe4311248fc /doc | |
parent | 97464e6cba8eb0008cf2727c15718671992b913f (diff) | |
download | tcl-f16a9d29ec4b0f401338397dee7f5d24f9acffb5.zip tcl-f16a9d29ec4b0f401338397dee7f5d24f9acffb5.tar.gz tcl-f16a9d29ec4b0f401338397dee7f5d24f9acffb5.tar.bz2 |
Development branch for TIPs 22 and 33
kennykb_tip_22_33_botched
Diffstat (limited to 'doc')
-rw-r--r-- | doc/AddErrInfo.3 | 174 | ||||
-rw-r--r-- | doc/Alloc.3 | 52 | ||||
-rw-r--r-- | doc/AllowExc.3 | 42 | ||||
-rw-r--r-- | doc/AppInit.3 | 73 | ||||
-rw-r--r-- | doc/AssocData.3 | 89 | ||||
-rw-r--r-- | doc/Async.3 | 156 | ||||
-rw-r--r-- | doc/BackgdErr.3 | 58 | ||||
-rw-r--r-- | doc/Backslash.3 | 53 | ||||
-rw-r--r-- | doc/BoolObj.3 | 83 | ||||
-rw-r--r-- | doc/ByteArrObj.3 | 91 | ||||
-rw-r--r-- | doc/CallDel.3 | 63 | ||||
-rw-r--r-- | doc/CmdCmplt.3 | 36 | ||||
-rw-r--r-- | doc/Concat.3 | 55 | ||||
-rw-r--r-- | doc/CrtChannel.3 | 592 | ||||
-rw-r--r-- | doc/CrtChnlHdlr.3 | 92 | ||||
-rw-r--r-- | doc/CrtCloseHdlr.3 | 59 | ||||
-rw-r--r-- | doc/CrtCommand.3 | 143 | ||||
-rw-r--r-- | doc/CrtFileHdlr.3 | 100 | ||||
-rw-r--r-- | doc/CrtInterp.3 | 131 | ||||
-rw-r--r-- | doc/CrtMathFnc.3 | 93 | ||||
-rw-r--r-- | doc/CrtObjCmd.3 | 261 | ||||
-rw-r--r-- | doc/CrtSlave.3 | 230 | ||||
-rw-r--r-- | doc/CrtTimerHdlr.3 | 76 | ||||
-rw-r--r-- | doc/CrtTrace.3 | 106 | ||||
-rw-r--r-- | doc/DString.3 | 145 | ||||
-rw-r--r-- | doc/DetachPids.3 | 62 | ||||
-rw-r--r-- | doc/DoOneEvent.3 | 108 | ||||
-rw-r--r-- | doc/DoWhenIdle.3 | 86 | ||||
-rw-r--r-- | doc/DoubleObj.3 | 79 | ||||
-rw-r--r-- | doc/Encoding.3 | 484 | ||||
-rw-r--r-- | doc/Eval.3 | 196 | ||||
-rw-r--r-- | doc/Exit.3 | 131 | ||||
-rw-r--r-- | doc/ExprLong.3 | 114 | ||||
-rw-r--r-- | doc/ExprLongObj.3 | 104 | ||||
-rw-r--r-- | doc/FindExec.3 | 56 | ||||
-rwxr-xr-x | doc/GetCwd.3 | 54 | ||||
-rw-r--r-- | doc/GetIndex.3 | 100 | ||||
-rw-r--r-- | doc/GetInt.3 | 81 | ||||
-rw-r--r-- | doc/GetOpnFl.3 | 61 | ||||
-rw-r--r-- | doc/GetStdChan.3 | 73 | ||||
-rwxr-xr-x | doc/GetVersion.3 | 49 | ||||
-rw-r--r-- | doc/Hash.3 | 208 | ||||
-rw-r--r-- | doc/IntObj.3 | 104 | ||||
-rw-r--r-- | doc/Interp.3 | 125 | ||||
-rw-r--r-- | doc/LinkVar.3 | 115 | ||||
-rw-r--r-- | doc/ListObj.3 | 249 | ||||
-rw-r--r-- | doc/Notifier.3 | 537 | ||||
-rw-r--r-- | doc/Object.3 | 337 | ||||
-rw-r--r-- | doc/ObjectType.3 | 198 | ||||
-rw-r--r-- | doc/OpenFileChnl.3 | 566 | ||||
-rw-r--r-- | doc/OpenTcp.3 | 179 | ||||
-rw-r--r-- | doc/ParseCmd.3 | 426 | ||||
-rw-r--r-- | doc/PkgRequire.3 | 87 | ||||
-rw-r--r-- | doc/Preserve.3 | 103 | ||||
-rw-r--r-- | doc/PrintDbl.3 | 47 | ||||
-rw-r--r-- | doc/RecEvalObj.3 | 55 | ||||
-rw-r--r-- | doc/RecordEval.3 | 57 | ||||
-rw-r--r-- | doc/RegExp.3 | 131 | ||||
-rw-r--r-- | doc/SaveResult.3 | 65 | ||||
-rw-r--r-- | doc/SetErrno.3 | 48 | ||||
-rw-r--r-- | doc/SetRecLmt.3 | 55 | ||||
-rw-r--r-- | doc/SetResult.3 | 225 | ||||
-rw-r--r-- | doc/SetVar.3 | 261 | ||||
-rw-r--r-- | doc/Sleep.3 | 37 | ||||
-rw-r--r-- | doc/SplitList.3 | 191 | ||||
-rw-r--r-- | doc/SplitPath.3 | 93 | ||||
-rw-r--r-- | doc/StaticPkg.3 | 70 | ||||
-rw-r--r-- | doc/StrMatch.3 | 39 | ||||
-rw-r--r-- | doc/StringObj.3 | 161 | ||||
-rw-r--r-- | doc/Tcl.n | 195 | ||||
-rw-r--r-- | doc/Tcl_Main.3 | 61 | ||||
-rw-r--r-- | doc/Thread.3 | 100 | ||||
-rw-r--r-- | doc/ToUpper.3 | 90 | ||||
-rw-r--r-- | doc/TraceVar.3 | 366 | ||||
-rw-r--r-- | doc/Translate.3 | 66 | ||||
-rw-r--r-- | doc/UpVar.3 | 76 | ||||
-rw-r--r-- | doc/Utf.3 | 160 | ||||
-rw-r--r-- | doc/WrongNumArgs.3 | 79 | ||||
-rw-r--r-- | doc/after.n | 109 | ||||
-rw-r--r-- | doc/append.n | 32 | ||||
-rw-r--r-- | doc/array.n | 116 | ||||
-rw-r--r-- | doc/bgerror.n | 68 | ||||
-rw-r--r-- | doc/binary.n | 532 | ||||
-rw-r--r-- | doc/break.n | 34 | ||||
-rw-r--r-- | doc/case.n | 59 | ||||
-rw-r--r-- | doc/catch.n | 70 | ||||
-rw-r--r-- | doc/cd.n | 28 | ||||
-rw-r--r-- | doc/clock.n | 188 | ||||
-rw-r--r-- | doc/close.n | 59 | ||||
-rw-r--r-- | doc/concat.n | 40 | ||||
-rw-r--r-- | doc/continue.n | 34 | ||||
-rw-r--r-- | doc/dde.n | 124 | ||||
-rw-r--r-- | doc/encoding.n | 79 | ||||
-rw-r--r-- | doc/eof.n | 27 | ||||
-rw-r--r-- | doc/error.n | 58 | ||||
-rw-r--r-- | doc/eval.n | 30 | ||||
-rw-r--r-- | doc/exec.n | 358 | ||||
-rw-r--r-- | doc/exit.n | 28 | ||||
-rw-r--r-- | doc/expr.n | 323 | ||||
-rw-r--r-- | doc/fblocked.n | 32 | ||||
-rw-r--r-- | doc/fconfigure.n | 200 | ||||
-rw-r--r-- | doc/fcopy.n | 127 | ||||
-rw-r--r-- | doc/file.n | 331 | ||||
-rw-r--r-- | doc/fileevent.n | 109 | ||||
-rw-r--r-- | doc/filename.n | 197 | ||||
-rw-r--r-- | doc/flush.n | 35 | ||||
-rw-r--r-- | doc/for.n | 60 | ||||
-rw-r--r-- | doc/foreach.n | 86 | ||||
-rw-r--r-- | doc/format.n | 214 | ||||
-rw-r--r-- | doc/gets.n | 50 | ||||
-rw-r--r-- | doc/glob.n | 93 | ||||
-rw-r--r-- | doc/global.n | 35 | ||||
-rw-r--r-- | doc/history.n | 104 | ||||
-rw-r--r-- | doc/http.n | 362 | ||||
-rw-r--r-- | doc/if.n | 43 | ||||
-rw-r--r-- | doc/incr.n | 31 | ||||
-rw-r--r-- | doc/info.n | 185 | ||||
-rw-r--r-- | doc/interp.n | 540 | ||||
-rw-r--r-- | doc/join.n | 29 | ||||
-rw-r--r-- | doc/lappend.n | 35 | ||||
-rw-r--r-- | doc/library.n | 288 | ||||
-rw-r--r-- | doc/lindex.n | 35 | ||||
-rw-r--r-- | doc/linsert.n | 33 | ||||
-rw-r--r-- | doc/list.n | 45 | ||||
-rw-r--r-- | doc/llength.n | 26 | ||||
-rw-r--r-- | doc/load.n | 120 | ||||
-rw-r--r-- | doc/lrange.n | 39 | ||||
-rw-r--r-- | doc/lreplace.n | 43 | ||||
-rw-r--r-- | doc/lsearch.n | 45 | ||||
-rw-r--r-- | doc/lsort.n | 89 | ||||
-rw-r--r-- | doc/man.macros | 236 | ||||
-rw-r--r-- | doc/msgcat.n | 207 | ||||
-rw-r--r-- | doc/namespace.n | 563 | ||||
-rw-r--r-- | doc/open.n | 249 | ||||
-rw-r--r-- | doc/package.n | 193 | ||||
-rw-r--r-- | doc/pid.n | 34 | ||||
-rw-r--r-- | doc/pkgMkIndex.n | 240 | ||||
-rw-r--r-- | doc/proc.n | 74 | ||||
-rw-r--r-- | doc/puts.n | 69 | ||||
-rw-r--r-- | doc/pwd.n | 25 | ||||
-rw-r--r-- | doc/read.n | 50 | ||||
-rw-r--r-- | doc/regexp.n | 1048 | ||||
-rw-r--r-- | doc/registry.n | 168 | ||||
-rw-r--r-- | doc/regsub.n | 72 | ||||
-rw-r--r-- | doc/rename.n | 32 | ||||
-rw-r--r-- | doc/resource.n | 155 | ||||
-rw-r--r-- | doc/return.n | 89 | ||||
-rw-r--r-- | doc/safe.n | 350 | ||||
-rw-r--r-- | doc/scan.n | 182 | ||||
-rw-r--r-- | doc/seek.n | 55 | ||||
-rw-r--r-- | doc/set.n | 48 | ||||
-rw-r--r-- | doc/socket.n | 134 | ||||
-rw-r--r-- | doc/source.n | 44 | ||||
-rw-r--r-- | doc/split.n | 44 | ||||
-rw-r--r-- | doc/string.n | 143 | ||||
-rw-r--r-- | doc/subst.n | 48 | ||||
-rw-r--r-- | doc/switch.n | 107 | ||||
-rw-r--r-- | doc/tclsh.1 | 118 | ||||
-rw-r--r-- | doc/tclvars.n | 367 | ||||
-rw-r--r-- | doc/tell.n | 28 | ||||
-rw-r--r-- | doc/time.n | 33 | ||||
-rw-r--r-- | doc/trace.n | 158 | ||||
-rw-r--r-- | doc/unknown.n | 75 | ||||
-rw-r--r-- | doc/unset.n | 34 | ||||
-rw-r--r-- | doc/update.n | 48 | ||||
-rw-r--r-- | doc/uplevel.n | 80 | ||||
-rw-r--r-- | doc/upvar.n | 92 | ||||
-rw-r--r-- | doc/variable.n | 63 | ||||
-rw-r--r-- | doc/vwait.n | 38 | ||||
-rw-r--r-- | doc/while.n | 55 |
170 files changed, 0 insertions, 22758 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 deleted file mode 100644 index b1820af..0000000 --- a/doc/AddErrInfo.3 +++ /dev/null @@ -1,174 +0,0 @@ -'\" -'\" Copyright (c) 1989-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. -'\" -'\" RCS: @(#) $Id: AddErrInfo.3,v 1.3 1999/03/10 05:52:45 stanton Exp $ -'\" -.so man.macros -.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, 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_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR) -.sp -\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR) -.sp -\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR) -.sp -char * -\fBTcl_PosixError\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_Interp *message -.AP Tcl_Interp *interp in -Interpreter in which to record information. -.AP char *message in -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. -.AP va_list argList in -An argument list which must have been initialised using -\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. -.BE - -.SH DESCRIPTION -.PP -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. -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 -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_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 -to the application, it will contain a complete trace -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_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_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_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 -\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_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that -instead of taking a variable number of arguments it takes an argument list. -.PP -\fBTcl_PosixError\fR -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. -The caller must previously have called \fBTcl_SetErrno\fR to set -\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl -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 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 -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_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_AddObjErrorInfo\fR is called -for an error, it clears the existing value of \fBerrorInfo\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\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 -(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_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno - -.SH KEYWORDS -error, object, object result, stack, trace, variable diff --git a/doc/Alloc.3 b/doc/Alloc.3 deleted file mode 100644 index 405d7fa..0000000 --- a/doc/Alloc.3 +++ /dev/null @@ -1,52 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: Alloc.3,v 1.2 1998/09/14 18:39:45 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Alloc, Tcl_Free, Tcl_Realloc \- allocate or free heap memory -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -char * -\fBTcl_Alloc\fR(\fIsize\fR) -.sp -\fBTcl_Free\fR(\fIptr\fR) -.sp -char * -\fBTcl_Realloc\fR(\fIptr, size\fR) -.SH ARGUMENTS -.AS char *size -.AP int size in -Size in bytes of the memory block to allocate. -.AP char *ptr in -Pointer to memory block to free or realloc. -.BE - -.SH DESCRIPTION -.PP -These procedures provide a platform and compiler independent interface -for memory allocation. Programs that need to transfer ownership of -memory blocks between Tcl and other modules should use these routines -rather than the native \fBmalloc()\fR and \fBfree()\fR routines -provided by the C run-time library. -.PP -\fBTcl_Alloc\fR returns a pointer to a block of at least \fIsize\fR -bytes suitably aligned for any use. -.PP -\fBTcl_Free\fR makes the space referred to by \fIptr\fR available for -further allocation. -.PP -\fBTcl_Realloc\fR changes the size of the block pointed to by -\fIptr\fR to \fIsize\fR bytes and returns a pointer to the new block. -The contents will be unchanged up to the lesser of the new and old -sizes. The returned location may be different from \fIptr\fR. -.SH KEYWORDS -alloc, allocation, free, malloc, memory, realloc diff --git a/doc/AllowExc.3 b/doc/AllowExc.3 deleted file mode 100644 index 1145fa4..0000000 --- a/doc/AllowExc.3 +++ /dev/null @@ -1,42 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: AllowExc.3,v 1.2 1998/09/14 18:39:45 stanton Exp $ -'\" -.so man.macros -.TH Tcl_AllowExceptions 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_AllowExceptions \- allow all exceptions in next script evaluation -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_AllowExceptions\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_Interp *doublePtr -.AP Tcl_Interp *interp in -Interpreter in which script will be evaluated. -.BE - -.SH DESCRIPTION -.PP -If a script is evaluated at top-level (i.e. no other scripts are -pending evaluation when the script is invoked), and if the script -terminates with a completion code other than TCL_OK, TCL_CONTINUE -or TCL_RETURN, then Tcl normally converts this into a TCL_ERROR -return with an appropriate message. -.PP -However, if \fBTcl_AllowExceptions\fR is invoked immediately before -calling a procedure such as \fBTcl_Eval\fR, then arbitrary completion -codes are permitted from the script, and they are returned without -modification. -This is useful in cases where the caller can deal with exceptions -such as TCL_BREAK or TCL_CONTINUE in a meaningful way. - -.SH KEYWORDS -continue, break, exception, interpreter diff --git a/doc/AppInit.3 b/doc/AppInit.3 deleted file mode 100644 index 15ea1e8..0000000 --- a/doc/AppInit.3 +++ /dev/null @@ -1,73 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: AppInit.3,v 1.2 1998/09/14 18:39:46 stanton Exp $ -'\" -.so man.macros -.TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_AppInit \- perform application-specific initialization -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_AppInit\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Interpreter for the application. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by -the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR. -Its purpose is to allow new Tcl applications to be created without -modifying the main programs provided as part of Tcl and Tk. -To create a new application you write a new version of -\fBTcl_AppInit\fR to replace the default version provided by Tcl, -then link your new \fBTcl_AppInit\fR with the Tcl library. -.PP -\fBTcl_AppInit\fR is invoked after by \fBTcl_Main\fR and \fBTk_Main\fR -after their own initialization and before entering the main loop -to process commands. -Here are some examples of things that \fBTcl_AppInit\fR might do: -.IP [1] -Call initialization procedures for various packages used by -the application. -Each initialization procedure adds new commands to \fIinterp\fR -for its package and performs other package-specific initialization. -.IP [2] -Process command-line arguments, which can be accessed from the -Tcl variables \fBargv\fR and \fBargv0\fR in \fIinterp\fR. -.IP [3] -Invoke a startup script to initialize the application. -.LP -\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. -.PP -In addition to \fBTcl_AppInit\fR, your application should also contain -a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows: -.CS -Tcl_Main(argc, argv, Tcl_AppInit); -.CE -The third argument to \fBTcl_Main\fR gives the address of the -application-specific initialization procedure to invoke. -This means that you don't have to use the name \fBTcl_AppInit\fR -for the procedure, but in practice the name is nearly always -\fBTcl_AppInit\fR (in versions before Tcl 7.4 the name \fBTcl_AppInit\fR -was implicit; there was no way to specify the procedure explicitly). -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. - -.SH KEYWORDS -application, argument, command, initialization, interpreter diff --git a/doc/AssocData.3 b/doc/AssocData.3 deleted file mode 100644 index 9b68c43..0000000 --- a/doc/AssocData.3 +++ /dev/null @@ -1,89 +0,0 @@ -'\" -'\" 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. -'\" -'\" -'\" RCS: @(#) $Id: AssocData.3,v 1.3 1999/04/16 00:46:30 stanton Exp $ -.so man.macros -.TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage -associations of string keys and user specified data with Tcl -interpreters. -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -ClientData -\fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR) -.sp -\fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR) -.sp -\fBTcl_DeleteAssocData\fR(\fIinterp, key\fR) -.SH ARGUMENTS -.AS Tcl_InterpDeleteProc *delProcPtr -.AP Tcl_Interp *interp in -Interpreter in which to execute the specified command. -.AP char *key in -Key for association with which to store data or from which to delete or -retrieve data. Typically the module prefix for a package. -.AP Tcl_InterpDeleteProc *delProc in -Procedure to call when \fIinterp\fR is deleted. -.AP Tcl_InterpDeleteProc **delProcPtr in -Pointer to location in which to store address of current deletion procedure -for association. Ignored if NULL. -.AP ClientData clientData in -Arbitrary one-word value associated with the given key in this -interpreter. This data is owned by the caller. -.BE - -.SH DESCRIPTION -.PP -These procedures allow extensions to associate their own data with -a Tcl interpreter. -An association consists of a string key, typically the name of -the extension, and a one-word value, which is typically a pointer -to a data structure holding data specific to the extension. -Tcl makes no interpretation of either the key or the value for -an association. -.PP -Storage management is facilitated by storing with each association a -procedure to call when the interpreter is deleted. This -procedure can dispose of the storage occupied by the client's data in any -way it sees fit. -.PP -\fBTcl_SetAssocData\fR creates an association between a string -key and a user specified datum in the given interpreter. -If there is already an association with the given \fIkey\fR, -\fBTcl_SetAssocData\fR overwrites it with the new information. -It is up to callers to organize their use of names to avoid conflicts, -for example, by using package names as the keys. -If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a -procedure to invoke if the interpreter is deleted before the association -is deleted. \fIDeleteProc\fR should have arguments and result that match -the type \fBTcl_InterpDeleteProc\fR: -.CS -typedef void Tcl_InterpDeleteProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR); -.CE -When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR -arguments will be the same as the corresponding arguments passed to -\fBTcl_SetAssocData\fR. -The deletion procedure will \fInot\fR be invoked if the association -is deleted before the interpreter is deleted. -.PP -\fBTcl_GetAssocData\fR returns the datum stored in the association with the -specified key in the given interpreter, and if the \fIdelProcPtr\fR field -is non-\fBNULL\fR, the address indicated by it gets the address of the -delete procedure stored with this association. If no association with the -specified key exists in the given interpreter \fBTcl_GetAssocData\fR -returns \fBNULL\fR. -.PP -\fBTcl_DeleteAssocData\fR deletes an association with a specified key in -the given interpreter. Then it calls the deletion procedure. -.SH KEYWORDS -association, data, deletion procedure, interpreter, key diff --git a/doc/Async.3 b/doc/Async.3 deleted file mode 100644 index 5086557..0000000 --- a/doc/Async.3 +++ /dev/null @@ -1,156 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Async.3,v 1.3 1999/04/16 00:46:30 stanton Exp $ -'\" -.so man.macros -.TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_AsyncHandler -\fBTcl_AsyncCreate\fR(\fIproc, clientData\fR) -.sp -\fBTcl_AsyncMark\fR(\fIasync\fR) -.sp -int -\fBTcl_AsyncInvoke\fR(\fIinterp, code\fR) -.sp -\fBTcl_AsyncDelete\fR(\fIasync\fR) -.sp -int -\fBTcl_AsyncReady\fR() -.SH ARGUMENTS -.AS Tcl_AsyncHandler clientData -.AP Tcl_AsyncProc *proc in -Procedure to invoke to handle an asynchronous event. -.AP ClientData clientData in -One-word value to pass to \fIproc\fR. -.AP Tcl_AsyncHandler async in -Token for asynchronous event handler. -.AP Tcl_Interp *interp in -Tcl interpreter in which command was being evaluated when handler was -invoked, or NULL if handler was invoked when there was no interpreter -active. -.AP int code in -Completion code from command that just completed in \fIinterp\fR, -or 0 if \fIinterp\fR is NULL. -.BE - -.SH DESCRIPTION -.PP -These procedures provide a safe mechanism for dealing with -asynchronous events such as signals. -If an event such as a signal occurs while a Tcl script is being -evaluated then it isn't safe to take any substantive action to -process the event. -For example, it isn't safe to evaluate a Tcl script since the -interpreter may already be in the middle of evaluating a script; -it may not even be safe to allocate memory, since a memory -allocation could have been in progress when the event occurred. -The only safe approach is to set a flag indicating that the event -occurred, then handle the event later when the world has returned -to a clean state, such as after the current Tcl command completes. -.PP -\fBTcl_AsyncCreate\fR creates an asynchronous handler and returns -a token for it. -The asynchronous handler must be created before -any occurrences of the asynchronous event that it is intended -to handle (it is not safe to create a handler at the time of -an event). -When an asynchronous event occurs the code that detects the event -(such as a signal handler) should call \fBTcl_AsyncMark\fR with the -token for the handler. -\fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it -will not invoke the handler immediately. -Tcl will call the \fIproc\fR associated with the handler later, when -the world is in a safe state, and \fIproc\fR can then carry out -the actions associated with the asynchronous event. -\fIProc\fR should have arguments and result that match the -type \fBTcl_AsyncProc\fR: -.CS -typedef int Tcl_AsyncProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIcode\fR); -.CE -The \fIclientData\fR will be the same as the \fIclientData\fR -argument passed to \fBTcl_AsyncCreate\fR when the handler was -created. -If \fIproc\fR is invoked just after a command has completed -execution in an interpreter, then \fIinterp\fR will identify -the interpreter in which the command was evaluated and -\fIcode\fR will be the completion code returned by that -command. -The command's result will be present in \fIinterp->result\fR. -When \fIproc\fR returns, whatever it leaves in \fIinterp->result\fR -will be returned as the result of the command and the integer -value returned by \fIproc\fR will be used as the new completion -code for the command. -.PP -It is also possible for \fIproc\fR to be invoked when no interpreter -is active. -This can happen, for example, if an asynchronous event occurs while -the application is waiting for interactive input or an X event. -In this case \fIinterp\fR will be NULL and \fIcode\fR will be -0, and the return value from \fIproc\fR will be ignored. -.PP -The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the -handlers that are ready. -The procedure \fBTcl_AsyncReady\fR will return non-zero whenever any -asynchronous handlers are ready; it can be checked to avoid calls -to \fBTcl_AsyncInvoke\fR when there are no ready handlers. -Tcl calls \fBTcl_AsyncReady\fR after each command is evaluated -and calls \fBTcl_AsyncInvoke\fR if needed. -Applications may also call \fBTcl_AsyncInvoke\fR at interesting -times for that application. -For example, Tcl's event handler calls \fBTcl_AsyncReady\fR -after each event and calls \fBTcl_AsyncInvoke\fR if needed. -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 -that just completed. -.PP -\fBTcl_AsyncDelete\fR removes an asynchronous handler so that -its \fIproc\fR will never be invoked again. -A handler can be deleted even when ready, and it will still -not be invoked. -.PP -If multiple handlers become active at the same time, the -handlers are invoked in the order they were created (oldest -handler first). -The \fIcode\fR and \fIinterp->result\fR for later handlers -reflect the values returned by earlier handlers, so that -the most recently created handler has last say about -the interpreter's result and completion code. -If new handlers become ready while handlers are executing, -\fBTcl_AsyncInvoke\fR will invoke them all; at each point it -invokes the highest-priority (oldest) ready handler, repeating -this over and over until there are no longer any ready handlers. - -.SH WARNING -.PP -It is almost always a bad idea for an asynchronous event -handler to modify \fIinterp->result\fR or return a code different -from its \fIcode\fR argument. -This sort of behavior can disrupt the execution of scripts in -subtle ways and result in bugs that are extremely difficult -to track down. -If an asynchronous event handler needs to evaluate Tcl scripts -then it should first save \fIinterp->result\fR plus the values -of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can -be done, for example, by storing them in dynamic strings). -When the asynchronous handler is finished it should restore -\fIinterp->result\fR, \fBerrorInfo\fR, and \fBerrorCode\fR, -and return the \fIcode\fR argument. - -.SH KEYWORDS -asynchronous event, handler, signal diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3 deleted file mode 100644 index 72d1530..0000000 --- a/doc/BackgdErr.3 +++ /dev/null @@ -1,58 +0,0 @@ -'\" -'\" Copyright (c) 1992-1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: BackgdErr.3,v 1.2 1998/09/14 18:39:46 stanton Exp $ -'\" -.so man.macros -.TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_BackgroundError \- report Tcl error that occurred in background processing -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_BackgroundError\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Interpreter in which the error occurred. -.BE - -.SH DESCRIPTION -.PP -This procedure is typically invoked when a Tcl error occurs during -``background processing'' such as executing an event handler. -When such an error occurs, the error condition is reported to Tcl -or to a widget or some other C code, and there is not usually any -obvious way for that code to report the error to the user. -In these cases the code calls \fBTcl_BackgroundError\fR with an -\fIinterp\fR argument identifying the interpreter in which the -error occurred. At the time \fBTcl_BackgroundError\fR is invoked, -\fIinterp->result\fR is expected to contain an error message. -\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR -Tcl command to report the error in an application-specific fashion. -If no \fBbgerror\fR command exists, or if it returns with an error condition, -then \fBTcl_BackgroundError\fR reports the error itself by printing -a message on the standard error file. -.PP -\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately -because this could potentially interfere with scripts that are in process -at the time the error occurred. -Instead, it invokes \fBbgerror\fR later as an idle callback. -\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and -\fBerrorCode\fR variables and restores these values just before -invoking \fBbgerror\fR. -.PP -It is possible for many background errors to accumulate before -\fBbgerror\fR is invoked. When this happens, each of the errors -is processed in order. However, if \fBbgerror\fR returns a -break exception, then all remaining error reports for the -interpreter are skipped. - -.SH KEYWORDS -background, bgerror, error diff --git a/doc/Backslash.3 b/doc/Backslash.3 deleted file mode 100644 index 95fc7e8..0000000 --- a/doc/Backslash.3 +++ /dev/null @@ -1,53 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Backslash.3,v 1.3 1999/04/16 00:46:30 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Backslash \- parse a backslash sequence -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -char -\fBTcl_Backslash\fR(\fIsrc, countPtr\fR) -.SH ARGUMENTS -.AS char *countPtr -.AP char *src in -Pointer to a string starting with a backslash. -.AP int *countPtr out -If \fIcountPtr\fR isn't NULL, \fI*countPtr\fR gets filled -in with number of characters in the backslash sequence, including -the backslash character. -.BE - -.SH DESCRIPTION -.PP -.VS 8.1 -The use of \fBTcl_Backslash\fR is deprecated in favor of -\fBTcl_UtfBackslash\fR. -.PP -This is a utility procedure provided for backwards compatibilty with -non-internationalized Tcl extensions. It parses a backslash sequence and -returns the low byte of the Unicode character corresponding to the sequence. -.VE -\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of -characters in the backslash sequence. -.PP -See the Tcl manual entry for information on the valid backslash sequences. -All of the sequences described in the Tcl manual entry are supported by -\fBTcl_Backslash\fR. -.VS 8.1 br -.SH "SEE ALSO" -Tcl(n), Tcl_UtfBackslash(3) -.VE - -.SH KEYWORDS -backslash, parse diff --git a/doc/BoolObj.3 b/doc/BoolObj.3 deleted file mode 100644 index 2306350..0000000 --- a/doc/BoolObj.3 +++ /dev/null @@ -1,83 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: BoolObj.3,v 1.2 1998/09/14 18:39:46 stanton Exp $ -'\" -.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/doc/ByteArrObj.3 b/doc/ByteArrObj.3 deleted file mode 100644 index b3ed34f..0000000 --- a/doc/ByteArrObj.3 +++ /dev/null @@ -1,91 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: ByteArrObj.3,v 1.2 1999/03/03 00:38:36 stanton Exp $ -'\" -.so man.macros -.TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Obj * -\fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR) -.sp -void -\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR) -.sp -unsigned char * -\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR) -.sp -unsigned char * -\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR) -.SH ARGUMENTS -.AS "unsigned char" *lengthPtr in/out -.AP "unsigned char" *bytes in -The array of bytes used to initialize or set a byte-array object. -.AP int length in -The length of the array of bytes. It must be >= 0. -.AP Tcl_Obj *objPtr in/out -For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to -byte-array type. For \fBTcl_GetByteArrayFromObj\fR and -\fBTcl_SetByteArrayLength\fR, this points to the object from which to get -the byte-array value; if \fIobjPtr\fR does not already point to a byte-array -object, it will be converted to one. -.AP int *lengthPtr out -If non-NULL, filled with the length of the array of bytes in the object. -.BE - -.SH DESCRIPTION -.PP -These procedures are used to create, modify, and read Tcl byte-array objects -from C code. Byte-array objects are typically used to hold the -results of binary IO operations or data structures created with the -\fBbinary\fR command. In Tcl, an array of bytes is not equivalent to a -string. Conceptually, a string is an array of Unicode characters, while a -byte-array is an array of 8-bit quantities with no implicit meaning. -Accesser functions are provided to get the string representation of a -byte-array or to convert an arbitrary object to a byte-array. Obtaining the -string representation of a byte-array object (by calling -\fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a -one-to-one mapping between the bytes in the internal representation and the -UTF-8 characters in the string representation. -.PP -\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will -create a new object of byte-array type or modify an existing object to have a -byte-array type. Both of these procedures set the object's type to be -byte-array and set the object's internal representation to a copy of the -array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a -pointer to a newly allocated object with a reference count of zero. -\fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if -the object is not already a byte-array object, frees any old internal -representation. -.PP -\fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and -returns a pointer to the object's new internal representation as an array of -bytes. The length of this array is stored in \fIlengthPtr\fR if -\fIlengthPtr\fR is non-NULL. The storage for the array of bytes is owned by -the object and should not be freed. The contents of the array may be -modified by the caller only if the object is not shared and the caller -invalidates the string representation. -.PP -\fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type -and changes the length of the object's internal representation as an -array of bytes. If \fIlength\fR is greater than the space currently -allocated for the array, the array is reallocated to the new length; the -newly allocated bytes at the end of the array have arbitrary values. If -\fIlength\fR is less than the space currently allocated for the array, -the length of array is reduced to the new length. The return value is a -pointer to the object's new array of bytes. - -.SH "SEE ALSO" -Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount - -.SH KEYWORDS -object, byte array, utf, unicode, internationalization diff --git a/doc/CallDel.3 b/doc/CallDel.3 deleted file mode 100644 index 089a922..0000000 --- a/doc/CallDel.3 +++ /dev/null @@ -1,63 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: CallDel.3,v 1.2 1998/09/14 18:39:46 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interpreter is deleted -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_CallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) -.sp -\fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) -.SH ARGUMENTS -.AS Tcl_InterpDeleteProc clientData -.AP Tcl_Interp *interp in -Interpreter with which to associated callback. -.AP Tcl_InterpDeleteProc *proc in -Procedure to call when \fIinterp\fR is deleted. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by -\fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future -time. \fIProc\fR will be invoked just before the interpreter -is deleted, but the interpreter will still be valid at the -time of the call. -\fIProc\fR should have arguments and result that match the -type \fBTcl_InterpDeleteProc\fR: -.CS -typedef void Tcl_InterpDeleteProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR); -.CE -The \fIclientData\fR and \fIinterp\fR parameters are -copies of the \fIclientData\fR and \fIinterp\fR arguments given -to \fBTcl_CallWhenDeleted\fR. -Typically, \fIclientData\fR points to an application-specific -data structure that \fIproc\fR uses to perform cleanup when an -interpreter is about to go away. -\fIProc\fR does not return a value. -.PP -\fBTcl_DontCallWhenDeleted\fR cancels a previous call to -\fBTcl_CallWhenDeleted\fR with the same arguments, so that -\fIproc\fR won't be called after all when \fIinterp\fR is -deleted. -If there is no deletion callback that matches \fIinterp\fR, -\fIproc\fR, and \fIclientData\fR then the call to -\fBTcl_DontCallWhenDeleted\fR has no effect. - -.SH KEYWORDS -callback, delete, interpreter diff --git a/doc/CmdCmplt.3 b/doc/CmdCmplt.3 deleted file mode 100644 index b7effed..0000000 --- a/doc/CmdCmplt.3 +++ /dev/null @@ -1,36 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: CmdCmplt.3,v 1.2 1998/09/14 18:39:46 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CommandComplete 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CommandComplete \- Check for unmatched braces in a Tcl command -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_CommandComplete\fR(\fIcmd\fR) -.SH ARGUMENTS -.AS char *cmd -.AP char *cmd in -Command string to test for completeness. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CommandComplete\fR takes a Tcl command string -as argument and determines whether it contains one or more -complete commands (i.e. there are no unclosed quotes, braces, -brackets, or variable references). -If the command string is complete then it returns 1; otherwise it returns 0. - -.SH KEYWORDS -complete command, partial command diff --git a/doc/Concat.3 b/doc/Concat.3 deleted file mode 100644 index edebc01..0000000 --- a/doc/Concat.3 +++ /dev/null @@ -1,55 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Concat.3,v 1.2 1998/09/14 18:39:46 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Concat \- concatenate a collection of strings -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -char * -\fBTcl_Concat\fR(\fIargc, argv\fR) -.SH ARGUMENTS -.AP int argc in -Number of strings. -.AP char *argv[] in -Array of strings to concatenate. Must have \fIargc\fR entries. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_Concat\fR is a utility procedure used by several of the -Tcl commands. Given a collection of strings, it concatenates -them together into a single string, with the original strings -separated by spaces. This procedure behaves differently than -\fBTcl_Merge\fR, in that the arguments are simply concatenated: -no effort is made to ensure proper list structure. -However, in most common usage the arguments will all be proper -lists themselves; if this is true, then the result will also have -proper list structure. -.PP -\fBTcl_Concat\fR eliminates leading and trailing white space as it -copies strings from \fBargv\fR to the result. If an element of -\fBargv\fR consists of nothing but white space, then that string -is ignored entirely. This white-space removal was added to make -the output of the \fBconcat\fR command cleaner-looking. -.PP -.VS -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/doc/CrtChannel.3 b/doc/CrtChannel.3 deleted file mode 100644 index dc0f91b..0000000 --- a/doc/CrtChannel.3 +++ /dev/null @@ -1,592 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: CrtChannel.3,v 1.3 1999/04/16 00:46:30 stanton Exp $ -.so man.macros -.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_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, 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, instanceData, mask\fR) -.sp -ClientData -\fBTcl_GetChannelInstanceData\fR(\fIchannel\fR) -.sp -Tcl_ChannelType * -\fBTcl_GetChannelType\fR(\fIchannel\fR) -.sp -char * -\fBTcl_GetChannelName\fR(\fIchannel\fR) -.VS -.sp -int -\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR) -.VE -.sp -int -\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR) -.sp -\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_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. -.AP char *channelName in -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 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 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 -.PP -Tcl uses a two-layered channel architecture. It provides a generic upper -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 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 -functions implementing the various operations used by the generic layer to -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 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 -that opens a channel by invoking \fBTcl_CreateChannel\fR. -When your driver calls \fBTcl_CreateChannel\fR it passes in -a \fBTcl_ChannelType\fR structure describing the driver's I/O -procedures. -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 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 -\fBTcl_GetChannelInstanceData\fR returns the instance data associated with -the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR -argument in the call to \fBTcl_CreateChannel\fR that created this channel. -.PP -\fBTcl_GetChannelType\fR returns a pointer to the \fBTcl_ChannelType\fR -structure used by the channel in the \fIchannel\fR argument. This is -the same as the \fItypePtr\fR argument in the call to -\fBTcl_CreateChannel\fR that created this channel. -.PP -\fBTcl_GetChannelName\fR returns a string containing the name associated -with the channel, or NULL if the \fIchannelName\fR argument to -\fBTcl_CreateChannel\fR was NULL. -.PP -.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_GetChannelBufferSize\fR returns the size, in bytes, of buffers -allocated to store input or output in \fIchan\fR. If the value was not set -by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then -the default value of 4096 is returned. -.PP -\fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that -will be allocated in subsequent operations on the channel to store input or -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 -A channel driver provides a \fBTcl_ChannelType\fR structure that contains -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; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; - Tcl_DriverCloseProc *\fIcloseProc\fR; - Tcl_DriverInputProc *\fIinputProc\fR; - Tcl_DriverOutputProc *\fIoutputProc\fR; - Tcl_DriverSeekProc *\fIseekProc\fR; - Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; - Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; - Tcl_DriverWatchProc *\fIwatchProc\fR; - Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; - Tcl_DriverClose2Proc *\fIclose2Proc\fR; -} Tcl_ChannelType; -.CE -.VE -.PP -The driver must provide implementations for all functions except -\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, -.VS -\fIgetOptionProc\fR, and \fIclose2Proc\fR, which may be specified as -.VE -NULL. Other functions that can not be implemented for this type of -device should return \fBEINVAL\fR when invoked to indicate that they -are not implemented. - -.SH TYPENAME -.PP -The \fItypeName\fR field contains a null-terminated string that -identifies the type of the device implemented by this driver, e.g. -\fBfile\fR or \fBsocket\fR. - -.SH BLOCKMODEPROC -.PP -The \fIblockModeProc\fR field contains the address of a function called by -the generic layer to set blocking and nonblocking mode on the device. -\fIBlockModeProc\fR should match the following prototype: -.PP -.CS -typedef int Tcl_DriverBlockModeProc( - ClientData \fIinstanceData\fR, - int \fImode\fR); -.CE -.PP -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 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. - -.SH CLOSEPROC AND CLOSE2PROC -.PP -The \fIcloseProc\fR field contains the address of a function called by the -generic layer to clean up driver-related information when the channel is -closed. \fICloseProc\fR must match the following prototype: -.PP -.CS -typedef int Tcl_DriverCloseProc( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR); -.CE -.PP -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. -.PP -.VS -Alternatively, channels that support closing the read and write sides -independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set -\fIclose2Proc\fR to the address of a function that matches the -following prototype: -.PP -.CS -typedef int Tcl_DriverClose2Proc( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIflags\fR); -.CE -.PP -The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed -combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to -indicate that the driver should close the read and/or write side of -the channel. The channel driver may be invoked to perform -additional operations on the channel after \fIclose2Proc\fR is -called to close one or both sides of the channel. If \fIflags\fR is -\fB0\fR (zero), the driver should close the channel in the manner -described above for \fIcloseProc\fR. No further operations will be -invoked on this instance after \fIclose2Proc\fR is called with all -flags cleared. In all cases, the \fIclose2Proc\fR function should -return zero if the close operation was successful; 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. -.VE - -.SH INPUTPROC -.PP -The \fIinputProc\fR field contains the address of a function called by the -generic layer to read data from the file or device and store it in an -internal buffer. \fIInputProc\fR must match the following prototype: -.PP -.CS -typedef int Tcl_DriverInputProc( - ClientData \fIinstanceData\fR, - char *\fIbuf\fR, - int \fIbufSize\fR, - int *\fIerrorCodePtr\fR); -.CE -.PP -\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 -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 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 -function should only attempt to read as much data as is available and -return without blocking. If the input device has no data available -whatsoever and the channel is in nonblocking mode, the function should -return an \fBEAGAIN\fR error. If the input device has no data available -whatsoever and the channel is in blocking mode, the function should block -for the shortest possible time until at least one byte of data can be read -from the device; then, it should return as much data as it can read without -blocking. - -.SH OUTPUTPROC -.PP -The \fIoutputProc\fR field contains the address of a function called by the -generic layer to transfer data from an internal buffer to the output device. -\fIOutputProc\fR must match the following prototype: -.PP -.CS -typedef int Tcl_DriverOutputProc( - ClientData \fIinstanceData\fR, - char *\fIbuf\fR, - int \fItoWrite\fR, - int *\fIerrorCodePtr\fR); -.CE -.PP -\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 -\fIbuf\fR argument. -.PP -The \fIerrorCodePtr\fR argument points to an integer variable provided by -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 -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 -without writing any data. - -.SH SEEKPROC -.PP -The \fIseekProc\fR field contains the address of a function called by the -generic layer to move the access point at which subsequent input or output -operations will be applied. \fISeekProc\fR must match the following -prototype: -.PP -.CS -typedef int Tcl_DriverSeekProc( - ClientData \fIinstanceData\fR, - long \fIoffset\fR, - int \fIseekMode\fR, - int *\fIerrorCodePtr\fR); -.CE -.PP -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_Seek\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. -.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. - -.SH SETOPTIONPROC -.PP -The \fIsetOptionProc\fR field contains the address of a function called by -the generic layer to set a channel type specific option on a channel. -\fIsetOptionProc\fR must match the following prototype: -.PP -.CS -typedef int Tcl_DriverSetOptionProc( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR, - char *\fIoptionName\fR, - char *\fIoptionValue\fR); -.CE -.PP -\fIoptionName\fR is the name of an option to set, and \fIoptionValue\fR is -the new value for that option, as a string. The \fIinstanceData\fR is the -same as the value given to \fBTcl_CreateChannel\fR when this channel was -created. The function should do whatever channel type specific action is -required to implement the new value of the option. -.PP -Some options are handled by the generic code and this function is never -called to set them, e.g. \fB-blockmode\fR. Other options are specific to -each channel type and the \fIsetOptionProc\fR procedure of the channel -driver will get called to implement them. The \fIsetOptionProc\fR field can -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. -.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. - -.SH GETOPTIONPROC -.PP -The \fIgetOptionProc\fR field contains the address of a function called by -the generic layer to get the value of a channel type specific option on a -channel. \fIgetOptionProc\fR must match the following prototype: -.PP -.CS -typedef int Tcl_DriverGetOptionProc( - ClientData \fIinstanceData\fR, -.VS - Tcl_Interp *\fIinterp\fR, -.VE - char *\fIoptionName\fR, - Tcl_DString *\fIdsPtr\fR); -.CE -.PP -\fIOptionName\fR is the name of an option supported by this type of -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. -.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 -specific to each channel type and the \fIgetOptionProc\fR procedure of the -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_QueueEvent(3) - -.SH KEYWORDS -blocking, channel driver, channel registration, channel type, nonblocking diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3 deleted file mode 100644 index 4536ef6..0000000 --- a/doc/CrtChnlHdlr.3 +++ /dev/null @@ -1,92 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: CrtChnlHdlr.3,v 1.2 1998/09/14 18:39:46 stanton Exp $ -.so man.macros -.TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable -.SH SYNOPSIS -.nf -.nf -\fB#include <tcl.h>\fR -.sp -void -\fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR) -.sp -void -\fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR) -.sp -.SH ARGUMENTS -.AS Tcl_ChannelProc clientData -.AP Tcl_Channel channel in -Tcl channel such as returned by \fBTcl_CreateChannel\fR. -.AP int mask in -Conditions under which \fIproc\fR should be called: OR-ed combination of -\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify -a zero value to temporarily disable an existing handler. -.AP Tcl_FileProc *proc in -Procedure to invoke whenever the channel indicated by \fIchannel\fR meets -the conditions specified by \fImask\fR. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the -future whenever input or output becomes possible on the channel identified -by \fIchannel\fR, or whenever an exceptional condition exists for -\fIchannel\fR. The conditions of interest under which \fIproc\fR will be -invoked are specified by the \fImask\fR argument. -See the manual entry for \fBfileevent\fR for a precise description of -what it means for a channel to be readable or writable. -\fIProc\fR must conform to the following prototype: -.CS -typedef void Tcl_ChannelProc( - ClientData \fIclientData\fR, - int \fImask\fR); -.CE -.PP -The \fIclientData\fR argument is the same as the value passed to -\fBTcl_CreateChannelHandler\fR when the handler was created. Typically, -\fIclientData\fR points to a data structure containing application-specific -information about the channel. \fIMask\fR is an integer mask indicating -which of the requested conditions actually exists for the channel; it will -contain a subset of the bits from the \fImask\fR argument to -\fBTcl_CreateChannelHandler\fR when the handler was created. -.PP -Each channel handler is identified by a unique combination of \fIchannel\fR, -\fIproc\fR and \fIclientData\fR. -There may be many handlers for a given channel as long as they don't -have the same \fIchannel\fR, \fIproc\fR, and \fIclientData\fR. -If \fBTcl_CreateChannelHandler\fR is invoked when there is already a handler -for \fIchannel\fR, \fIproc\fR, and \fIclientData\fR, then no new -handler is created; instead, the \fImask\fR is changed for the -existing handler. -.PP -\fBTcl_DeleteChannelHandler\fR deletes a channel handler identified by -\fIchannel\fR, \fIproc\fR and \fIclientData\fR; if no such handler exists, -the call has no effect. -.PP -Channel handlers are invoked via the Tcl event mechanism, so they -are only useful in applications that are event-driven. -Note also that the conditions specified in the \fImask\fR argument -to \fIproc\fR may no longer exist when \fIproc\fR is invoked: for -example, if there are two handlers for \fBTCL_READABLE\fR on the same -channel, the first handler could consume all of the available input -so that the channel is no longer readable when the second handler -is invoked. -For this reason it may be useful to use nonblocking I/O on channels -for which there are event handlers. - -.SH "SEE ALSO" -Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). - -.SH KEYWORDS -blocking, callback, channel, events, handler, nonblocking. diff --git a/doc/CrtCloseHdlr.3 b/doc/CrtCloseHdlr.3 deleted file mode 100644 index 8f7b4ba..0000000 --- a/doc/CrtCloseHdlr.3 +++ /dev/null @@ -1,59 +0,0 @@ -'\" -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: CrtCloseHdlr.3,v 1.2 1998/09/14 18:39:47 stanton Exp $ -.so man.macros -.TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Tcl_CreateCloseHandler, Tcl_DeleteCloseHandler \- arrange for callbacks when channels are closed -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -void -\fBTcl_CreateCloseHandler\fR(\fIchannel, proc, clientData\fR) -.sp -void -\fBTcl_DeleteCloseHandler\fR(\fIchannel, proc, clientData\fR) -.sp -.SH ARGUMENTS -.AS Tcl_CloseProc callbackData in -.AP Tcl_Channel channel in -The channel for which to create or delete a close callback. -.AP Tcl_CloseProc *proc in -The procedure to call as the callback. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CreateCloseHandler\fR arranges for \fIproc\fR to be called when -\fIchannel\fR is closed with \fBTcl_Close\fR or -\fBTcl_UnregisterChannel\fR, or using the Tcl \fBclose\fR command. -\fIProc\fR should match the following prototype: -.PP -.CS -typedef void Tcl_CloseProc( - ClientData \fIclientData\fR); -.CE -.PP -The \fIclientData\fR is the same as the value provided in the call to -\fBTcl_CreateCloseHandler\fR. -.PP -\fBTcl_DeleteCloseHandler\fR removes a close callback for \fIchannel\fR. -The \fIproc\fR and \fIclientData\fR identify which close callback to -remove; \fBTcl_DeleteCloseHandler\fR does nothing if its \fIproc\fR and -\fIclientData\fR arguments do not match the \fIproc\fR and \fIclientData\fR -for a close handler for \fIchannel\fR. - -.SH "SEE ALSO" -close(n), Tcl_Close(3), Tcl_UnregisterChannel(3) - -.SH KEYWORDS -callback, channel closing diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3 deleted file mode 100644 index f2f6cea..0000000 --- a/doc/CrtCommand.3 +++ /dev/null @@ -1,143 +0,0 @@ -'\" -'\" Copyright (c) 1989-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. -'\" -'\" RCS: @(#) $Id: CrtCommand.3,v 1.3 1998/10/05 17:35:53 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateCommand \- implement new commands in C -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Command -\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR) -.SH ARGUMENTS -.AS Tcl_CmdDeleteProc **deleteProcPtr -.AP Tcl_Interp *interp in -Interpreter in which to create new command. -.AP char *cmdName in -Name of command. -.AP Tcl_CmdProc *proc in -Implementation of 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. -.BE - -.SH DESCRIPTION -.PP -\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. -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. -\fIProc\fR should have arguments and result that match the type -\fBTcl_CmdProc\fR: -.CS -typedef int Tcl_CmdProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIargc\fR, - char *\fIargv\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_CreateCommand\fR. -Typically, \fIclientData\fR points to an application-specific -data structure that describes what to do when the command procedure -is invoked. \fIArgc\fR and \fIargv\fR describe the arguments to -the command, \fIargc\fR giving the number of arguments (including -the command name) and \fIargv\fR giving the values of the arguments -as strings. The \fIargv\fR array will contain \fIargc\fR+1 values; -the first \fIargc\fR values point to the argument strings, and the -last value is NULL. -.VS -Note that the argument strings should not be modified as they may -point to constant strings or may be shared with other parts of the -interpreter. -.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, \fIproc\fR must set -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 the interpreter result -field is managed, see the \fBTcl_Interp\fR man page. -Before invoking a command procedure, -\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 -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 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. -.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, -or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\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_CreateCommand\fR. -.PP - -.SH "SEE ALSO" -Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult - -.SH KEYWORDS -bind, command, create, delete, interpreter, namespace diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3 deleted file mode 100644 index b660170..0000000 --- a/doc/CrtFileHdlr.3 +++ /dev/null @@ -1,100 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 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. -'\" -'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.2 1998/09/14 18:39:47 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -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(\fIfd, mask, proc, clientData\fR) -.sp -\fBTcl_DeleteFileHandler\fR(\fIfd\fR) -.VE -.SH ARGUMENTS -.AS Tcl_FileProc clientData -.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, -and \fBTCL_EXCEPTION\fR. May be set to 0 to temporarily disable -a handler. -.AP Tcl_FileProc *proc in -Procedure to invoke whenever the file or device indicated -by \fIfile\fR meets the conditions specified by \fImask\fR. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.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 \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. -The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so -\fBTcl_CreateFileHandler\fR is only useful in programs that dispatch -events through \fBTcl_DoOneEvent\fR or through Tcl commands such -as \fBvwait\fR. -.PP -\fIProc\fR should have arguments and result that match the -type \fBTcl_FileProc\fR: -.CS -typedef void Tcl_FileProc( - ClientData \fIclientData\fR, - int \fImask\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy -of the \fIclientData\fR -argument given to \fBTcl_CreateFileHandler\fR when the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information about -the file. \fIMask\fR is an integer mask indicating which -of the requested conditions actually exists for the file; it -will contain a subset of the bits in the \fImask\fR argument -to \fBTcl_CreateFileHandler\fR. -.PP -.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 \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 \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 -correctly, the application may need to use non-blocking I/O operations on -the files for which handlers are declared. Otherwise the application may -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/doc/CrtInterp.3 b/doc/CrtInterp.3 deleted file mode 100644 index 62055d9..0000000 --- a/doc/CrtInterp.3 +++ /dev/null @@ -1,131 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: CrtInterp.3,v 1.2 1998/09/14 18:39:47 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted \- create and delete Tcl command interpreters -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Interp * -\fBTcl_CreateInterp\fR() -.sp -\fBTcl_DeleteInterp\fR(\fIinterp\fR) -.sp -int -\fBTcl_InterpDeleted\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Token for interpreter to be destroyed. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CreateInterp\fR creates a new interpreter structure and returns -a token for it. The token is required in calls to most other Tcl -procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and -\fBTcl_DeleteInterp\fR. -Clients are only allowed to access a few of the fields of -Tcl_Interp structures; see the Tcl_Interp -and \fBTcl_CreateCommand\fR man pages for details. -The new interpreter is initialized with no defined variables and only -the built-in Tcl commands. To bind in additional commands, call -\fBTcl_CreateCommand\fR. -.PP -\fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter -will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have -been matched by calls to \fBTcl_Release\fR. At that time, all of the -resources associated with it, including variables, procedures, and -application-specific command bindings, will be deleted. After -\fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the -interpreter will fail and return \fBTCL_ERROR\fR. After the call to -\fBTcl_DeleteInterp\fR it is safe to examine \fIinterp->result\fR, query or -set the values of variables, define, undefine or retrieve procedures, and -examine the runtime evaluation stack. See below, in the section -\fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details. -.PP -\fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was -called with \fIinterp\fR as its argument; this indicates that the -interpreter will eventually be deleted, when the last call to -\fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If -nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter -will return \fBTCL_ERROR\fR. -.PP -\fBTcl_InterpDeleted\fR is useful in deletion callbacks to distinguish -between when only the memory the callback is responsible for is being -deleted and when the whole interpreter is being deleted. In the former case -the callback may recreate the data being deleted, but this would lead to an -infinite loop if the interpreter were being deleted. - -.SH "INTERPRETERS AND MEMORY MANAGEMENT" -.PP -\fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may -be used by nested evaluations and C code in various extensions. Tcl -implements a simple mechanism that allows callers to use interpreters -without worrying about the interpreter being deleted in a nested call, and -without requiring special code to protect the interpreter, in most cases. -This mechanism ensures that nested uses of an interpreter can safely -continue using it even after \fBTcl_DeleteInterp\fR is called. -.PP -The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls -to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when -the last call to \fBTcl_Preserve\fR is matched by a call to -\fBTcl_Release\fR, will the interpreter be freed. See the manual entry for -\fBTcl_Preserve\fR for a description of these functions. -.PP -The rules for when the user of an interpreter must call \fBTcl_Preserve\fR -and \fBTcl_Release\fR are simple: -.TP -Interpreters Passed As Arguments -Functions that are passed an interpreter as an argument can safely use the -interpreter without any special protection. Thus, when you write an -extension consisting of new Tcl commands, no special code is needed to -protect interpreters received as arguments. This covers the majority of all -uses. -.TP -Interpreter Creation And Deletion -When a new interpreter is created and used in a call to \fBTcl_Eval\fR, -\fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or -\fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and -\fBTcl_Release\fR should be wrapped around all uses of the interpreter. -Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR -has been called. To ensure that the interpreter is properly deleted when -it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other -code already called \fBTcl_DeleteInterp\fR; if not, call -\fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code. -Do not call \fBTcl_DeleteInterp\fR on an interpreter for which -\fBTcl_InterpDeleted\fR returns nonzero. -.TP -Retrieving An Interpreter From A Data Structure -When an interpreter is retrieved from a data structure (e.g. the client -data of a callback) for use in \fBTcl_Eval\fR, \fBTcl_VarEval\fR, -\fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or \fBTcl_GetVar\fR, a pair of -calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around -all uses of the interpreter; it is unsafe to reuse the interpreter once -\fBTcl_Release\fR has been called. If an interpreter is stored inside a -callback data structure, an appropriate deletion cleanup mechanism should -be set up by the code that creates the data structure so that the -interpreter is removed from the data structure (e.g. by setting the field -to NULL) when the interpreter is deleted. Otherwise, you may be using an -interpreter that has been freed and whose memory may already have been -reused. -.PP -All uses of interpreters in Tcl and Tk have already been protected. -Extension writers should ensure that their code also properly protects any -additional interpreters used, as described above. - -.SH KEYWORDS -command, create, delete, interpreter - -.SH "SEE ALSO" -Tcl_Preserve(3), Tcl_Release(3) diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3 deleted file mode 100644 index 21a7761..0000000 --- a/doc/CrtMathFnc.3 +++ /dev/null @@ -1,93 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.2 1998/09/14 18:39:47 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CreateMathFunc 3 7.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateMathFunc \- Define a new math function for expressions -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR) -.SH ARGUMENTS -.AS Tcl_ValueType clientData -.AP Tcl_Interp *interp in -Interpreter in which new function will be defined. -.AP char *name in -Name for new function. -.AP int numArgs in -Number of arguments to new function; also gives size of \fIargTypes\fR array. -.AP Tcl_ValueType *argTypes in -Points to an array giving the permissible types for each argument to -function. -.AP Tcl_MathProc *proc in -Procedure that implements the function. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR when it is invoked. -.BE - -.SH DESCRIPTION -.PP -Tcl allows a number of mathematical functions to be used in -expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR. -\fBTcl_CreateMathFunc\fR allows applications to add additional functions -to those already provided by Tcl or to replace existing functions. -\fIName\fR is the name of the function as it will appear in expressions. -If \fIname\fR doesn't already exist as a function then a new function -is created. If it does exist, then the existing function is replaced. -\fINumArgs\fR and \fIargTypes\fR describe the arguments to the function. -Each entry in the \fIargTypes\fR array must be either TCL_INT, TCL_DOUBLE, -or TCL_EITHER to indicate whether the corresponding argument must be an -integer, a double-precision floating value, or either, respectively. -.PP -Whenever the function is invoked in an expression Tcl will invoke -\fIproc\fR. \fIProc\fR should have arguments and result that match -the type \fBTcl_MathProc\fR: -.CS -typedef int Tcl_MathProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - Tcl_Value *\fIargs\fR, - Tcl_Value *\fIresultPtr\fR); -.CE -.PP -When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR -arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR. -\fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures, -which describe the actual arguments to the function: -.CS -typedef struct Tcl_Value { - Tcl_ValueType \fItype\fR; - long \fIintValue\fR; - double \fIdoubleValue\fR; -} Tcl_Value; -.CE -.PP -The \fItype\fR field indicates the type of the argument and is -either TCL_INT or TCL_DOUBLE. -It will match the \fIargTypes\fR value specified for the function unless -the \fIargTypes\fR value was TCL_EITHER. Tcl converts -the argument supplied in the expression to the type requested in -\fIargTypes\fR, if that is necessary. -Depending on the value of the \fItype\fR field, the \fIintValue\fR -or \fIdoubleValue\fR field will contain the actual value of the argument. -.PP -\fIProc\fR should compute its result and store it either as an integer -in \fIresultPtr->intValue\fR or as a floating value in -\fIresultPtr->doubleValue\fR. -It should set also \fIresultPtr->type\fR to either TCL_INT or TCL_DOUBLE -to indicate which value was set. -Under normal circumstances \fIproc\fR should return TCL_OK. -If an error occurs while executing the function, \fIproc\fR should -return TCL_ERROR and leave an error message in \fIinterp->result\fR. - -.SH KEYWORDS -expression, mathematical function diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 deleted file mode 100644 index 756b970..0000000 --- a/doc/CrtObjCmd.3 +++ /dev/null @@ -1,261 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.3 1999/04/16 00:46:30 stanton Exp $ -'\" -.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 deletes any existing command -\fIname\fR already associated with the interpreter -(however see below for an exception where the existing command -is not deleted). -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_GetIntFromObj\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 -Ordinarily, \fBTcl_CreateObjCommand\fR deletes any existing command -\fIname\fR already associated with the interpreter. -However, if the existing command was created by a previous call to -\fBTcl_CreateCommand\fR, -\fBTcl_CreateObjCommand\fR does not delete the command -but instead arranges for the Tcl interpreter to call the -\fBTcl_ObjCmdProc\fR \fIproc\fR in the future. -The old string-based \fBTcl_CmdProc\fR associated with the command -is retained and its address can be obtained by subsequent -\fBTcl_GetCommandInfo\fR calls. This is done for backwards compatibility. -.PP -\fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted. -This can occur through a call to \fBTcl_DeleteCommand\fR, -\fBTcl_DeleteCommandFromToken\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, -\fBTcl_DeleteCommandFromToken\fR deletes the command -from a command interpreter. -It will delete a command even if that command has been renamed. -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/doc/CrtSlave.3 b/doc/CrtSlave.3 deleted file mode 100644 index 940ae57..0000000 --- a/doc/CrtSlave.3 +++ /dev/null @@ -1,230 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: CrtSlave.3,v 1.2 1998/09/14 18:39:47 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands. -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_IsSafe\fR(\fIinterp\fR) -.sp -int -\fBTcl_MakeSafe\fR(\fIinterp\fR) -.sp -Tcl_Interp * -\fBTcl_CreateSlave\fR(\fIinterp, slaveName, isSafe\fR) -.sp -Tcl_Interp * -\fBTcl_GetSlave\fR(\fIinterp, slaveName\fR) -.sp -Tcl_Interp * -\fBTcl_GetMaster\fR(\fIinterp\fR) -.sp -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 **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 -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). -.AP char *srcCmd in -Name of source command for alias. -.AP Tcl_Interp *targetInterp in -Interpreter that contains the target command for an alias. -.AP char *targetCmd in -Name of target command for alias in \fItargetInterp\fR. -.AP int argc in -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. -.AP char **targetCmdPtr out -Pointer to location to store the address of the name of the target command -for an alias. -.AP int *argcPtr out -Pointer to location to store count of additional arguments to be passed to -the alias. The location is in storage owned by the caller. -.AP char ***argvPtr out -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 under which a hidden command is stored and with which it can be -exposed or invoked. -.VE -.BE - -.SH DESCRIPTION -.PP -These procedures are intended for access to the multiple interpreter -facility from inside C programs. They enable managing multiple interpreters -in a hierarchical relationship, and the management of aliases, commands -that when invoked in one interpreter execute a command in another -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 \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 \fIinterp\fR is ``safe'' (was created -with the \fBTCL_SAFE_INTERPRETER\fR flag specified), -\fB0\fR otherwise. -.PP -\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. -.PP -\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of -\fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR. -If no such slave interpreter exists, \fBNULL\fR is returned. -.PP -\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 -to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR; -\fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation -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 -.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, putting -it under the name -\fIcmdName\fR. -\fIHiddenCmdName\fR must be the name of an existing hidden -command, or the operation will return \fBTCL_ERROR\fR and leave 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, under the name -\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. -Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain -namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and -leave an error message in the object result of \fIinterp\fR. -The \fICmdName\fR will be looked up in the global namespace, and not -relative to the current namespace, even if the current namespace is not the -global one. -If a hidden command whose name is \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 -.SH "SEE ALSO" -For a description of the Tcl interface to multiple interpreters, see -\fIinterp(n)\fR. - -.SH KEYWORDS -alias, command, exposed commands, hidden commands, interpreter, invoke, -master, slave, - diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3 deleted file mode 100644 index ecfa4c3..0000000 --- a/doc/CrtTimerHdlr.3 +++ /dev/null @@ -1,76 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.2 1998/09/14 18:39:47 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a -given time -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_TimerToken -\fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR) -.sp -\fBTcl_DeleteTimerHandler\fR(\fItoken\fR) -.SH ARGUMENTS -.AS Tcl_TimerToken milliseconds -.AP int milliseconds in -How many milliseconds to wait before invoking \fIproc\fR. -.AP Tcl_TimerProc *proc in -Procedure to invoke after \fImilliseconds\fR have elapsed. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.AP Tcl_TimerToken token in -Token for previously-created timer handler (the return value -from some previous call to \fBTcl_CreateTimerHandler\fR). -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be -invoked at a time \fImilliseconds\fR milliseconds in the -future. -The callback to \fIproc\fR will be made by \fBTcl_DoOneEvent\fR, -so \fBTcl_CreateTimerHandler\fR is only useful in programs that -dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands -such as \fBvwait\fR. -The call to \fIproc\fR may not be made at the exact time given by -\fImilliseconds\fR: it will be made at the next opportunity -after that time. For example, if \fBTcl_DoOneEvent\fR isn't -called until long after the time has elapsed, or if there -are other pending events to process before the call to -\fIproc\fR, then the call to \fIproc\fR will be delayed. -.PP -\fIProc\fR should have arguments and return value that match -the type \fBTcl_TimerProc\fR: -.CS -typedef void Tcl_TimerProc(ClientData \fIclientData\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a -copy of the \fIclientData\fR argument given to -\fBTcl_CreateTimerHandler\fR when the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information about -what to do in \fIproc\fR. -.PP -\fBTcl_DeleteTimerHandler\fR may be called to delete a -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. -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/doc/CrtTrace.3 b/doc/CrtTrace.3 deleted file mode 100644 index dff97d1..0000000 --- a/doc/CrtTrace.3 +++ /dev/null @@ -1,106 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: CrtTrace.3,v 1.2 1998/09/14 18:39:47 stanton Exp $ -'\" -.so man.macros -.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateTrace, Tcl_DeleteTrace \- arrange for command execution to be traced -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Trace -\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR) -.sp -\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) -.SH ARGUMENTS -.AS Tcl_CmdTraceProc (clientData)() -.AP Tcl_Interp *interp in -Interpreter containing command to be traced or untraced. -.AP int level in -Only commands at or below this nesting level will be traced. 1 means -top-level commands only, 2 means top-level commands or those that are -invoked as immediate consequences of executing top-level commands -(procedure bodies, bracketed commands, etc.) and so on. -.AP Tcl_CmdTraceProc *proc in -Procedure to call for each command that's executed. See below for -details on the calling sequence. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.AP Tcl_Trace trace in -Token for trace to be removed (return value from previous call -to \fBTcl_CreateTrace\fR). -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CreateTrace\fR arranges for command tracing. From now on, \fIproc\fR -will be invoked before Tcl calls command procedures to process -commands in \fIinterp\fR. The return value from -\fBTcl_CreateTrace\fR is a token for the trace, -which may be passed to \fBTcl_DeleteTrace\fR to remove the trace. There may -be many traces in effect simultaneously for the same command interpreter. -.PP -\fIProc\fR should have arguments and result that match the -type \fBTcl_CmdTraceProc\fR: -.CS -typedef void Tcl_CmdTraceProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIlevel\fR, - char *\fIcommand\fR, - Tcl_CmdProc *\fIcmdProc\fR, - ClientData \fIcmdClientData\fR, - int \fIargc\fR, - char *\fIargv\fR[]); -.CE -The \fIclientData\fR and \fIinterp\fR parameters are -copies of the corresponding arguments given to \fBTcl_CreateTrace\fR. -\fIClientData\fR typically points to an application-specific -data structure that describes what to do when \fIproc\fR -is invoked. \fILevel\fR gives the nesting level of the command -(1 for top-level commands passed to \fBTcl_Eval\fR by the application, -2 for the next-level commands passed to \fBTcl_Eval\fR as part of parsing -or interpreting level-1 commands, and so on). \fICommand\fR -points to a string containing the text of the -command, before any argument substitution. -\fICmdProc\fR contains the address of the command procedure that -will be called to process the command (i.e. the \fIproc\fR argument -of some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR -contains the associated client data for \fIcmdProc\fR (the \fIclientData\fR -value passed to \fBTcl_CreateCommand\fR). \fIArgc\fR and \fIargv\fR give -the final argument information that will be passed to \fIcmdProc\fR, after -command, variable, and backslash substitution. -\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings. -.PP -Tracing will only occur for commands at nesting level less than -or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR -parameter to \fIproc\fR will always be less than or equal to the -\fIlevel\fR parameter to \fBTcl_CreateTrace\fR). -.PP -Calls to \fIproc\fR will be made by the Tcl parser immediately before -it calls the command procedure for the command (\fIcmdProc\fR). This -occurs after argument parsing and substitution, so tracing for -substituted commands occurs before tracing of the commands -containing the substitutions. If there is a syntax error in a -command, or if there is no command procedure associated with a -command name, then no tracing will occur for that command. If a -string passed to Tcl_Eval contains multiple commands (bracketed, or -on different lines) then multiple calls to \fIproc\fR will occur, -one for each command. The \fIcommand\fR string for each of these -trace calls will reflect only a single command, not the entire string -passed to Tcl_Eval. -.PP -\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be -made to the procedure associated with the trace. After \fBTcl_DeleteTrace\fR -returns, the caller should never again use the \fItrace\fR token. - -.SH KEYWORDS -command, create, delete, interpreter, trace diff --git a/doc/DString.3 b/doc/DString.3 deleted file mode 100644 index e8cc5e1..0000000 --- a/doc/DString.3 +++ /dev/null @@ -1,145 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: DString.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.so man.macros -.TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_DStringInit\fR(\fIdsPtr\fR) -.sp -char * -\fBTcl_DStringAppend\fR(\fIdsPtr, string, length\fR) -.sp -char * -\fBTcl_DStringAppendElement\fR(\fIdsPtr, string\fR) -.sp -\fBTcl_DStringStartSublist\fR(\fIdsPtr\fR) -.sp -\fBTcl_DStringEndSublist\fR(\fIdsPtr\fR) -.sp -int -\fBTcl_DStringLength\fR(\fIdsPtr\fR) -.sp -char * -\fBTcl_DStringValue\fR(\fIdsPtr\fR) -.sp -\fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR) -.sp -\fBTcl_DStringFree\fR(\fIdsPtr\fR) -.sp -\fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR) -.sp -\fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR) -.SH ARGUMENTS -.AS Tcl_DString newLength -.AP Tcl_DString *dsPtr in/out -Pointer to structure that is used to manage a dynamic string. -.AP char *string in -Pointer to characters to add to dynamic string. -.AP int length in -Number of characters from string to add to dynamic string. If -1, -add all characters up to null terminating character. -.AP int newLength in -New length for dynamic string, not including null terminating -character. -.AP Tcl_Interp *interp in/out -Interpreter whose result is to be set from or moved to the -dynamic string. -.BE - -.SH DESCRIPTION -.PP -Dynamic strings provide a mechanism for building up arbitrarily long -strings by gradually appending information. If the dynamic string is -short then there will be no memory allocation overhead; as the string -gets larger, additional space will be allocated as needed. -.PP -\fBTcl_DStringInit\fR initializes a dynamic string to zero length. -The Tcl_DString structure must have been allocated by the caller. -No assumptions are made about the current state of the structure; -anything already in it is discarded. -If the structure has been used previously, \fBTcl_DStringFree\fR should -be called first to free up any memory allocated for the old -string. -.PP -\fBTcl_DStringAppend\fR adds new information to a dynamic string, -allocating more memory for the string if needed. -If \fIlength\fR is less than zero then everything in \fIstring\fR -is appended to the dynamic string; otherwise \fIlength\fR -specifies the number of bytes to append. -\fBTcl_DStringAppend\fR returns a pointer to the characters of -the new string. The string can also be retrieved from the -\fIstring\fR field of the Tcl_DString structure. -.PP -\fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR -except that it doesn't take a \fIlength\fR argument (it appends -all of \fIstring\fR) and it converts the string to a proper list element -before appending. -\fBTcl_DStringAppendElement\fR adds a separator space before the -new list element unless the new list element is the first in a -list or sub-list (i.e. either the current string is empty, or it -contains the single character ``{'', or the last two characters of -the current string are `` {''). -\fBTcl_DStringAppendElement\fR returns a pointer to the -characters of the new string. -.PP -\fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be -used to create nested lists. -To append a list element that is itself a sublist, first -call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR -for each of the elements in the sublist, then call -\fBTcl_DStringEndSublist\fR to end the sublist. -\fBTcl_DStringStartSublist\fR appends a space character if needed, -followed by an open brace; \fBTcl_DStringEndSublist\fR appends -a close brace. -Lists can be nested to any depth. -.PP -\fBTcl_DStringLength\fR is a macro that returns the current length -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 -.PP -\fBTcl_DStringSetLength\fR changes the length of a dynamic string. -If \fInewLength\fR is less than the string's current length, then -the string is truncated. -If \fInewLength\fR is greater than the string's current length, -then the string will become longer and new space will be allocated -for the string if needed. -However, \fBTcl_DStringSetLength\fR will not initialize the new -space except to provide a terminating null character; it is up to the -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. -.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 -and reinitializes the string's value to an empty string. -.PP -\fBTcl_DStringResult\fR sets the result of \fIinterp\fR to the value of -the dynamic string given by \fIdsPtr\fR. It does this by moving -a pointer from \fIdsPtr\fR to \fIinterp->result\fR. -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 -\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. - -.SH KEYWORDS -append, dynamic string, free, result diff --git a/doc/DetachPids.3 b/doc/DetachPids.3 deleted file mode 100644 index 23b16c5..0000000 --- a/doc/DetachPids.3 +++ /dev/null @@ -1,62 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: DetachPids.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.so man.macros -.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_DetachPids, Tcl_ReapDetachedProcs \- manage child processes in background -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR) -.sp -\fBTcl_ReapDetachedProcs\fR() -.SH ARGUMENTS -.AS int *statusPtr -.AP int numPids in -Number of process ids contained in the array pointed to by \fIpidPtr\fR. -.AP int *pidPtr in -Address of array containing \fInumPids\fR process ids. -.BE - -.SH DESCRIPTION -.PP -\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 -eventually invoke the \fBwaitpid\fR kernel call (or one of a few other -similar kernel calls) to wait for the child to exit. Until the -parent waits for the child, the child's state cannot be completely -reclaimed by the system. If a parent continually creates children -and doesn't wait on them, the system's process table will eventually -overflow, even if all the children have exited. -.PP -\fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility -for one or more processes whose process ids are contained in the -\fIpidPtr\fR array passed as argument. The caller presumably -has started these processes running in background and doesn't -want to have to deal with them again. -.PP -\fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call -on each of the background processes so that its state can be cleaned -up if it has exited. If the process hasn't exited yet, -\fBTcl_ReapDetachedProcs\fR doesn't wait for it to exit; it will check again -the next time it is invoked. -Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the -\fBexec\fR command is executed, so in most cases it isn't necessary -for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR. -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. - -.SH KEYWORDS -background, child, detach, process, wait diff --git a/doc/DoOneEvent.3 b/doc/DoOneEvent.3 deleted file mode 100644 index 8ae7a88..0000000 --- a/doc/DoOneEvent.3 +++ /dev/null @@ -1,108 +0,0 @@ -'\" -'\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: DoOneEvent.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.so man.macros -.TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_DoOneEvent \- wait for events and invoke event handlers -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_DoOneEvent\fR(\fIflags\fR) -.SH ARGUMENTS -.AS int flags -.AP int flags in -This parameter is normally zero. It may be an OR-ed combination -of any of the following flag bits: -TCL_WINDOW_EVENTS, -TCL_FILE_EVENTS, TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or -TCL_DONT_WAIT. -.BE - -.SH DESCRIPTION -.PP -This procedure is the entry point to Tcl's event loop; it is responsible for -waiting for events and dispatching event handlers created with -procedures such as \fBTk_CreateEventHandler\fR, \fBTcl_CreateFileHandler\fR, -\fBTcl_CreateTimerHandler\fR, and \fBTcl_DoWhenIdle\fR. -\fBTcl_DoOneEvent\fR checks to see if -events are already present on the Tcl event queue; if so, -it calls the handler(s) for the first (oldest) event, removes it from -the queue, and returns. -If there are no events ready to be handled, then \fBTcl_DoOneEvent\fR -checks for new events from all possible sources. -If any are found, it puts all of them on Tcl's event queue, calls -handlers for the first event on the queue, and returns. -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 -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). -.PP -If the \fIflags\fR argument to \fBTcl_DoOneEvent\fR is non-zero, -it restricts the kinds of events that will be processed by -\fBTcl_DoOneEvent\fR. -\fIFlags\fR may be an OR-ed combination of any of the following bits: -.TP 27 -\fBTCL_WINDOW_EVENTS\fR \- -Process window system events. -.TP 27 -\fBTCL_FILE_EVENTS\fR \- -Process file events. -.TP 27 -\fBTCL_TIMER_EVENTS\fR \- -Process timer events. -.TP 27 -\fBTCL_IDLE_EVENTS\fR \- -Process idle callbacks. -.TP 27 -\fBTCL_ALL_EVENTS\fR \- -Process all kinds of events: equivalent to OR-ing together all of the -above flags or specifying none of them. -.TP 27 -\fBTCL_DONT_WAIT\fR \- -Don't sleep: process only events that are ready at the time of the -call. -.LP -If any of the flags \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR, -\fBTCL_TIMER_EVENTS\fR, or \fBTCL_IDLE_EVENTS\fR is set, then the only -events that will be considered are those for which flags are set. -Setting none of these flags is equivalent to the value -\fBTCL_ALL_EVENTS\fR, which causes all event types to be processed. -If an application has defined additional event sources with -\fBTcl_CreateEventSource\fR, then additional \fIflag\fR values -may also be valid, depending on those event sources. -.PP -The \fBTCL_DONT_WAIT\fR flag causes \fBTcl_DoOneEvent\fR not to put -the process to sleep: it will check for events but if none are found -then it returns immediately with a return value of 0 to indicate -that no work was done. -\fBTcl_DoOneEvent\fR will also return 0 without doing anything if -the only alternative is to block forever (this can happen, for example, -if \fIflags\fR is \fBTCL_IDLE_EVENTS\fR and there are no -\fBTcl_DoWhenIdle\fR callbacks pending, or if no event handlers or -timer handlers exist). -.PP -\fBTcl_DoOneEvent\fR may be invoked recursively. For example, -it is possible to invoke \fBTcl_DoOneEvent\fR recursively -from a handler called by \fBTcl_DoOneEvent\fR. This sort -of operation is useful in some modal situations, such -as when a -notification dialog has been popped up and an application wishes to -wait for the user to click a button in the dialog before -doing anything else. - -.SH KEYWORDS -callback, event, handler, idle, timer diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3 deleted file mode 100644 index 90a6aa7..0000000 --- a/doc/DoWhenIdle.3 +++ /dev/null @@ -1,86 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.so man.macros -.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR) -.sp -\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR) -.SH ARGUMENTS -.AS Tcl_IdleProc clientData -.AP Tcl_IdleProc *proc in -Procedure to invoke. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked -when the application becomes idle. The application is -considered to be idle when \fBTcl_DoOneEvent\fR has been -called, couldn't find any events to handle, and is about -to go to sleep waiting for an event to occur. At this -point all pending \fBTcl_DoWhenIdle\fR handlers are -invoked. For each call to \fBTcl_DoWhenIdle\fR there will -be a single call to \fIproc\fR; after \fIproc\fR is -invoked the handler is automatically removed. -\fBTcl_DoWhenIdle\fR is only usable in programs that -use \fBTcl_DoOneEvent\fR to dispatch events. -.PP -\fIProc\fR should have arguments and result that match the -type \fBTcl_IdleProc\fR: -.CS -typedef void Tcl_IdleProc(ClientData \fIclientData\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR -argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR -points to a data structure containing application-specific information about -what \fIproc\fR should do. -.PP -\fBTcl_CancelIdleCall\fR -may be used to cancel one or more previous -calls to \fBTcl_DoWhenIdle\fR: if there is a \fBTcl_DoWhenIdle\fR -handler registered for \fIproc\fR and \fIclientData\fR, then it -is removed without invoking it. If there is more than one -handler on the idle list that refers to \fIproc\fR and \fIclientData\fR, -all of the handlers are removed. If no existing handlers match -\fIproc\fR and \fIclientData\fR then nothing happens. -.PP -\fBTcl_DoWhenIdle\fR is most useful in situations where -(a) a piece of work will have to be done but (b) it's -possible that something will happen in the near future -that will change what has to be done or require something -different to be done. \fBTcl_DoWhenIdle\fR allows the -actual work to be deferred until all pending events have -been processed. At this point the exact work to be done -will presumably be known and it can be done exactly once. -.PP -For example, \fBTcl_DoWhenIdle\fR might be used by an editor -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 -continuously. This will interact badly with certain features of Tk -that attempt to wait for all idle callbacks to complete. If you would -like for an idle callback to reschedule itself continuously, it is -better to use a timer handler with a zero timeout period. - -.SH KEYWORDS -callback, defer, idle callback diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3 deleted file mode 100644 index 164d4c9..0000000 --- a/doc/DoubleObj.3 +++ /dev/null @@ -1,79 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: DoubleObj.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.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/doc/Encoding.3 b/doc/Encoding.3 deleted file mode 100644 index e9329dd..0000000 --- a/doc/Encoding.3 +++ /dev/null @@ -1,484 +0,0 @@ -'\" -'\" Copyright (c) 1997-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Encoding.3,v 1.2 1999/04/16 00:46:31 stanton Exp $ -'\" -.so man.macros -.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings. - - - - -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Encoding -\fBTcl_GetEncoding\fR(\fIinterp, name\fR) -.sp -void -\fBTcl_FreeEncoding\fR(\fIencoding\fR) -.sp -void -\fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR) -.sp -int -\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, - dstCharsPtr\fR) -.sp -void -\fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR) -.sp -int -\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, - dstCharsPtr\fR) -.sp -char * -\fBTcl_GetEncodingName\fR(\fIencoding\fR) -.sp -int -\fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR) -.sp -void -\fBTcl_GetEncodingNames\fR(\fIinterp\fR) -.sp -Tcl_Encoding -\fBTcl_CreateEncoding\fR(\fItypePtr\fR) - -.sp -char * -\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR) -.sp -void -\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR) - - -.SH ARGUMENTS -.AS Tcl_EncodingState *dstWrotePtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting, or NULL if no error reporting is -desired. -.AP "CONST char" *name in -Name of encoding to load. -.AP Tcl_Encoding encoding in -The encoding to query, free, or use for converting text. If \fIencoding\fR is -NULL, the current system encoding is used. -.AP "CONST char" *src in -For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the -specified encoding that are to be converted to UTF-8. For the -\fBTcl_UtfToExternal\fR functions, an array of UTF-8 characters to be -converted to the specified encoding. -.AP int srcLen in -Length of \fIsrc\fR in bytes. If the length is negative, the -encoding-specific length of the string is used. -.AP Tcl_DString *dstPtr out -Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted -result will be stored. -.AP int flags in -Various flag bits OR-ed together. -TCL_ENCODING_START signifies that the -source buffer is the first block in a (potentially multi-block) input -stream, telling the conversion routine to reset to an initial state and -perform any initialization that needs to occur before the first byte is -converted. TCL_ENCODING_END signifies that the source buffer is the last -block in a (potentially multi-block) input stream, telling the conversion -routine to perform any finalization that needs to occur after the last -byte is converted and then to reset to an initial state. -TCL_ENCODING_STOPONERROR signifies that the conversion routine should -return immediately upon reading a source character that doesn't exist in -the target encoding; otherwise a default fallback character will -automatically be substituted. -.AP Tcl_EncodingState *statePtr in/out -Used when converting a (generally long or indefinite length) byte stream -in a piece by piece fashion. The conversion routine stores its current -state in \fI*statePtr\fR after \fIsrc\fR (the buffer containing the -current piece) has been converted; that state information must be passed -back when converting the next piece of the stream so the conversion -routine knows what state it was in when it left off at the end of the -last piece. May be NULL, in which case the value specified for \fIflags\fR -is ignored and the source buffer is assumed to contain the complete string to -convert. -.AP char *dst out -Buffer in which the converted result will be stored. No more than -\fIdstLen\fR bytes will be stored in \fIdst\fR. -.AP int dstLen in -The maximum length of the output buffer \fIdst\fR in bytes. -.AP int *srcReadPtr out -Filled with the number of bytes from \fIsrc\fR that were actually -converted. This may be less than the original source length if there was -a problem converting some source characters. May be NULL. -.AP int *dstWrotePtr out -Filled with the number of bytes that were actually stored in the output -buffer as a result of the conversion. May be NULL. -.AP int *dstCharsPtr out -Filled with the number of characters that correspond to the number of bytes -stored in the output buffer. May be NULL. -.AP Tcl_EncodingType *typePtr in -Structure that defines a new type of encoding. -.AP char *path in -A path to the location of the encoding file. -.BE -.SH INTRODUCTION -.PP -These routines convert between Tcl's internal character representation, -UTF-8, and character representations used by various operating systems or -file systems, such as Unicode, ASCII, or Shift-JIS. When operating on -strings, such as such as obtaining the names of files or displaying -characters using international fonts, the strings must be translated into -one or possibly multiple formats that the various system calls can use. For -instance, on a Japanese Unix workstation, a user might obtain a filename -represented in the EUC-JP file encoding and then translate the characters to -the jisx0208 font encoding in order to display the filename in a Tk widget. -The purpose of the encoding package is to help bridge the translation gap. -UTF-8 provides an intermediate staging ground for all the various -encodings. In the example above, text would be translated into UTF-8 from -whatever file encoding the operating system is using. Then it would be -translated from UTF-8 into whatever font encoding the display routines -require. -.PP -Some basic encodings are compiled into Tcl. Others can be defined by the -user or dynamically loaded from encoding files in a -platform-independent manner. -.SH DESCRIPTION -.PP -\fBTcl_GetEncoding\fR finds an encoding given its \fIname\fR. The name may -refer to a builtin Tcl encoding, a user-defined encoding registered by -calling \fBTcl_CreateEncoding\fR, or a dynamically-loadable encoding -file. The return value is a token that represents the encoding and can be -used in subsequent calls to procedures such as \fBTcl_GetEncodingName\fR, -\fBTcl_FreeEncoding\fR, and \fBTcl_UtfToExternal\fR. If the name did not -refer to any known or loadable encoding, NULL is returned and an error -message is returned in \fIinterp\fR. -.PP -The encoding package maintains a database of all encodings currently in use. -The first time \fIname\fR is seen, \fBTcl_GetEncoding\fR returns an -encoding with a reference count of 1. If the same \fIname\fR is requested -further times, then the reference count for that encoding is incremented -without the overhead of allocating a new encoding and all its associated -data structures. -.PP -When an \fIencoding\fR is no longer needed, \fBTcl_FreeEncoding\fR -should be called to release it. When an \fIencoding\fR is no longer in use -anywhere (i.e., it has been freed as many times as it has been gotten) -\fBTcl_FreeEncoding\fR will release all storage the encoding was using -and delete it from the database. -.PP -\fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the -specified \fIencoding\fR into UTF-8. The converted bytes are stored in -\fIdstPtr\fR, which is then NULL terminated. The caller should eventually -call \fBTcl_DStringFree\fR to free any information stored in \fIdstPtr\fR. -When converting, if any of the characters in the source buffer cannot be -represented in the target encoding, a default fallback character will be -used. -.PP -\fBTcl_ExternalToUtf\fR converts a source buffer \fIsrc\fR from the specified -\fIencoding\fR into UTF-8. Up to \fIsrcLen\fR bytes are converted from the -source buffer and up to \fIdstLen\fR converted bytes are stored in \fIdst\fR. -In all cases, \fI*srcReadPtr\fR is filled with the number of bytes that were -successfully converted from \fIsrc\fR and \fI*dstWrotePtr\fR is filled with -the corresponding number of bytes that were stored in \fIdst\fR. The return -value is one of the following: -.RS -.IP \fBTCL_OK\fR 29 -All bytes of \fIsrc\fR were converted. -.IP \fBTCL_CONVERT_NOSPACE\fR 29 -The destination buffer was not large enough for all of the converted data; as -many characters as could fit were converted though. -.IP \fBTCL_CONVERT_MULTIBYTE\fR 29 -The last fews bytes in the source buffer were the beginning of a multibyte -sequence, but more bytes were needed to complete this sequence. A -subsequent call to the conversion routine should pass a buffer containing -the unconverted bytes that remained in \fIsrc\fR plus some further bytes -from the source stream to properly convert the formerly split-up multibyte -sequence. -.IP \fBTCL_CONVERT_SYNTAX\fR 29 -The source buffer contained an invalid character sequence. This may occur -if the input stream has been damaged or if the input encoding method was -misidentified. -.IP \fBTCL_CONVERT_UNKNOWN\fR 29 -The source buffer contained a character that could not be represented in -the target encoding and TCL_ENCODING_STOPONERROR was specified. -.RE -.LP -\fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 -into the specified \fIencoding\fR. The converted bytes are stored in -\fIdstPtr\fR, which is then terminated with the appropriate encoding-specific -NULL. The caller should eventually call \fBTcl_DStringFree\fR to free any -information stored in \fIdstPtr\fR. When converting, if any of the -characters in the source buffer cannot be represented in the target -encoding, a default fallback character will be used. -.PP -\fBTcl_UtfToExternal\fR converts a source buffer \fIsrc\fR from UTF-8 into -the specified \fIencoding\fR. Up to \fIsrcLen\fR bytes are converted from -the source buffer and up to \fIdstLen\fR converted bytes are stored in -\fIdst\fR. In all cases, \fI*srcReadPtr\fR is filled with the number of -bytes that were successfully converted from \fIsrc\fR and \fI*dstWrotePtr\fR -is filled with the corresponding number of bytes that were stored in -\fIdst\fR. The return values are the same as the return values for -\fBTcl_ExternalToUtf\fR. -.PP -\fBTcl_GetEncodingName\fR is roughly the inverse of \fBTk_GetEncoding\fR. -Given an \fIencoding\fR, the return value is the \fIname\fR argument that -was used to create the encoding. The string returned by -\fBTcl_GetEncodingName\fR is only guaranteed to persist until the -\fIencoding\fR is deleted. The caller must not modify this string. -.PP -\fBTcl_SetSystemEncoding\fR sets the default encoding that should be used -whenever the user passes a NULL value for the \fIencoding\fR argument to -any of the other encoding functions. If \fIname\fR is NULL, the system -encoding is reset to the default system encoding, \fBbinary\fR. If the -name did not refer to any known or loadable encoding, TCL_ERROR is -returned and an error message is left in \fIinterp\fR. Otherwise, this -procedure increments the reference count of the new system encoding, -decrements the reference count of the old system encoding, and returns -TCL_OK. -.PP -\fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list -consisting of the names of all the encodings that are currently defined -or can be dynamically loaded, searching the encoding path specified by -\fBTcl_SetDefaultEncodingDir\fR. This procedure does not ensure that the -dynamically-loadable encoding files contain valid data, but merely that they -exist. -.PP -\fBTcl_CreateEncoding\fR defines a new encoding and registers the C -procedures that are called back to convert between the encoding and -UTF-8. Encodings created by \fBTcl_CreateEncoding\fR are thereafter -visible in the database used by \fBTcl_GetEncoding\fR. Just as with the -\fBTcl_GetEncoding\fR procedure, the return value is a token that -represents the encoding and can be used in subsequent calls to other -encoding functions. \fBTcl_CreateEncoding\fR returns an encoding with a -reference count of 1. If an encoding with the specified \fIname\fR -already exists, then its entry in the database is replaced with the new -encoding; the token for the old encoding will remain valid and continue -to behave as before, but users of the new token will now call the new -encoding procedures. -.PP -The \fItypePtr\fR argument to \fBTcl_CreateEncoding\fR contains information -about the name of the encoding and the procedures that will be called to -convert between this encoding and UTF-8. It is defined as follows: -.PP -.CS -typedef struct Tcl_EncodingType { - CONST char *\fIencodingName\fR; - Tcl_EncodingConvertProc *\fItoUtfProc\fR; - Tcl_EncodingConvertProc *\fIfromUtfProc\fR; - Tcl_EncodingFreeProc *\fIfreeProc\fR; - ClientData \fIclientData\fR; - int \fInullSize\fR; -} Tcl_EncodingType; -.CE -.PP -The \fIencodingName\fR provides a string name for the encoding, by -which it can be referred in other procedures such as -\fBTcl_GetEncoding\fR. The \fItoUtfProc\fR refers to a callback -procedure to invoke to convert text from this encoding into UTF-8. -The \fIfromUtfProc\fR refers to a callback procedure to invoke to -convert text from UTF-8 into this encoding. The \fIfreeProc\fR refers -to a callback procedure to invoke when this encoding is deleted. The -\fIfreeProc\fR field may be NULL. The \fIclientData\fR contains an -arbitrary one-word value passed to \fItoUtfProc\fR, \fIfromUtfProc\fR, -and \fIfreeProc\fR whenever they are called. Typically, this is a -pointer to a data structure containing encoding-specific information -that can be used by the callback procedures. For instance, two very -similar encodings such as \fBascii\fR and \fBmacRoman\fR may use the -same callback procedure, but use different values of \fIclientData\fR -to control its behavior. The \fInullSize\fR specifies the number of -zero bytes that signify end-of-string in this encoding. It must be -\fB1\fR (for single-byte or multi-byte encodings like ASCII or -Shift-JIS) or \fB2\fR (for double-byte encodings like Unicode). -Constant-sized encodings with 3 or more bytes per character (such as -CNS11643) are not accepted. -.PP -The callback procedures \fItoUtfProc\fR and \fIfromUtfProc\fR should match the -type \fBTcl_EncodingConvertProc\fR: -.PP -.CS -typedef int Tcl_EncodingConvertProc( - ClientData \fIclientData\fR, - CONST char *\fIsrc\fR, - int \fIsrcLen\fR, - int \fIflags\fR, - Tcl_Encoding *\fIstatePtr\fR, - char *\fIdst\fR, - int \fIdstLen\fR, - int *\fIsrcReadPtr\fR, - int *\fIdstWrotePtr\fR, - int *\fIdstCharsPtr\fR); -.CE -.PP -The \fItoUtfProc\fR and \fIfromUtfProc\fR procedures are called by the -\fBTcl_ExternalToUtf\fR or \fBTcl_UtfToExternal\fR family of functions to -perform the actual conversion. The \fIclientData\fR parameter to these -procedures is the same as the \fIclientData\fR field specified to -\fBTcl_CreateEncoding\fR when the encoding was created. The remaining -arguments to the callback procedures are the same as the arguments, -documented at the top, to \fBTcl_ExternalToUtf\fR or -\fBTcl_UtfToExternal\fR, with the following exceptions. If the -\fIsrcLen\fR argument to one of those high-level functions is negative, -the value passed to the callback procedure will be the appropriate -encoding-specific string length of \fIsrc\fR. If any of the \fIsrcReadPtr\fR, -\fIdstWrotePtr\fR, or \fIdstCharsPtr\fR arguments to one of the high-level -functions is NULL, the corresponding value passed to the callback -procedure will be a non-NULL location. -.PP -The callback procedure \fIfreeProc\fR, if non-NULL, should match the type -\fBTcl_EncodingFreeProc\fR: -.CS -typedef void Tcl_EncodingFreeProc( - ClientData \fIclientData\fR); -.CE -.PP -This \fIfreeProc\fR function is called when the encoding is deleted. The -\fIclientData\fR parameter is the same as the \fIclientData\fR field -specified to \fBTcl_CreateEncoding\fR when the encoding was created. -.PP - -\fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR -access and set the directory to use when locating the default encoding -files. If this value is not NULL, the \fBTclpInitLibraryPath\fR routine -appends the path to the head of the search path, and uses this path as -the first place to look into when trying to locate the encoding file. - -.SH ENCODING FILES -Space would prohibit precompiling into Tcl every possible encoding -algorithm, so many encodings are stored on disk as dynamically-loadable -encoding files. This behavior also allows the user to create additional -encoding files that can be loaded using the same mechanism. These -encoding files contain information about the tables and/or escape -sequences used to map between an external encoding and Unicode. The -external encoding may consist of single-byte, multi-byte, or double-byte -characters. -.PP -Each dynamically-loadable encoding is represented as a text file. The -initial line of the file, beginning with a ``#'' symbol, is a comment -that provides a human-readable description of the file. The next line -identifies the type of encoding file. It can be one of the following -letters: -.IP "[1] \fBS\fR" -A single-byte encoding, where one character is always one byte long in the -encoding. An example is \fBiso8859-1\fR, used by many European languages. -.IP "[2] \fBD\fR" -A double-byte encoding, where one character is always two bytes long in the -encoding. An example is \fBbig5\fR, used for Chinese text. -.IP "[3] \fBM\fR" -A multi-byte encoding, where one character may be either one or two bytes long. -Certain bytes are a lead bytes, indicating that another byte must follow -and that together the two bytes represent one character. Other bytes are not -lead bytes and represent themselves. An example is \fBshiftjis\fR, used by -many Japanese computers. -.IP "[4] \fBE\fR" -An escape-sequence encoding, specifying that certain sequences of bytes -do not represent characters, but commands that describe how following bytes -should be interpreted. -.PP -The rest of the lines in the file depend on the type. -.PP -Cases [1], [2], and [3] are collectively referred to as table-based encoding -files. The lines in a table-based encoding file are in the same -format as this example taken from the \fBshiftjis\fR encoding (this is not -the complete file): -.CS -# Encoding file: shiftjis, multi-byte -M -003F 0 40 -00 -0000000100020003000400050006000700080009000A000B000C000D000E000F -0010001100120013001400150016001700180019001A001B001C001D001E001F -0020002100220023002400250026002700280029002A002B002C002D002E002F -0030003100320033003400350036003700380039003A003B003C003D003E003F -0040004100420043004400450046004700480049004A004B004C004D004E004F -0050005100520053005400550056005700580059005A005B005C005D005E005F -0060006100620063006400650066006700680069006A006B006C006D006E006F -0070007100720073007400750076007700780079007A007B007C007D203E007F -0080000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000 -0000FF61FF62FF63FF64FF65FF66FF67FF68FF69FF6AFF6BFF6CFF6DFF6EFF6F -FF70FF71FF72FF73FF74FF75FF76FF77FF78FF79FF7AFF7BFF7CFF7DFF7EFF7F -FF80FF81FF82FF83FF84FF85FF86FF87FF88FF89FF8AFF8BFF8CFF8DFF8EFF8F -FF90FF91FF92FF93FF94FF95FF96FF97FF98FF99FF9AFF9BFF9CFF9DFF9EFF9F -0000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000 -81 -0000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000 -0000000000000000000000000000000000000000000000000000000000000000 -300030013002FF0CFF0E30FBFF1AFF1BFF1FFF01309B309C00B4FF4000A8FF3E -FFE3FF3F30FD30FE309D309E30034EDD30053006300730FC20152010FF0F005C -301C2016FF5C2026202520182019201C201DFF08FF0930143015FF3BFF3DFF5B -FF5D30083009300A300B300C300D300E300F30103011FF0B221200B100D70000 -00F7FF1D2260FF1CFF1E22662267221E22342642264000B0203220332103FFE5 -FF0400A200A3FF05FF03FF06FF0AFF2000A72606260525CB25CF25CE25C725C6 -25A125A025B325B225BD25BC203B301221922190219121933013000000000000 -000000000000000000000000000000002208220B2286228722822283222A2229 -000000000000000000000000000000002227222800AC21D221D4220022030000 -0000000000000000000000000000000000000000222022A52312220222072261 -2252226A226B221A223D221D2235222B222C0000000000000000000000000000 -212B2030266F266D266A2020202100B6000000000000000025EF000000000000 -.CE -.PP -The third line of the file is three numbers. The first number is the -fallback character (in base 16) to use when converting from UTF-8 to this -encoding. The second number is a \fB1\fR if this file represents the -encoding for a symbol font, or \fB0\fR otherwise. The last number (in base -10) is how many pages of data follow. -.PP -Subsequent lines in the example above are pages that describe how to map -from the encoding into 2-byte Unicode. The first line in a page identifies -the page number. Following it are 256 double-byte numbers, arranged as 16 -rows of 16 numbers. Given a character in the encoding, the high byte of -that character is used to select which page, and the low byte of that -character is used as an index to select one of the double-byte numbers in -that page \- the value obtained being the corresponding Unicode character. -By examination of the example above, one can see that the characters 0x7E -and 0x8163 in \fBshiftjis\fR map to 203E and 2026 in Unicode, respectively. -.PP -Following the first page will be all the other pages, each in the same -format as the first: one number identifying the page followed by 256 -double-byte Unicode characters. If a character in the encoding maps to the -Unicode character 0000, it means that the character doesn't actually exist. -If all characters on a page would map to 0000, that page can be omitted. -.PP -Case [4] is the escape-sequence encoding file. The lines in an this type of -file are in the same format as this example taken from the \fBiso2022-jp\fR -encoding: -.CS -.ta 1.5i -# Encoding file: iso2022-jp, escape-driven -E -init {} -final {} -iso8859-1 \\x1b(B -jis0201 \\x1b(J -jis0208 \\x1b$@ -jis0208 \\x1b$B -jis0212 \\x1b$(D -gb2312 \\x1b$A -ksc5601 \\x1b$(C -.CE -.PP -In the file, the first column represents an option and the second column -is the associated value. \fBinit\fR is a string to emit or expect before -the first character is converted, while \fBfinal\fR is a string to emit -or expect after the last character. All other options are names of -table-based encodings; the associated value is the escape-sequence that -marks that encoding. Tcl syntax is used for the values; in the above -example, for instance, ``\fB{}\fR'' represents the empty string and -``\fB\\x1b\fR'' represents character 27. -.PP -When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not -been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR -from the \fBencoding\fR subdirectory of each directory specified in the -library path \fB$tcl_libPath\fR. If the encoding file exists, but is -malformed, an error message will be left in \fIinterp\fR. -.SH KEYWORDS -utf, encoding, convert - - - diff --git a/doc/Eval.3 b/doc/Eval.3 deleted file mode 100644 index bc0effc..0000000 --- a/doc/Eval.3 +++ /dev/null @@ -1,196 +0,0 @@ -'\" -'\" Copyright (c) 1989-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. -'\" -'\" RCS: @(#) $Id: Eval.3,v 1.4 1999/04/16 00:46:31 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -.VS -int -\fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR) -.sp -int -\fBTcl_EvalFile\fR(\fIinterp, fileName\fR) -.sp -int -\fBTcl_EvalObjv\fR(\fIinterp, objc, objv, flags\fR) -.sp -int -\fBTcl_Eval\fR(\fIinterp, script\fR) -.sp -int -\fBTcl_EvalEx\fR(\fIinterp, script, numBytes, flags\fR) -.sp -int -\fBTcl_GlobalEval\fR(\fIinterp, script\fR) -.sp -int -\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr, flags\fR) -.sp -int -\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR) -.sp -int -\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR) -.SH ARGUMENTS -.AS Tcl_Interp **termPtr; -.AP Tcl_Interp *interp in -Interpreter in which to execute the script. The interpreter's result is -modified to hold the result or error message from the script. -.AP Tcl_Obj *objPtr in -A Tcl object containing the script to execute. -.AP int flags in -ORed combination of flag bits that specify additional options. -\fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported. -.AP char *fileName in -Name of a file containing a Tcl script. -.AP int *objc in -The number of objects in the array pointed to by \fIobjPtr\fR; -this is also the number of words in the command. -.AP Tcl_Obj **objv in -Points to an array of pointers to objects; each object holds the -value of a single word in the command to execute. -.AP int numBytes in -The number of bytes in \fIscript\fR, not including any -null terminating character. If \-1, then all characters up to the -first null byte are used. -.AP char *script in -Points to first byte of script to execute. This script must be in -writable memory: temporary modifications are made to it during -parsing. -.AP char *string in -String forming part of a Tcl script. -.AP va_list argList in -An argument list which must have been initialised using -\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. -.BE - -.SH DESCRIPTION -.PP -The procedures described here are invoked to execute Tcl scripts in -various forms. -\fBTcl_EvalObjEx\fR is the core procedure and is used by many of the others. -It executes the commands in the script stored in \fIobjPtr\fR -until either an error occurs or the end of the script is reached. -If this is the first time \fIobjPtr\fR has been executed, -its commands are compiled into bytecode instructions -which are then executed. The -bytecodes are saved in \fIobjPtr\fR so that the compilation step -can be skipped if the object is evaluated again in the future. -.PP -The return value from \fBTcl_EvalObjEx\fR (and all the other procedures -described here) is a Tcl completion code with -one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, -\fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. -In addition, a result value or error message is left in \fIinterp\fR's -result; it can be retrieved using \fBTcl_GetObjResult\fR. -.PP -\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates -its contents as a Tcl script. It returns the same information as -\fBTcl_EvalObjEx\fR. -If the file couldn't be read then a Tcl error is returned to describe -why the file couldn't be read. -.PP -\fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a -script. The \fIobjc\fR and \fIobjv\fR arguments contain the values -of the words for the Tcl command, one word in each object in -\fIobjv\fR. \fBTcl_EvalObjv\fR evaluates the command and returns -a completion code and result just like \fBTcl_EvalObjEx\fR. -.PP -\fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that -the script to be executed is supplied as a string instead of an -object and no compilation occurs. The string is parsed and executed -directly (using \fBTcl_EvalObjv\fR) instead of compiling it and -executing the bytecodes. In situations where it is known that the -script will never be executed again, \fBTcl_Eval\fR may be -faster than \fBTcl_EvalObjEx\fR. \fBTcl_Eval\fR returns a completion -code and result just like \fBTcl_EvalObjEx\fR. Note: for backward -compatibility with versions before Tcl 8.0, \fBTcl_Eval\fR -copies the object result in \fIinterp\fR to \fIinterp->result\fR -where it can be accessed directly. This makes \fBTcl_Eval\fR somewhat -slower than \fBTcl_EvalEx\fR, which doesn't do the copy. -.PP -\fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes -additional arguments \fInumBytes\fR and \fIflags\fR. For the -efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred -over \fBTcl_Eval\fR. -.PP -\fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures -that are now deprecated. They are similar to \fBTcl_EvalEx\fR and -\fBTcl_EvalObjEx\fR except that the script is evaluated in the global -namespace and its variable context consists of global variables only -(it ignores any Tcl procedures that are active). These functions are -equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below). -.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. -It returns the result of the command and also modifies -\fIinterp->result\fR in the same way as \fBTcl_Eval\fR. -The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end -of arguments. \fBTcl_VarEval\fR is now deprecated. -.PP -\fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that -instead of taking a variable number of arguments it takes an argument -list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated. - -.SH "FLAG BITS" -Any ORed combination of the following values may be used for the -\fIflags\fR argument to procedures such as \fBTcl_EvalObjEx\fR: -.TP 23 -\fBTCL_EVAL_DIRECT\fR -This flag is only used by \fBTcl_EvalObjEx\fR; it is ignored by -other procedures. If this flag bit is set, the script is not -compiled to bytecodes; instead it is executed directly -as is done by \fBTcl_EvalEx\fR. The -\fBTCL_EVAL_DIRECT\fR flag is useful in situations where the -contents of an object are going to change immediately, so the -bytecodes won't be reused in a future execution. In this case, -it's faster to execute the script directly. -.TP 23 -\fBTCL_EVAL_GLOBAL\fR -If this flag is set, the script is processed at global level. This -means that it is evaluated in the global namespace and its variable -context consists of global variables only (it ignores any Tcl -procedures at are active). - -.SH "MISCELLANEOUS DETAILS" -.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_EvalObjEx\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_EvalObjEx\fR keeps track of how many nested \fBTcl_EvalObjEx\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_EvalObjEx\fR -invocation for \fIinterp\fR, -it converts the return code to \fBTCL_ERROR\fR -and sets \fIinterp\fR's result 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_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR. -.VE - -.SH KEYWORDS -execute, file, global, object, result, script diff --git a/doc/Exit.3 b/doc/Exit.3 deleted file mode 100644 index c533efe..0000000 --- a/doc/Exit.3 +++ /dev/null @@ -1,131 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: Exit.3,v 1.3 1999/04/16 00:46:31 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Exit 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Exit, Tcl_Finalize, Tcl_FinalizeThread, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler \- end the application or thread (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) -.sp -\fBTcl_ExitThread\fR(\fIstatus\fR) -.sp -\fBTcl_FinalizeThread\fR() -.sp -\fBTcl_CreateThreadExitHandler\fR(\fIproc, clientData\fR) -.sp -\fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR) -.SH ARGUMENTS -.AS Tcl_ExitProc clientData -.AP int status in -Provides information about why the application or thread exited. -Exact meaning may -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 -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -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 -\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. -.PP -.VS -\fBTcl_ExitThread\fR is used to terminate the current thread and invoke -per-thread exit handlers. This finalization is done by -\fBTcl_FinalizeThread\fR, which you can call if you just want to clean -up per-thread state and invoke the thread exit handlers. -\fBTcl_Finalize\fR calls \fBTcl_FinalizeThread\fR for the current -thread automatically. -.VE -.PP -\fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked -by \fBTcl_Finalize\fR and \fBTcl_Exit\fR. -\fBTcl_CreateThreadExitHandler\fR arranges for \fIproc\fR to be invoked -by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR. -This provides a hook for cleanup operations such as flushing buffers -and freeing global memory. -\fIProc\fR should match the type \fBTcl_ExitProc\fR: -.CS -typedef void Tcl_ExitProc(ClientData \fIclientData\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a -copy of the \fIclientData\fR argument given to -\fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when -the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information about -what to do in \fIproc\fR. -.PP -\fBTcl_DeleteExitHandler\fR and \fBTcl_DeleteThreadExitHandler\fR may be -called to delete a -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 or \fBTcl_DeleteThreadExitHandler\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 -.VS -.PP -\fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR -and the thread exit handlers \fIafter\fR -the process-wide exit handlers. This is because thread finalization shuts -down the I/O channel system, so any attempt at I/O by the global exit -handlers will vanish into the bitbucket. -.VE - -.SH KEYWORDS -callback, cleanup, dynamic loading, end application, exit, unloading, thread diff --git a/doc/ExprLong.3 b/doc/ExprLong.3 deleted file mode 100644 index ba15782..0000000 --- a/doc/ExprLong.3 +++ /dev/null @@ -1,114 +0,0 @@ -'\" -'\" Copyright (c) 1989-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. -'\" -'\" RCS: @(#) $Id: ExprLong.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.so man.macros -.TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an expression -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_ExprLong\fR(\fIinterp, string, longPtr\fR) -.sp -int -\fBTcl_ExprDouble\fR(\fIinterp, string, doublePtr\fR) -.sp -int -\fBTcl_ExprBoolean\fR(\fIinterp, string, booleanPtr\fR) -.sp -int -\fBTcl_ExprString\fR(\fIinterp, string\fR) -.SH ARGUMENTS -.AS Tcl_Interp *booleanPtr -.AP Tcl_Interp *interp in -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 -it undoes before returning). -.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. -.BE - -.SH DESCRIPTION -.PP -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 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 -evaluated, and \fBTCL_ERROR\fR means that an error occurred while -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. -.PP -If the expression is successfully evaluated, then its value is -returned in one of four forms, depending on which procedure -is invoked. -\fBTcl_ExprLong\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_ExprDouble\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_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 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 -\fBTcl_ExprString\fR returns the value of the expression as a -string stored in \fIinterp->result\fR. -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. - -.SH "SEE ALSO" -Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj - -.SH KEYWORDS -boolean, double, evaluate, expression, integer, object, string diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3 deleted file mode 100644 index f1e500d..0000000 --- a/doc/ExprLongObj.3 +++ /dev/null @@ -1,104 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: ExprLongObj.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.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/doc/FindExec.3 b/doc/FindExec.3 deleted file mode 100644 index 098c7a2..0000000 --- a/doc/FindExec.3 +++ /dev/null @@ -1,56 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: FindExec.3,v 1.3 1998/09/14 18:39:48 stanton Exp $ -'\" -.so man.macros -.TH Tcl_FindExecutable 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of the binary file containing the application -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -char * -\fBTcl_FindExecutable\fR(\fIargv0\fR) -.sp -CONST char * -\fBTcl_GetNameOfExecutable\fR() -.SH ARGUMENTS -.AS char *argv0 in -.AP char *argv0 in -The first command-line argument to the program, which gives the -application's name. -.BE - -.SH DESCRIPTION -.PP -The \fBTcl_FindExecutable\fR 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, 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 -On UNIX platforms this procedure is typically invoked as the very -first thing in the application's main program; it must be passed -\fIargv[0]\fR as its argument. \fBTcl_FindExecutable\fR uses \fIargv0\fR -along with the \fBPATH\fR environment variable to find the -application's executable, if possible. If it fails to find -the binary, then future calls to \fBinfo nameofexecutable\fR -will return an empty string. -.PP -\fBTcl_GetNameOfExecutable\fR simply returns a pointer to the -internal full path name of the executable file as computed by -\fBTcl_FindExecutable\fR. This procedure call is the C API -equivalent to the \fBinfo nameofexecutable\fR command. NULL -is returned if the internal full path name has not been -computed or unknown. - -.SH KEYWORDS -binary, executable file diff --git a/doc/GetCwd.3 b/doc/GetCwd.3 deleted file mode 100755 index 4c8d65d..0000000 --- a/doc/GetCwd.3 +++ /dev/null @@ -1,54 +0,0 @@ -'\" -'\" Copyright (c) 1998-1999 Scriptics Corportation -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: GetCwd.3,v 1.2 1999/04/16 00:46:31 stanton Exp $ -'\" -.so man.macros -.TH Tcl_GetCwd 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetCwd, Tcl_Chdir \- manipulate the current working directory -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -char * -\fBTcl_GetCwd\fR(\fIinterp\fR, \fIbufferPtr\fR) -.sp -int -\fBTcl_Chdir\fR(\fIpath\fR) -.SH ARGUMENTS -.AS Tcl_DString *bufferPtr -.AP Tcl_Interp *interp in -Interpreter in which to report an error, if any. -.AP Tcl_DString *bufferPtr in/out -This dynamic string is used to store the current working directory. -At the time of the call it should be uninitialized or free. The -caller must eventually call \fBTcl_DStringFree\fR to free up -anything stored here. -.AP char *path in -File path in UTF\-8 format. -.BE - -.SH DESCRIPTION -.PP -These procedures may be used to manipulate the current working -directory for the application. They provide C\-level access to -the same functionality as the Tcl \fBpwd\fR command. -.PP -\fBTcl_GetCwd\fR returns a pointer to a string specifying the current -directory, or NULL if the current directory could not be determined. -If NULL is returned, an error message is left in the interp's result. -Storage for the result string is allocated in bufferPtr; the caller -must call \fBTcl_DStringFree()\fR when the result is no longer needed. -The format of the path is UTF\-8. -.PP -\fBTcl_Chdir\fR changes the applications current working directory to -the value specified in \fIpath\fR. The format of the passed in string -must be UTF\-8. The function returns -1 on error or 0 on success. - -.SH KEYWORDS -pwd diff --git a/doc/GetIndex.3 b/doc/GetIndex.3 deleted file mode 100644 index 342069a..0000000 --- a/doc/GetIndex.3 +++ /dev/null @@ -1,100 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: GetIndex.3,v 1.3 1999/04/16 00:46:31 stanton Exp $ -'\" -.so man.macros -.TH Tcl_GetIndexFromObj 3 8.1 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) -.VS -.sp -int -\fBTcl_GetIndexFromObjStruct\fR(\fIinterp, objPtr, tablePtr, offset, -msg, flags, indexPtr\fR) -.VE -.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. -.VS -.AP int offset in -The offset to add to tablePtr to get to the next string in the -list. The end of the array is marked by a NULL string pointer. -.VE -.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. -.VS -.PP -\fBTcl_GetIndexFromObjStruct\fR works just like -\fBTcl_GetIndexFromObj\fR, except that instead of treating -\fItablePtr\fR as an array of string pointers, it treats it as the -first in a series of string ptrs that are spaced apart by \fIoffset\fR -bytes. This is particularly useful when processing things like -\fBTk_ConfigurationSpec\fR, whose string keys are in the same place in -each of several array elements. -.VE - -.SH "SEE ALSO" -Tcl_WrongNumArgs - -.SH KEYWORDS -index, object, table lookup diff --git a/doc/GetInt.3 b/doc/GetInt.3 deleted file mode 100644 index 473a12f..0000000 --- a/doc/GetInt.3 +++ /dev/null @@ -1,81 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: GetInt.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.so man.macros -.TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, double, or boolean -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_GetInt\fR(\fIinterp, string, intPtr\fR) -.sp -int -\fBTcl_GetDouble\fR(\fIinterp, string, doublePtr\fR) -.sp -int -\fBTcl_GetBoolean\fR(\fIinterp, string, boolPtr\fR) -.SH ARGUMENTS -.AS Tcl_Interp *doublePtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP char *string in -Textual value to be converted. -.AP int *intPtr out -Points to place to store integer value converted from \fIstring\fR. -.AP double *doublePtr out -Points to place to store double-precision floating-point -value converted from \fIstring\fR. -.AP int *boolPtr out -Points to place to store boolean value (0 or 1) converted from \fIstring\fR. -.BE - -.SH DESCRIPTION -.PP -These procedures convert from strings to integers or double-precision -floating-point values or booleans (represented as 0- or 1-valued -integers). Each of the procedures takes a \fIstring\fR argument, -converts it to an internal form of a particular type, and stores -the converted value at the location indicated by the procedure's -third argument. If all goes well, each of the procedures returns -TCL_OK. If \fIstring\fR doesn't have the proper syntax for the -desired type then TCL_ERROR is returned, an error message is left -in \fIinterp->result\fR, and nothing is stored at *\fIintPtr\fR -or *\fIdoublePtr\fR or *\fIboolPtr\fR. -.PP -\fBTcl_GetInt\fR expects \fIstring\fR to consist of a collection -of integer digits, optionally signed and optionally preceded by -white space. If the first two characters of \fIstring\fR are ``0x'' -then \fIstring\fR is expected to be in hexadecimal form; otherwise, -if the first character of \fIstring\fR is ``0'' then \fIstring\fR -is expected to be in octal form; otherwise, \fIstring\fR is -expected to be in decimal form. -.PP -\fBTcl_GetDouble\fR expects \fIstring\fR to consist of a floating-point -number, which is: white space; a sign; a sequence of digits; a -decimal point; a sequence of digits; the letter ``e''; and a -signed decimal exponent. Any of the fields may be omitted, except that -the digits either before or after the decimal point must be present -and if the ``e'' is present then it must be followed by the -exponent number. -.PP -\fBTcl_GetBoolean\fR expects \fIstring\fR to specify a boolean -value. If \fIstring\fR is any of \fB0\fR, \fBfalse\fR, -\fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero -value at \fI*boolPtr\fR. -If \fIstring\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR, -then 1 is stored at \fI*boolPtr\fR. -Any of these values may be abbreviated, and upper-case spellings -are also acceptable. - -.SH KEYWORDS -boolean, conversion, double, floating-point, integer diff --git a/doc/GetOpnFl.3 b/doc/GetOpnFl.3 deleted file mode 100644 index 38c7a07..0000000 --- a/doc/GetOpnFl.3 +++ /dev/null @@ -1,61 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: GetOpnFl.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -.so man.macros -.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetOpenFile \- Get a standard IO File * handle from a channel. (Unix only) -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR) -.sp -.SH ARGUMENTS -.AS Tcl_Interp checkUsage -.AP Tcl_Interp *interp in -Tcl interpreter from which file handle is to be obtained. -.AP char *string in -String identifying channel, such as \fBstdin\fR or \fBfile4\fR. -.AP int write in -Non-zero means the file will be used for writing, zero means it will -be used for reading. -.AP int checkUsage in -If non-zero, then an error will be generated if the file wasn't opened -for the access indicated by \fIwrite\fR. -.AP ClientData *filePtr out -Points to word in which to store pointer to FILE structure for -the file given by \fIstring\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_GetOpenFile\fR takes as argument a file identifier of the form -returned by the \fBopen\fR command and -returns at \fI*filePtr\fR a pointer to the FILE structure for -the file. -The \fIwrite\fR argument indicates whether the FILE pointer will -be used for reading or writing. -In some cases, such as a channel that connects to a pipeline of -subprocesses, different FILE pointers will be returned for reading -and writing. -\fBTcl_GetOpenFile\fR normally returns TCL_OK. -If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't -make any sense or \fIcheckUsage\fR was set and the file wasn't opened -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/doc/GetStdChan.3 b/doc/GetStdChan.3 deleted file mode 100644 index 565eaa7..0000000 --- a/doc/GetStdChan.3 +++ /dev/null @@ -1,73 +0,0 @@ -'\" -'\" Copyright (c) 1996 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. -'\" -'\" RCS: @(#) $Id: GetStdChan.3,v 1.2 1998/09/14 18:39:48 stanton Exp $ -'\" -.so man.macros -.TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Tcl_GetStdChannel, Tcl_SetStdChannel \- procedures for retrieving and replacing the standard channels -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Channel -\fBTcl_GetStdChannel\fR(\fItype\fR) -.sp -\fBTcl_SetStdChannel\fR(\fIchannel, type\fR) -.sp -.SH ARGUMENTS -.AS Tcl_Channel channel in -.AP int type in -The identifier for the standard channel to retrieve or modify. Must be one of -\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR. -.AP Tcl_Channel channel in -The channel to use as the new value for the specified standard channel. -.BE - -.SH DESCRIPTION -.PP -Tcl defines three special channels that are used by various I/O related -commands if no other channels are specified. The standard input channel -has a channel name of \fBstdin\fR and is used by \fBread\fR and \fBgets\fR. -The standard output channel is named \fBstdout\fR and is used by -\fBputs\fR. The standard error channel is named \fBstderr\fR and is used for -reporting errors. In addition, the standard channels are inherited by any -child processes created using \fBexec\fR or \fBopen\fR in the absence of any -other redirections. -.PP -The standard channels are actually aliases for other normal channels. The -current channel associated with a standard channel can be retrieved by calling -\fBTcl_GetStdChannel\fR with one of -\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR as the \fItype\fR. The -return value will be a valid channel, or NULL. -.PP -A new channel can be set for the standard channel specified by \fItype\fR -by calling \fBTcl_SetStdChannel\fR with a new channel or NULL in the -\fIchannel\fR argument. If the specified channel is closed by a later call to -\fBTcl_Close\fR, then the corresponding standard channel will automatically be -set to NULL. -.PP -If \fBTcl_GetStdChannel\fR is called before \fBTcl_SetStdChannel\fR, Tcl will -construct a new channel to wrap the appropriate platform-specific standard -file handle. If \fBTcl_SetStdChannel\fR is called before -\fBTcl_GetStdChannel\fR, then the default channel will not be created. -.PP -If one of the standard channels is set to NULL, either by calling -\fBTcl_SetStdChannel\fR with a null \fIchannel\fR argument, or by calling -\fBTcl_Close\fR on the channel, then the next call to \fBTcl_CreateChannel\fR -will automatically set the standard channel with the newly created channel. If -more than one standard channel is NULL, then the standard channels will be -assigned starting with standard input, followed by standard output, with -standard error being last. - -.SH "SEE ALSO" -Tcl_Close(3), Tcl_CreateChannel(3) - -.SH KEYWORDS -standard channel, standard input, standard output, standard error diff --git a/doc/GetVersion.3 b/doc/GetVersion.3 deleted file mode 100755 index 0b88dc5..0000000 --- a/doc/GetVersion.3 +++ /dev/null @@ -1,49 +0,0 @@ -'\" -'\" Copyright (c) 1999 Scriptics Corporation -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: GetVersion.3,v 1.2 1999/04/16 00:46:32 stanton Exp $ -'\" -.so man.macros -.TH Tcl_GetVersion 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetVersion \- get the version of the library at runtime -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_GetVersion\fR(\fImajor, minor, patchLevel, type\fR) -.SH ARGUMENTS -.AP int *major out -Major version number of the Tcl library. -.AP int *minor out -Minor version number of the Tcl library. -.AP int *patchLevel out -The patch level of the Tcl library (or alpha or beta number). -.AP Tcl_ReleaseType *type out -The type of release, also indicates the type of patch level. Can be -one of \fBTCL_ALPHA_RELEASE\fR, \fBTCL_BETA_RELEASE\fR, or -\fBTCL_FINAL_RELEASE\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_GetVersion\fR should be used to query the version number -of the Tcl library at runtime. This is useful when using a -dynamically loaded Tcl library or when writing a stubs-aware -extension. For instance, if you write an extension that is -linked against the Tcl stubs library, it could be loaded into -a program linked to an older version of Tcl than you expected. -Use \fBTcl_GetVersion\fR to verify that fact, and possibly to -change the behavior of your extension. -.PP -If may pass a NULL for any of the arguments. For instance if -you do not care about the \fIpatchLevel\fR of the library, pass -a NULL for the \fIpatchLevel\fR argument. - -.SH KEYWORDS -version, patchlevel, major, minor, alpha, beta, release - diff --git a/doc/Hash.3 b/doc/Hash.3 deleted file mode 100644 index 0c5bb35..0000000 --- a/doc/Hash.3 +++ /dev/null @@ -1,208 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Hash.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_InitHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_InitHashTable\fR(\fItablePtr, keyType\fR) -.sp -\fBTcl_DeleteHashTable\fR(\fItablePtr\fR) -.sp -Tcl_HashEntry * -\fBTcl_CreateHashEntry\fR(\fItablePtr, key, newPtr\fR) -.sp -\fBTcl_DeleteHashEntry\fR(\fIentryPtr\fR) -.sp -Tcl_HashEntry * -\fBTcl_FindHashEntry\fR(\fItablePtr, key\fR) -.sp -ClientData -\fBTcl_GetHashValue\fR(\fIentryPtr\fR) -.sp -\fBTcl_SetHashValue\fR(\fIentryPtr, value\fR) -.sp -char * -\fBTcl_GetHashKey\fR(\fItablePtr, entryPtr\fR) -.sp -Tcl_HashEntry * -\fBTcl_FirstHashEntry\fR(\fItablePtr, searchPtr\fR) -.sp -Tcl_HashEntry * -\fBTcl_NextHashEntry\fR(\fIsearchPtr\fR) -.sp -char * -\fBTcl_HashStats\fR(\fItablePtr\fR) -.SH ARGUMENTS -.AS Tcl_HashSearch *searchPtr -.AP Tcl_HashTable *tablePtr in -Address of hash table structure (for all procedures but -\fBTcl_InitHashTable\fR, this must have been initialized by -previous call to \fBTcl_InitHashTable\fR). -.AP int keyType in -Kind of keys to use for new hash table. Must be either -TCL_STRING_KEYS, TCL_ONE_WORD_KEYS, or an integer value -greater than 1. -.AP char *key in -Key to use for probe into table. Exact form depends on -\fIkeyType\fR used to create table. -.AP int *newPtr out -The word at \fI*newPtr\fR is set to 1 if a new entry was created -and 0 if there was already an entry for \fIkey\fR. -.AP Tcl_HashEntry *entryPtr in -Pointer to hash table entry. -.AP ClientData value in -New value to assign to hash table entry. Need not have type -ClientData, but must fit in same space as ClientData. -.AP Tcl_HashSearch *searchPtr in -Pointer to record to use to keep track of progress in enumerating -all the entries in a hash table. -.BE - -.SH DESCRIPTION -.PP -A hash table consists of zero or more entries, each consisting of -a key and a value. -Given the key for an entry, the hashing routines can very quickly -locate the entry, and hence its value. -There may be at most one entry in a hash table with a -particular key, but many entries may have the same value. -Keys can take one of three forms: strings, -one-word values, or integer arrays. -All of the keys in a given table have the same form, which is -specified when the table is initialized. -.PP -The value of a hash table entry can be anything that fits in -the same space as a ``char *'' pointer. -Values for hash table entries are managed entirely by clients, -not by the hash module itself. -Typically each entry's value is a pointer to a data structure -managed by client code. -.PP -Hash tables grow gracefully as the number of entries increases, -so that there are always less than three entries per hash bucket, -on average. -This allows for fast lookups regardless of the number of entries -in a table. -.PP -\fBTcl_InitHashTable\fR initializes a structure that describes -a new hash table. -The space for the structure is provided by the caller, not by -the hash module. -The value of \fIkeyType\fR indicates what kinds of keys will -be used for all entries in the table. \fIKeyType\fR must have -one of the following values: -.IP \fBTCL_STRING_KEYS\fR 25 -Keys are null-terminated ASCII strings. -They are passed to hashing routines using the address of the -first character of the string. -.IP \fBTCL_ONE_WORD_KEYS\fR 25 -Keys are single-word values; they are passed to hashing routines -and stored in hash table entries as ``char *'' values. -The pointer value is the key; it need not (and usually doesn't) -actually point to a string. -.IP \fIother\fR 25 -If \fIkeyType\fR is not TCL_STRING_KEYS or TCL_ONE_WORD_KEYS, -then it must be an integer value greater than 1. -In this case the keys will be arrays of ``int'' values, where -\fIkeyType\fR gives the number of ints in each key. -This allows structures to be used as keys. -All keys must have the same size. -Array keys are passed into hashing functions using the address -of the first int in the array. -.PP -\fBTcl_DeleteHashTable\fR deletes all of the entries in a hash -table and frees up the memory associated with the table's -bucket array and entries. -It does not free the actual table structure (pointed to -by \fItablePtr\fR), since that memory is assumed to be managed -by the client. -\fBTcl_DeleteHashTable\fR also does not free or otherwise -manipulate the values of the hash table entries. -If the entry values point to dynamically-allocated memory, then -it is the client's responsibility to free these structures -before deleting the table. -.PP -\fBTcl_CreateHashEntry\fR locates the entry corresponding to a -particular key, creating a new entry in the table if there -wasn't already one with the given key. -If an entry already existed with the given key then \fI*newPtr\fR -is set to zero. -If a new entry was created, then \fI*newPtr\fR is set to a non-zero -value and the value of the new entry will be set to zero. -The return value from \fBTcl_CreateHashEntry\fR is a pointer to -the entry, which may be used to retrieve and modify the entry's -value or to delete the entry from the table. -.PP -\fBTcl_DeleteHashEntry\fR will remove an existing entry from a -table. -The memory associated with the entry itself will be freed, but -the client is responsible for any cleanup associated with the -entry's value, such as freeing a structure that it points to. -.PP -\fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR -except that it doesn't create a new entry if the key doesn't exist; -instead, it returns NULL as result. -.PP -\fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to -read and write an entry's value, respectively. -Values are stored and retrieved as type ``ClientData'', which is -large enough to hold a pointer value. On almost all machines this is -large enough to hold an integer value too. -.PP -\fBTcl_GetHashKey\fR returns the key for a given hash table entry, -either as a pointer to a string, a one-word (``char *'') key, or -as a pointer to the first word of an array of integers, depending -on the \fIkeyType\fR used to create a hash table. -In all cases \fBTcl_GetHashKey\fR returns a result with type -``char *''. -When the key is a string or array, the result of \fBTcl_GetHashKey\fR -points to information in the table entry; this information will -remain valid until the entry is deleted or its table is deleted. -.PP -\fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used -to scan all of the entries in a hash table. -A structure of type ``Tcl_HashSearch'', provided by the client, -is used to keep track of progress through the table. -\fBTcl_FirstHashEntry\fR initializes the search record and -returns the first entry in the table (or NULL if the table is -empty). -Each subsequent call to \fBTcl_NextHashEntry\fR returns the -next entry in the table or -NULL if the end of the table has been reached. -A call to \fBTcl_FirstHashEntry\fR followed by calls to -\fBTcl_NextHashEntry\fR will return each of the entries in -the table exactly once, in an arbitrary order. -It is unadvisable to modify the structure of the table, e.g. -by creating or deleting entries, while the search is in -progress. -.PP -\fBTcl_HashStats\fR returns a dynamically-allocated string with -overall information about a hash table, such as the number of -entries it contains, the number of buckets in its hash array, -and the utilization of the buckets. -It is the caller's responsibility to free the result string -by passing it to \fBfree\fR. -.PP -The header file \fBtcl.h\fR defines the actual data structures -used to implement hash tables. -This is necessary so that clients can allocate Tcl_HashTable -structures and so that macros can be used to read and write -the values of entries. -However, users of the hashing routines should never refer directly -to any of the fields of any of the hash-related data structures; -use the procedures and macros defined here. - -.SH KEYWORDS -hash table, key, lookup, search, value diff --git a/doc/IntObj.3 b/doc/IntObj.3 deleted file mode 100644 index 6222498..0000000 --- a/doc/IntObj.3 +++ /dev/null @@ -1,104 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: IntObj.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.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/doc/Interp.3 b/doc/Interp.3 deleted file mode 100644 index db08dcd..0000000 --- a/doc/Interp.3 +++ /dev/null @@ -1,125 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Interp.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Interp \- client-visible fields of interpreter structures -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -typedef struct { - char *\fIresult\fR; - Tcl_FreeProc *\fIfreeProc\fR; - int \fIerrorLine\fR; -} Tcl_Interp; - -typedef void Tcl_FreeProc(char *\fIblockPtr\fR); -.BE - -.SH DESCRIPTION -.PP -The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp -structure. This pointer is then passed into other Tcl procedures -to process commands in the interpreter and perform other operations -on the interpreter. Interpreter structures contain many many fields -that are used by Tcl, but only three that may be accessed by -clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR. -.PP -The \fIresult\fR and \fIfreeProc\fR fields are used to return -results or error messages from commands. -This information is returned by command procedures back to \fBTcl_Eval\fR, -and by \fBTcl_Eval\fR back to its callers. -The \fIresult\fR field points to the string that represents the -result or error message, and the \fIfreeProc\fR field tells how -to dispose of the storage for the string when it isn't needed anymore. -The easiest way for command procedures to manipulate these -fields is to call procedures like \fBTcl_SetResult\fR -or \fBTcl_AppendResult\fR; they -will hide all the details of managing the fields. -The description below is for those procedures that manipulate the -fields directly. -.PP -Whenever a command procedure returns, it must ensure -that the \fIresult\fR field of its interpreter points to the string -being returned by the command. -The \fIresult\fR field must always point to a valid string. -If a command wishes to return no result then \fIinterp->result\fR -should point to an empty string. -Normally, results are assumed to be statically allocated, -which means that the contents will not change before the next time -\fBTcl_Eval\fR is called or some other command procedure is invoked. -.VS -In this case, the \fIfreeProc\fR field must be zero. -Alternatively, a command procedure may dynamically -allocate its return value (e.g. using \fBTcl_Alloc\fR) -and store a pointer to it in \fIinterp->result\fR. -In this case, the command procedure must also set \fIinterp->freeProc\fR -to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR -if the storage was allocated directly by Tcl or by a call to -\fBTcl_Alloc\fR. -.VE -If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR -to free the space pointed to by \fIinterp->result\fR before it -invokes the next command. -If a client procedure overwrites \fIinterp->result\fR when -\fIinterp->freeProc\fR is non-zero, then it is responsible for calling -\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR -macro should be used for this purpose). -.PP -\fIFreeProc\fR should have arguments and result that match the -\fBTcl_FreeProc\fR declaration above: it receives a single -argument which is a pointer to the result value to free. -.VS -In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever -used for \fIfreeProc\fR. -.VE -However, an application may store a different procedure address -in \fIfreeProc\fR in order to use an alternate memory allocator -or in order to do other cleanup when the result memory is freed. -.PP -As part of processing each command, \fBTcl_Eval\fR initializes -\fIinterp->result\fR -and \fIinterp->freeProc\fR just before calling the command procedure for -the command. The \fIfreeProc\fR field will be initialized to zero, -and \fIinterp->result\fR will point to an empty string. Commands that -do not return any value can simply leave the fields alone. -Furthermore, the empty string pointed to by \fIresult\fR is actually -part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200). -If a command wishes to return a short string, it can simply copy -it to the area pointed to by \fIinterp->result\fR. Or, it can use -the sprintf procedure to generate a short result string at the location -pointed to by \fIinterp->result\fR. -.PP -It is a general convention in Tcl-based applications that the result -of an interpreter is normally in the initialized state described -in the previous paragraph. -Procedures that manipulate an interpreter's result (e.g. by -returning an error) will generally assume that the result -has been initialized when the procedure is called. -If such a procedure is to be called after the result has been -changed, then \fBTcl_ResetResult\fR should be called first to -reset the result to its initialized state. -.PP -The \fIerrorLine\fR -field is valid only after \fBTcl_Eval\fR returns -a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR -field identifies the line number of the command being executed when -the error occurred. The line numbers are relative to the command -being executed: 1 means the first line of the command passed to -\fBTcl_Eval\fR, 2 means the second line, and so on. -The \fIerrorLine\fR field is typically used in conjunction with -\fBTcl_AddErrorInfo\fR to report information about where an error -occurred. -\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR. - -.SH KEYWORDS -free, initialized, interpreter, malloc, result diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 deleted file mode 100644 index 25d3c17..0000000 --- a/doc/LinkVar.3 +++ /dev/null @@ -1,115 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: LinkVar.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros -.TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR) -.sp -\fBTcl_UnlinkVar\fR(\fIinterp, varName\fR) -.sp -\fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR) -.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. 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 -Type of C variable. Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE, -TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with -TCL_LINK_READ_ONLY to make Tcl variable read-only. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable -named by \fIvarName\fR in sync with the C variable at the address -given by \fIaddr\fR. -Whenever the Tcl variable is read the value of the C variable will -be returned, and whenever the Tcl variable is written the C -variable will be updated to have the same value. -\fBTcl_LinkVar\fR normally returns TCL_OK; if an error occurs -while setting up the link (e.g. because \fIvarName\fR is the -name of array) then TCL_ERROR is returned and \fIinterp->result\fR -contains an error message. -.PP -The \fItype\fR argument specifies the type of the C variable, -and must have one of the following values, optionally OR'ed with -TCL_LINK_READ_ONLY: -.TP -\fBTCL_LINK_INT\fR -The C variable is of type \fBint\fR. -Any value written into the Tcl variable must have a proper integer -form acceptable to \fBTcl_GetInt\fR; attempts to write -non-integer values into \fIvarName\fR will be rejected with -Tcl errors. -.TP -\fBTCL_LINK_DOUBLE\fR -The C variable is of type \fBdouble\fR. -Any value written into the Tcl variable must have a proper real -form acceptable to \fBTcl_GetDouble\fR; attempts to write -non-real values into \fIvarName\fR will be rejected with -Tcl errors. -.TP -\fBTCL_LINK_BOOLEAN\fR -The C variable is of type \fBint\fR. -If its value is zero then it will read from Tcl as ``0''; -otherwise it will read from Tcl as ``1''. -Whenever \fIvarName\fR is -modified, the C variable will be set to a 0 or 1 value. -Any value written into the Tcl variable must have a proper boolean -form acceptable to \fBTcl_GetBoolean\fR; attempts to write -non-boolean values into \fIvarName\fR will be rejected with -Tcl errors. -.TP -\fBTCL_LINK_STRING\fR -The C variable is of type \fBchar *\fR. -.VS -If its value is not null then it must be a pointer to a string -allocated with \fBTcl_Alloc\fR. -.VE -Whenever the Tcl variable is modified the current C string will be -freed and new memory will be allocated to hold a copy of the variable's -new value. -If the C variable contains a null pointer then the Tcl variable -will read as ``NULL''. -.PP -If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the -variable will be read-only from Tcl, so that its value can only be -changed by modifying the C variable. -Attempts to write the variable from Tcl will be rejected with errors. -.PP -\fBTcl_UnlinkVar\fR removes the link previously set up for the -variable given by \fIvarName\fR. If there does not exist a link -for \fIvarName\fR then the procedure has no effect. -.PP -\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 -read the Tcl variable will return the latest value of the C variable. -However, if a trace has been set on the Tcl variable (such as a -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. - -.SH KEYWORDS -boolean, integer, link, read-only, real, string, traces, variable diff --git a/doc/ListObj.3 b/doc/ListObj.3 deleted file mode 100644 index c36bdfe..0000000 --- a/doc/ListObj.3 +++ /dev/null @@ -1,249 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: ListObj.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.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 count in -The number of elements 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/doc/Notifier.3 b/doc/Notifier.3 deleted file mode 100644 index dcd8250..0000000 --- a/doc/Notifier.3 +++ /dev/null @@ -1,537 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: Notifier.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros -.TH Notifier 3 8.0 Tcl "Tcl Library Procedures" -.BS -.VS -.SH NAME -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\fR(\fIsetupProc, checkProc, clientData\fB)\fR -.sp -\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR -.sp -\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fB)\fR -.sp -\fBTcl_QueueEvent\fR(\fIevPtr, position\fR) -.VS -.sp -\fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR) -.sp -int -\fBTcl_WaitForEvent\fR(\fItimePtr\fR) -.sp -\fBTcl_SetTimer\fR(\fItimePtr\fR) -.sp -int -\fBTcl_ServiceAll\fR() -.sp -int -\fBTcl_ServiceEvent\fR(\fIflags\fR) -.sp -int -\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_DoOneEvent\fR. -.AP Tcl_EventCheckProc *checkProc in -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, \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 -time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR -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 -have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR. -.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 -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 -.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 -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 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. 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 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: -.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 -.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 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 -information provided by the event sources. -It may cause the application to block if \fItimePtr\fR specifies -an interval other than 0. -\fBTcl_WaitForEvent\fR returns when something has happened, -such as a file becoming readable or the interval given by \fItimePtr\fR -expiring. If there are no events for \fBTcl_WaitForEvent\fR to -wait for, so that it would block forever, then it returns immediately -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. 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. -.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. - -.SH "CREATING A NEW EVENT SOURCE" -.PP -An event source consists of three procedures invoked by the notifier, -plus additional C procedures that are invoked by higher-level code -to arrange for event-driven callbacks. The three procedures called -by the notifier consist of the setup and check procedures described -above, plus an additional procedure that is invoked when an event -is removed from the event queue for servicing. -.PP -The procedure \fBTcl_CreateEventSource\fR creates a new event source. -Its arguments specify the setup procedure and check procedure for -the event source. -\fISetupProc\fR should match the following prototype: -.CS -typedef void Tcl_EventSetupProc( - ClientData \fIclientData\fR, - int \fIflags\fR); -.CE -The \fIclientData\fR argument will be the same as the \fIclientData\fR -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 -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 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. 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: -.CS -typedef struct Tcl_Time { - long \fIsec\fR; - long \fIusec\fR; -} Tcl_Time; -.CE -The \fIusec\fR field should be less than 1000000. -.PP -.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 -.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 -\fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the -following prototype: -.CS -typedef void Tcl_EventCheckProc( - ClientData \fIclientData\fR, - int \fIflags\fR); -.CE -The arguments to this procedure are the same as those for \fIsetupProc\fR. -\fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited -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. -.PP -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; - struct Tcl_Event *\fInextPtr\fR; -}; -.CE -The event source must fill in the \fIproc\fR field of -the event before calling \fBTcl_QueueEvent\fR. -The \fInextPtr\fR is used to link together the events in the queue -and should not be modified by the event source. -.PP -An event may be added to the queue at any of three positions, depending -on the \fIposition\fR argument to \fBTcl_QueueEvent\fR: -.IP \fBTCL_QUEUE_TAIL\fR 24 -Add the event at the back of the queue, so that all other pending -events will be serviced first. This is almost always the right -place for new events. -.IP \fBTCL_QUEUE_HEAD\fR 24 -Add the event at the front of the queue, so that it will be serviced -before all other queued events. -.IP \fBTCL_QUEUE_MARK\fR 24 -Add the event at the front of the queue, unless there are other -events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so, -add the new event just after all other \fBTCL_QUEUE_MARK\fR events. -This value of \fIposition\fR is used to insert an ordered sequence of -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 -.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 -typedef int Tcl_EventProc( - Tcl_Event *\fIevPtr\fR, - int \fIflags\fR); -.CE -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 -.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 -one or more Tcl commands or C-level callbacks. -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 -.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 -\fIflags\fR argument. -For example, the file event source will always return 0 if the -\fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR. -Another example of deferring events happens in Tk if -\fBTk_RestrictEvents\fR has been invoked to defer certain kinds -of window events. -.PP -.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 -the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR) -before calling \fBTcl_QueueEvent\fR, but it -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, 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. -.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 \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 \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 -event, notifier, event queue, event sources, file events, timer, idle, service mode diff --git a/doc/Object.3 b/doc/Object.3 deleted file mode 100644 index 214695f..0000000 --- a/doc/Object.3 +++ /dev/null @@ -1,337 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: Object.3,v 1.3 1999/04/16 00:46:32 stanton Exp $ -'\" -.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 and \fBTcl_GetString\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 and \fBTcl_GetString\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 or \fBTcl_GetString\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 -or \fBTcl_GetString\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_AppendToObj\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 0. -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/doc/ObjectType.3 b/doc/ObjectType.3 deleted file mode 100644 index df79219..0000000 --- a/doc/ObjectType.3 +++ /dev/null @@ -1,198 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: ObjectType.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.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/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 deleted file mode 100644 index e9205e3..0000000 --- a/doc/OpenFileChnl.3 +++ /dev/null @@ -1,566 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.3 1999/04/16 00:46:32 stanton Exp $ -.so man.macros -.TH Tcl_OpenFileChannel 3 8.1 Tcl "Tcl Library Procedures" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, \- buffered I/O facilities using channels -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -typedef ... Tcl_Channel; -.sp -Tcl_Channel -\fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR) -.sp -Tcl_Channel -\fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR) -.VS 8.0 -.sp -Tcl_Channel -\fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR) -.VE -.sp -Tcl_Channel -\fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR) -.sp -void -\fBTcl_RegisterChannel\fR(\fIinterp, channel\fR) -.sp -int -\fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR) -.sp -int -\fBTcl_Close\fR(\fIinterp, channel\fR) -.sp -.VS 8.1 -int -\fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR) -.sp -int -\fBTcl_Read\fR(\fIchannel, byteBuf, bytesToRead\fR) -.sp -int -\fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) -.sp -int -\fBTcl_Gets\fR(\fIchannel, lineRead\fR) -.sp -int -\fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) -.sp -int -\fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) -.sp -int -\fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) -.VE -.sp -int -\fBTcl_Flush\fR(\fIchannel\fR) -.sp -int -\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) -.sp -int -\fBTcl_Tell\fR(\fIchannel\fR) -.sp -int -\fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) -.sp -int -\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) -.sp -int -\fBTcl_Eof\fR(\fIchannel\fR) -.sp -int -\fBTcl_InputBlocked\fR(\fIchannel\fR) -.sp -int -\fBTcl_InputBuffered\fR(\fIchannel\fR) -.sp -.SH ARGUMENTS -.AS Tcl_ChannelType newClientProcPtr in -.AP Tcl_Interp *interp in -Used for error reporting and to look up a channel registered in it. -.AP char *fileName in -The name of a local or network file. -.AP char *mode in -Specifies how the file is to be accessed. May have any of the values -allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. For -\fBTcl_OpenCommandChannel\fR, may be NULL. -.AP int permissions in -POSIX-style permission flags such as 0644. If a new file is created, these -permissions will be set on the created file. -.AP int argc in -The number of elements in \fIargv\fR. -.AP char **argv in -Arguments for constructing a command pipeline. These values have the same -meaning as the non-switch arguments to the Tcl \fBexec\fR command. -.AP int flags in -Specifies the disposition of the stdio handles in pipeline: OR-ed -combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and -\fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child -in the pipe is the pipe channel, otherwise it is the same as the standard -input of the invoking process; likewise for \fBTCL_STDOUT\fR and -\fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, 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. -.VS 8.0 -.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 -what operations are valid on \fIhandle\fR. -.AP char *channelName in -The name of the channel. -.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 -open for reading and writing. -.AP Tcl_Channel channel in -A Tcl channel for input or output. Must have been the return value -from a procedure such as \fBTcl_OpenFileChannel\fR. -.VS 8.1 br -.AP Tcl_Obj *readObjPtr in/out -A pointer to a Tcl Object in which to store the characters read from the -channel. -.AP int charsToRead in -The number of characters to read from the channel. If the channel's encoding -is \fBbinary\fR, this is equivalent to the number of bytes to read from the -channel. -.AP int appendFlag in -If non-zero, data read from the channel will be appended to the object. -Otherwise, the data will replace the existing contents of the object. -.AP char *readBuf out -A buffer in which to store the bytes read from the channel. -.AP int bytesToRead in -The number of bytes to read from the channel. The buffer \fIreadBuf\fR must -be large enough to hold this many bytes. -.AP Tcl_Obj *lineObjPtr in/out -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 Tcl_DString *lineRead in/out -A pointer to a Tcl dynamic string in which to store the line read from the -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 *writeObjPtr in -A pointer to a Tcl Object whose contents will be output to the channel. -.AP "CONST char" *charBuf in -A buffer containing the characters to output to the channel. -.AP char *byteBuf in -A buffer containing the bytes to output to the channel. -.AP int bytesToWrite in -The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and -output to the channel. -.VE -.AP int offset in -How far to move the access point in the channel at which the next input or -output operation will be applied, measured in bytes from the position -given by \fIseekMode\fR. May be either positive or negative. -.AP int seekMode in -Relative to which point to seek; used with \fIoffset\fR to calculate the new -access point for the channel. Legal values are \fBSEEK_SET\fR, -\fBSEEK_CUR\fR, and \fBSEEK_END\fR. -.AP char *optionName in -The name of an option applicable to this channel, such as \fB\-blocking\fR. -May have any of the values accepted by the \fBfconfigure\fR command. -.AP Tcl_DString *optionValue in -Where to store the value of an option or a list of all options and their -values. Must have been initialized by the caller. -.AP char *newValue in -New value for the option given by \fIoptionName\fR. -.BE - -.SH DESCRIPTION -.PP -The Tcl channel mechanism provides a device-independent and -platform-independent mechanism for performing buffered input -and output operations on a variety of file, socket, and device -types. -The channel mechanism is extensible to new channel types, by -providing a low level channel driver for the new type; the channel driver -interface is described in the manual entry for \fBTcl_CreateChannel\fR. The -channel mechanism provides a buffering scheme modeled after -Unix's standard I/O, and it also allows for nonblocking I/O on -channels. -.PP -The procedures described in this manual entry comprise the C APIs of the -generic layer of the channel architecture. For a description of the channel -driver architecture and how to implement channel drivers for new types of -channels, see the manual entry for \fBTcl_CreateChannel\fR. - -.SH TCL_OPENFILECHANNEL -.PP -\fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and -returns a channel handle that can be used to perform input and output on -the file. This API is modeled after the \fBfopen\fR procedure of -the Unix standard I/O library. -The syntax and meaning of all arguments is similar to those -given in the Tcl \fBopen\fR command when opening a file. -If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR -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\fR's result 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 -\fBTcl_OpenCommandChannel\fR provides a C-level interface to the -functions of the \fBexec\fR and \fBopen\fR commands. -It creates a sequence of subprocesses specified -by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can -be used to communicate with these subprocesses. -The \fIflags\fR argument indicates what sort of communication will -exist with the command pipeline. -.PP -If the \fBTCL_STDIN\fR flag is set then the standard input for the -first subprocess will be tied to the channel: writing to the channel -will provide input to the subprocess. If \fBTCL_STDIN\fR is not set, -then standard input for the first subprocess will be the same as this -application's standard input. If \fBTCL_STDOUT\fR is set then -standard output from the last subprocess can be read from the channel; -otherwise it goes to this application's standard output. If -\fBTCL_STDERR\fR is set, standard error output for all subprocesses is -returned to the channel and results in an error when the channel is -closed; otherwise it goes to this application's standard error. If -\fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can -redirect the stdio handles to override \fBTCL_STDIN\fR, -\fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an -error for argc and argv to override stdio channels for which -\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set. -.PP -If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR -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 -\fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to -create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in -\fIinterp\fR. If a channel by that name is not registered in that interpreter, -the procedure returns NULL. If the \fImode\fR argument is not NULL, it -points at an integer variable that will receive an OR-ed combination of -\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is -open for reading and writing. - -.SH TCL_REGISTERCHANNEL -.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, 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. -.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. 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 -POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. -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 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. - -.VS 8.1 br -.SH TCL_READCHARS AND TCL_READ -.PP -\fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes -to UTF-8 based on the channel's encoding and storing the produced data in -\fIreadObjPtr\fR's string representation. The return value of -\fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR, -that were stored in \fIobjPtr\fR. If an error occurs while reading, the -return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that -can be retrieved with \fBTcl_GetErrno\fR. -.PP -The return value may be smaller than the value to read, indicating that less -data than requested was available. This is called a \fIshort read\fR. In -blocking mode, this can only happen on an end-of-file. In nonblocking mode, -a short read can also occur if there is not enough input currently -available: \fBTcl_ReadChars\fR returns a short count rather than waiting -for more data. -.PP -If the channel is in blocking mode, a return value of zero indicates an -end-of-file condition. If the channel is in nonblocking mode, a return -value of zero indicates either that no input is currently available or an -end-of-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell -which of these conditions actually occurred. -.PP -\fBTcl_ReadChars\fR translates the various end-of-line representations into -the canonical \fB\en\fR internal representation according to the 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. -.PP -As a performance optimization, when reading from a channel with the encoding -\fBbinary\fR, the bytes are not converted to UTF-8 as they are read. -Instead, they are stored in \fIreadObjPtr\fR's internal representation as a -byte-array object. The string representation of this object will only be -constructed if it is needed (e.g., because of a call to -\fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read -from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and -related functions, and then written to a channel without the expense of ever -converting to or from UTF-8. -.PP -\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do -encoding conversions, regardless of the channel's encoding. It is deprecated -and exists for backwards compatibility with non-internationalized Tcl -extensions. It consumes bytes from \fIchannel\fR and stores them in -\fIbuf\fR, performing end-of-line translations on the way. The return value -of \fBTcl_Read\fR is the number of bytes, up to \fItoRead\fR, written in -\fIbuf\fR. The buffer produced by \fBTcl_Read\fR is not NULL terminated. -Its contents are valid from the zeroth position up to and excluding the -position indicated by the return value. - -.SH TCL_GETSOBJ AND TCL_GETS -.PP -\fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to -UTF-8 based on the channel's encoding, until a full line of input has been -seen. If the channel's encoding is \fBbinary\fR, each byte read from the -channel is treated as an individual Unicode character. All of the -characters of the line except for the terminating end-of-line character(s) -are appended to \fIlineObjPtr\fR's string representation. The end-of-line -character(s) are read and discarded. -.PP -If a line was successfully read, the return value is greater than or equal -to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an -error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code -that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also -returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure -can be used to distinguish an error from an end-of-file condition. -.PP -If the channel is in nonblocking mode, the return value can also be \-1 if -no data was available or the data that was available 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_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting -characters are appended to the appended to the dynamic string given by -\fIdsPtr\fR rather than a Tcl object. - -.SH TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE -.PP -\fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at -\fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the -channel's encoding and queued for output to \fIchannel\fR. If -\fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR -to be NULL terminated and it outputs everything up to the NULL. -.PP -Data queued for output may not appear on the output device immediately, due -to internal buffering. If the data should appear immediately, call -\fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the -\fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data -to appear as soon as a complete line is accepted for output, set the -\fB\-buffering\fR option on the channel to \fBline\fR mode. -.PP -The return value of \fBTcl_WriteChars\fR is a count of how many bytes were -accepted for output to the channel. This is either greater than zero to -indicate success or \-1 to indicate that an error occurred. If an error -occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be -retrieved with \fBTcl_GetErrno\fR. -.PP -Newline characters in the output data are translated to platform-specific -end-of-line sequences according to the \fB\-translation\fR option for the -channel. This is done even if the channel has no encoding. -.PP -\fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it -accepts a Tcl object whose contents will be output to the channel. The -UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted -to the channel's encoding and queued for output to \fIchannel\fR. -As a performance optimization, when writing to a channel with the encoding -\fBbinary\fR, UTF-8 characters are not converted as they are written. -Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a -byte-array object are written to the channel. The byte-array representation -of the object will be constructed if it is needed. In this way, -byte-oriented data can be read from a channel, manipulated by calling -\fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a -channel without the expense of ever converting to or from UTF-8. -.PP -\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do -encoding conversions, regardless of the channel's encoding. It is -deprecated and exists for backwards compatibility with non-internationalized -Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at -\fIbyteBuf\fR and queues them for output to \fIchannel\fR. If -\fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be -NULL terminated and it outputs everything up to the NULL. -.VE - -.SH TCL_FLUSH -.PP -\fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR -to be written to its underlying file or device as soon as possible. -If the channel is in blocking mode, the call does not return until -all the buffered data has been sent to the channel or some error occurred. -The call returns immediately if the channel is nonblocking; it starts -a background flush that will write the buffered data to the channel -eventually, as fast as the channel is able to absorb it. -.PP -The return value is normally \fBTCL_OK\fR. -If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and -records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. - -.SH TCL_SEEK -.PP -\fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent -data will be read or written. Buffered output is flushed to the channel and -buffered input is discarded, prior to the seek operation. -.PP -\fBTcl_Seek\fR normally returns the new access point. -If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error -code that can be retrieved with \fBTcl_GetErrno\fR. -After an error, the access point may or may not have been moved. - -.SH TCL_TELL -.PP -\fBTcl_Tell\fR returns the current access point for a channel. The returned -value is \-1 if the channel does not support seeking. - -.SH TCL_GETCHANNELOPTION -.PP -\fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of -the options currently in effect for a channel, or a list of all options and -their values. The \fIchannel\fR argument identifies the channel for which -to query an option or retrieve all options and their values. -If \fIoptionName\fR is not NULL, it is the name of the -option to query; the option's value is copied to the Tcl dynamic string -denoted by \fIoptionValue\fR. If -\fIoptionName\fR is NULL, the function stores an alternating list of option -names and their values in \fIoptionValue\fR, using a series of calls to -\fBTcl_DStringAppendElement\fR. The various preexisting options and -their possible values are described in the manual entry for the Tcl -\fBfconfigure\fR command. Other options can be added by each channel type. -These channel type specific options are described in the manual entry for -the Tcl command that creates a channel of that type; for example, the -additional options for TCP based channels are described in the manual entry -for the Tcl \fBsocket\fR command. -The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns -\fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX -error code. - -.SH TCL_SETCHANNELOPTION -.PP -\fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR. -\fIOptionName\fR is the option to set and \fInewValue\fR is the value to -set. -The procedure normally returns \fBTCL_OK\fR. If an error occurs, -it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL, -\fBTcl_SetChannelOption\fR leaves an error message in \fIinterp->result\fR. - -.SH TCL_EOF -.PP -\fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered -an end of file during the last input operation. - -.SH TCL_INPUTBLOCKED -.PP -\fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in -nonblocking mode and the last input operation returned less data than -requested because there was insufficient data available. -The call always returns zero if the channel is in blocking mode. - -.SH TCL_INPUTBUFFERED -.PP -\fBTcl_InputBuffered\fR returns the number of bytes of input currently -buffered in the internal buffers for a channel. If the channel is not open -for reading, this function always returns zero. - -.VS 8.0 -.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) - -.SH KEYWORDS -access point, blocking, buffered I/O, channel, channel driver, end of file, -flush, input, nonblocking, output, read, seek, write diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 deleted file mode 100644 index 6f5da00..0000000 --- a/doc/OpenTcp.3 +++ /dev/null @@ -1,179 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: OpenTcp.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -.so man.macros -.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_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets -.SH SYNOPSIS -.nf -\fB#include <tcl.h> \fR -.sp -Tcl_Channel -\fBTcl_OpenTcpClient\fR(\fIinterp, port, host, myaddr, myport, async\fR) -.sp -Tcl_Channel -\fBTcl_MakeTcpClientChannel\fR(\fIsock\fR) -.sp -Tcl_Channel -\fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR) -.sp -.SH ARGUMENTS -.AS Tcl_ChannelType newClientProcPtr in -.AP Tcl_Interp *interp in -Tcl interpreter to use for error reporting. If non-NULL and an -error occurs, an error message is left in \fIinterp->result\fR. -.AP int port in -A port number to connect to as a client or to listen on as a server. -.AP char *host in -A string specifying a host name or address for the remote end of the connection. -.AP int myport in -A port number for the client's end of the socket. If 0, a port number -is allocated at random. -.AP char *myaddr in -A string specifying the host name or address for network interface to use -for the local end of the connection. If NULL, a default interface is -chosen. -.AP int async in -If nonzero, the client socket is connected asynchronously to the server. -.AP ClientData sock in -Platform-specific handle for client TCP socket. -.AP Tcl_TcpAcceptProc *proc in -Pointer to a procedure to invoke each time a new connection is -accepted via the socket. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -These functions are convenience procedures for creating -channels that communicate over TCP sockets. -The operations on a channel -are described in the manual entry for \fBTcl_OpenFileChannel\fR. - -.SH TCL_OPENTCPCLIENT -.PP -\fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR -on a specific \fIhost\fR, and returns a channel that can be used to -communicate with the server. The host to connect to can be specified either -as a domain name style name (e.g. \fBwww.sunlabs.com\fR), or as a string -containing the alphanumeric representation of its four-byte address (e.g. -\fB127.0.0.1\fR). Use the string \fBlocalhost\fR to connect to a TCP socket on -the host on which the function is invoked. -.PP -The \fImyaddr\fR and \fImyport\fR arguments allow a client to specify an -address for the local end of the connection. If \fImyaddr\fR is NULL, then -an interface is chosen automatically by the operating system. -If \fImyport\fR is 0, then a port number is chosen at random by -the operating system. -.PP -If \fIasync\fR is zero, the call to \fBTcl_OpenTcpClient\fR returns only -after the client socket has either successfully connected to the server, or -the attempted connection has failed. -If \fIasync\fR is nonzero the socket is connected asynchronously and the -returned channel may not yet be connected to the server when the call to -\fBTcl_OpenTcpClient\fR returns. If the channel is in blocking mode and an -input or output operation is done on the channel before the connection is -completed or fails, that operation will wait until the connection either -completes successfully or fails. If the channel is in nonblocking mode, the -input or output operation will return immediately and a subsequent call to -\fBTcl_InputBlocked\fR on the channel will return nonzero. -.PP -The returned channel is opened for reading and writing. -If an error occurs in opening the socket, \fBTcl_OpenTcpClient\fR returns -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 -\fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified -\fIport\fR and uses the Tcl event mechanism to accept requests from clients -to connect to it. The \fImyaddr\fP argument specifies the network interface. -If \fImyaddr\fP is NULL the special address INADDR_ANY should be used to -allow connections from any network interface. -Each time a client connects to this socket, Tcl creates a channel -for the new connection and invokes \fIproc\fR with information about -the channel. \fIProc\fR must match the following prototype: -.CS -typedef void Tcl_TcpAcceptProc( - ClientData \fIclientData\fR, - Tcl_Channel \fIchannel\fR, - char *\fIhostName\fR, - int \fIport\fP); -.CE -.PP -The \fIclientData\fR argument will be the same as the \fIclientData\fR -argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle -for the new channel, \fIhostName\fR points to a string containing -the name of the client host making the connection, and \fIport\fP -will contain the client's port number. -The new channel -is opened for both input and output. -If \fIproc\fR raises an error, the connection is closed automatically. -\fIProc\fR has no return value, but if it wishes to reject the -connection it can close \fIchannel\fR. -.PP -\fBTcl_OpenTcpServer\fR normally returns a pointer to a channel -representing the server socket. -If an error occurs, \fBTcl_OpenTcpServer\fR returns NULL and -records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. -In addition, if \fIinterp->result\fR is non-NULL, an error message -is left in \fIinterp->result\fR. -.PP -The channel returned by \fBTcl_OpenTcpServer\fR cannot be used for -either input or output. -It is simply a handle for the socket used to accept connections. -The caller can close the channel to shut down the server and disallow -further connections from new clients. -.PP -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), Tcl_RegisterChannel(3), vwait(n) - -.SH KEYWORDS -client, server, TCP diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 deleted file mode 100644 index 2a180a6..0000000 --- a/doc/ParseCmd.3 +++ /dev/null @@ -1,426 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: ParseCmd.3,v 1.2 1999/04/16 00:46:32 stanton Exp $ -'\" -.so man.macros -.TH Tcl_ParseCommand 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_FreeParse, Tcl_EvalTokens \- parse Tcl scripts and expressions -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_ParseCommand\fR(\fIinterp, string, numBytes, nested, parsePtr\fR) -.sp -int -\fBTcl_ParseExpr\fR(\fIinterp, string, numBytes, parsePtr\fR) -.sp -int -\fBTcl_ParseBraces\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR) -.sp -int -\fBTcl_ParseQuotedString\fR(\fIinterp, string, numBytes, parsePtr, append, termPtr\fR) -.sp -int -\fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR) -.sp -\fBTcl_FreeParse\fR(\fIusedParsePtr\fR) -.sp -Tcl_Obj * -\fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR) -.SH ARGUMENTS -.AS Tcl_Interp *usedParsePtr -.AP Tcl_Interp *interp out -For procedures other than \fBTcl_FreeParse\fR and \fBTcl_EvalTokens\fR, -used only for error reporting; -if NULL, then no error messages are left after errors. -For \fBTcl_EvalTokens\fR, determines the context for evaluating the -script and also is used for error reporting; must not be NULL. -.AP char *string in -Pointer to first character in string to parse. -.AP int numBytes in -Number of bytes in \fIstring\fR, not including any terminating null -character. If less than 0 then the script consists of all characters -in \fIstring\fR up to the first null character. -.AP int nested in -Non-zero means that the script is part of a command substitution so an -unquoted close bracket should be treated as a command terminator. If zero, -close brackets have no special meaning. -.AP int append in -Non-zero means that \fI*parsePtr\fR already contains valid tokens; the new -tokens should be appended to those already present. Zero means that -\fI*parsePtr\fR is uninitialized; any information in it is ignored. -This argument is normally 0. -.AP Tcl_Parse *parsePtr out -Points to structure to fill in with information about the parsed -command, expression, variable name, etc. -Any previous information in this structure -is ignored, unless \fIappend\fR is non-zero in a call to -\fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, -or \fBTcl_ParseVarName\fR. -.AP char **termPtr out -If not NULL, points to a location where -\fBTcl_ParseBraces\fR and \fBTcl_ParseQuotedString\fR -will store a pointer to the character -just after the terminating close-brace or close-quote (respectively) -if the parse was successful. -.AP Tcl_Parse *usedParsePtr in -Points to structure that was filled in by a previous call to -\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseVarName\fR, etc. -.BE - -.SH DESCRIPTION -.PP -These procedures parse Tcl commands or portions of Tcl commands such as -expressions or references to variables. -Each procedure takes a pointer to a script (or portion thereof) -and fills in the structure pointed to by \fIparsePtr\fR -with a collection of tokens describing the information that was parsed. -The procedures normally return \fBTCL_OK\fR. -However, if an error occurs then they return \fBTCL_ERROR\fR, -leave an error message in \fIinterp's\fR result -(if \fIinterp\fR is not NULL), -and leave nothing in \fIparsePtr\fR. -.PP -\fBTcl_ParseCommand\fR is a procedure that parses Tcl -scripts. Given a pointer to a script, it -parses the first command from the script. If the command was parsed -successfully, \fBTcl_ParseCommand\fR returns \fBTCL_OK\fR and fills in the -structure pointed to by \fIparsePtr\fR with information about the -structure of the command (see below for details). -If an error occurred in parsing the command then -\fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's -result, and no information is left at \fI*parsePtr\fR. -.PP -\fBTcl_ParseExpr\fR parses Tcl expressions. -Given a pointer to a script containing an expression, -\fBTcl_ParseCommand\fR parses the expression. -If the expression was parsed successfully, -\fBTcl_ParseExpr\fR returns \fBTCL_OK\fR and fills in the -structure pointed to by \fIparsePtr\fR with information about the -structure of the expression (see below for details). -If an error occurred in parsing the command then -\fBTCL_ERROR\fR is returned, an error message is left in \fIinterp\fR's -result, and no information is left at \fI*parsePtr\fR. -.PP -\fBTcl_ParseBraces\fR parses a string or command argument -enclosed in braces such as -\fB{hello}\fR or \fB{string \\t with \\t tabs}\fR -from the beginning of its argument \fIstring\fR. -The first character of \fIstring\fR must be \fB{\fR. -If the braced string was parsed successfully, -\fBTcl_ParseBraces\fR returns \fBTCL_OK\fR, -fills in the structure pointed to by \fIparsePtr\fR -with information about the structure of the string -(see below for details), -and stores a pointer to the character just after the terminating \fB}\fR -in the location given by \fI*termPtr\fR. -If an error occurrs while parsing the string -then \fBTCL_ERROR\fR is returned, -an error message is left in \fIinterp\fR's result, -and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. -.PP -\fBTcl_ParseQuotedString\fR parses a double-quoted string such as -\fB"sum is [expr $a+$b]"\fR -from the beginning of the argument \fIstring\fR. -The first character of \fIstring\fR must be \fB"\fR. -If the double-quoted string was parsed successfully, -\fBTcl_ParseQuotedString\fR returns \fBTCL_OK\fR, -fills in the structure pointed to by \fIparsePtr\fR -with information about the structure of the string -(see below for details), -and stores a pointer to the character just after the terminating \fB"\fR -in the location given by \fI*termPtr\fR. -If an error occurrs while parsing the string -then \fBTCL_ERROR\fR is returned, -an error message is left in \fIinterp\fR's result, -and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. -.PP -\fBTcl_ParseVarName\fR parses a Tcl variable reference such as -\fB$abc\fR or \fB$x([expr $index + 1])\fR from the beginning of its -\fIstring\fR argument. -The first character of \fIstring\fR must be \fB$\fR. -If a variable name was parsed successfully, \fBTcl_ParseVarName\fR -returns \fBTCL_OK\fR and fills in the structure pointed to by -\fIparsePtr\fR with information about the structure of the variable name -(see below for details). If an error -occurrs while parsing the command then \fBTCL_ERROR\fR is returned, an -error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't -NULL), and no information is left at \fI*parsePtr\fR. -.PP -The information left at \fI*parsePtr\fR -by \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, -\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR -may include dynamically allocated memory. -If these five parsing procedures return \fBTCL_OK\fR -then the caller must invoke \fBTcl_FreeParse\fR to release -the storage at \fI*parsePtr\fR. -These procedures ignore any existing information in -\fI*parsePtr\fR (unless \fIappend\fR is non-zero), -so if repeated calls are being made to any of them -then \fBTcl_FreeParse\fR must be invoked once after each call. -.PP -\fBTcl_EvalTokens\fR evaluates a sequence of parse tokens from a Tcl_Parse -structure. The tokens typically consist -of all the tokens in a word or all the tokens that make up the index for -a reference to an array variable. \fBTcl_EvalTokens\fR performs the -substitutions requested by the tokens, concatenates the -resulting values, and returns the result in a new Tcl_Obj. The -reference count of the object returned as result has been -incremented, so the caller must -invoke \fBTcl_DecrRefCount\fR when it is finished with the object. -If an error occurs while evaluating the tokens (such as a reference to -a non-existent variable) then the return value is NULL and an error -message is left in \fIinterp\fR's result. - -.SH TCL_PARSE STRUCTURE -.PP -\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, -\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR -return parse information in two data structures, Tcl_Parse and Tcl_Token: -.CS -typedef struct Tcl_Parse { - char *\fIcommentStart\fR; - int \fIcommentSize\fR; - char *\fIcommandStart\fR; - int \fIcommandSize\fR; - int \fInumWords\fR; - Tcl_Token *\fItokenPtr\fR; - int \fInumTokens\fR; - ... -} Tcl_Parse; - -typedef struct Tcl_Token { - int \fItype\fR; - char *\fIstart\fR; - int \fIsize\fR; - int \fInumComponents\fR; -} Tcl_Token; -.CE -.PP -The first five fields of a Tcl_Parse structure -are filled in only by \fBTcl_ParseCommand\fR. -These fields are not used by the other parsing procedures. -.PP -\fBTcl_ParseCommand\fR fills in a Tcl_Parse structure -with information that describes one Tcl command and any comments that -precede the command. -If there are comments, -the \fIcommentStart\fR field points to the \fB#\fR character that begins -the first comment and \fIcommentSize\fR indicates the number of bytes -in all of the comments preceding the command, including the newline -character that terminates the last comment. -If the command is not preceded by any comments, \fIcommentSize\fR is 0. -\fBTcl_ParseCommand\fR also sets the \fIcommandStart\fR field -to point to the first character of the first -word in the command (skipping any comments and leading space) and -\fIcommandSize\fR gives the total number of bytes in the command, -including the character pointed to by \fIcommandStart\fR up to and -including the newline, close bracket, or semicolon character that -terminates the command. The \fInumWords\fR field gives the -total number of words in the command. -.PP -All parsing procedures set the remaining fields, -\fItokenPtr\fR and \fInumTokens\fR. -The \fItokenPtr\fR field points to the first in an array of Tcl_Token -structures that describe the components of the entity being parsed. -The \fInumTokens\fR field gives the total number of tokens -present in the array. -Each token contains four fields. -The \fItype\fR field selects one of several token types -that are described below. The \fIstart\fR field -points to the first character in the token and the \fIsize\fR field -gives the total number of characters in the token. Some token types, -such as \fBTCL_TOKEN_WORD\fR and \fBTCL_TOKEN_VARIABLE\fR, consist of -several component tokens, which immediately follow the parent token; -the \fInumComponents\fR field describes how many of these there are. -The \fItype\fR field has one of the following values: -.TP 20 -\fBTCL_TOKEN_WORD\fR -This token ordinarily describes one word of a command -but it may also describe a quoted or braced string in an expression. -The token describes a component of the script that is -the result of concatenating together a sequence of subcomponents, -each described by a separate subtoken. -The token starts with the first non-blank -character of the component (which may be a double-quote or open brace) -and includes all characters in the component up to but not including the -space, semicolon, close bracket, close quote, or close brace that -terminates the component. The \fInumComponents\fR field counts the total -number of sub-tokens that make up the word, including sub-tokens -of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens. -.TP -\fBTCL_TOKEN_SIMPLE_WORD\fR -This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that -the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR -sub-token. The \fInumComponents\fR field is always 1. -.TP -\fBTCL_TOKEN_TEXT\fR -The token describes a range of literal text that is part of a word. -The \fInumComponents\fR field is always 0. -.TP -\fBTCL_TOKEN_BS\fR -The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR. -The \fInumComponents\fR field is always 0. -.TP -\fBTCL_TOKEN_COMMAND\fR -The token describes a command whose result result must be substituted into -the word. The token includes the square brackets that surround the -command. The \fInumComponents\fR field is always 0 (the nested command -is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to -see its tokens). -.TP -\fBTCL_TOKEN_VARIABLE\fR -The token describes a variable substitution, including the -\fB$\fR, variable name, and array index (if there is one) up through the -close parenthesis that terminates the index. This token is followed -by one or more additional tokens that describe the variable name and -array index. If \fInumComponents\fR is 1 then the variable is a -scalar and the next token is a \fBTCL_TOKEN_TEXT\fR token that gives the -variable name. If \fInumComponents\fR is greater than 1 then the -variable is an array: the first sub-token is a \fBTCL_TOKEN_TEXT\fR -token giving the array name and the remaining sub-tokens are -\fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, and -\fBTCL_TOKEN_VARIABLE\fR tokens that must be concatenated to produce the -array index. The \fInumComponents\fR field includes nested sub-tokens -that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index. -.TP -\fBTCL_TOKEN_SUB_EXPR\fR -The token describes one subexpression of an expression -(or an entire expression). -A subexpression may consist of a value -such as an integer literal, variable substitution, -or parenthesized subexpression; -it may also consist of an operator and its operands. -The token starts with the first non-blank character of the subexpression -up to but not including the space, brace, close-paren, or bracket -that terminates the subexpression. -This token is followed by one or more additional tokens -that describe the subexpression. -If the first sub-token after the \fBTCL_TOKEN_SUB_EXPR\fR token -is a \fBTCL_TOKEN_OPERATOR\fR token, -the subexpression consists of an operator and its token operands. -If the operator has no operands, the subexpression consists of -just the \fBTCL_TOKEN_OPERATOR\fR token. -Each operand is described by a \fBTCL_TOKEN_SUB_EXPR\fR token. -Otherwise, the subexpression is a value described by -one of the token types \fBTCL_TOKEN_WORD\fR, \fBTCL_TOKEN_TEXT\fR, -\fBTCL_TOKEN_BS\fR, \fBTCL_TOKEN_COMMAND\fR, -\fBTCL_TOKEN_VARIABLE\fR, and \fBTCL_TOKEN_SUB_EXPR\fR. -The \fInumComponents\fR field -counts the total number of sub-tokens that make up the subexpression; -this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens. -.TP -\fBTCL_TOKEN_OPERATOR\fR -The token describes one operator of an expression -such as \fB&&\fR or \fBhypot\fR. -An \fBTCL_TOKEN_OPERATOR\fR token is always preceeded by a -\fBTCL_TOKEN_SUB_EXPR\fR token -that describes the operator and its operands; -the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field -can be used to determine the number of operands. -A binary operator such as \fB*\fR -is followed by two \fBTCL_TOKEN_SUB_EXPR\fR tokens -that describe its operands. -A unary operator like \fB-\fR -is followed by a single \fBTCL_TOKEN_SUB_EXPR\fR token -for its operand. -If the operator is a math function such as \fBlog10\fR, -the \fBTCL_TOKEN_OPERATOR\fR token will give its name and -the following \fBTCL_TOKEN_SUB_EXPR\fR tokens will describe -its operands; -if there are no operands (as with \fBrand\fR), -no \fBTCL_TOKEN_SUB_EXPR\fR tokens follow. -There is one trinary operator, \fB?\fR, -that appears in if-then-else subexpressions -such as \fIx\fB?\fIy\fB:\fIz\fR; -in this case, the \fB?\fR \fBTCL_TOKEN_OPERATOR\fR token -is followed by three \fBTCL_TOKEN_SUB_EXPR\fR tokens for the operands -\fIx\fR, \fIy\fR, and \fIz\fR. -The \fInumComponents\fR field for a \fBTCL_TOKEN_OPERATOR\fR token -is always 0. -.PP -After \fBTcl_ParseCommand\fR returns, the first token pointed to by -the \fItokenPtr\fR field of the -Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or -\fBTCL_TOKEN_SIMPLE_WORD\fR. It is followed by the sub-tokens -that must be concatenated to produce the value of that word. -The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR -token for the second word, followed by sub-tokens for that -word, and so on until all \fInumWords\fR have been accounted -for. -.PP -After \fBTcl_ParseExpr\fR returns, the first token pointed to by -the \fItokenPtr\fR field of the -Tcl_Parse structure always has type \fBTCL_TOKEN_SUB_EXPR\fR. -It is followed by the sub-tokens that must be evaluated -to produce the value of the expression. -Only the token information in the Tcl_Parse structure -is modified: the \fIcommentStart\fR, \fIcommentSize\fR, -\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified -by \fBTcl_ParseExpr\fR. -.PP -After \fBTcl_ParseBraces\fR returns, -the array of tokens pointed to by the \fItokenPtr\fR field of the -Tcl_Parse structure will contain a single \fBTCL_TOKEN_TEXT\fR token -if the braced string does not contain any backslash-newlines. -If the string does contain backslash-newlines, -the array of tokens will contain one or more -\fBTCL_TOKEN_TEXT\fR or \fBTCL_TOKEN_BS\fR sub-tokens -that must be concatenated to produce the value of the string. -If the braced string was just \fB{}\fR -(that is, the string was empty), -the single \fBTCL_TOKEN_TEXT\fR token will have a \fIsize\fR field -containing zero; -this ensures that at least one token appears -to describe the braced string. -Only the token information in the Tcl_Parse structure -is modified: the \fIcommentStart\fR, \fIcommentSize\fR, -\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified -by \fBTcl_ParseBraces\fR. -.PP -After \fBTcl_ParseQuotedString\fR returns, -the array of tokens pointed to by the \fItokenPtr\fR field of the -Tcl_Parse structure depends on the contents of the quoted string. -It will consist of one or more \fBTCL_TOKEN_TEXT\fR, \fBTCL_TOKEN_BS\fR, -\fBTCL_TOKEN_COMMAND\fR, and \fBTCL_TOKEN_VARIABLE\fR sub-tokens. -The array always contains at least one token; -for example, if the argument \fIstring\fR is empty, -the array returned consists of a single \fBTCL_TOKEN_TEXT\fR token -with a zero \fIsize\fR field. -Only the token information in the Tcl_Parse structure -is modified: the \fIcommentStart\fR, \fIcommentSize\fR, -\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified. -.PP -After \fBTcl_ParseVarName\fR returns, the first token pointed to by -the \fItokenPtr\fR field of the -Tcl_Parse structure always has type \fBTCL_TOKEN_VARIABLE\fR. It -is followed by the sub-tokens that make up the variable name as -described above. The total length of the variable name is -contained in the \fIsize\fR field of the first token. -As in \fBTcl_ParseExpr\fR, -only the token information in the Tcl_Parse structure -is modified by \fBTcl_ParseVarName\fR: -the \fIcommentStart\fR, \fIcommentSize\fR, -\fIcommandStart\fR, and \fIcommandSize\fR fields are not modified. -.PP -All of the character pointers in the -Tcl_Parse and Tcl_Token structures refer -to characters in the \fIstring\fR argument passed to -\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, -\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR. -.PP -There are additional fields in the Tcl_Parse structure after the -\fInumTokens\fR field, but these are for the private use of -\fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, -\fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be -referenced by code outside of these procedures. - -.SH KEYWORDS -backslash substitution, braces, command, expression, parse, token, variable substitution diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3 deleted file mode 100644 index 796ee6f..0000000 --- a/doc/PkgRequire.3 +++ /dev/null @@ -1,87 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: PkgRequire.3,v 1.3 1999/03/10 05:52:45 stanton Exp $ -'\" -.so man.macros -.TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -char * -\fBTcl_PkgRequire\fR(\fIinterp, name, version, exact\fR) -.sp -char * -\fBTcl_PkgRequireEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR) -.sp -char * -\fBTcl_PkgPresent\fR(\fIinterp, name, version, exact\fR) -.sp -char * -\fBTcl_PkgPresentEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR) -.sp -int -\fBTcl_PkgProvide\fR(\fIinterp, name, version\fR) -.sp -int -\fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR) -.SH ARGUMENTS -.AS Tcl_FreeProc clientDataPtr -.AP Tcl_Interp *interp in -Interpreter where package is needed or available. -.AP char *name in -Name of package. -.AP char *version in -A version string consisting of one or more decimal numbers -separated by dots. -.AP int exact in -Non-zero means that only the particular version specified by -\fIversion\fR is acceptable. -Zero means that newer versions than \fIversion\fR are also -acceptable as long as they have the same major version number -as \fIversion\fR. -.AP ClientData clientData in -Arbitrary value to be associated with the package. -.AP ClientData *clientDataPtr out -Pointer to place to store the value associated with the matching -package. It is only changed if the pointer is not NULL and the -function completed successfully. -.BE - -.SH DESCRIPTION -.PP -These procedures provide C-level interfaces to Tcl's package and -version management facilities. -.PP -\fBTcl_PkgRequire\fR is equivalent to the \fBpackage require\fR -command, \fBTcl_PkgPresent\fR is equivalent to the \fBpackage present\fR -command, and \fBTcl_PkgProvide\fR is equivalent to the -\fBpackage provide\fR command. -.PP -See the documentation for the Tcl commands for details on what these -procedures do. -.PP -If \fBTcl_PkgPresent\fR or \fBTcl_PkgRequire\fR complete successfully -they return a pointer to the version string for the version of the package -that is provided in the interpreter (which may be different than -\fIversion\fR); if an error occurs they return NULL and leave an error -message in \fIinterp->result\fR. -.PP -\fBTcl_PkgProvide\fR returns TCL_OK if it completes successfully; -if an error occurs it returns TCL_ERROR and leaves an error message -in \fIinterp->result\fR. -.PP -\fBTcl_PkgProvideEx\fR, \fBTcl_PkgPresentEx\fR and \fBTcl_PkgRequireEx\fR -allow the setting and retrieving of the client data associated with -the package. In all other respects they are equivalent to the matching -functions. - -.SH KEYWORDS -package, present, provide, require, version diff --git a/doc/Preserve.3 b/doc/Preserve.3 deleted file mode 100644 index 07c6476..0000000 --- a/doc/Preserve.3 +++ /dev/null @@ -1,103 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Preserve.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it's being used -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_Preserve\fR(\fIclientData\fR) -.sp -\fBTcl_Release\fR(\fIclientData\fR) -.sp -\fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR) -.SH ARGUMENTS -.AS Tcl_FreeProc clientData -.AP ClientData clientData in -Token describing structure to be freed or reallocated. Usually a pointer -to memory for structure. -.AP Tcl_FreeProc *freeProc in -Procedure to invoke to free \fIclientData\fR. -.BE - -.SH DESCRIPTION -.PP -These three procedures help implement a simple reference count mechanism -for managing storage. They are designed to solve a problem -having to do with widget deletion, but are also useful in many other -situations. When a widget is deleted, its -widget record (the structure holding information specific to the -widget) must be returned to the storage allocator. -However, it's possible that the widget record is in active use -by one of the procedures on the stack at the time of the deletion. -This can happen, for example, if the command associated with a button -widget causes the button to be destroyed: an X event causes an -event-handling C procedure in the button to be invoked, which in -turn causes the button's associated Tcl command to be executed, -which in turn causes the button to be deleted, which in turn causes -the button's widget record to be de-allocated. -Unfortunately, when the Tcl command returns, the button's -event-handling procedure will need to reference the -button's widget record. -Because of this, the widget record must not be freed as part of the -deletion, but must be retained until the event-handling procedure has -finished with it. -In other situations where the widget is deleted, it may be possible -to free the widget record immediately. -.PP -\fBTcl_Preserve\fR and \fBTcl_Release\fR -implement short-term reference counts for their \fIclientData\fR -argument. -The \fIclientData\fR argument identifies an object and usually -consists of the address of a structure. -The reference counts guarantee that an object will not be freed -until each call to \fBTcl_Preserve\fR for the object has been -matched by calls to \fBTcl_Release\fR. -There may be any number of unmatched \fBTcl_Preserve\fR calls -in effect at once. -.PP -\fBTcl_EventuallyFree\fR is invoked to free up its \fIclientData\fR -argument. -It checks to see if there are unmatched \fBTcl_Preserve\fR calls -for the object. -If not, then \fBTcl_EventuallyFree\fR calls \fIfreeProc\fR immediately. -Otherwise \fBTcl_EventuallyFree\fR records the fact that \fIclientData\fR -needs eventually to be freed. -When all calls to \fBTcl_Preserve\fR have been matched with -calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by -\fBTcl_Release\fR to do the cleanup. -.PP -All the work of freeing the object is carried out by \fIfreeProc\fR. -\fIFreeProc\fR must have arguments and result that match the -type \fBTcl_FreeProc\fR: -.CS -typedef void Tcl_FreeProc(char *\fIblockPtr\fR); -.CE -The \fIblockPtr\fR argument to \fIfreeProc\fR will be the -same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR. -The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the -\fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical -reasons, but the value is the same. -.PP -This mechanism can be used to solve the problem described above -by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around -actions that may cause undesired storage re-allocation. The -mechanism is intended only for short-term use (i.e. while procedures -are pending on the stack); it will not work efficiently as a -mechanism for long-term reference counts. -The implementation does not depend in any way on the internal -structure of the objects being freed; it keeps the reference -counts in a separate structure. - -.SH KEYWORDS -free, reference count, storage diff --git a/doc/PrintDbl.3 b/doc/PrintDbl.3 deleted file mode 100644 index 81af506..0000000 --- a/doc/PrintDbl.3 +++ /dev/null @@ -1,47 +0,0 @@ -'\" -'\" Copyright (c) 1989-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. -'\" -'\" RCS: @(#) $Id: PrintDbl.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros -.TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_PrintDouble \- Convert floating value to string -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_PrintDouble\fR(\fIinterp, value, dst\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -.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 -the conversion is controlled by the \fBtcl_precision\fR variable -that is now shared by all interpreters. -.VE -.AP double value in -Floating-point value to be converted. -.AP char *dst out -Where to store string representing \fIvalue\fR. Must have at -least TCL_DOUBLE_SPACE characters of storage. -.BE - -.SH DESCRIPTION -.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 \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/doc/RecEvalObj.3 b/doc/RecEvalObj.3 deleted file mode 100644 index 6af989f..0000000 --- a/doc/RecEvalObj.3 +++ /dev/null @@ -1,55 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: RecEvalObj.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros -.TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_RecordAndEvalObj \- save command on history list before evaluating -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_RecordAndEvalObj\fR(\fIinterp, cmdPtr, flags\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp; -.AP Tcl_Interp *interp in -Tcl interpreter in which to evaluate command. -.AP Tcl_Obj *cmdPtr in -Points to a Tcl object containing a command (or sequence of commands) -to execute. -.AP int flags in -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. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event -on the history list and then execute it using \fBTcl_EvalObj\fR -(or \fBTcl_GlobalEvalObj\fR if the TCL_EVAL_GLOBAL bit is set -in \fIflags\fR). -It returns a completion code such as TCL_OK just like \fBTcl_EvalObj\fR, -as well as a result object containing additional information -(a result value or error message) -that can be retrieved using \fBTcl_GetObjResult\fR. -If you don't want the command recorded on the history list then -you should invoke \fBTcl_EvalObj\fR instead of \fBTcl_RecordAndEvalObj\fR. -Normally \fBTcl_RecordAndEvalObj\fR is only called with top-level -commands typed by the user, since the purpose of history is to -allow the user to re-issue recently-invoked commands. -If the \fIflags\fR argument contains the TCL_NO_EVAL bit then -the command is recorded without being evaluated. - -.SH "SEE ALSO" -Tcl_EvalObj, Tcl_GetObjResult - -.SH KEYWORDS -command, event, execute, history, interpreter, object, record diff --git a/doc/RecordEval.3 b/doc/RecordEval.3 deleted file mode 100644 index 090a56d..0000000 --- a/doc/RecordEval.3 +++ /dev/null @@ -1,57 +0,0 @@ -'\" -'\" Copyright (c) 1989-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. -'\" -'\" RCS: @(#) $Id: RecordEval.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ -'\" -.so man.macros -.TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_RecordAndEval \- save command on history list before evaluating -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_RecordAndEval\fR(\fIinterp, cmd, flags\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp; -.AP Tcl_Interp *interp in -Tcl interpreter in which to evaluate command. -.AP char *cmd in -Command (or sequence of commands) to execute. -.AP int flags in -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. -.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 -(or \fBTcl_GlobalEval\fR if the TCL_EVAL_GLOBAL bit is set in \fIflags\fR). -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 -you should invoke \fBTcl_Eval\fR instead of \fBTcl_RecordAndEval\fR. -Normally \fBTcl_RecordAndEval\fR is only called with top-level -commands typed by the user, since the purpose of history is to -allow the user to re-issue recently-invoked commands. -If the \fIflags\fR argument contains the TCL_NO_EVAL bit then -the command is recorded without being evaluated. -.PP -Note that \fBTcl_RecordAndEval\fR has been largely replaced by the -object-based procedure \fBTcl_RecordAndEvalObj\fR. -That object-based procedure records and optionally executes -a command held in a Tcl object instead of a string. - -.SH "SEE ALSO" -Tcl_RecordAndEvalObj - -.SH KEYWORDS -command, event, execute, history, interpreter, record diff --git a/doc/RegExp.3 b/doc/RegExp.3 deleted file mode 100644 index 1f1064d..0000000 --- a/doc/RegExp.3 +++ /dev/null @@ -1,131 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998-1999 Scriptics Corportation -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: RegExp.3,v 1.3 1999/04/16 00:46:32 stanton Exp $ -'\" -.so man.macros -.TH Tcl_RegExpMatch 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetRegExpFromObj, Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern matching with regular expressions -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_RegExp -\fBTcl_GetRegExpFromObj\fR(\fIinterp\fR, \fIpatObj\fR, \fIflags\fR) -.sp -int -\fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR) -.sp -Tcl_RegExp -\fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR) -.sp -int -\fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR) -.sp -\fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Tcl interpreter to use for error reporting. -.AP char *string in -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_Obj *patObj in -Refers to the object from which to get a compiled regular expression. -.AP int flags in -Various flags to control regular expression compile options. -.AP Tcl_RegExp regexp in -Compiled regular expression. Must have been returned previously -by \fBTcl_GetRegExpFromObj\fR. -.AP char *start in -If \fIstring\fR is just a portion of some other string, this argument -identifies the beginning of the larger string. -If it isn't the same as \fIstring\fR, then no \fB^\fR matches -will be allowed. -.AP int index in -Specifies which range is desired: 0 means the range of the entire -match, 1 or greater means the range that matched a parenthesized -sub-expression. -.AP char **startPtr out -The address of the first character in the range is stored here, or -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. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_GetRegExpFromObj\fR attepts to return a compiled regular -expression from the Tcl obj \fIpatObj\fR. If the object does not -already contain a compiled regular expression it will attempt to -create one from the string in the Tcl obj and assign it to the -internal representation of the \fIpatObj\fR. The return value -of this function is of type \fBTcl_RegExp\fR. -.PP -\fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument -matches \fIregexp\fR, where \fIregexp\fR is interpreted -as a regular expression using the same rules as for the -\fBregexp\fR Tcl command. -If there is a match then \fBTcl_RegExpMatch\fR returns 1. -If there is no match then \fBTcl_RegExpMatch\fR returns 0. -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 -\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 -the internal form used for efficient pattern matching. -The return value is a token for this compiled form, which can be -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. -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. -.PP -\fBTcl_RegExpExec\fR executes the regular expression pattern matcher. -It returns 1 if \fIstring\fR contains a range of characters that -match \fIregexp\fR, 0 if no match is found, and -\-1 if an error occurs. -In the case of an error, \fBTcl_RegExpExec\fR leaves an error -message in \fIinterp->result\fR. -When searching a string for multiple matches of a pattern, -it is important to distinguish between the start of the original -string and the start of the current search. -For example, when searching for the second occurrence of a -match, the \fIstring\fR argument might point to the character -just after the first match; however, it is important for the -pattern matcher to know that this is not the start of the entire string, -so that it doesn't allow \fB^\fR atoms in the pattern to match. -The \fIstart\fR argument provides this information by pointing -to the start of the overall string containing \fIstring\fR. -\fIStart\fR will be less than or equal to \fIstring\fR; if it -is less than \fIstring\fR then no \fB^\fR matches will be allowed. -.PP -\fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR -returns; it provides detailed information about what ranges of -the string matched what parts of the pattern. -\fBTcl_RegExpRange\fR returns a pair of pointers in \fI*startPtr\fR -and \fI*endPtr\fR that identify a range of characters in -the source string for the most recent call to \fBTcl_RegExpExec\fR. -\fIIndex\fR indicates which of several ranges is desired: -if \fIindex\fR is 0, information is returned about the overall range -of characters that matched the entire pattern; otherwise, -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. - -.SH KEYWORDS -match, pattern, regular expression, string, subexpression diff --git a/doc/SaveResult.3 b/doc/SaveResult.3 deleted file mode 100644 index 6a0a051..0000000 --- a/doc/SaveResult.3 +++ /dev/null @@ -1,65 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: SaveResult.3,v 1.2 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's result -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_SaveResult(\fIinterp, statePtr\fB)\fR -.sp -\fBTcl_RestoreResult(\fIinterp, statePtr\fB)\fR -.sp -\fBTcl_DiscardResult(\fIstatePtr\fB)\fR -.SH ARGUMENTS -.AS Tcl_SavedResult statePtr -.AP Tcl_Interp *interp in -Interpreter for which state should be saved. -.AP Tcl_SavedResult *statePtr in -Pointer to location where interpreter result should be saved or restored. -.BE - -.SH DESCRIPTION -.PP -These routines allows a C procedure to take a snapshot of the current -interpreter result so that it can be restored after a call -to \fBTcl_Eval\fR or some other routine that modifies the interpreter -result. These routines are passed a pointer to a structure that is -used to store enough information to restore the interpreter result -state. This structure can be allocated on the stack of the calling -procedure. These routines do not save the state of any error -information in the interpreter (e.g. the \fBerrorCode\fR or -\fBerrorInfo\fR variables). -.PP -\fBTcl_SaveResult\fR moves the string and object results -of \fIinterp\fR into the location specified by \fIstatePtr\fR. -\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and -leaves the result in its normal empty initialized state. -.PP -\fBTcl_RestoreResult\fR moves the string and object results from -\fIstatePtr\fR back into \fIinterp\fR. Any result or error that was -already in the interpreter will be cleared. The \fIstatePtr\fR is left -in an uninitialized state and cannot be used until another call to -\fBTcl_SaveResult\fR. -.PP -\fBTcl_DiscardResult\fR releases the saved interpreter state -stored at \fBstatePtr\fR. The state structure is left in an -uninitialized state and cannot be used until another call to -\fBTcl_SaveResult\fR. -.PP -Once \fBTcl_SaveResult\fR is called to save the interpreter -result, either \fBTcl_RestoreResult\fR or -\fBTcl_DiscardResult\fR must be called to properly clean up the -memory associated with the saved state. - -.SH KEYWORDS -result, state, interp diff --git a/doc/SetErrno.3 b/doc/SetErrno.3 deleted file mode 100644 index d57263b..0000000 --- a/doc/SetErrno.3 +++ /dev/null @@ -1,48 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: SetErrno.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ -.so man.macros -.TH Tcl_SetErrno 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_SetErrno, Tcl_GetErrno \- manipulate errno to store and retrieve error codes -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -void -\fBTcl_SetErrno\fR(\fIerrorCode\fR) -.sp -int -\fBTcl_GetErrno\fR() -.sp -.SH ARGUMENTS -.AS Tcl_Interp *errorCode in -.AP int errorCode in -A POSIX error code such as \fBENOENT\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_SetErrno\fR and \fBTcl_GetErrno\fR provide portable access -to the \fBerrno\fR variable, which is used to record a POSIX error -code after system calls and other operations such as \fBTcl_Gets\fR. -These procedures are necessary because global variable accesses cannot -be made across module boundaries on some platforms. -.PP -\fBTcl_SetErrno\fR sets the \fBerrno\fR variable to the value of the -\fIerrorCode\fR argument -C procedures that wish to return error information to their callers -via \fBerrno\fR should call \fBTcl_SetErrno\fR rather than setting -\fBerrno\fR directly. -.PP -\fBTcl_GetErrno\fR returns the current value of \fBerrno\fR. -Procedures wishing to access \fBerrno\fR should call this procedure -instead of accessing \fBerrno\fR directly. - -.SH KEYWORDS -errno, error code, global variables diff --git a/doc/SetRecLmt.3 b/doc/SetRecLmt.3 deleted file mode 100644 index 599e46f..0000000 --- a/doc/SetRecLmt.3 +++ /dev/null @@ -1,55 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: SetRecLmt.3,v 1.3 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl_SetRecursionLimit 3 7.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_SetRecursionLimit \- set maximum allowable nesting depth in interpreter -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_SetRecursionLimit\fR(\fIinterp, depth\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Interpreter whose recursion limit is to be set. -Must be greater than zero. -.AP int depth in -New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR. -.BE - -.SH DESCRIPTION -.PP -At any given time Tcl enforces a limit on the number of recursive -calls that may be active for \fBTcl_Eval\fR and related procedures -such as \fBTcl_GlobalEval\fR. -Any call to \fBTcl_Eval\fR that exceeds this depth is aborted with -an error. -By default the recursion limit is 1000. -.PP -\fBTcl_SetRecursionLimit\fR may be used to change the maximum -allowable nesting depth for an interpreter. -The \fIdepth\fR argument specifies a new limit for \fIinterp\fR, -and \fBTcl_SetRecursionLimit\fR returns the old limit. -To read out the old limit without modifying it, invoke -\fBTcl_SetRecursionLimit\fR with \fIdepth\fR equal to 0. -.PP -The \fBTcl_SetRecursionLimit\fR only sets the size of the Tcl -call stack: it cannot by itself prevent stack overflows on the -C stack being used by the application. If your machine has a -limit on the size of the C stack, you may get stack overflows -before reaching the limit set by \fBTcl_SetRecursionLimit\fR. -If this happens, see if there is a mechanism in your system for -increasing the maximum size of the C stack. - -.SH KEYWORDS -nesting depth, recursion diff --git a/doc/SetResult.3 b/doc/SetResult.3 deleted file mode 100644 index 1fed065..0000000 --- a/doc/SetResult.3 +++ /dev/null @@ -1,225 +0,0 @@ -'\" -'\" Copyright (c) 1989-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. -'\" -'\" RCS: @(#) $Id: SetResult.3,v 1.3 1999/03/10 05:52:45 stanton Exp $ -'\" -.so man.macros -.TH Tcl_SetResult 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, 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 -char * -\fBTcl_GetStringResult\fR(\fIinterp\fR) -.sp -\fBTcl_AppendResult\fR(\fIinterp, string, string, ... , \fB(char *) NULL\fR) -.sp -\fBTcl_AppendResultVA\fR(\fIinterp, argList\fR) -.sp -\fBTcl_AppendElement\fR(\fIinterp, string\fR) -.sp -\fBTcl_ResetResult\fR(\fIinterp\fR) -.sp -\fBTcl_FreeResult\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_FreeProc freeProc -.AP Tcl_Interp *interp out -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 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 -\fBTCL_VOLATILE\fR. -.AP va_list argList in -An argument list which must have been initialised using -\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. -.BE - -.SH DESCRIPTION -.PP -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_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 -\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 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 -\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 -to the current result associated with \fIinterp\fR. -If the result is in its initialized empty state (e.g. a command procedure -was just invoked or \fBTcl_ResetResult\fR was just called), -then \fBTcl_AppendResult\fR sets the result to the concatenation of -its \fIstring\fR arguments. -\fBTcl_AppendResult\fR may be called repeatedly as additional pieces -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. -.PP -\fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that -instead of taking a variable number of arguments it takes an argument list. -.PP -\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in -that it allows results to be built up in pieces. -However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR -argument and it appends that argument to the current result -as a proper Tcl list element. -\fBTcl_AppendElement\fR adds backslashes or braces if necessary -to ensure that \fIinterp\fR's result can be parsed as a list and that -\fIstring\fR will be extracted as a single element. -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. -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. -.PP -\fBTcl_FreeResult\fR performs part of the work -of \fBTcl_ResetResult\fR. -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_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp - -.SH KEYWORDS -append, command, element, list, object, result, return value, interpreter diff --git a/doc/SetVar.3 b/doc/SetVar.3 deleted file mode 100644 index bb07005..0000000 --- a/doc/SetVar.3 +++ /dev/null @@ -1,261 +0,0 @@ -'\" -'\" Copyright (c) 1989-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. -'\" -'\" RCS: @(#) $Id: SetVar.3,v 1.3 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -.VS 8.1 -Tcl_Obj * -\fBTcl_SetVar2Ex\fR(\fIinterp, name1, name2, newValuePtr, flags\fR) -.VE -.sp -char * -\fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR) -.sp -char * -\fBTcl_SetVar2\fR(\fIinterp, name1, name2, newValue, flags\fR) -.sp -Tcl_Obj * -\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR) -.sp -.VS 8.1 -Tcl_Obj * -\fBTcl_GetVar2Ex\fR(\fIinterp, name1, name2, flags\fR) -.VE -.sp -char * -\fBTcl_GetVar\fR(\fIinterp, varName, flags\fR) -.sp -char * -\fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR) -.sp -Tcl_Obj * -\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR) -.sp -int -\fBTcl_UnsetVar\fR(\fIinterp, varName, flags\fR) -.sp -int -\fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR) -.SH ARGUMENTS -.AS Tcl_Interp *newValuePtr -.AP Tcl_Interp *interp in -Interpreter containing variable. -.AP char *name1 in -Contains the name of an array variable (if \fIname2\fR is non-NULL) -or (if \fIname2\fR is NULL) either the name of a scalar variable -or a complete name including both variable name and index. -May include \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; in this -case \fIname1\fR must refer to an array variable. -.AP Tcl_Obj *newValuePtr in -.VS 8.1 -Points to a Tcl object containing the new value for the variable. -.VE -.AP int flags in -OR-ed combination of bits providing additional information. See below -for valid values. -.AP char *varName in -Name of variable. -May include \fB::\fR namespace qualifiers -to specify a variable in a particular namespace. -May refer to a scalar variable or an element of -an array. -If the name references an element of an array, then the name -must be in writable memory: Tcl will make temporary modifications -to it while looking up the name. -.AP char *newValue in -New value for variable, specified as a NULL-terminated string. -A copy of this value is stored in the 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. -.BE - -.SH DESCRIPTION -.PP -These procedures are used to create, modify, read, and delete -Tcl variables from C code. -.PP -.VS 8.1 -\fBTcl_SetVar2Ex\fR, \fBTcl_SetVar\fR, \fBTcl_SetVar2\fR, and -\fBTcl_ObjSetVar2\fR -will create a new variable or modify an existing one. -These procedures set the given variable to the value -given by \fInewValuePtr\fR or \fInewValue\fR and return a -pointer to the variable's new value, which is stored in Tcl's -variable structure. -\fBTcl_SetVar2Ex\fR and \fBTcl_ObjSetVar2\fR take the new value as a -Tcl_Obj and return -a pointer to a Tcl_Obj. \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR -take the new value as a string and return a string; they are -usually less efficient than \fBTcl_ObjSetVar2\fR. Note that the -return value may be different than the \fInewValuePtr\fR or -.VE -\fInewValue\fR argument, due to modifications made by write traces. -If an error occurs in setting the variable (e.g. an array -variable is referenced without giving an index into the array) -NULL is returned and an error message is left in \fIinterp\fR's -result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR bit is set. -.PP -.VS 8.1 -\fBTcl_GetVar2Ex\fR, \fBTcl_GetVar\fR, \fBTcl_GetVar2\fR, and -\fBTcl_ObjGetVar2\fR -return the current value of a variable. -The arguments to these procedures are treated in the same way -as the arguments to the procedures described above. -Under normal circumstances, the return value is a pointer -to the variable's value. For \fBTcl_GetVar2Ex\fR and -\fBTcl_ObjGetVar2\fR the value is -returned as a pointer to a Tcl_Obj. For \fBTcl_GetVar\fR and -\fBTcl_GetVar2\fR the value is returned as a string; this is -usually less efficient, so \fBTcl_GetVar2Ex\fR or \fBTcl_ObjGetVar2\fR -are preferred. -.VE -If an error occurs while reading the variable (e.g. the variable -doesn't exist or an array element is specified for a scalar -variable), then NULL is returned and an error message is left -in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR -bit is set. -.PP -\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove -a variable, so that future attempts to read the variable will return -an error. -The arguments to these procedures are treated in the same way -as the arguments to the procedures above. -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 and an error message is left -in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR -bit is set. -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. -.PP -The name of a variable may be specified to these procedures in -four ways: -.IP [1] -If \fBTcl_SetVar\fR, \fBTcl_GetVar\fR, or \fBTcl_UnsetVar\fR -is invoked, the variable name is given as -a single string, \fIvarName\fR. -If \fIvarName\fR contains an open parenthesis and ends with a -close parenthesis, then the value between the parentheses is -treated as an index (which can have any string value) and -the characters before the first open -parenthesis are treated as the name of an array variable. -If \fIvarName\fR doesn't have parentheses as described above, then -the entire string is treated as the name of a scalar variable. -.IP [2] -If the \fIname1\fR and \fIname2\fR arguments are provided and -\fIname2\fR is non-NULL, then an array element is specified and -the array name and index have -already been separated by the caller: \fIname1\fR contains the -name and \fIname2\fR contains the index. -.VS 8.1 -An error is generated -if \fIname1\fR contains an open parenthesis and ends with a -close parenthesis (array element) and \fIname2\fR is non-NULL. -.IP [3] -If \fIname2\fR is NULL, \fIname1\fR is treated just like -\fIvarName\fR in case [1] above (it can be either a scalar or an array -element variable name). -.VE -.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 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, -the variable is looked up at the current level of procedure call. -Otherwise, the 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 -If this bit is set in \fIflags\fR then the variable -is looked up only in the current namespace; if a procedure is active -its variables are ignored, and the global namespace is also ignored unless -it is the current namespace. -.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 or \fInewValue\fR is -appended to the current value instead of replacing it. -If the variable is currently undefined, then the bit is ignored. -This bit is only used by the \fBTcl_Set*\fR procedures. -.TP -\fBTCL_LIST_ELEMENT\fR -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 -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 `` }''). -.PP -\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 -to the variable's value (which is stored in Tcl's variable -structure and will not change before the next call to \fBTcl_SetVar\fR -or \fBTcl_SetVar2\fR). -\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR use the flag bits TCL_GLOBAL_ONLY -and TCL_LEAVE_ERR_MSG, both of -which have -the same meaning as for \fBTcl_SetVar\fR. -If an error occurs in reading the variable (e.g. the variable -doesn't exist or an array element is specified for a scalar -variable), then NULL is returned. -.PP -\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove -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. -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. -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_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar - -.SH KEYWORDS -array, get variable, interpreter, object, scalar, set, unset, variable diff --git a/doc/Sleep.3 b/doc/Sleep.3 deleted file mode 100644 index fcfed9b..0000000 --- a/doc/Sleep.3 +++ /dev/null @@ -1,37 +0,0 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Sleep.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Sleep \- delay execution for a given number of milliseconds -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_Sleep\fR(\fIms\fR) -.SH ARGUMENTS -.AP int ms in -Number of milliseconds to sleep. -.BE - -.SH DESCRIPTION -.PP -This procedure delays the calling process by the number of -milliseconds given by the \fIms\fR parameter and returns -after that time has elapsed. It is typically used for things -like flashing a button, where the delay is short and the -application needn't do anything while it waits. For longer -delays where the application needs to respond to other events -during the delay, the procedure \fBTcl_CreateTimerHandler\fR -should be used instead of \fBTcl_Sleep\fR. - -.SH KEYWORDS -sleep, time, wait diff --git a/doc/SplitList.3 b/doc/SplitList.3 deleted file mode 100644 index e30771c..0000000 --- a/doc/SplitList.3 +++ /dev/null @@ -1,191 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: SplitList.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ -'\" -.so man.macros -.TH Tcl_SplitList 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement \- manipulate Tcl lists -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR) -.sp -char * -\fBTcl_Merge\fR(\fIargc, argv\fR) -.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 -.VS -Interpreter to use for error reporting. If NULL, then no error message -is left. -.VE -.AP char *list in -Pointer to a string with proper list structure. -.AP int *argcPtr out -Filled in with number of elements in \fIlist\fR. -.AP char ***argvPtr out -\fI*argvPtr\fR will be filled in with the address of an array of -pointers to the strings that are the extracted elements of \fIlist\fR. -There will be \fI*argcPtr\fR valid entries in the array, followed by -a NULL entry. -.AP int argc in -Number of elements in \fIargv\fR. -.AP char **argv in -Array of strings to merge together into a single list. -Each string will become a separate element of the list. -.AP char *src in -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. -.AP int flags in -Information about \fIsrc\fR. Must be value returned by previous -call to \fBTcl_ScanElement\fR, possibly OR-ed -with \fBTCL_DONT_USE_BRACES\fR. -.BE - -.SH DESCRIPTION -.PP -These procedures may be used to disassemble and reassemble Tcl lists. -\fBTcl_SplitList\fR breaks a list up into its constituent elements, -returning an array of pointers to the elements using -\fIargcPtr\fR and \fIargvPtr\fR. -While extracting the arguments, \fBTcl_SplitList\fR obeys the usual -rules for backslash substitutions and braces. The area of -memory pointed to by \fI*argvPtr\fR is dynamically allocated; in -addition to the array of pointers, it -also holds copies of all the list elements. It is the caller's -responsibility to free up all of this storage. -For example, suppose that you have called \fBTcl_SplitList\fR with -the following code: -.CS -int argc, code; -char *string; -char **argv; -\&... -code = Tcl_SplitList(interp, string, &argc, &argv); -.CE -Then you should eventually free the storage with a call like the -following: -.VS -.CS -Tcl_Free((char *) argv); -.CE -.VE -.PP -\fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was -successfully parsed. -If there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned -and \fIinterp->result\fR will point to an error message describing the -.VS -problem (if \fIinterp\fR was not NULL). -.VE -If \fBTCL_ERROR\fR is returned then no memory is allocated and \fI*argvPtr\fR -is not modified. -.PP -\fBTcl_Merge\fR is the inverse of \fBTcl_SplitList\fR: it -takes a collection of strings given by \fIargc\fR -and \fIargv\fR and generates a result string -that has proper list structure. -This means that commands like \fBindex\fR may be used to -extract the original elements again. -In addition, if the result of \fBTcl_Merge\fR is passed to \fBTcl_Eval\fR, -it will be parsed into \fIargc\fR words whose values will -be the same as the \fIargv\fR strings passed to \fBTcl_Merge\fR. -\fBTcl_Merge\fR will modify the list elements with braces and/or -backslashes in order to produce proper Tcl list structure. -.VS -The result string is dynamically allocated -using \fBTcl_Alloc\fR; the caller must eventually release the space -using \fBTcl_Free\fR. -.VE -.PP -If the result of \fBTcl_Merge\fR is passed to \fBTcl_SplitList\fR, -the elements returned by \fBTcl_SplitList\fR will be identical to -those passed into \fBTcl_Merge\fR. -However, the converse is not true: if \fBTcl_SplitList\fR -is passed a given string, and the resulting \fIargc\fR and -\fIargv\fR are passed to \fBTcl_Merge\fR, the resulting string -may not be the same as the original string passed to \fBTcl_SplitList\fR. -This is because \fBTcl_Merge\fR may use backslashes and braces -differently than the original string. -.PP -\fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR are the -procedures that do all of the real work of \fBTcl_Merge\fR. -\fBTcl_ScanElement\fR scans its \fIsrc\fR argument -and determines how to use backslashes and braces -when converting it to a list element. -It returns an overestimate of the number of characters -required to represent \fIsrc\fR as a list element, and -it stores information in \fI*flagsPtr\fR that is needed -by \fBTcl_ConvertElement\fR. -.PP -\fBTcl_ConvertElement\fR is a companion procedure to \fBTcl_ScanElement\fR. -It does the actual work of converting a string to a list element. -Its \fIflags\fR argument must be the same as the value returned -by \fBTcl_ScanElement\fR. -\fBTcl_ConvertElement\fR writes a proper list element to memory -starting at *\fIdst\fR and returns a count of the total number -of characters written, which will be no more than the result -returned by \fBTcl_ScanElement\fR. -\fBTcl_ConvertElement\fR writes out only the actual list element -without any leading or trailing spaces: it is up to the caller to -include spaces between adjacent list elements. -.PP -\fBTcl_ConvertElement\fR uses one of two different approaches to -handle the special characters in \fIsrc\fR. Wherever possible, it -handles special characters by surrounding the string with braces. -This produces clean-looking output, but can't be used in some situations, -such as when \fIsrc\fR contains unmatched braces. -In these situations, \fBTcl_ConvertElement\fR handles special -characters by generating backslash sequences for them. -The caller may insist on the second approach by OR-ing the -flag value returned by \fBTcl_ScanElement\fR with -\fBTCL_DONT_USE_BRACES\fR. -Although this will produce an uglier result, it is useful in some -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/doc/SplitPath.3 b/doc/SplitPath.3 deleted file mode 100644 index b112b82..0000000 --- a/doc/SplitPath.3 +++ /dev/null @@ -1,93 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: SplitPath.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ -'\" -.so man.macros -.TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType \- manipulate platform-dependent file paths -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_SplitPath\fR(\fIpath, argcPtr, argvPtr\fR) -.sp -char * -\fBTcl_JoinPath\fR(\fIargc, argv, resultPtr\fR) -.sp -Tcl_PathType -\fBTcl_GetPathType\fR(\fIpath\fR) -.SH ARGUMENTS -.AS Tcl_DString ***argvPtr -.AP char *path in -File path in a form appropriate for the current platform (see the -\fBfilename\fR manual entry for acceptable forms for path names). -.AP int *argcPtr out -Filled in with number of path elements in \fIpath\fR. -.AP char ***argvPtr out -\fI*argvPtr\fR will be filled in with the address of an array of -pointers to the strings that are the extracted elements of \fIpath\fR. -There will be \fI*argcPtr\fR valid entries in the array, followed by -a NULL entry. -.AP int argc in -Number of elements in \fIargv\fR. -.AP char **argv in -Array of path elements to merge together into a single path. -.AP Tcl_DString *resultPtr in/out -A pointer to an initialized \fBTcl_DString\fR to which the result of -\fBTcl_JoinPath\fR will be appended. -.BE - -.SH DESCRIPTION -.PP -These procedures may be used to disassemble and reassemble file -paths in a platform independent manner: they provide C-level access to -the same functionality as the \fBfile split\fR, \fBfile join\fR, and -\fBfile pathtype\fR commands. -.PP -\fBTcl_SplitPath\fR breaks a path into its constituent elements, -returning an array of pointers to the elements using \fIargcPtr\fR and -\fIargvPtr\fR. The area of memory pointed to by \fI*argvPtr\fR is -dynamically allocated; in addition to the array of pointers, it also -holds copies of all the path elements. It is the caller's -responsibility to free all of this storage. -For example, suppose that you have called \fBTcl_SplitPath\fR with the -following code: -.CS -int argc; -char *path; -char **argv; -\&... -Tcl_SplitPath(string, &argc, &argv); -.CE -Then you should eventually free the storage with a call like the -following: -.CS -Tcl_Free((char *) argv); -.CE -.PP -\fBTcl_JoinPath\fR is the inverse of \fBTcl_SplitPath\fR: it takes a -collection of path elements given by \fIargc\fR and \fIargv\fR and -generates a result string that is a properly constructed path. The -result string is appended to \fIresultPtr\fR. \fIResultPtr\fR must -refer to an initialized \fBTcl_DString\fR. -.PP -If the result of \fBTcl_SplitPath\fR is passed to \fBTcl_JoinPath\fR, -the result will refer to the same location, but may not be in the same -form. This is because \fBTcl_SplitPath\fR and \fBTcl_JoinPath\fR -eliminate duplicate path separators and return a normalized form for -each platform. -.PP -\fBTcl_GetPathType\fR returns the type of the specified \fIpath\fR, -where \fBTcl_PathType\fR is one of \fBTCL_PATH_ABSOLUTE\fR, -\fBTCL_PATH_RELATIVE\fR, or \fBTCL_PATH_VOLUME_RELATIVE\fR. See the -\fBfilename\fR manual entry for a description of the path types for -each platform. - -.SH KEYWORDS -file, filename, join, path, split, type diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 deleted file mode 100644 index e268b5f..0000000 --- a/doc/StaticPkg.3 +++ /dev/null @@ -1,70 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: StaticPkg.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ -'\" -.so man.macros -.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_StaticPackage \- make a statically linked package available via the \fBload\fR command -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_StaticPackage\fR(\fIinterp, pkgName, initProc, safeInitProc\fR) -.SH ARGUMENTS -.AS Tcl_PackageInitProc *safeInitProc -.AP Tcl_Interp *interp in -If not NULL, points to an interpreter into which the package has -already been loaded (i.e., the caller has already invoked the -appropriate initialization procedure). NULL means the package -hasn't yet been incorporated into any interpreter. -.AP char *pkgName in -Name of the package; should be properly capitalized (first letter -upper-case, all others lower-case). -.AP Tcl_PackageInitProc *initProc in -Procedure to invoke to incorporate this package into a trusted -interpreter. -.AP Tcl_PackageInitProc *safeInitProc in -Procedure to call to incorporate this package into a safe interpreter -(one that will execute untrusted scripts). NULL means the package -can't be used in safe interpreters. -.BE - -.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 -has already been loaded into an interpreter. -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 -be invoked, depending on whether the target interpreter is safe -or not. -\fIinitProc\fR and \fIsafeInitProc\fR must both match the -following prototype: -.CS -typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); -.CE -The \fIinterp\fR argument identifies the interpreter in which the -package is to be loaded. The initialization procedure must return -\fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed -successfully; in the event of an error it should set \fIinterp->result\fR -to point to an error message. -The result or error from the initialization procedure will be returned -as the result of the \fBload\fR command that caused the -initialization procedure to be invoked. - -.SH KEYWORDS -initialization procedure, package, static linking diff --git a/doc/StrMatch.3 b/doc/StrMatch.3 deleted file mode 100644 index 09cd6df..0000000 --- a/doc/StrMatch.3 +++ /dev/null @@ -1,39 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: StrMatch.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ -'\" -.so man.macros -.TH Tcl_StringMatch 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_StringMatch \- test whether a string matches a pattern -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_StringMatch\fR(\fIstring\fR, \fIpattern\fR) -.SH ARGUMENTS -.AP char *string in -String to test. -.AP char *pattern in -Pattern to match against string. May contain special -characters from the set *?\e[]. -.BE - -.SH DESCRIPTION -.PP -This utility procedure determines whether a string matches -a given pattern. If it does, then \fBTcl_StringMatch\fR returns -1. Otherwise \fBTcl_StringMatch\fR returns 0. The algorithm -used for matching is the same algorithm used in the ``string match'' -Tcl command and is similar to the algorithm used by the C-shell -for file name matching; see the Tcl manual entry for details. - -.SH KEYWORDS -match, pattern, string diff --git a/doc/StringObj.3 b/doc/StringObj.3 deleted file mode 100644 index 46fe959..0000000 --- a/doc/StringObj.3 +++ /dev/null @@ -1,161 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: StringObj.3,v 1.4 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_AppendToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj \- 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 -char * -\fBTcl_GetString\fR(\fIobjPtr\fR) -.sp -\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR) -.VS -.sp -\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR) -.VE -.sp -\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR) -.sp -\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) -.sp -\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) -.sp -Tcl_Obj * -\fBTcl_ConcatObj\fR(\fIobjc, objv\fR) -.SH ARGUMENTS -.AS Tcl_Interp *appendObjPtr in/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. -.VS -.AP Tcl_Obj *appendObjPtr in -The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. -.VE -.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 va_list argList in -An argument list which must have been initialised using -\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\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 and \fBTcl_GetString\fR -return an object's string representation. -This is given by the returned byte pointer -and (for \fBTcl_GetStringFromObj\fR) 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. -The procedure \fBTcl_GetString\fR is used in the common case -where the caller does not need the length of the string representation. -.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). -.VS -.PP -\fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it -appends the string value of \fIappendObjPtr\fR to \fIobjPtr\fR. -.VE -.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 -\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR -except that instead of taking a variable number of arguments it takes an -argument 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/doc/Tcl.n b/doc/Tcl.n deleted file mode 100644 index 6bd8511..0000000 --- a/doc/Tcl.n +++ /dev/null @@ -1,195 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Tcl.n,v 1.3 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl n "8.1" Tcl "Tcl Built-In Commands" -.BS -.SH NAME -Tcl \- Summary of Tcl language syntax. -.BE - -.SH DESCRIPTION -.PP -The following rules define the syntax and semantics of the Tcl language: -.IP [1] -A Tcl script is a string containing one or more commands. -Semi-colons and newlines are command separators unless quoted as -described below. -Close brackets are command terminators during command substitution -(see below) unless quoted. -.IP [2] -A command is evaluated in two steps. -First, the Tcl interpreter breaks the command into \fIwords\fR -and performs substitutions as described below. -These substitutions are performed in the same way for all -commands. -The first word is used to locate a command procedure to -carry out the command, then all of the words of the command are -passed to the command procedure. -The command procedure is free to interpret each of its words -in any way it likes, such as an integer, variable name, list, -or Tcl script. -Different commands interpret their words differently. -.IP [3] -Words of a command are separated by white space (except for -newlines, which are command separators). -.IP [4] -If the first character of a word is double-quote (``"'') then -the word is terminated by the next double-quote character. -If semi-colons, close brackets, or white space characters -(including newlines) appear between the quotes then they are treated -as ordinary characters and included in the word. -Command substitution, variable substitution, and backslash substitution -are performed on the characters between the quotes as described below. -The double-quotes are not retained as part of the word. -.IP [5] -If the first character of a word is an open brace (``{'') then -the word is terminated by the matching close brace (``}''). -Braces nest within the word: for each additional open -brace there must be an additional close brace (however, -if an open brace or close brace within the word is -quoted with a backslash then it is not counted in locating the -matching close brace). -No substitutions are performed on the characters between the -braces except for backslash-newline substitutions described -below, nor do semi-colons, newlines, close brackets, -or white space receive any special interpretation. -The word will consist of exactly the characters between the -outer braces, not including the braces themselves. -.IP [6] -If a word contains an open bracket (``['') then Tcl performs -\fIcommand substitution\fR. -To do this it invokes the Tcl interpreter recursively to process -the characters following the open bracket as a Tcl script. -The script may contain any number of commands and must be terminated -by a close bracket (``]''). -The result of the script (i.e. the result of its last command) is -substituted into the word in place of the brackets and all of the -characters between them. -There may be any number of command substitutions in a single word. -Command substitution is not performed on words enclosed in braces. -.IP [7] -If a word contains a dollar-sign (``$'') then Tcl performs \fIvariable -substitution\fR: the dollar-sign and the following characters are -replaced in the word by the value of a variable. -Variable substitution may take any of the following forms: -.RS -.TP 15 -\fB$\fIname\fR -\fIName\fR is the name of a scalar variable; the name is terminated -by any character that isn't a letter, digit, or underscore. -.TP 15 -\fB$\fIname\fB(\fIindex\fB)\fR -\fIName\fR gives the name of an array variable and \fIindex\fR gives -the name of an element within that array. -\fIName\fR must contain only letters, digits, and underscores. -Command substitutions, variable substitutions, and backslash -substitutions are performed on the characters of \fIindex\fR. -.TP 15 -\fB${\fIname\fB}\fR -\fIName\fR is the name of a scalar variable. It may contain any -characters whatsoever except for close braces. -.LP -There may be any number of variable substitutions in a single word. -Variable substitution is not performed on words enclosed in braces. -.RE -.IP [8] -If a backslash (``\e'') appears within a word then -\fIbackslash substitution\fR occurs. -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. -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 -.TP 7 -\e\fBa\fR -Audible alert (bell) (0x7). -.TP 7 -\e\fBb\fR -Backspace (0x8). -.TP 7 -\e\fBf\fR -Form feed (0xc). -.TP 7 -\e\fBn\fR -Newline (0xa). -.TP 7 -\e\fBr\fR -Carriage-return (0xd). -.TP 7 -\e\fBt\fR -Tab (0x9). -.TP 7 -\e\fBv\fR -Vertical tab (0xb). -.TP 7 -\e\fB<newline>\fIwhiteSpace\fR -. -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 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. -.TP 7 -\e\e -Backslash (``\e''). -.VS 8.1 br -.TP 7 -\e\fIooo\fR -. -The digits \fIooo\fR (one, two, or three of them) give an eight-bit octal -value for the Unicode character that will be inserted. The upper bits of the -Unicode character will be 0. -.TP 7 -\e\fBx\fIhh\fR -. -The hexadecimal digits \fIhh\fR give an eight-bit hexadecimal value for the -Unicode character that will be inserted. Any number of hexadecimal digits -may be present; however, all but the last two are ignored (the result is -always a one-byte quantity). The upper bits of the Unicode character will -be 0. -.TP 7 -\e\fBu\fIhhhh\fR -. -The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a -sixteen-bit hexadecimal value for the Unicode character that will be -inserted. -.VE -.LP -Backslash substitution is not performed on words enclosed in braces, -except for backslash-newline as described above. -.RE -.IP [9] -If a hash character (``#'') appears at a point where Tcl is -expecting the first character of the first word of a command, -then the hash character and the characters that follow it, up -through the next newline, are treated as a comment and ignored. -The comment character only has significance when it appears -at the beginning of a command. -.IP [10] -Each character is processed exactly once by the Tcl interpreter -as part of creating the words of a command. -For example, if variable substitution occurs then no further -substitutions are performed on the value of the variable; the -value is inserted into the word verbatim. -If command substitution occurs then the nested command is -processed entirely by the recursive call to the Tcl interpreter; -no substitutions are performed before making the recursive -call and no additional substitutions are performed on the result -of the nested script. -.IP [11] -Substitutions do not affect the word boundaries of a command. -For example, during variable substitution the entire value of -the variable becomes part of a single word, even if the variable's -value contains spaces. diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 deleted file mode 100644 index 0979994..0000000 --- a/doc/Tcl_Main.3 +++ /dev/null @@ -1,61 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: Tcl_Main.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ -'\" -.so man.macros -.TH Tcl_Main 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Main \- main program for Tcl-based applications -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_Main\fR(\fIargc, argv, appInitProc\fR) -.SH ARGUMENTS -.AS Tcl_AppInitProc *appInitProc -.AP int argc in -Number of elements in \fIargv\fR. -.AP char *argv[] in -Array of strings containing command-line arguments. -.AP Tcl_AppInitProc *appInitProc in -Address of an application-specific initialization procedure. -The value for this argument is usually \fBTcl_AppInit\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_Main\fR acts as the main program for most Tcl-based applications. -Starting with Tcl 7.4 it is not called \fBmain\fR anymore because it -is part of the Tcl library and having a function \fBmain\fR -in a library (particularly a shared library) causes problems on many -systems. -Having \fBmain\fR in the Tcl library would also make it hard to use -Tcl in C++ programs, since C++ programs must have special C++ -\fBmain\fR functions. -.PP -Normally each application contains a small \fBmain\fR function that does -nothing but invoke \fBTcl_Main\fR. -\fBTcl_Main\fR then does all the work of creating and running a -\fBtclsh\fR-like application. -.PP -When it is has finished its own initialization, but before -it processes commands, \fBTcl_Main\fR calls the procedure given by -the \fIappInitProc\fR argument. This procedure provides a ``hook'' -for the application to perform its own initialization, such as defining -application-specific commands. The procedure must have an interface -that matches the type \fBTcl_AppInitProc\fR: -.CS -typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR); -.CE -\fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; -for more details on this procedure, see the documentation -for \fBTcl_AppInit\fR. - -.SH KEYWORDS -application-specific initialization, command-line arguments, main program diff --git a/doc/Thread.3 b/doc/Thread.3 deleted file mode 100644 index 595fac3..0000000 --- a/doc/Thread.3 +++ /dev/null @@ -1,100 +0,0 @@ -'\" -'\" Copyright (c) 1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Thread.3,v 1.2 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl_ConditionNotify 3 "8.1" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock \- thread synchronization support. -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -void -\fBTcl_ConditionNotify\fR(\fIcondPtr\fR) -.sp -void -\fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR) -.sp -VOID * -\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR) -.sp -void -\fBTcl_MutexLock\fR(\fImutexPtr\fR) -.sp -void -\fBTcl_MutexUnlock\fR(\fImutexPtr\fR) -.SH ARGUMENTS -.AS Tcl_ThreadDataKey *keyPtr -.AP Tcl_Condition *condPtr in -A condition variable, which must be associated with a mutex lock. -.AP Tcl_Condition *mutexPtr in -A mutex lock. -.AP Tcl_Time *timePtr in -A time limit on the condition wait. NULL to wait forever. -Note that a polling value of 0 seconds doesn't make much sense. -.AP Tcl_ThreadDataKey *keyPtr in -This identifies a block of thread local storage. The key should be -static and process-wide, yet each thread will end up associating -a different block of storage with this key. -.AP int *size in -The size of the thread local storage block. This amount of data -is allocated and initialized to zero the first time each thread -calls \fBTcl_GetThreadData\fR. -.BE - -.SH DESCRIPTION -.PP -A mutex is a lock that is used to serialize all threads through a piece -of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR. -If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will -block until \fBTcl_MutexUnlock\fR is called. -.VS -The result of locking a mutex twice from the same thread is undefined. -On some platforms it will result in a deadlock. -.VE -\fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR -procedures are defined as empty macros if not compiling with threads enabled. -.PP -A condition variable is used as a signaling mechanism: -a thread can lock a mutex and then wait on a condition variable -with \fBTcl_ConditionWait\fR. This atomically releases the mutex lock -and blocks the waiting thread until another thread calls -\fBTcl_ConditionNotify\fR. The caller of \fBTcl_ConditionNotify\fR should -have the associated mutex held by previously calling \fBTcl_MutexLock\fR, -but this is not enforced. Notifying the -condition variable unblocks all threads waiting on the condition variable, -but they do not proceed until the mutex is released with \fBTcl_MutexUnlock\fR. -The implementation of \fBTcl_ConditionWait\fR automatically locks -the mutex before returning. -.PP -The caller of \fBTcl_ConditionWait\fR should be prepared for spurious -notifications by calling \fBTcl_ConditionWait\fR within a while loop -that tests some invariant. -.PP -The \fBTcl_GetThreadData\fR call returns a pointer to a block of -thread-private data. Its argument is a key that is shared by all threads -and a size for the block of storage. The storage is automatically -allocated and initialized to all zeros the first time each thread asks for it. -The storage is automatically deallocated by \fBTcl_FinalizeThread\fR -.SH INITIALIZATION -.PP -.PP -All of these synchronization objects are self initializing. -They are implemented as opaque pointers that should be NULL -upon first use. -The mutexes and condition variables are -cleaned up by process exit handlers. Thread local storage is -reclaimed during \fBTcl_FinalizeThread\fR. -.SH CREATING THREADS -The API to create threads is not finalized at this time. -There are private facilities to create threads that contain a new -Tcl interpreter, and to send scripts among threads. -Dive into tclThreadTest.c and tclThread.c for examples. -.SH KEYWORDS -thread, mutex, condition variable, thread local storage diff --git a/doc/ToUpper.3 b/doc/ToUpper.3 deleted file mode 100644 index 639dd61..0000000 --- a/doc/ToUpper.3 +++ /dev/null @@ -1,90 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: ToUpper.3,v 1.2 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl_UtfToUpper 3 "8.1" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle \- routines for manipulating the case of Unicode characters and UTF-8 strings. -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_UniChar -\fBTcl_UniCharToUpper\fR(\fIch\fR) -.sp -Tcl_UniChar -\fBTcl_UniCharToLower\fR(\fIch\fR) -.sp -Tcl_UniChar -\fBTcl_UniCharToTitle\fR(\fIch\fR) -.sp -int -\fBTcl_UtfToUpper\fR(\fIstr\fR) -.sp -int -\fBTcl_UtfToLower\fR(\fIstr\fR) -.sp -int -\fBTcl_UtfToTitle\fR(\fIstr\fR) -.SH ARGUMENTS -.AS char *str in/out -.AP int ch in -The Tcl_UniChar to be converted. -.AP char *str in/out -Pointer to UTF-8 string to be converted in place. -.BE - -.SH DESCRIPTION -.PP -The first three routines convert the case of individual Unicode characters: -.PP -If \fIch\fR represents a lower-case character, -\fBTcl_UniCharToUpper\fR returns the corresponding upper-case -character. If no upper-case character is defined, it returns the -character unchanged. -.PP -If \fIch\fR represents an upper-case character, -\fBTcl_UniCharToLower\fR returns the corresponding lower-case -character. If no lower-case character is defined, it returns the -character unchanged. -.PP -If \fIch\fR represents a lower-case character, -\fBTcl_UniCharToTitle\fR returns the corresponding title-case -character. If no title-case character is defined, it returns the -corresponding upper-case character. If no upper-case character is -defined, it returns the character unchanged. Title-case is defined -for a small number of characters that have a different appearance when -they are at the beginning of a capitalized word. -.PP -The next three routines convert the case of UTF-8 strings in place in -memory: -.PP -\fBTcl_UtfToUpper\fR changes every UTF-8 character in \fIstr\fR to -upper-case. Because changing the case of a character may change its -size, the byte offset of each character in the resulting string may -differ from its original location. \fBTcl_UtfToUpper\fR writes a null -byte at the end of the converted string. \fBTcl_UtfToUpper\fR returns -the new length of the string in bytes. This new length is guaranteed -to be no longer than the original string length. -.PP -\fBTcl_UtfToLower\fR is the same as \fBTcl_UtfToUpper\fR except it -turns each character in the string into its lower-case equivalent. -.PP -\fBTcl_UtfToTitle\fR is the same as \fBTcl_UtfToUpper\fR except it -turns the first character in the string into its title-case equivalent -and all following characters into their lower-case equivalents. - -.SH BUGS -.PP -At this time, the case conversions are only defined for the ISO8859-1 -characters. Unicode characters above 0x00ff are not modified by these -routines. - -.SH KEYWORDS -utf, unicode, toupper, tolower, totitle, case diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 deleted file mode 100644 index 57a3350..0000000 --- a/doc/TraceVar.3 +++ /dev/null @@ -1,366 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: TraceVar.3,v 1.3 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_TraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR -.sp -int -\fBTcl_TraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR -.sp -\fBTcl_UntraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR -.sp -\fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR -.sp -ClientData -\fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR -.sp -ClientData -\fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR -.SH ARGUMENTS -.AS Tcl_VarTraceProc prevClientData -.AP Tcl_Interp *interp in -Interpreter containing variable. -.AP char *varName in -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. -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. -.AP int flags in -OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and -TCL_TRACE_UNSETS, TCL_TRACE_ARRAY, and TCL_GLOBAL_ONLY. -Not all flags are used by all -procedures. See below for more information. -.AP Tcl_VarTraceProc *proc in -Procedure to invoke whenever one of the traced operations occurs. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.AP char *name1 in -Name of scalar or array variable (without array index). -.AP char *name2 in -For a trace on an element of an array, gives the index of the -element. For traces on scalar variables or on whole arrays, -is NULL. -.AP ClientData prevClientData in -If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or -\fBTcl_VarTraceInfo2\fR, so this call will return information about -next trace. If NULL, this call will return information about first -trace. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_TraceVar\fR allows a C procedure to monitor and control -access to a Tcl variable, so that the C procedure is invoked -whenever the variable is read or written or unset. -If the trace is created successfully then \fBTcl_TraceVar\fR returns -TCL_OK. If an error occurred (e.g. \fIvarName\fR specifies an element -of an array, but the actual variable isn't an array) then TCL_ERROR -is returned and an error message is left in \fIinterp->result\fR. -.PP -The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the -trace procedure is to be invoked and provides information -for setting up the trace. It consists of an OR-ed combination -of any of the following values: -.TP -\fBTCL_GLOBAL_ONLY\fR -Normally, the variable will be looked up at the current level of -procedure call; if this bit is set then the variable will be looked -up at global level, ignoring any active procedures. -.TP -\fBTCL_TRACE_READS\fR -Invoke \fIproc\fR whenever an attempt is made to read the variable. -.TP -\fBTCL_TRACE_WRITES\fR -Invoke \fIproc\fR whenever an attempt is made to modify the variable. -.TP -\fBTCL_TRACE_UNSETS\fR -Invoke \fIproc\fR whenever the variable is unset. -A variable may be unset either explicitly by an \fBunset\fR command, -or implicitly when a procedure returns (its local variables are -automatically unset) or when the interpreter is deleted (all -variables are automatically unset). -.TP -\fBTCL_TRACE_ARRAY\fR -Invoke \fIproc\fR whenever the array command is invoked. -This gives the trace procedure a chance to update the array before -array names or array get is called. Note that this is called -before an array set, but that will trigger write traces. -.PP -Whenever one of the specified operations occurs on the variable, -\fIproc\fR will be invoked. -It should have arguments and result that match the type -\fBTcl_VarTraceProc\fR: -.CS -typedef char *Tcl_VarTraceProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - char *\fIname1\fR, - char *\fIname2\fR, - int \fIflags\fR); -.CE -The \fIclientData\fR and \fIinterp\fR parameters will -have the same values as those passed to \fBTcl_TraceVar\fR when the -trace was created. -\fIClientData\fR typically points to an application-specific -data structure that describes what to do when \fIproc\fR -is invoked. -\fIName1\fR and \fIname2\fR give the name of the traced variable -in the normal two-part form (see the description of \fBTcl_TraceVar2\fR -below for details). -\fIFlags\fR is an OR-ed combination of bits providing several -pieces of information. -One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, TCL_TRACE_ARRAY, -or TCL_TRACE_UNSETS -will be set in \fIflags\fR to indicate which operation is being performed -on the variable. -The bit TCL_GLOBAL_ONLY will be set whenever the variable being -accessed is a global one not accessible from the current level of -procedure call: the trace procedure will need to pass this flag -back to variable-related procedures like \fBTcl_GetVar\fR if it -attempts to access the variable. -The bit TCL_TRACE_DESTROYED will be set in \fIflags\fR if the trace is -about to be destroyed; this information may be useful to \fIproc\fR -so that it can clean up its own internal data structures (see -the section TCL_TRACE_DESTROYED below for more details). -Lastly, the bit TCL_INTERP_DESTROYED will be set if the entire -interpreter is being destroyed. -When this bit is set, \fIproc\fR must be especially careful in -the things it does (see the section TCL_INTERP_DESTROYED below). -The trace procedure's return value should normally be NULL; see -ERROR RETURNS below for information on other possibilities. -.PP -\fBTcl_UntraceVar\fR may be used to remove a trace. -If the variable specified by \fIinterp\fR, \fIvarName\fR, and \fIflags\fR -has a trace set with \fIflags\fR, \fIproc\fR, and -\fIclientData\fR, then the corresponding trace is removed. -If no such trace exists, then the call to \fBTcl_UntraceVar\fR -has no effect. -The same bits are valid for \fIflags\fR as for calls to \fBTcl_TraceVar\fR. -.PP -\fBTcl_VarTraceInfo\fR may be used to retrieve information about -traces set on a given variable. -The return value from \fBTcl_VarTraceInfo\fR is the \fIclientData\fR -associated with a particular trace. -The trace must be on the variable specified by the \fIinterp\fR, -\fIvarName\fR, and \fIflags\fR arguments (only the TCL_GLOBAL_ONLY -bit from \fIflags\fR is used; other bits are ignored) and its trace procedure -must the same as the \fIproc\fR argument. -If the \fIprevClientData\fR argument is NULL then the return -value corresponds to the first (most recently created) matching -trace, or NULL if there are no matching traces. -If the \fIprevClientData\fR argument isn't NULL, then it should -be the return value from a previous call to \fBTcl_VarTraceInfo\fR. -In this case, the new return value will correspond to the next -matching trace after the one whose \fIclientData\fR matches -\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR -or if there are no more matching traces after it. -This mechanism makes it possible to step through all of the -traces for a given variable that have the same \fIproc\fR. - -.SH "TWO-PART NAMES" -.PP -The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and -\fBTcl_VarTraceInfo2\fR are identical to \fBTcl_TraceVar\fR, -\fBTcl_UntraceVar\fR, and \fBTcl_VarTraceInfo\fR, respectively, -except that the name of the variable consists of two parts. -\fIName1\fR gives the name of a scalar variable or array, -and \fIname2\fR gives the name of an element within an array. -.VS 8.1 -When \fIname2\fR is NULL, -\fIname1\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 \fIname2\fR is NULL and \fIname1\fR does not refer -to an array element -.VE -it means that either the variable is -a scalar or the trace is to be set on the entire array rather -than an individual element (see WHOLE-ARRAY TRACES below for -more information). - - -.SH "ACCESSING VARIABLES DURING TRACES" -.PP -During read, write, and array traces, the -trace procedure can read, write, or unset the traced -variable using \fBTcl_GetVar2\fR, \fBTcl_SetVar2\fR, and -other procedures. -While \fIproc\fR is executing, traces are temporarily disabled -for the variable, so that calls to \fBTcl_GetVar2\fR and -\fBTcl_SetVar2\fR will not cause \fIproc\fR or other trace procedures -to be invoked again. -Disabling only occurs for the variable whose trace procedure -is active; accesses to other variables will still be traced. -However, if a variable is unset during a read or write trace then unset -traces will be invoked. -.PP -During unset traces the variable has already been completely -expunged. -It is possible for the trace procedure to read or write the -variable, but this will be a new version of the variable. -Traces are not disabled during unset traces as they are for -read and write traces, but existing traces have been removed -from the variable before any trace procedures are invoked. -If new traces are set by unset trace procedures, these traces -will be invoked on accesses to the variable by the trace -procedures. - -.SH "CALLBACK TIMING" -.PP -When read tracing has been specified for a variable, the trace -procedure will be invoked whenever the variable's value is -read. This includes \fBset\fR Tcl commands, \fB$\fR-notation -in Tcl commands, and invocations of the \fBTcl_GetVar\fR -and \fBTcl_GetVar2\fR procedures. -\fIProc\fR is invoked just before the variable's value is -returned. -It may modify the value of the variable to affect what -is returned by the traced access. -If it unsets the variable then the access will return an error -just as if the variable never existed. -.PP -When write tracing has been specified for a variable, the -trace procedure will be invoked whenever the variable's value -is modified. This includes \fBset\fR commands, -commands that modify variables as side effects (such as -\fBcatch\fR and \fBscan\fR), and calls to the \fBTcl_SetVar\fR -and \fBTcl_SetVar2\fR procedures). -\fIProc\fR will be invoked after the variable's value has been -modified, but before the new value of the variable has been -returned. -It may modify the value of the variable to override the change -and to determine the value actually returned by the traced -access. -If it deletes the variable then the traced access will return -an empty string. -.PP -When array tracing has been specified, the trace procedure -will be invoked at the beginning of the array command implementation, -before any of the operations like get, set, or names have been invoked. -The trace procedure can modify the array elements with \fBTcl_SetVar\fR -and \fBTcl_SetVar2\fR. -.PP -When unset tracing has been specified, the trace procedure -will be invoked whenever the variable is destroyed. -The traces will be called after the variable has been -completely unset. - -.SH "WHOLE-ARRAY TRACES" -.PP -If a call to \fBTcl_TraceVar\fR or \fBTcl_TraceVar2\fR specifies -the name of an array variable without an index into the array, -then the trace will be set on the array as a whole. -This means that \fIproc\fR will be invoked whenever any -element of the array is accessed in the ways specified by -\fIflags\fR. -When an array is unset, a whole-array trace will be invoked -just once, with \fIname1\fR equal to the name of the array -and \fIname2\fR NULL; it will not be invoked once for each -element. - -.SH "MULTIPLE TRACES" -.PP -It is possible for multiple traces to exist on the same variable. -When this happens, all of the trace procedures will be invoked on each -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. -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. - -.SH "ERROR RETURNS" -.PP -Under normal conditions trace procedures should return NULL, indicating -successful completion. -If \fIproc\fR returns a non-NULL value it signifies that an -error occurred. -The return value must be a pointer to a static character string -containing an error message. -If a trace procedure returns an error, no further traces are -invoked for the access and the traced access aborts with the -given message. -Trace procedures can use this facility to make variables -read-only, for example (but note that the value of the variable -will already have been modified before the trace procedure is -called, so the trace procedure will have to restore the correct -value). -.PP -The return value from \fIproc\fR is only used during read and -write tracing. -During unset traces, the return value is ignored and all relevant -trace procedures will always be invoked. - -.SH "RESTRICTIONS" -.PP -A trace procedure can be called at any time, even when there -is a partially-formed result in the interpreter's result area. If -the trace procedure does anything that could damage this result (such -as calling \fBTcl_Eval\fR) then it must save the original values of -the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore -them before it returns. - -.SH "UNDEFINED VARIABLES" -.PP -It is legal to set a trace on an undefined variable. -The variable will still appear to be undefined until the -first time its value is set. -If an undefined variable is traced and then unset, the unset will fail -with an error (``no such variable''), but the trace -procedure will still be invoked. - -.SH "TCL_TRACE_DESTROYED FLAG" -.PP -In an unset callback to \fIproc\fR, the TCL_TRACE_DESTROYED bit -is set in \fIflags\fR if the trace is being removed as part -of the deletion. -Traces on a variable are always removed whenever the variable -is deleted; the only time TCL_TRACE_DESTROYED isn't set is for -a whole-array trace invoked when only a single element of an -array is unset. - -.SH "TCL_INTERP_DESTROYED" -.PP -When an interpreter is destroyed, unset traces are called for -all of its variables. -The TCL_INTERP_DESTROYED bit will be set in the \fIflags\fR -argument passed to the trace procedures. -Trace procedures must be extremely careful in what they do if -the TCL_INTERP_DESTROYED bit is set. -It is not safe for the procedures to invoke any Tcl procedures -on the interpreter, since its state is partially deleted. -All that trace procedures should do under these circumstances is -to clean up and free their own internal data structures. - -.SH BUGS -.PP -Tcl doesn't do any error checking to prevent trace procedures -from misusing the interpreter during traces with TCL_INTERP_DESTROYED -set. -.PP -Array traces are not yet integrated with the Tcl "info exists" command, -nor is there Tcl-level access to array traces. - -.SH KEYWORDS -clientData, trace, variable diff --git a/doc/Translate.3 b/doc/Translate.3 deleted file mode 100644 index 5d0d598..0000000 --- a/doc/Translate.3 +++ /dev/null @@ -1,66 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Translate.3,v 1.3 1999/04/16 00:46:33 stanton Exp $ -'\" -.so man.macros -.TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -char * -\fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR) -.SH ARGUMENTS -.AS Tcl_DString *bufferPtr -.AP Tcl_Interp *interp in -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 -If needed, this dynamic string is used to store the new file name. -At the time of the call it should be uninitialized or free. The -caller must eventually call \fBTcl_DStringFree\fR to free up -anything stored here. -.BE - -.SH DESCRIPTION -.PP -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. -.PP -If -\fBTcl_TranslateFileName\fR has to do tilde substitution or translate -the name then it uses -the dynamic string at \fI*bufferPtr\fR to hold the new string it -generates. -After \fBTcl_TranslateFileName\fR returns a non-NULL result, the caller must -eventually invoke \fBTcl_DStringFree\fR to free any information -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. -.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. -When an error occurs, \fBTcl_TranslateFileName\fR -frees the dynamic string itself so that the caller need not call -\fBTcl_DStringFree\fR. -.PP -The caller is responsible for making sure that \fIinterp->result\fR -has its default empty value when \fBTcl_TranslateFileName\fR is invoked. - -.SH "SEE ALSO" -filename - -.SH KEYWORDS -file name, home directory, tilde, translate, user diff --git a/doc/UpVar.3 b/doc/UpVar.3 deleted file mode 100644 index 8dcb06f..0000000 --- a/doc/UpVar.3 +++ /dev/null @@ -1,76 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: UpVar.3,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH Tcl_UpVar 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_UpVar, Tcl_UpVar2 \- link one variable to another -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_UpVar(\fIinterp, frameName, sourceName, destName, flags\fB)\fR -.sp -int -\fBTcl_UpVar2(\fIinterp, frameName, name1, name2, destName, flags\fB)\fR -.SH ARGUMENTS -.AS Tcl_VarTraceProc prevClientData -.AP Tcl_Interp *interp in -Interpreter containing variables; also used for error reporting. -.AP char *frameName in -Identifies the stack frame containing source variable. -May have any of the forms accepted by -the \fBupvar\fR command, such as \fB#0\fR or \fB1\fR. -.AP char *sourceName in -Name of source variable, in the frame given by \fIframeName\fR. -May refer to a scalar variable or to an array variable with a -parenthesized index. -.AP char *destName in -Name of destination variable, which is to be linked to source -variable so that references to \fIdestName\fR -refer to the other variable. Must not currently exist except as -an upvar-ed variable. -.AP int flags in -Either TCL_GLOBAL_ONLY or 0; if non-zero, then \fIdestName\fR is -a global variable; otherwise it is a local to the current procedure -(or global if no procedure is active). -.AP char *name1 in -First part of source variable's name (scalar name, or name of array -without array index). -.AP char *name2 in -If source variable is an element of an array, gives the index of the element. -For scalar source variables, is NULL. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_UpVar\fR and \fBTcl_UpVar2\fR provide the same functionality -as the \fBupvar\fR command: they make a link from a source variable -to a destination variable, so that references to the destination are -passed transparently through to the source. -The name of the source variable may be specified either as a single -string such as \fBxyx\fR or \fBa(24)\fR (by calling \fBTcl_UpVar\fR) -or in two parts where the array name has been separated from the -element name (by calling \fBTcl_UpVar2\fR). -The destination variable name is specified in a single string; it -may not be an array element. -.PP -Both procedures return either TCL_OK or TCL_ERROR, and they -leave an error message in \fIinterp->result\fR if an error -occurs. -.PP -As with the \fBupvar\fR command, the source variable need not exist; -if it does exist, unsetting it later does not destroy the link. The -destination variable may exist at the time of the call, but if so -it must exist as a linked variable. - -.SH KEYWORDS -linked variable, upvar, variable diff --git a/doc/Utf.3 b/doc/Utf.3 deleted file mode 100644 index f68a6cb..0000000 --- a/doc/Utf.3 +++ /dev/null @@ -1,160 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: Utf.3,v 1.2 1999/04/16 00:46:34 stanton Exp $ -'\" -.so man.macros -.TH Utf 3 "8.1" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings. -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -typedef ... Tcl_UniChar; -.sp -int -\fBTcl_UniCharToUtf\fR(\fIch, buf\fR) -.sp -int -\fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR) -.sp -int -\fBTcl_UtfCharComplete\fR(\fIsrc, len\fR) -.sp -int -\fBTcl_NumUtfChars\fR(\fIsrc, len\fR) -.sp -char * -\fBTcl_UtfFindFirst\fR(\fIsrc, ch\fR) -.sp -char * -\fBTcl_UtfFindLast\fR(\fIsrc, ch\fR) -.sp -char * -\fBTcl_UtfNext\fR(\fIsrc\fR) -.sp -char * -\fBTcl_UtfPrev\fR(\fIsrc, start\fR) -.sp -Tcl_UniChar -\fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR) -.sp -char * -\fBTcl_UtfAtIndex\fR(\fIsrc, index\fR) -.sp -int -\fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR) -.SH ARGUMENTS -.AS "CONST char" *chPtr out -.AP char *buf out -Buffer in which the UTF-8 representation of the Tcl_UniChar is stored. At most -TCL_UTF_MAX bytes are stored in the buffer. -.AP int ch in -The Tcl_UniChar to be converted or examined. -.AP Tcl_UniChar *chPtr out -Filled with the Tcl_UniChar represented by the head of the UTF-8 string. -.AP "CONST char" *src in -Pointer to a UTF-8 string. -.AP int len in -The length of the UTF-8 string in bytes (not UTF-8 characters). If -negative, all bytes up to the first null byte are used. -.AP "CONST char" *start in -Pointer to the beginning of a UTF-8 string. -.AP int index in -The index of a character (not byte) in the UTF-8 string. -.AP int *readPtr out -If non-NULL, filled with the number of bytes in the backslash sequence, -including the backslash character. -.AP char *dst out -Buffer in which the bytes represented by the backslash sequence are stored. -At most TCL_UTF_MAX bytes are stored in the buffer. -.BE - -.SH DESCRIPTION -.PP -These routines convert between UTF-8 strings and Tcl_UniChars. A -Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size -quantity. A UTF-8 character is a Unicode character represented as -a varying-length sequence of up to TCL_UTF_MAX bytes. A multibyte UTF-8 -sequence consists of a lead byte followed by some number of trail bytes. -.PP -\fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to -represent one Unicode character in the UTF-8 representation. -.PP -\fBTcl_UniCharToUtf\fR stores the Tcl_UniChar \fIch\fR as a UTF-8 string -in starting at \fIbuf\fR. The return value is the number of bytes stored -in \fIbuf\fR. -.PP -\fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR -and stores it as a Tcl_UniChar in \fI*chPtr\fR. The return value is the -number of bytes read from \fIsrc\fR.. The caller must ensure that the -source buffer is long enough such that this routine does not run off the -end and dereference non-existent or random memory; if the source buffer -is known to be null terminated, this will not happen. If the input is -not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first -byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0000 and -0x00ff and return 1. -.PP -\fBTcl_UtfCharComplete\fR returns 1 if the source UTF-8 string \fIsrc\fR -of length \fIlen\fR bytes is long enough to be decoded by -\fBTcl_UtfToUniChar\fR, or 0 otherwise. This function does not guarantee -that the UTF-8 string is properly formed. This routine is used by -procedures that are operating on a byte at a time and need to know if a -full Tcl_UniChar has been seen. -.PP -\fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings. It -returns the number of Tcl_UniChars that are represented by the UTF-8 string -\fIsrc\fR. The length of the source string is \fIlen\fR bytes. If the -length is negative, all bytes up to the first NULL byte are used. -.PP -\fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings. It -returns a pointer to the first occurance of the Tcl_UniChar \fIch\fR -in the NULL-terminated UTF-8 string \fIsrc\fR. The NULL terminator is -considered part of the UTF-8 string. -.PP -\fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings. It -returns a pointer to the last occurance of the Tcl_UniChar \fIch\fR -in the NULL terminated UTF-8 string \fIsrc\fR. The NULL terminator is -considered part of the UTF-8 string. -.PP -Given \fIsrc\fR, a pointer to some location in a UTF-8 string, -\fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the -string. The caller must not ask for the next character after the last -character in the string. -.PP -Given \fIsrc\fR, a pointer to some location in a UTF-8 string, -\fBTcl_UtfPrev\fR returns a pointer to the previous UTF-8 character in the -string. This function will not back up to a position before \fIstart\fR, -the start of the UTF-8 string. If \fIsrc\fR was already at \fIstart\fR, the -return value will be \fIstart\fR. -.PP -\fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the -Pascal Ord() function. It returns the Tcl_UniChar represented at the -specified character (not byte) \fIindex\fR in the UTF-8 string -\fIsrc\fR. The source string must contain at least \fIindex\fR -characters. -.PP -\fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not -byte) \fIindex\fR in the UTF-8 string \fIsrc\fR. The source string must -contain at least \fIindex\fR characters. This is equivalent to calling -\fBTcl_UtfNext\fR \fIindex\fR times. -.PP -\fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl -commands. It parses a backslash sequence and stores the properly formed -UTF-8 character represented by the backslash sequence in the output -buffer \fIdst\fR. At most TCL_UTF_MAX bytes are stored in the buffer. -\fBTcl_UtfBackslash\fR modifies \fI*readPtr\fR to contain the number -of bytes in the backslash sequence, including the backslash character. -The return value is the number of bytes stored in the output buffer. -.PP -See the \fBTcl\fR manual entry for information on the valid backslash -sequences. All of the sequences described in the Tcl manual entry are -supported by \fBTcl_UtfBackslash\fR. - -.SH KEYWORDS -utf, unicode, backslash diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3 deleted file mode 100644 index 30157d9..0000000 --- a/doc/WrongNumArgs.3 +++ /dev/null @@ -1,79 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.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. This argument may be NULL. -.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. -.PP -Some of the objects in the \fIobjv\fR array may be abbreviations for -a subcommand. The command -\fBTcl_GetIndexFromObj\fR will convert the abbreviated string object -into an \fIindexObject\fR. If an error occurs in the parsing of the -subcommand we would like to use the full subcommand name rather than -the abbreviation. If the \fBTcl_WrongNumArgs\fR command finds any -\fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand -name in the error message instead of the abbreviated name that was -origionally passed in. Using the above example, lets assume that -\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object -is now an indexObject becasue it was passed to -\fBTcl_GetIndexFromObj\fR. In this case the error message would be: -.CS -wrong # args: should be "foo barfly fileName count" -.CE - -.SH "SEE ALSO" -Tcl_GetIndexFromObj - -.SH KEYWORDS -command, error message, wrong number of arguments diff --git a/doc/after.n b/doc/after.n deleted file mode 100644 index 17fcf7f..0000000 --- a/doc/after.n +++ /dev/null @@ -1,109 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: after.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH after n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -after \- Execute a command after a time delay -.SH SYNOPSIS -\fBafter \fIms\fR -.sp -\fBafter \fIms \fR?\fIscript script script ...\fR? -.sp -\fBafter cancel \fIid\fR -.sp -\fBafter cancel \fIscript script script ...\fR -.sp -\fBafter idle \fR?\fIscript script script ...\fR? -.sp -\fBafter info \fR?\fIid\fR? -.BE - -.SH DESCRIPTION -.PP -This command is used to delay execution of the program or to execute -a command in background sometime in the future. It has several forms, -depending on the first argument to the command: -.TP -\fBafter \fIms\fR -\fIMs\fR must be an integer giving a time in milliseconds. -The command sleeps for \fIms\fR milliseconds and then returns. -While the command is sleeping the application does not respond to -events. -.TP -\fBafter \fIms \fR?\fIscript script script ...\fR? -In this form the command returns immediately, but it arranges -for a Tcl command to be executed \fIms\fR milliseconds later as an -event handler. -The command will be executed exactly once, at the given time. -The delayed command is formed by concatenating all the \fIscript\fR -arguments in the same fashion as the \fBconcat\fR command. -The command will be executed at global level (outside the context -of any Tcl procedure). -If an error occurs while executing the delayed command then the -\fBbgerror\fR mechanism is used to report the error. -The \fBafter\fR command returns an identifier that can be used -to cancel the delayed command using \fBafter cancel\fR. -.TP -\fBafter cancel \fIid\fR -Cancels the execution of a delayed command that -was previously scheduled. -\fIId\fR indicates which command should be canceled; it must have -been the return value from a previous \fBafter\fR command. -If the command given by \fIid\fR has already been executed then -the \fBafter cancel\fR command has no effect. -.TP -\fBafter cancel \fIscript script ...\fR -This command also cancels the execution of a delayed command. -The \fIscript\fR arguments are concatenated together with space -separators (just as in the \fBconcat\fR command). -If there is a pending command that matches the string, it is -cancelled and will never be executed; if no such command is -currently pending then the \fBafter cancel\fR command has no effect. -.TP -\fBafter idle \fIscript \fR?\fIscript script ...\fR? -Concatenates the \fIscript\fR arguments together with space -separators (just as in the \fBconcat\fR command), and arranges -for the resulting script to be evaluated later as an idle callback. -The script will be run exactly once, the next time the event -loop is entered and there are no events to process. -The command returns an identifier that can be used -to cancel the delayed command using \fBafter cancel\fR. -If an error occurs while executing the script then the -\fBbgerror\fR mechanism is used to report the error. -.TP -\fBafter info \fR?\fIid\fR? -This command returns information about existing event handlers. -If no \fIid\fR argument is supplied, the command returns -a list of the identifiers for all existing -event handlers created by the \fBafter\fR command for this -interpreter. -If \fIid\fR is supplied, it specifies an existing handler; -\fIid\fR must have been the return value from some previous call -to \fBafter\fR and it must not have triggered yet or been cancelled. -In this case the command returns a list with two elements. -The first element of the list is the script associated -with \fIid\fR, and the second element is either -\fBidle\fR or \fBtimer\fR to indicate what kind of event -handler it is. -.LP -The \fBafter \fIms\fR and \fBafter idle\fR forms of the command -assume that the application is event driven: the delayed commands -will not be executed unless the application enters the event loop. -In applications that are not normally event-driven, such as -\fBtclsh\fR, the event loop can be entered with the \fBvwait\fR -and \fBupdate\fR commands. - -.SH "SEE ALSO" -bgerror - -.SH KEYWORDS -cancel, delay, idle callback, sleep, time diff --git a/doc/append.n b/doc/append.n deleted file mode 100644 index 1a28065..0000000 --- a/doc/append.n +++ /dev/null @@ -1,32 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: append.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH append n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -append \- Append to variable -.SH SYNOPSIS -\fBappend \fIvarName \fR?\fIvalue value value ...\fR? -.BE - -.SH DESCRIPTION -.PP -Append all of the \fIvalue\fR arguments to the current value -of variable \fIvarName\fR. If \fIvarName\fR doesn't exist, -it is given a value equal to the concatenation of all the -\fIvalue\fR arguments. -This command provides an efficient way to build up long -variables incrementally. -For example, ``\fBappend a $b\fR'' is much more efficient than -``\fBset a $a$b\fR'' if \fB$a\fR is long. - -.SH KEYWORDS -append, variable diff --git a/doc/array.n b/doc/array.n deleted file mode 100644 index f18c91e..0000000 --- a/doc/array.n +++ /dev/null @@ -1,116 +0,0 @@ -'\" -'\" Copyright (c) 1993-1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: array.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH array n 7.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -array \- Manipulate array variables -.SH SYNOPSIS -\fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command performs one of several operations on the -variable given by \fIarrayName\fR. -Unless otherwise specified for individual commands below, -\fIarrayName\fR must be the name of an existing array variable. -The \fIoption\fR argument determines what action is carried -out by the command. -The legal \fIoptions\fR (which may be abbreviated) are: -.TP -\fBarray anymore \fIarrayName searchId\fR -Returns 1 if there are any more elements left to be processed -in an array search, 0 if all elements have already been -returned. -\fISearchId\fR indicates which search on \fIarrayName\fR to -check, and must have been the return value from a previous -invocation of \fBarray startsearch\fR. -This option is particularly useful if an array has an element -with an empty name, since the return value from -\fBarray nextelement\fR won't indicate whether the search -has been completed. -.TP -\fBarray donesearch \fIarrayName searchId\fR -This command terminates an array search and destroys all the -state associated with that search. \fISearchId\fR indicates -which search on \fIarrayName\fR to destroy, and must have -been the return value from a previous invocation of -\fBarray startsearch\fR. Returns an empty string. -.TP -\fBarray exists \fIarrayName\fR -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. -.TP -\fBarray get \fIarrayName\fR ?\fIpattern\fR? -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. -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. -If \fIarrayName\fR isn't the name of an array variable, or if -the array contains no elements, then an empty list is returned. -.TP -\fBarray names \fIarrayName\fR ?\fIpattern\fR? -Returns a list containing the names of all of the elements in -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 -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. -.TP -\fBarray nextelement \fIarrayName searchId\fR -Returns the name of the next element in \fIarrayName\fR, or -an empty string if all elements of \fIarrayName\fR have -already been returned in this search. The \fIsearchId\fR -argument identifies the search, and must have -been the return value of an \fBarray startsearch\fR command. -Warning: if elements are added to or deleted from the array, -then all searches are automatically terminated just as if -\fBarray donesearch\fR had been invoked; this will cause -\fBarray nextelement\fR operations to fail for those searches. -.TP -\fBarray set \fIarrayName list\fR -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. -If the variable \fIarrayName\fR does not already exist -and \fIlist\fR is empty, -\fIarrayName\fR is created with an empty array value. -.TP -\fBarray size \fIarrayName\fR -Returns a decimal string giving the number of elements in the -array. -If \fIarrayName\fR isn't the name of an array then 0 is returned. -.TP -\fBarray startsearch \fIarrayName\fR -This command initializes an element-by-element search through the -array given by \fIarrayName\fR, such that invocations of the -\fBarray nextelement\fR command will return the names of the -individual elements in the array. -When the search has been completed, the \fBarray donesearch\fR -command should be invoked. -The return value is a -search identifier that must be used in \fBarray nextelement\fR -and \fBarray donesearch\fR commands; it allows multiple -searches to be underway simultaneously for the same array. - -.SH KEYWORDS -array, element names, search diff --git a/doc/bgerror.n b/doc/bgerror.n deleted file mode 100644 index 3f946c3..0000000 --- a/doc/bgerror.n +++ /dev/null @@ -1,68 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: bgerror.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH bgerror n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -bgerror \- Command invoked to process background errors -.SH SYNOPSIS -\fBbgerror \fImessage\fR -.BE - -.SH DESCRIPTION -.PP -The \fBbgerror\fR command doesn't exist as built-in part of Tcl. Instead, -individual applications or users can define a \fBbgerror\fR -command (e.g. as a Tcl procedure) if they wish to handle background -errors. -.PP -A background error is one that occurs in an event handler or some -other command that didn't originate with the application. -For example, if an error occurs while executing a command specified -with the \fBafter\fR command, then it is a background error. -For a non-background error, the error can simply be returned up -through nested Tcl command evaluations until it reaches the top-level -code in the application; then the application can report the error -in whatever way it wishes. -When a background error occurs, the unwinding ends in -the Tcl library and there is no obvious way for Tcl to report -the error. -.PP -When Tcl detects a background error, it saves information about the -error and invokes the \fBbgerror\fR command later as an idle event handler. -Before invoking \fBbgerror\fR, Tcl restores the \fBerrorInfo\fR -and \fBerrorCode\fR variables to their values at the time the -error occurred, then it invokes \fBbgerror\fR with -the error message as its only argument. -Tcl assumes that the application has implemented the \fBbgerror\fR -command, and that the command will report the error in a way that -makes sense for the application. Tcl will ignore any result returned -by the \fBbgerror\fR command as long as no error is generated. -.PP -If another Tcl error occurs within the \fBbgerror\fR command -(for example, because no \fBbgerror\fR command has been defined) -then Tcl reports the error itself by writing a message to stderr. -.PP -If several background errors accumulate before \fBbgerror\fR -is invoked to process them, \fBbgerror\fR will be invoked once -for each error, in the order they occurred. -However, if \fBbgerror\fR returns with a break exception, then -any remaining errors are skipped without calling \fBbgerror\fR. -.PP -Tcl has no default implementation for \fBbgerror\fR. -However, in applications using Tk there is a default -\fBbgerror\fR procedure -which posts a dialog box containing -the error message and offers the user a chance to see a stack -trace showing where the error occurred. - -.SH KEYWORDS -background error, reporting diff --git a/doc/binary.n b/doc/binary.n deleted file mode 100644 index 8b20259..0000000 --- a/doc/binary.n +++ /dev/null @@ -1,532 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: binary.n,v 1.3 1999/04/16 00:46:34 stanton Exp $ -'\" -.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\\x00\\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\\x00\\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} 260 {2 5}\fR -.CE -will return a string equivalent to -\fB\\x03\\xfd\\x80\\x04\\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\\x01\\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\\x01\\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 overflows the -machine's native representation, then the value of 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 -high-to-low 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/doc/break.n b/doc/break.n deleted file mode 100644 index 86d0d8b..0000000 --- a/doc/break.n +++ /dev/null @@ -1,34 +0,0 @@ -'\" -'\" Copyright (c) 1993-1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: break.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH break n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -break \- Abort looping command -.SH SYNOPSIS -\fBbreak\fR -.BE - -.SH DESCRIPTION -.PP -This command is typically invoked inside the body of a looping command -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 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 -scripts of procedure bodies. - -.SH KEYWORDS -abort, break, loop diff --git a/doc/case.n b/doc/case.n deleted file mode 100644 index cf15a94..0000000 --- a/doc/case.n +++ /dev/null @@ -1,59 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: case.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH case n 7.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -case \- Evaluate one of several scripts, depending on a given value -.SH SYNOPSIS -\fBcase\fI string \fR?\fBin\fR? \fIpatList body \fR?\fIpatList body \fR...? -.sp -\fBcase\fI string \fR?\fBin\fR? {\fIpatList body \fR?\fIpatList body \fR...?} -.BE - -.SH DESCRIPTION -.PP -\fINote: the \fBcase\fI command is obsolete and is supported only -for backward compatibility. At some point in the future it may be -removed entirely. You should use the \fBswitch\fI command instead.\fR -.PP -The \fBcase\fR command matches \fIstring\fR against each of -the \fIpatList\fR arguments in order. -Each \fIpatList\fR argument is a list of one or -more patterns. If any of these patterns matches \fIstring\fR then -\fBcase\fR evaluates the following \fIbody\fR argument -by passing it recursively to the Tcl interpreter and returns the result -of that evaluation. -Each \fIpatList\fR argument consists of a single -pattern or list of patterns. Each pattern may contain any of the wild-cards -described under \fBstring match\fR. If a \fIpatList\fR -argument is \fBdefault\fR, the corresponding body will be evaluated -if no \fIpatList\fR matches \fIstring\fR. If no \fIpatList\fR argument -matches \fIstring\fR and no default is given, then the \fBcase\fR -command returns an empty string. -.PP -Two syntaxes are provided for the \fIpatList\fR and \fIbody\fR arguments. -The first uses a separate argument for each of the patterns and commands; -this form is convenient if substitutions are desired on some of the -patterns or commands. -The second form places all of the patterns and commands together into -a single argument; the argument must have proper list structure, with -the elements of the list being the patterns and commands. -The second form makes it easy to construct multi-line case commands, -since the braces around the whole list make it unnecessary to include a -backslash at the end of each line. -Since the \fIpatList\fR arguments are in braces in the second form, -no command or variable substitutions are performed on them; this makes -the behavior of the second form different than the first form in some -cases. - -.SH KEYWORDS -case, match, regular expression diff --git a/doc/catch.n b/doc/catch.n deleted file mode 100644 index 23771f9..0000000 --- a/doc/catch.n +++ /dev/null @@ -1,70 +0,0 @@ -'\" -'\" Copyright (c) 1993-1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: catch.n,v 1.3 1999/04/16 00:46:34 stanton Exp $ -'\" -.so man.macros -.TH catch n "8.0" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -catch \- Evaluate script and trap exceptional returns -.SH SYNOPSIS -\fBcatch\fI script \fR?\fIvarName\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBcatch\fR command may be used to prevent errors from aborting command -interpretation. \fBCatch\fR calls the Tcl interpreter recursively to -execute \fIscript\fR, and always returns without raising an error, -regardless of any errors that might occur while executing \fIscript\fR. -.PP -If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer -value corresponding to one of the exceptional return codes (see tcl.h -for the definitions of code values). If the \fIvarName\fR argument is -given, then the variable it names is set to the error message from -interpreting \fIscript\fR. -.PP -If \fIscript\fR does not raise an error, \fBcatch\fR will return 0 -(TCL_OK) and set the variable to the value returned from \fIscript\fR. -.PP -Note that \fBcatch\fR catches all exceptions, including those -generated by \fBbreak\fR and \fBcontinue\fR as well as errors. The -only errors that are not caught are syntax errors found when the -script is compiled. This is because the catch command only catches -errors during runtime. When the catch statement is compiled, the -script is compiled as well and any syntax errors will generate a Tcl -error. - -.SH EXAMPLES - -The \fBcatch\fR command may be used in an \fBif\fR to branch based on -the success of a script. - -.DS -.CS -if { [catch {open $someFile w} fid] } { - puts stderr "Could not open $someFile for writing\\n$fid" - exit 1 -} -.CE -.DE -The \fBcatch\fR command will not catch compiled syntax errors. The -first time proc \fBfoo\fR is called, the body will be compiled and a -Tcl error will be generated. - -.DS -.CS -proc foo {} { - catch {expr {1 +- }} -} -.CE -.DE - -.SH KEYWORDS -catch, error diff --git a/doc/cd.n b/doc/cd.n deleted file mode 100644 index a570cdc..0000000 --- a/doc/cd.n +++ /dev/null @@ -1,28 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: cd.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH cd n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -cd \- Change working directory -.SH SYNOPSIS -\fBcd \fR?\fIdirName\fR? -.BE - -.SH DESCRIPTION -.PP -Change the current working directory to \fIdirName\fR, or to the -home directory (as specified in the HOME environment variable) if -\fIdirName\fR is not given. -Returns an empty string. - -.SH KEYWORDS -working directory diff --git a/doc/clock.n b/doc/clock.n deleted file mode 100644 index db8af8a..0000000 --- a/doc/clock.n +++ /dev/null @@ -1,188 +0,0 @@ -'\" -'\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans. -'\" 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. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: clock.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH clock n 7.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -clock \- Obtain and manipulate time -.SH SYNOPSIS -\fBclock \fIoption\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command performs one of several operations that may obtain -or manipulate strings or values that represent some notion of -time. The \fIoption\fR argument determines what action is carried -out by the command. The legal \fIoptions\fR (which may be -abbreviated) are: -.TP -\fBclock clicks\fR -Return a high-resolution time value as a system-dependent integer -value. The unit of the value is system-dependent but should be the -highest resolution clock available on the system such as a CPU cycle -counter. This value should only be used for the relative measurement -of elapsed time. -.TP -\fBclock format \fIclockValue\fR ?\fB\-format \fIstring\fR? ?\fB\-gmt \fIboolean\fR? -Converts an integer time value, typically returned by -\fBclock seconds\fR, \fBclock scan\fR, or the \fBatime\fR, \fBmtime\fR, -or \fBctime\fR options of the \fBfile\fR command, to human-readable -form. If the \fB\-format\fR argument is present the next argument is a -string that describes how the date and time are to be formatted. -Field descriptors consist of a \fB%\fR followed by a field -descriptor character. All other characters are copied into the result. -Valid field descriptors are: -.RS -.IP \fB%%\fR -Insert a %. -.IP \fB%a\fR -Abbreviated weekday name (Mon, Tue, etc.). -.IP \fB%A\fR -Full weekday name (Monday, Tuesday, etc.). -.IP \fB%b\fR -Abbreviated month name (Jan, Feb, etc.). -.IP \fB%B\fR -Full month name. -.IP \fB%c\fR -Locale specific date and time. -.IP \fB%d\fR -Day of month (01 - 31). -.IP \fB%H\fR -Hour in 24-hour format (00 - 23). -.IP \fB%I\fR -Hour in 12-hour format (00 - 12). -.IP \fB%j\fR -Day of year (001 - 366). -.IP \fB%m\fR -Month number (01 - 12). -.IP \fB%M\fR -Minute (00 - 59). -.IP \fB%p\fR -AM/PM indicator. -.IP \fB%S\fR -Seconds (00 - 59). -.IP \fB%U\fR -Week of year (01 - 52), Sunday is the first day of the week. -.IP \fB%w\fR -Weekday number (Sunday = 0). -.IP \fB%W\fR -Week of year (01 - 52), Monday is the first day of the week. -.IP \fB%x\fR -Locale specific date format. -.IP \fB%X\fR -Locale specific time format. -.IP \fB%y\fR -Year without century (00 - 99). -.IP \fB%Y\fR -Year with century (e.g. 1990) -.IP \fB%Z\fR -Time zone name. -.RE -.sp -.RS -In addition, the following field descriptors may be supported on some -systems (e.g. Unix but not Windows): -.IP \fB%D\fR -Date as %m/%d/%y. -.IP \fB%e\fR -Day of month (1 - 31), no leading zeros. -.IP \fB%h\fR -Abbreviated month name. -.IP \fB%n\fR -Insert a newline. -.IP \fB%r\fR -Time as %I:%M:%S %p. -.IP \fB%R\fR -Time as %H:%M. -.IP \fB%t\fR -Insert a tab. -.IP \fB%T\fR -Time as %H:%M:%S. -.RE -.sp -.RS -If the \fB\-format\fR argument is not specified, the format string -"\fB%a %b %d %H:%M:%S %Z %Y\fR" is used. If the \fB\-gmt\fR argument -is present the next argument must be a boolean which if true specifies -that the time will be formatted as Greenwich Mean Time. If false -then the local timezone will be used as defined by the operating -environment. -.RE -.TP -\fBclock scan \fIdateString\fR ?\fB\-base \fIclockVal\fR? ?\fB\-gmt \fIboolean\fR? -Convert \fIdateString\fR to an integer clock value (see \fBclock seconds\fR). -This command can parse and convert virtually any standard date and/or time -string, which can include standard time zone mnemonics. If only a time is -specified, the current date is assumed. If the string does not contain a -time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR -argument is true, in which case the clock value is calculated assuming -that the specified time is relative to Greenwich Mean Time. -.sp -If the \fB\-base\fR flag is specified, the next argument should contain -an integer clock value. Only the date in this value is used, not the -time. This is useful for determining the time on a specific day or -doing other date-relative conversions. -.sp -The \fIdateString\fR consists of zero or more specifications of the -following form: -.RS -.TP -\fItime\fR -A time of day, which is of the form: \fIhh\fR?\fI:mm\fR?\fI:ss\fR?? -?\fImeridian\fR? ?\fIzone\fR? or \fIhhmm \fR?\fImeridian\fR? -?\fIzone\fR?. If no meridian is specified, \fIhh\fR is interpreted on -a 24-hour clock. -.TP -\fIdate\fR -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 -.VS -than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 -as 1969-1999. Not all platforms can represent the years 38-70, so -an error may result if these years are used. -.VE -.TP -\fIrelative time\fR -A specification relative to the current time. The format is \fInumber -unit\fR acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR, -\fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The -unit can be specified as a singular or plural, as in \fB3 weeks\fR. -These modifiers may also be specified: -\fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR, -\fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR. -.RE -.sp -.RS -The actual date is calculated according to the following steps. -First, any absolute date and/or time is processed and converted. -Using that time as the base, day-of-week specifications are added. -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 and the correct date is given when going from the end -of a long month to a short month. -.RE -.TP -\fBclock seconds\fR -Return the current date and time as a system-dependent integer value. The -unit of the value is seconds, allowing it to be used for relative time -calculations. The value is usually defined as total elapsed time from -an ``epoch''. You shouldn't assume the value of the epoch. - -.SH KEYWORDS -clock, date, time diff --git a/doc/close.n b/doc/close.n deleted file mode 100644 index 2097e04..0000000 --- a/doc/close.n +++ /dev/null @@ -1,59 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: close.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH close n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -close \- Close an open channel. -.SH SYNOPSIS -\fBclose \fIchannelId\fR -.BE - -.SH DESCRIPTION -.PP -Closes the channel given by \fIchannelId\fR. \fIChannelId\fR must be a -channel identifier such as the return value from a previous \fBopen\fR -or \fBsocket\fR command. -All buffered output is flushed to the channel's output device, -any buffered input is discarded, the underlying file or device is closed, -and \fIchannelId\fR becomes unavailable for use. -.VS "" br -.PP -If the channel is blocking, the command does not return until all output -is flushed. -If the channel is nonblocking and there is unflushed output, the -channel remains open and the command -returns immediately; output will be flushed in the background and the -channel will be closed when all the flushing is complete. -.VE -.PP -If \fIchannelId\fR is a blocking channel for a command pipeline then -\fBclose\fR waits for the child processes to complete. -.VS "" br -.PP -If the channel is shared between interpreters, then \fBclose\fR -makes \fIchannelId\fR unavailable in the invoking interpreter but has no -other effect until all of the sharing interpreters have closed the -channel. -When the last interpreter in which the channel is registered invokes -\fBclose\fR, the cleanup actions described above occur. See the -\fBinterp\fR command for a description of channel sharing. -.PP -Channels are automatically closed when an interpreter is destroyed and -when the process exits. Channels are switched to blocking mode, to ensure -that all output is correctly flushed before the process exits. -.VE -.PP -The command returns an empty string, and may generate an error if -an error occurs while flushing output. - -.SH KEYWORDS -blocking, channel, close, nonblocking diff --git a/doc/concat.n b/doc/concat.n deleted file mode 100644 index a2f9c1e..0000000 --- a/doc/concat.n +++ /dev/null @@ -1,40 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: concat.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH concat n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -concat \- Join lists together -.SH SYNOPSIS -\fBconcat\fI \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command treats each argument as a list and concatenates them -into a single list. -It also eliminates leading and trailing spaces in the \fIarg\fR's -and adds a single separator space between \fIarg\fR's. -It permits any number of arguments. For example, -the command -.CS -\fBconcat a b {c d e} {f {g h}}\fR -.CE -will return -.CS -\fBa b c d e f {g h}\fR -.CE -as its result. -.PP -If no \fIarg\fRs are supplied, the result is an empty string. - -.SH KEYWORDS -concatenate, join, lists diff --git a/doc/continue.n b/doc/continue.n deleted file mode 100644 index 2faddd1..0000000 --- a/doc/continue.n +++ /dev/null @@ -1,34 +0,0 @@ -'\" -'\" Copyright (c) 1993-1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: continue.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH continue n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -continue \- Skip to the next iteration of a loop -.SH SYNOPSIS -\fBcontinue\fR -.BE - -.SH DESCRIPTION -.PP -This command is typically invoked inside the body of a looping command -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 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 -bodies. - -.SH KEYWORDS -continue, iteration, loop diff --git a/doc/dde.n b/doc/dde.n deleted file mode 100644 index c9797a6..0000000 --- a/doc/dde.n +++ /dev/null @@ -1,124 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: dde.n,v 1.2 1999/04/16 00:46:34 stanton Exp $ -'\" -.so man.macros -.TH dde n 8.1 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -dde \- Execute a Dynamic Data Exchange command -.SH SYNOPSIS -.sp -\fBpackage require dde 1.0\fR -.sp -\fBdde \fIservername \fR?\fItopic\fR? -.sp -\fBdde ?\-async?\fR \fIcommand service topic \fR?\fIdata\fR? -.BE - -.SH DESCRIPTION -.PP -This command allows an application to send Dynamic Data Exchange (DDE) -command when running under Microsoft Windows. Dynamic Data Exchange is -a mechanism where applications can exchange raw data. Each DDE -transaction needs a \fIservice name\fR and a \fItopic\fR. Both the -\fIservice name\fR and \fItopic\fR are application defined; Tcl uses -the service name \fBTclEval\fR, while the topic name is the name of the -interpreter given by \fBdde servername\fR. Other applications have their -own \fIservice names\fR and \fItopics\fR. For instance, Microsoft Excel -has the service name \fBExcel\fR. -.PP -The only option to the \fBdde\fR command is: -.TP -\fB\-async\fR -Requests asynchronous invocation. This is valid only for the -\fBexecute\fR subcommand. Normally, the \fBdde execute\fR subcommand -waits until the command completes, returning appropriate error -messages. When the \fB\-async\fR option is used, the command returns -immediately, and no error information is available. -.SH "DDE COMMANDS" -.PP -The following commands are a subset of the full Dynamic Data Exchange -set of commands. -.TP -\fBdde servername \fR?\fItopic\fR? -\fBdde servername\fR registers the interpreter as a DDE server with -the service name TclEval and the topic name specified byt \fItopic\fR. -If no \fItopic\fR is given, \fBdde servername\fR returns the name -of the current topic or the empty string if it is not registered as a service. -.TP -\fBdde execute \fIservice topic data\fR -\fBdde execute\fR takes the \fIdata\fR and sends it to the server -indicated by \fIservice\fR with the topic indicated by -\fItopic\fR. Typically, \fIservice\fR is the name of an application, -and \fItopic\fR is a file to work on. The \fIdata\fR field is given -to the remote application. Typically, the application treats the -\fIdata\fR field as a script, and the script is run in the -application. The command returns an error if the script did not -run. If the \fB\-async\fR flag was used, the command -returns immediately with no error. -.TP -\fBdde request \fIservice topic item\fR -\fBdde request\fR is typically used to get the value of something; the -value of a cell in Microsoft Excel or the text of a selection in -Microsoft Word. \fIservice\fR is typically the name of an application, -\fItopic\fR is typically the name of the file, and \fIitem\fR is -application-specific. The command returns the value of \fIitem\fR as -defined in the application. -.TP -\fBdde services \fIservice topic\fR -\fBdde services\fR returns a list of service-topic pairs that -currently exist on the machine. If \fIservice\fR and \fItopic\fR are -both null strings ({}), then all service-topic pairs currently -available on the system are returned. If \fIservice\fR is null and -\fItopic\fR is not, then all services with the specified topic are -returned. If \fIservice\fR is not null and \fItopic\fR is, all topics -for a given service are returned. If both are not null, if that -service-topic pair currently exists, it is returned; otherwise, null -is returned. -.TP -\fBdde eval \fItopic cmd \fR?\fIarg arg ...\fR? -\fBdde eval\fR evaluates a command and its arguments using the -interpreter specified by \fItopic\fR. The DDE service must be the -"TclEval" service. This command can be used to replace send on Windows. -.SH "DDE AND TCL" -A Tcl interpreter always has a service name of "TclEval". Each -different interp of all running Tcl applications should a unique -name specified by \fBdde servername\fR. Each interp is available as a -DDE topic only if the \fBdde servername\fR command was used to set the -name of the topic for each interp. So a \fBdde services TclEval {}\fR -command will return a list of service-topic pairs, where each of the -currently running interps will be a topic. -.PP -When Tcl processes a \fBdde execute\fR command, the data for the -execute is run as a script in the interp named by the topic of the -\fBdde execute\fR command. -.PP -When Tcl processes a \fBdde request\fR command, it returns the value of -the variable given in the dde command in the context of the interp -named by the dde topic. Tcl reserves the variable "$TCLEVAL$EXECUTE$RESULT" -for internal use, and \fBdde request\fR commands for that variable -will give unpredictable results. -.PP -An external application which wishes to run a script in Tcl should have -that script store its result in a variable, run the \fBdde execute\fR -command, and the run \fBdde request\fR to get the value of the -variable. -.PP -When using DDE, be careful to ensure that the event queue is flushed -using either \fBupdate\fR or \fBvwait\fR. This happens by default -when using \fBwish\fR unless a blocking command is called (such as \fBexec\fR -without adding the \fB&\fR to place the process in the background). -If for any reason the event queue is not flushed, DDE commands may -hang until the event queue is flushed. This can create a deadlock -situation. -.SH KEYWORDS -application, dde, name, remote execution -.SH "SEE ALSO" -tk, winfo, send - diff --git a/doc/encoding.n b/doc/encoding.n deleted file mode 100644 index fc6d4f7..0000000 --- a/doc/encoding.n +++ /dev/null @@ -1,79 +0,0 @@ -'\" -'\" Copyright (c) 1998 by Scriptics Corporation. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: encoding.n,v 1.2 1999/04/16 00:46:34 stanton Exp $ -'\" -.so man.macros -.TH encoding n "8.1" Tcl "Tcl Built-In Commands" -.BS -.SH NAME -encoding \- Manipulate encodings -.SH SYNOPSIS -\fBencoding \fIoption\fR ?\fIarg arg ...\fR? -.BE - -.SH INTRODUCTION -.PP -Strings in Tcl are encoded using 16-bit Unicode characters. Different -operating system interfaces or applications may generate strings in -other encodings such as Shift-JIS. The \fBencoding\fR command helps -to bridge the gap between Unicode and these other formats. - -.SH DESCRIPTION -.PP -Performs one of several encoding related operations, depending on -\fIoption\fR. The legal \fIoption\fRs are: -.TP -\fBencoding convertfrom ?\fIencoding\fR? \fIdata\fR -Convert \fIdata\fR to Unicode from the specified \fIencoding\fR. The -characters in \fIdata\fR are treated as binary data where the lower -8-bits of each character is taken as a single byte. The resulting -sequence of bytes is treated as a string in the specified -\fIencoding\fR. If \fIencoding\fR is not specified, the current -system encoding is used. -.TP -\fBencoding convertto ?\fIencoding\fR? \fIstring\fR -Convert \fIstring\fR from Unicode to the specified \fIencoding\fR. -The result is a sequence of bytes that represents the converted -string. Each byte is stored in the lower 8-bits of a Unicode -character. If \fIencoding\fR is not specified, the current -system encoding is used. -.TP -\fBencoding names\fR -Returns a list containing the names of all of the encodings that are -currently available. -.TP -\fBencoding system\fR ?\fIencoding\fR? -Set the system encoding to \fIencoding\fR. If \fIencoding\fR is -omitted then the command returns the current system encoding. The -system encoding is used whenever Tcl passes strings to system calls. - -.SH EXAMPLE -.PP -It is common practice to write script files using a text editor that -produces output in the euc-jp encoding, which represents the ASCII -characters as singe bytes and Japanese characters as two bytes. This -makes it easy to embed literal strings that correspond to non-ASCII -characters by simply typing the strings in place in the script. -However, because the \fBsource\fR command always reads files using the -ISO8859-1 encoding, Tcl will treat each byte in the file as a separate -character that maps to the 00 page in Unicode. The -resulting Tcl strings will not contain the expected Japanese -characters. Instead, they will contain a sequence of Latin-1 -characters that correspond to the bytes of the original string. The -\fBencoding\fR command can be used to convert this string to the -expected Japanese Unicode characters. For example, -.CS - set s [encoding convertfrom euc-jp "\\xA4\\xCF"] -.CE -would return the Unicode string "\\u306F", which is the Hiragana -letter HA. - -.SH "SEE ALSO" -Tcl_GetEncoding - -.SH KEYWORDS -encoding diff --git a/doc/eof.n b/doc/eof.n deleted file mode 100644 index a9f97c9..0000000 --- a/doc/eof.n +++ /dev/null @@ -1,27 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: eof.n,v 1.2 1998/09/14 18:39:51 stanton Exp $ -'\" -.so man.macros -.TH eof n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -eof \- Check for end of file condition on channel -.SH SYNOPSIS -\fBeof \fIchannelId\fR -.BE - -.SH DESCRIPTION -.PP -Returns 1 if an end of file condition occurred during the most -recent input operation on \fIchannelId\fR (such as \fBgets\fR), -0 otherwise. - -.SH KEYWORDS -channel, end of file diff --git a/doc/error.n b/doc/error.n deleted file mode 100644 index 347e26e..0000000 --- a/doc/error.n +++ /dev/null @@ -1,58 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: error.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH error n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -error \- Generate an error -.SH SYNOPSIS -\fBerror \fImessage\fR ?\fIinfo\fR? ?\fIcode\fR? -.BE - -.SH DESCRIPTION -.PP -Returns a TCL_ERROR code, which causes command interpretation to be -unwound. \fIMessage\fR is a string that is returned to the application -to indicate what went wrong. -.PP -If the \fIinfo\fR argument is provided and is non-empty, -it is used to initialize the global variable \fBerrorInfo\fR. -\fBerrorInfo\fR is used to accumulate a stack trace of what -was in progress when an error occurred; as nested commands unwind, -the Tcl interpreter adds information to \fBerrorInfo\fR. If the -\fIinfo\fR argument is present, it is used to initialize -\fBerrorInfo\fR and the first increment of unwind information -will not be added by the Tcl interpreter. In other -words, the command containing the \fBerror\fR command will not appear -in \fBerrorInfo\fR; in its place will be \fIinfo\fR. -This feature is most useful in conjunction with the \fBcatch\fR command: -if a caught error cannot be handled successfully, \fIinfo\fR can be used -to return a stack trace reflecting the original point of occurrence -of the error: -.CS -\fBcatch {...} errMsg -set savedInfo $errorInfo -\&... -error $errMsg $savedInfo\fR -.CE -.PP -If the \fIcode\fR argument is present, then its value is stored -in the \fBerrorCode\fR global variable. This variable is intended -to hold a machine-readable description of the error in cases where -such information is available; see the \fBtclvars\fR manual -page for information on the proper format for the variable. -If the \fIcode\fR argument is not -present, then \fBerrorCode\fR is automatically reset to -``NONE'' by the Tcl interpreter as part of processing the -error generated by the command. - -.SH KEYWORDS -error, errorCode, errorInfo diff --git a/doc/eval.n b/doc/eval.n deleted file mode 100644 index 698b28e..0000000 --- a/doc/eval.n +++ /dev/null @@ -1,30 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: eval.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH eval n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -eval \- Evaluate a Tcl script -.SH SYNOPSIS -\fBeval \fIarg \fR?\fIarg ...\fR? -.BE - -.SH DESCRIPTION -.PP -\fBEval\fR takes one or more arguments, which together comprise a Tcl -script containing one or more commands. -\fBEval\fR concatenates all its arguments in the same -fashion as the \fBconcat\fR command, passes the concatenated string to the -Tcl interpreter recursively, and returns the result of that -evaluation (or any error generated by it). - -.SH KEYWORDS -concatenate, evaluate, script diff --git a/doc/exec.n b/doc/exec.n deleted file mode 100644 index f30f6b0..0000000 --- a/doc/exec.n +++ /dev/null @@ -1,358 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: exec.n,v 1.3 1999/04/16 00:46:34 stanton Exp $ -'\" -.so man.macros -.TH exec n 7.6 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -exec \- Invoke subprocess(es) -.SH SYNOPSIS -\fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command treats its arguments as the specification -of one or more subprocesses to execute. -The arguments take the form of a standard shell pipeline -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 -they are treated as command-line switches and are not part -of the pipeline specification. The following switches are -currently supported: -.TP 13 -\fB\-keepnewline\fR -Retains a trailing newline in the pipeline's output. -Normally a trailing newline will be deleted. -.TP 13 -\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. -.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 -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''). -.TP 15 -| -Separates distinct commands in the pipeline. The standard output -of the preceding command will be piped into the standard input -of the next command. -.TP 15 -|& -Separates distinct commands in the pipeline. Both standard output -and standard error of the preceding command will be piped into -the standard input of the next command. -This form of redirection overrides forms such as 2> and >&. -.TP 15 -<\0\fIfileName\fR -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 -\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. -.TP 15 -<<\0\fIvalue\fR -\fIValue\fR is passed to the first command as its standard input. -.TP 15 ->\0\fIfileName\fR -Standard output from the last command is redirected to the file named -\fIfileName\fR, overwriting its previous contents. -.TP 15 -2>\0\fIfileName\fR -Standard error from all commands in the pipeline is redirected to the -file named \fIfileName\fR, overwriting its previous contents. -.TP 15 ->&\0\fIfileName\fR -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. -.TP 15 ->>\0\fIfileName\fR -Standard output from the last command is -redirected to the file named \fIfileName\fR, appending to it rather -than overwriting it. -.TP 15 -2>>\0\fIfileName\fR -Standard error from all commands in the pipeline is -redirected to the file named \fIfileName\fR, appending to it rather -than overwriting it. -.TP 15 ->>&\0\fIfileName\fR -Both standard output from the last command and standard error from -all commands are redirected to the file named \fIfileName\fR, -appending to it rather than overwriting it. -.TP 15 ->@\0\fIfileId\fR -\fIFileId\fR must be the identifier for an open file, such as the return -value from a previous call to \fBopen\fR. -Standard output from the last command is redirected to \fIfileId\fR's -file, which must have been opened for writing. -.TP 15 -2>@\0\fIfileId\fR -\fIFileId\fR must be the identifier for an open file, such as the return -value from a previous call to \fBopen\fR. -Standard error from all commands in the pipeline is -redirected to \fIfileId\fR's file. -The file must have been opened for writing. -.TP 15 ->&@\0\fIfileId\fR -\fIFileId\fR must be the identifier for an open file, such as the return -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. -.PP -If standard output has not been redirected then the \fBexec\fR -command returns the standard output from the last command -in the pipeline. -If any of the commands in the pipeline exit abnormally or -are killed or suspended, then \fBexec\fR will return an error -and the error message will include the pipeline's output followed by -error messages describing the abnormal terminations; the -\fBerrorCode\fR variable will contain additional information -about the last abnormal termination encountered. -If any of the commands writes to its standard error file and that -standard error isn't redirected, -then \fBexec\fR will return an error; the error message -will include the pipeline's standard output, followed by messages -about abnormal terminations (if any), followed by the standard error -output. -.PP -If the last character of the result or error message -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. -However, if \fB\-keepnewline\fR is specified then the trailing -newline is retained. -.PP -If standard input isn't redirected with ``<'' or ``<<'' -or ``<@'' then the standard input for the first command in the -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. -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. -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 -the commands in the pipeline will go to the application's -standard error file unless redirected. -.PP -The first word in each command is taken as the command name; -tilde-substitution is performed on it, and if the result contains -no slashes then the directories -in the PATH environment variable are searched for -an executable by the given name. -If the name contains a slash then it must refer to an executable -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 mount -point called \fBsystem\fR on the machine called \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. The \fBfile join\fR -command should be used to concatenate path components. -.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 standard Windows 95 DOS shell -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/doc/exit.n b/doc/exit.n deleted file mode 100644 index d3960f0..0000000 --- a/doc/exit.n +++ /dev/null @@ -1,28 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: exit.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH exit n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -exit \- End the application -.SH SYNOPSIS -\fBexit \fR?\fIreturnCode\fR? -.BE - -.SH DESCRIPTION -.PP -Terminate the process, returning \fIreturnCode\fR to the -system as the exit status. -If \fIreturnCode\fR isn't specified then it defaults -to 0. - -.SH KEYWORDS -exit, process diff --git a/doc/expr.n b/doc/expr.n deleted file mode 100644 index 25f6ad6..0000000 --- a/doc/expr.n +++ /dev/null @@ -1,323 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: expr.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH expr n 8.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -expr \- Evaluate an expression -.SH SYNOPSIS -\fBexpr \fIarg \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -Concatenates \fIarg\fR's (adding separator spaces between them), -evaluates the result as a Tcl expression, and returns the value. -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. -Expressions almost always yield numeric results -(integer or floating-point values). -For example, the expression -.CS -\fBexpr 8.2 + 6\fR -.CE -evaluates to 14.2. -Tcl expressions differ from C expressions in the way that -operands are specified. Also, Tcl expressions support -non-numeric operands and string comparisons. -.SH OPERANDS -.PP -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'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 -two characters of the operand are \fB0x\fR). -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 -\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 -as a string (and only a limited set of operators may be applied to -it). -.PP -Operands may be specified in any of the following ways: -.IP [1] -As an numeric value, either integer or floating-point. -.IP [2] -As a Tcl variable, using standard \fB$\fR notation. -The variable's value will be used as the operand. -.IP [3] -As a string enclosed in double-quotes. -The expression parser will perform backslash, variable, and -command substitutions on the information between the quotes, -and use the resulting value as the operand -.IP [4] -As a string enclosed in braces. -The characters between the open brace and matching close brace -will be used as the operand without any substitutions. -.IP [5] -As a Tcl command enclosed in brackets. -The command will be executed and its result will be used as -the operand. -.IP [6] -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 -functions. -.LP -Where substitutions occur above (e.g. inside quoted strings), they -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. -As discussed below, it is usually best to enclose expressions -in braces to prevent the command parser from performing substitutions -on the contents. -.PP -For some examples of simple expressions, suppose the variable -\fBa\fR has the value 3 and -the variable \fBb\fR has the value 6. -Then the command on the left side of each of the lines below -will produce the value on the right side of the line: -.CS -.ta 6c -\fBexpr 3.1 + $a 6.1 -expr 2 + "$a.$b" 5.6 -expr 4*[llength "6 2"] 8 -expr {{word one} < "word $a"} 0\fR -.CE -.SH OPERATORS -.PP -The valid operators are listed below, grouped in decreasing order -of precedence: -.TP 20 -\fB\-\0\0+\0\0~\0\0!\fR -Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands -may be applied to string operands, and bit-wise NOT may be -applied only to integers. -.TP 20 -\fB*\0\0/\0\0%\fR -Multiply, divide, remainder. None of these operands may be -applied to string operands, and remainder may be applied only -to integers. -The remainder will always have the same sign as the divisor and -an absolute value smaller than the divisor. -.TP 20 -\fB+\0\0\-\fR -Add and subtract. Valid for any numeric operands. -.TP 20 -\fB<<\0\0>>\fR -Left and right shift. Valid for integer operands only. -A right shift always propagates the sign bit. -.TP 20 -\fB<\0\0>\0\0<=\0\0>=\fR -Boolean less, greater, less than or equal, and greater than or equal. -Each operator produces 1 if the condition is true, 0 otherwise. -These operators may be applied to strings as well as numeric operands, -in which case string comparison is used. -.TP 20 -\fB==\0\0!=\fR -Boolean equal and not equal. Each operator produces a zero/one result. -Valid for all operand types. -.TP 20 -\fB&\fR -Bit-wise AND. Valid for integer operands only. -.TP 20 -\fB^\fR -Bit-wise exclusive OR. Valid for integer operands only. -.TP 20 -\fB|\fR -Bit-wise OR. Valid for integer operands only. -.TP 20 -\fB&&\fR -Logical AND. Produces a 1 result if both operands are non-zero, -0 otherwise. -Valid for boolean and numeric (integers or floating-point) operands only. -.TP 20 -\fB||\fR -Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. -Valid for boolean and numeric (integers or floating-point) operands only. -.TP 20 -\fIx\fB?\fIy\fB:\fIz\fR -If-then-else, as in C. If \fIx\fR -evaluates to non-zero, then the result is the value of \fIy\fR. -Otherwise the result is the value of \fIz\fR. -The \fIx\fR operand must have a numeric value. -.LP -See the C manual for more details on the results -produced by each operator. -All of the binary operators group left-to-right within the same -precedence level. For example, the command -.CS -\fBexpr 4*2 < 7\fR -.CE -returns 0. -.PP -The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have ``lazy -evaluation'', just as in C, -which means that operands are not evaluated if they are -not needed to determine the outcome. For example, in the command -.CS -\fBexpr {$v ? [a] : [b]}\fR -.CE -only one of \fB[a]\fR or \fB[b]\fR will actually be evaluated, -depending on the value of \fB$v\fR. Note, however, that this is -only true if the entire expression is enclosed in braces; otherwise -the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before -invoking the \fBexpr\fR command. -.SH "MATH FUNCTIONS" -.PP -Tcl supports the following mathematical functions in expressions: -.DS -.ta 3c 6c 9c -\fBacos\fR \fBcos\fR \fBhypot\fR \fBsinh\fR -\fBasin\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR -\fBatan\fR \fBexp\fR \fBlog10\fR \fBtan\fR -\fBatan2\fR \fBfloor\fR \fBpow\fR \fBtanh\fR -\fBceil\fR \fBfmod\fR \fBsin\fR -.DE -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 and the -generation of random numbers: -.TP -\fBabs(\fIarg\fB)\fR -Returns the absolute value of \fIarg\fR. \fIArg\fR may be either -integer or floating-point, and the result is returned in the same form. -.TP -\fBdouble(\fIarg\fB)\fR -If \fIarg\fR is a floating value, returns \fIarg\fR, otherwise converts -\fIarg\fR to floating and returns the converted value. -.TP -\fBint(\fIarg\fB)\fR -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(). -.SH "TYPES, OVERFLOW, AND PRECISION" -.PP -All internal computations involving integers are done with the C type -\fIlong\fR, and all internal computations involving floating-point are -done with the C type \fIdouble\fR. -When converting a string to floating-point, exponent overflow is -detected and results in a Tcl error. -For conversion to integer from string, detection of overflow depends -on the behavior of some routines in the local C library, so it should -be regarded as unreliable. -In any case, integer overflow and underflow are generally not detected -reliably for intermediate results. Floating-point overflow and underflow -are detected to the degree supported by the hardware, which is generally -pretty reliable. -.PP -Conversion among internal representations for integer, floating-point, -and string operands is done automatically as needed. -For arithmetic computations, integers are used until some -floating-point number is introduced, after which floating-point is used. -For example, -.CS -\fBexpr 5 / 4\fR -.CE -returns 1, while -.CS -\fBexpr 5 / 4.0\fR -\fBexpr 5 / ( [string length "abcd"] + 0.0 )\fR -.CE -both return 1.25. -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 \fB4.0\fR, not \fB4\fR. - -.SH "STRING OPERATIONS" -.PP -String values may be used as operands of the comparison operators, -although the expression evaluator tries to do comparisons as integer -or floating-point when it can. -If one of the operands of a comparison is a string and the other -has a numeric value, the numeric operand is converted back to -a string using the C \fIsprintf\fR format specifier -\fB%d\fR for integers and \fB%g\fR for floating-point values. -For example, the commands -.CS -\fBexpr {"0x03" > "2"}\fR -\fBexpr {"0y" < "0x12"}\fR -.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 \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. - -.SH "PERFORMANCE CONSIDERATIONS" -.VS -.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. -.VE - -.SH KEYWORDS -arithmetic, boolean, compare, expression, fuzzy comparison diff --git a/doc/fblocked.n b/doc/fblocked.n deleted file mode 100644 index 3481c7d..0000000 --- a/doc/fblocked.n +++ /dev/null @@ -1,32 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: fblocked.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -.so man.macros -.TH fblocked n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -fblocked \- Test whether the last input operation exhausted all available input -.SH SYNOPSIS -\fBfblocked \fIchannelId\fR -.BE - -.SH DESCRIPTION -.PP -The \fBfblocked\fR command returns 1 if the most recent input operation -on \fIchannelId\fR returned less information than requested because all -available input was exhausted. -For example, if \fBgets\fR is invoked when there are only three -characters available for input and no end-of-line sequence, \fBgets\fR -returns an empty string and a subsequent call to \fBfblocked\fR will -return 1. -.PP -.SH "SEE ALSO" -gets(n), read(n) - -.SH KEYWORDS -blocking, nonblocking diff --git a/doc/fconfigure.n b/doc/fconfigure.n deleted file mode 100644 index e2479e8a..0000000 --- a/doc/fconfigure.n +++ /dev/null @@ -1,200 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: fconfigure.n,v 1.3 1999/04/16 00:46:34 stanton Exp $ -'\" -.so man.macros -.TH fconfigure n 8.1 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -fconfigure \- Set and get options on a channel -.SH SYNOPSIS -.nf -\fBfconfigure \fIchannelId\fR -\fBfconfigure \fIchannelId\fR \fIname\fR -\fBfconfigure \fIchannelId\fR \fIname value \fR?\fIname value ...\fR? -.fi -.BE - -.SH DESCRIPTION -.PP -The \fBfconfigure\fR command sets and retrieves options for channels. -\fIChannelId\fR identifies the channel for which to set or query an option. -If no \fIname\fR or \fIvalue\fR arguments are supplied, the command -returns a list containing alternating option names and values for the channel. -If \fIname\fR is supplied but no \fIvalue\fR then the command returns -the current value of the given option. -If one or more pairs of \fIname\fR and \fIvalue\fR are supplied, the -command sets each of the named options to the corresponding \fIvalue\fR; -in this case the return value is an empty string. -.PP -The options described below are supported for all channels. In addition, -each channel type may add options that only it supports. See the manual -entry for the command that creates each type of channels for the options -that that specific type of channel supports. For example, see the manual -entry for the \fBsocket\fR command for its additional options. -.TP -\fB\-blocking\fR \fIboolean\fR -The \fB\-blocking\fR option determines whether I/O operations on the -channel can cause the process to block indefinitely. -The value of the option must be a proper boolean value. -Channels are normally in blocking mode; if a channel is placed into -nonblocking mode it will affect the operation of the \fBgets\fR, -\fBread\fR, \fBputs\fR, \fBflush\fR, and \fBclose\fR commands; -see the documentation for those commands for details. -For nonblocking mode to work correctly, the application must be -using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or -invoking the \fBvwait\fR command). -.TP -\fB\-buffering\fR \fInewValue\fR -. -If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output -until its internal buffer is full or until the \fBflush\fR command is -invoked. If \fInewValue\fR is \fBline\fR, then the I/O system will -automatically flush output for the channel whenever a newline character -is output. If \fInewValue\fR is \fBnone\fR, the I/O system will flush -automatically after every output operation. The default is for -\fB\-buffering\fR to be set to \fBfull\fR except for channels that -connect to terminal-like devices; for these channels the initial setting -is \fBline\fR. -.TP -\fB\-buffersize\fR \fInewSize\fR -. -\fINewvalue\fR must be an integer; its value is used to set the size of -buffers, in bytes, subsequently allocated for this channel to store input -or output. \fINewvalue\fR must be between ten and one million, allowing -buffers of ten to one million bytes in size. -.VS 8.1 br -.TP -\fB\-encoding\fR \fIname\fR -. -This option is used to specify the encoding of the channel, so that the data -can be converted to and from Unicode for use in Tcl. For instance, in -order for Tcl to read characters from a Japanese file in \fBshiftjis\fR -and properly process and display the contents, the encoding would be set -to \fBshiftjis\fR. Thereafter, when reading from the channel, the bytes in -the Japanese file would be converted to Unicode as they are read. -Writing is also supported \- as Tcl strings are written to the channel they -will automatically be converted to the specified encoding on output. -.RS -.PP -If a file contains pure binary data (for instance, a JPEG image), the -encoding for the channel should be configured to be \fBbinary\fR. Tcl -will then assign no interpretation to the data in the file and simply read or -write raw bytes. The Tcl \fBbinary\fR command can be used to manipulate this -byte-oriented data. -.PP -The default encoding for newly opened channels is the same platform- and -locale-dependent system encoding used for interfacing with the operating -system. -.RE -.VE -.TP -\fB\-eofchar\fR \fIchar\fR -.TP -\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR -. -This option supports DOS file systems that use Control-z (\ex1a) as an -end of file marker. If \fIchar\fR is not an empty string, then this -character signals end-of-file when it is encountered during input. For -output, the end-of-file character is output when the channel is closed. -If \fIchar\fR is the empty string, then there is no special end of file -character marker. For read-write channels, a two-element list specifies -the end of file marker for input and output, respectively. As a -convenience, when setting the end-of-file character for a read-write -channel you can specify a single value that will apply to both reading -and writing. When querying the end-of-file character of a read-write -channel, a two-element list will always be returned. The default value -for \fB\-eofchar\fR is the empty string in all cases except for files -under Windows. In that case the \fB\-eofchar\fR is Control-z (\ex1a) for -reading and the empty string for writing. -.TP -\fB\-translation\fR \fImode\fR -.TP -\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR -. -In Tcl scripts the end of a line is always represented using a single -newline character (\en). However, in actual files and devices the end of -a line may be represented differently on different platforms, or even for -different devices on the same platform. For example, under UNIX newlines -are used in files, whereas carriage-return-linefeed sequences are -normally used in network connections. On input (i.e., with \fBgets\fP -and \fBread\fP) the Tcl I/O system automatically translates the external -end-of-line representation into newline characters. Upon output (i.e., -with \fBputs\fP), the I/O system translates newlines to the external -end-of-line representation. The default translation mode, \fBauto\fP, -handles all the common cases automatically, but the \fB\-translation\fR -option provides explicit control over the end of line translations. -.RS -.PP -The value associated with \fB\-translation\fR is a single item for -read-only and write-only channels. The value is a two-element list for -read-write channels; the read translation mode is the first element of -the list, and the write translation mode is the second element. As a -convenience, when setting the translation mode for a read-write channel -you can specify a single value that will apply to both reading and -writing. When querying the translation mode of a read-write channel, a -two-element list will always be returned. The following values are -currently supported: -.TP -\fBauto\fR -. -As the input translation mode, \fBauto\fR treats any of newline -(\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by a -newline (\fBcrlf\fP) as the end of line representation. The end of line -representation can even change from line-to-line, and all cases are -translated to a newline. As the output translation mode, \fBauto\fR -chooses a platform specific representation; for sockets on all platforms -Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, for the -Macintosh platform it chooses \fBcr\fR and for the various flavors of -Windows it chooses \fBcrlf\fR. The default setting for -\fB\-translation\fR is \fBauto\fR for both input and output. -.VS 8.1 br -.TP -\fBbinary\fR -. -No end-of-line translations are performed. This is nearly identical to -\fBlf\fP mode, except that in addition \fBbinary\fP mode also sets the -end-of-file character to the empty string (which disables it) and sets the -encoding to \fBbinary\fR (which disables encoding filtering). See the -description of \fB\-eofchar\fR and \fB\-encoding\fR for more information. -.VE -.TP -\fBcr\fR -. -The end of a line in the underlying file or device is represented by a -single carriage return character. As the input translation mode, -\fBcr\fP mode converts carriage returns to newline characters. As the -output translation mode, \fBcr\fP mode translates newline characters to -carriage returns. This mode is typically used on Macintosh platforms. -.TP -\fBcrlf\fR -. -The end of a line in the underlying file or device is represented by a -carriage return character followed by a linefeed character. As the input -translation mode, \fBcrlf\fP mode converts carriage-return-linefeed -sequences to newline characters. As the output translation mode, -\fBcrlf\fP mode translates newline characters to carriage-return-linefeed -sequences. This mode is typically used on Windows platforms and for -network connections. -.TP -\fBlf\fR -. -The end of a line in the underlying file or device is represented by a -single newline (linefeed) character. In this mode no translations occur -during either input or output. This mode is typically used on UNIX -platforms. -.RE -.PP - -.SH "SEE ALSO" -close(n), flush(n), gets(n), puts(n), read(n), socket(n) - -.SH KEYWORDS -blocking, buffering, carriage return, end of line, flushing, linemode, -newline, nonblocking, platform, translation, encoding, filter, byte array, -binary diff --git a/doc/fcopy.n b/doc/fcopy.n deleted file mode 100644 index 5261f70..0000000 --- a/doc/fcopy.n +++ /dev/null @@ -1,127 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: fcopy.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.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/doc/file.n b/doc/file.n deleted file mode 100644 index 79644e9..0000000 --- a/doc/file.n +++ /dev/null @@ -1,331 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: file.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH file n 7.6 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -file \- Manipulate file names and attributes -.SH SYNOPSIS -\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -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). \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 -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'' -on the Macintosh). If \fIname\fR refers to a root directory, then the -root directory is returned. For example, -.RS -.CS -\fBfile dirname c:/\fR -.CE -returns \fBc:/\fR. -.PP -Note that tilde substitution will only be -performed if it is necessary to complete the command. For example, -.CS -\fBfile dirname ~/src/foo.c\fR -.CE -returns \fB~/src\fR, whereas -.CS -\fBfile dirname ~\fR -.CE -returns \fB/home\fR (or something similar). -.RE -.TP -\fBfile executable \fIname\fR -. -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. -.TP -\fBfile isdirectory \fIname\fR -. -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. -.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 -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, -.RS -.CS -\fBfile join a b /foo bar\fR -.CE -returns \fB/foo/bar\fR. -.PP -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 -.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 -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. -.VS -.TP -\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 -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. -.TP -\fBfile readable \fIname\fR -. -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. -.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 -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. -.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. -For example, under Unix -.RS -.CS -\fBfile split /foo/~bar/baz\fR -.CE -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 -.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. -.TP -\fBfile tail \fIname\fR -. -Returns all of the characters in \fIname\fR after the last directory -separator. If \fIname\fR contains no separators then returns -\fIname\fR. -.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. -.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. -.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. - -.SH "SEE ALSO" -filename - -.SH KEYWORDS -attributes, copy files, delete files, directory, file, move files, name, rename files, stat diff --git a/doc/fileevent.n b/doc/fileevent.n deleted file mode 100644 index 99051ee..0000000 --- a/doc/fileevent.n +++ /dev/null @@ -1,109 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: fileevent.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH fileevent n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -fileevent \- Execute a script when a channel becomes readable or writable -.SH SYNOPSIS -\fBfileevent \fIchannelId \fBreadable \fR?\fIscript\fR? -.sp -\fBfileevent \fIchannelId \fBwritable \fR?\fIscript\fR? -.BE - -.SH DESCRIPTION -.PP -This command is used to create \fIfile event handlers\fR. A file event -handler is a binding between a channel and a script, such that the script -is evaluated whenever the channel becomes readable or writable. File event -handlers are most commonly used to allow data to be received from another -process on an event-driven basis, so that the receiver can continue to -interact with the user while waiting for the data to arrive. If an -application invokes \fBgets\fR or \fBread\fR on a blocking channel when -there is no input data available, the process will block; until the input -data arrives, it will not be able to service other events, so it will -appear to the user to ``freeze up''. With \fBfileevent\fR, the process can -tell when data is present and only invoke \fBgets\fR or \fBread\fR when -they won't block. -.PP -The \fIchannelId\fR argument to \fBfileevent\fR refers to an open channel, -such as the return value from a previous \fBopen\fR or \fBsocket\fR -command. -If the \fIscript\fR argument is specified, then \fBfileevent\fR -creates a new event handler: \fIscript\fR will be evaluated -whenever the channel becomes readable or writable (depending on the -second argument to \fBfileevent\fR). -In this case \fBfileevent\fR returns an empty string. -The \fBreadable\fR and \fBwritable\fR event handlers for a file -are independent, and may be created and deleted separately. -However, there may be at most one \fBreadable\fR and one \fBwritable\fR -handler for a file at a given time in a given interpreter. -If \fBfileevent\fR is called when the specified handler already -exists in the invoking interpreter, the new script replaces the old one. -.PP -If the \fIscript\fR argument is not specified, \fBfileevent\fR -returns the current script for \fIchannelId\fR, or an empty string -if there is none. -If the \fIscript\fR argument is specified as an empty string -then the event handler is deleted, so that no script will be invoked. -A file event handler is also deleted automatically whenever -its channel is closed or its interpreter is deleted. -.PP -A channel is considered to be readable if there is unread data -available on the underlying device. -A channel is also considered to be readable if there is unread -data in an input buffer, except in the special case where the -most recent attempt to read from the channel was a \fBgets\fR -call that could not find a complete line in the input buffer. -This feature allows a file to be read a line at a time in nonblocking mode -using events. -A channel is also considered to be readable if an end of file or -error condition is present on the underlying file or device. -It is important for \fIscript\fR to check for these conditions -and handle them appropriately; for example, if there is no special -check for end of file, an infinite loop may occur where \fIscript\fR -reads no data, returns, and is immediately invoked again. -.PP -A channel is considered to be writable if at least one byte of data -can be written to the underlying file or device without blocking, -or if an error condition is present on the underlying file or device. -.PP -Event-driven I/O works best for channels that have been -placed into nonblocking mode with the \fBfconfigure\fR command. -In blocking mode, a \fBputs\fR command may block if you give it -more data than the underlying file or device can accept, and a -\fBgets\fR or \fBread\fR command will block if you attempt to read -more data than is ready; no events will be processed while the -commands block. -In nonblocking mode \fBputs\fR, \fBread\fR, and \fBgets\fR never block. -See the documentation for the individual commands for information -on how they handle blocking and nonblocking channels. -.PP -The script for a file event is executed at global level (outside the -context of any Tcl procedure) in the interpreter in which the -\fBfileevent\fR command was invoked. -If an error occurs while executing the script then the -\fBbgerror\fR mechanism is used to report the error. -In addition, the file event handler is deleted if it ever returns -an error; this is done in order to prevent infinite loops due to -buggy handlers. - -.SH CREDITS -.PP -\fBfileevent\fR is based on the \fBaddinput\fR command created -by Mark Diekhans. - -.SH "SEE ALSO" -bgerror, fconfigure, gets, puts, read - -.SH KEYWORDS -asynchronous I/O, blocking, channel, event handler, nonblocking, readable, -script, writable. diff --git a/doc/filename.n b/doc/filename.n deleted file mode 100644 index dd82a86..0000000 --- a/doc/filename.n +++ /dev/null @@ -1,197 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: filename.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH filename n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -filename \- File name conventions supported by Tcl commands -.BE -.SH INTRODUCTION -.PP -All Tcl commands and C procedures that take file names as arguments -expect the file names to be in one of three forms, depending on the -current platform. On each platform, Tcl supports file names in the -standard forms(s) for that platform. In addition, on all platforms, -Tcl supports a Unix-like syntax intended to provide a convenient way -of constructing simple file names. However, scripts that are intended -to be portable should not assume a particular form for file names. -Instead, portable scripts must use the \fBfile split\fR and \fBfile -join\fR commands to manipulate file names (see the \fBfile\fR manual -entry for more details). - -.SH PATH TYPES -.PP -File names are grouped into three general types based on the starting point -for the path used to specify the file: absolute, relative, and -volume-relative. Absolute names are completely qualified, giving a path to -the file relative to a particular volume and the root directory on that -volume. Relative names are unqualified, giving a path to the file relative -to the current working directory. Volume-relative names are partially -qualified, either giving the path relative to the root directory on the -current volume, or relative to the current directory of the specified -volume. The \fBfile pathtype\fR command can be used to determine the -type of a given path. - -.SH PATH SYNTAX -.PP -The rules for native names depend on the value reported in the Tcl -array element \fBtcl_platform(platform)\fR: -.TP 10 -\fBmac\fR -On Apple Macintosh systems, Tcl supports two forms of path names. The -normal Mac style names use colons as path separators. Paths may be -relative or absolute, and file names may contain any character other -than colon. A leading colon causes the rest of the path to be -interpreted relative to the current directory. If a path contains a -colon that is not at the beginning, then the path is interpreted as an -absolute path. Sequences of two or more colons anywhere in the path -are used to construct relative paths where \fB::\fR refers to the -parent of the current directory, \fB:::\fR refers to the parent of the -parent, and so forth. -.RS -.PP -In addition to Macintosh style names, Tcl also supports a subset of -Unix-like names. If a path contains no colons, then it is interpreted -like a Unix path. Slash is used as the path separator. The file name -\fB\&.\fR refers to the current directory, and \fB\&..\fR refers to the -parent of the current directory. However, some names like \fB/\fR or -\fB/..\fR have no mapping, and are interpreted as Macintosh names. In -general, commands that generate file names will return Macintosh style -names, but commands that accept file names will take both Macintosh -and Unix-style names. -.PP -The following examples illustrate various forms of path names: -.TP 15 -\fB:\fR -Relative path to the current folder. -.TP 15 -\fBMyFile\fR -Relative path to a file named \fBMyFile\fR in the current folder. -.TP 15 -\fBMyDisk:MyFile\fR -Absolute path to a file named \fBMyFile\fR on the device named \fBMyDisk\fR. -.TP 15 -\fB:MyDir:MyFile\fR -Relative path to a file name \fBMyFile\fR in a folder named -\fBMyDir\fR in the current folder. -.TP 15 -\fB::MyFile\fR -Relative path to a file named \fBMyFile\fR in the folder above the -current folder. -.TP 15 -\fB:::MyFile\fR -Relative path to a file named \fBMyFile\fR in the folder two levels above the -current folder. -.TP 15 -\fB/MyDisk/MyFile\fR -Absolute path to a file named \fBMyFile\fR on the device named -\fBMyDisk\fR. -.TP 15 -\fB\&../MyFile\fR -Relative path to a file named \fBMyFile\fR in the folder above the -current folder. -.RE -.TP -\fBunix\fR -On Unix platforms, Tcl uses path names where the components are -separated by slashes. Path names may be relative or absolute, and -file names may contain any character other than slash. The file names -\fB\&.\fR and \fB\&..\fR are special and refer to the current directory -and the parent of the current directory respectively. Multiple -adjacent slash characters are interpreted as a single separator. -The following examples illustrate various forms of path names: -.RS -.TP 15 -\fB/\fR -Absolute path to the root directory. -.TP 15 -\fB/etc/passwd\fR -Absolute path to the file named \fBpasswd\fR in the directory -\fBetc\fR in the root directory. -.TP 15 -\fB\&.\fR -Relative path to the current directory. -.TP 15 -\fBfoo\fR -Relative path to the file \fBfoo\fR in the current directory. -.TP 15 -\fBfoo/bar\fR -Relative path to the file \fBbar\fR in the directory \fBfoo\fR in the -current directory. -.TP 15 -\fB\&../foo\fR -Relative path to the file \fBfoo\fR in the directory above the current -directory. -.RE -.TP -\fBwindows\fR -On Microsoft Windows platforms, Tcl supports both drive-relative and UNC -style names. Both \fB/\fR and \fB\e\fR may be used as directory separators -in either type of name. Drive-relative names consist of an optional drive -specifier followed by an absolute or relative path. UNC paths follow the -general form \fB\e\eservername\esharename\epath\efile\fR. In both forms, -the file names \fB.\fR and \fB..\fR are special and refer to the current -directory and the parent of the current directory respectively. The -following examples illustrate various forms of path names: -.RS -.TP 15 -\fB\&\e\eHost\eshare/file\fR -Absolute UNC path to a file called \fBfile\fR in the root directory of -the export point \fBshare\fR on the host \fBHost\fR. -.TP 15 -\fBc:foo\fR -Volume-relative path to a file \fBfoo\fR in the current directory on drive -\fBc\fR. -.TP 15 -\fBc:/foo\fR -Absolute path to a file \fBfoo\fR in the root directory of drive -\fBc\fR. -.TP 15 -\fBfoo\ebar\fR -Relative path to a file \fBbar\fR in the \fBfoo\fR directory in the current -directory on the current volume. -.TP 15 -\fB\&\efoo\fR -Volume-relative path to a file \fBfoo\fR in the root directory of the current -volume. -.RE - -.SH TILDE SUBSTITUTION -.PP -In addition to the file name rules described above, Tcl also supports -\fIcsh\fR-style tilde substitution. If a file name starts with a -tilde, then the file name will be interpreted as if the first element -is replaced with the location of the home directory for the given -user. If the tilde is followed immediately by a separator, then the -\fB$HOME\fR environment variable is substituted. Otherwise the -characters between the tilde and the next separator are taken as a -user name, which is used to retrieve the user's home directory for -substitution. -.PP -The Macintosh and Windows platforms do not support tilde substitution -when a user name follows the tilde. On these platforms, attempts to -use a tilde followed by a user name will generate an error. File -names that have a tilde without a user name will be substituted using -the \fB$HOME\fR environment variable, just like for Unix. - -.SH PORTABILITY ISSUES -.PP -Not all file systems are case sensitive, so scripts should avoid code -that depends on the case of characters in a file name. In addition, -the character sets allowed on different devices may differ, so scripts -should choose file names that do not contain special characters like: -\fB<>:"/\e|\fR. The safest approach is to use names consisting of -alphanumeric characters only. Also Windows 3.1 only supports file -names with a root of no more than 8 characters and an extension of no -more than 3 characters. - -.SH KEYWORDS -current directory, absolute file name, relative file name, -volume-relative file name, portability diff --git a/doc/flush.n b/doc/flush.n deleted file mode 100644 index d88ccec..0000000 --- a/doc/flush.n +++ /dev/null @@ -1,35 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: flush.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH flush n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -flush \- Flush buffered output for a channel -.SH SYNOPSIS -\fBflush \fIchannelId\fR -.BE - -.SH DESCRIPTION -.PP -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. -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. - -.SH "SEE ALSO" -open(n), socket(n) - -.SH KEYWORDS -blocking, buffer, channel, flush, nonblocking, output diff --git a/doc/for.n b/doc/for.n deleted file mode 100644 index 73abb9f..0000000 --- a/doc/for.n +++ /dev/null @@ -1,60 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: for.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH for n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -for \- ``For'' loop -.SH SYNOPSIS -\fBfor \fIstart test next body\fR -.BE - -.SH DESCRIPTION -.PP -\fBFor\fR is a looping command, similar in structure to the C -\fBfor\fR statement. The \fIstart\fR, \fInext\fR, and -\fIbody\fR arguments must be Tcl command strings, and \fItest\fR -is an expression string. -The \fBfor\fR command first invokes the Tcl interpreter to -execute \fIstart\fR. Then it repeatedly evaluates \fItest\fR as -an expression; if the result is non-zero it invokes the Tcl -interpreter on \fIbody\fR, then invokes the Tcl interpreter on \fInext\fR, -then repeats the loop. The command terminates when \fItest\fR evaluates -to 0. If a \fBcontinue\fR command is invoked within \fIbody\fR then -any remaining commands in the current execution of \fIbody\fR are skipped; -processing continues by invoking the Tcl interpreter on \fInext\fR, then -evaluating \fItest\fR, and so on. If a \fBbreak\fR command is invoked -within \fIbody\fR -or \fInext\fR, -then the \fBfor\fR command will -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/doc/foreach.n b/doc/foreach.n deleted file mode 100644 index 213a6fc..0000000 --- a/doc/foreach.n +++ /dev/null @@ -1,86 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: foreach.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH foreach n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -foreach \- Iterate over all elements in one or more lists -.SH SYNOPSIS -\fBforeach \fIvarname list body\fR -.br -\fBforeach \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR -.BE - -.SH DESCRIPTION -.PP -The \fBforeach\fR command implements a loop where the loop -variable(s) take on values from one or more lists. -In the simplest case there is one loop variable, \fIvarname\fR, -and one list, \fIlist\fR, that is a list of values to assign to \fIvarname\fR. -The \fIbody\fR argument is a Tcl script. -For each element of \fIlist\fR (in order -from first to last), \fBforeach\fR assigns the contents of the -element to \fIvarname\fR as if the \fBlindex\fR command had been used -to extract the element, then calls the Tcl interpreter to execute -\fIbody\fR. -.PP -In the general case there can be more than one value list -(e.g., \fIlist1\fR and \fIlist2\fR), -and each value list can be associated with a list of loop variables -(e.g., \fIvarlist1\fR and \fIvarlist2\fR). -During each iteration of the loop -the variables of each \fIvarlist\fP are assigned -consecutive values from the corresponding \fIlist\fP. -Values in each \fIlist\fP are used in order from first to last, -and each value is used exactly once. -The total number of loop iterations is large enough to use -up all the values from all the value lists. -If a value list does not contain enough -elements for each of its loop variables in each iteration, -empty values are used for the missing elements. -.PP -The \fBbreak\fR and \fBcontinue\fR statements may be -invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR -command. \fBForeach\fR returns an empty string. -.SH EXAMPLES -.PP -The following loop uses i and j as loop variables to iterate over -pairs of elements of a single list. -.DS -set x {} -foreach {i j} {a b c d e f} { - lappend x $j $i -} -# The value of x is "b a d c f e" -# There are 3 iterations of the loop. -.DE -.PP -The next loop uses i and j to iterate over two lists in parallel. -.DS -set x {} -foreach i {a b c} j {d e f g} { - lappend x $i $j -} -# The value of x is "a d b e c f {} g" -# There are 4 iterations of the loop. -.DE -.PP -The two forms are combined in the following example. -.DS -set x {} -foreach i {a b c} {j k} {d e f g} { - lappend x $i $j $k -} -# The value of x is "a d e b f g c {} {}" -# There are 3 iterations of the loop. -.DE -.SH KEYWORDS -foreach, iteration, list, looping diff --git a/doc/format.n b/doc/format.n deleted file mode 100644 index 9f737e0..0000000 --- a/doc/format.n +++ /dev/null @@ -1,214 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: format.n,v 1.3 1999/04/16 00:46:34 stanton Exp $ -'\" -.so man.macros -.TH format n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -format \- Format a string in the style of sprintf -.SH SYNOPSIS -\fBformat \fIformatString \fR?\fIarg arg ...\fR? -.BE - -.SH INTRODUCTION -.PP -This command generates a formatted string in the same way as the -ANSI C \fBsprintf\fR procedure (it uses \fBsprintf\fR in its -implementation). -\fIFormatString\fR indicates how to format the result, using -\fB%\fR conversion specifiers as in \fBsprintf\fR, and the additional -arguments, if any, provide values to be substituted into the result. -The return value from \fBformat\fR is the formatted string. - -.SH "DETAILS ON FORMATTING" -.PP -The command operates by scanning \fIformatString\fR from left to right. -Each character from the format string is appended to the result -string unless it is a percent sign. -If the character is a \fB%\fR then it is not copied to the result string. -Instead, the characters following the \fB%\fR character are treated as -a conversion specifier. -The conversion specifier controls the conversion of the next successive -\fIarg\fR to a particular format and the result is appended to -the result string in place of the conversion specifier. -If there are multiple conversion specifiers in the format string, -then each one controls the conversion of one additional \fIarg\fR. -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: -an XPG3 position specifier, -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 -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. -Instead, it is taken from the argument indicated by the number, -where 1 corresponds to the first \fIarg\fR. -If the conversion specifier requires multiple arguments because -of \fB*\fR characters in the specifier then -successive arguments are used, starting with the argument -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. -.PP -The second portion of a conversion specifier may contain any of the -following flag characters, in any order: -.TP 10 -\fB\-\fR -Specifies that the converted argument should be left-justified -in its field (numbers are normally right-justified with leading -spaces if needed). -.TP 10 -\fB+\fR -Specifies that a number should always be printed with a sign, -even if positive. -.TP 10 -\fIspace\fR -Specifies that a space should be added to the beginning of the -number if the first character isn't a sign. -.TP 10 -\fB0\fR -Specifies that the number should be padded on the left with -zeroes instead of spaces. -.TP 10 -\fB#\fR -Requests an alternate output form. For \fBo\fR and \fBO\fR -conversions it guarantees that the first digit is always \fB0\fR. -For \fBx\fR or \fBX\fR conversions, \fB0x\fR or \fB0X\fR (respectively) -will be added to the beginning of the result unless it is zero. -For all floating-point conversions (\fBe\fR, \fBE\fR, \fBf\fR, -\fBg\fR, and \fBG\fR) it guarantees that the result always -has a decimal point. -For \fBg\fR and \fBG\fR conversions it specifies that -trailing zeroes should not be removed. -.PP -The third portion of a conversion specifier is a number giving a -minimum field width for this conversion. -It is typically used to make columns line up in tabular printouts. -If the converted argument contains fewer characters than the -minimum field width then it will be padded so that it is as wide -as the minimum field width. -Padding normally occurs by adding extra spaces on the left of the -converted argument, but the \fB0\fR and \fB\-\fR flags -may be used to specify padding with zeroes on the left or with -spaces on the right, respectively. -If the minimum field width is specified as \fB*\fR rather than -a number, then the next argument to the \fBformat\fR command -determines the minimum field width; it must be a numeric string. -.PP -The fourth portion of a conversion specifier is a precision, -which consists of a period followed by a number. -The number is used in different ways for different conversions. -For \fBe\fR, \fBE\fR, and \fBf\fR conversions it specifies the number -of digits to appear to the right of the decimal point. -For \fBg\fR and \fBG\fR conversions it specifies the total number -of digits to appear, including those on both sides of the decimal -point (however, trailing zeroes after the decimal point will still -be omitted unless the \fB#\fR flag has been specified). -For integer conversions, it specifies a minimum number of digits -to print (leading zeroes will be added if necessary). -For \fBs\fR conversions it specifies the maximum number of characters to be -printed; if the string is longer than this then the trailing characters will be dropped. -If the precision is specified with \fB*\fR rather than a number -then the next argument to the \fBformat\fR command determines the precision; -it must be a numeric string. -.PP -The fifth part of a conversion specifier is a length modifier, -which must be \fBh\fR or \fBl\fR. -If it is \fBh\fR it specifies that the numeric value should be -truncated to a 16-bit value before converting. -This option is rarely useful. -The \fBl\fR modifier is ignored. -.PP -The last thing in a conversion specifier is an alphabetic character -that determines what kind of conversion to perform. -The following conversion characters are currently supported: -.TP 10 -\fBd\fR -Convert integer to signed decimal string. -.TP 10 -\fBu\fR -Convert integer to unsigned decimal string. -.TP 10 -\fBi\fR -Convert integer to signed decimal string; the integer may either be -in decimal, in octal (with a leading \fB0\fR) or in hexadecimal -(with a leading \fB0x\fR). -.TP 10 -\fBo\fR -Convert integer to unsigned octal string. -.TP 10 -\fBx\fR or \fBX\fR -Convert integer to unsigned hexadecimal string, using digits -``0123456789abcdef'' for \fBx\fR and ``0123456789ABCDEF'' for \fBX\fR). -.VS -.TP 10 -\fBc\fR -Convert integer to the Unicode character it represents. -.VE -.TP 10 -\fBs\fR -No conversion; just insert string. -.TP 10 -\fBf\fR -Convert floating-point number to signed decimal string of -the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by -the precision (default: 6). -If the precision is 0 then no decimal point is output. -.TP 10 -\fBe\fR or \fBe\fR -Convert floating-point number to scientific notation in the -form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined -by the precision (default: 6). -If the precision is 0 then no decimal point is output. -If the \fBE\fR form is used then \fBE\fR is -printed instead of \fBe\fR. -.TP 10 -\fBg\fR or \fBG\fR -If the exponent is less than \-4 or greater than or equal to the -precision, then convert floating-point number as for \fB%e\fR or -\fB%E\fR. -Otherwise convert as for \fB%f\fR. -Trailing zeroes and a trailing decimal point are omitted. -.TP 10 -\fB%\fR -No conversion: just insert \fB%\fR. -.LP -For the numerical conversions the argument being converted must -be an integer or floating-point string; format converts the argument -to binary and then converts it back to a string according to -the conversion specifier. - -.SH "DIFFERENCES FROM ANSI SPRINTF" -.PP -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. -.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] -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. - -.SH KEYWORDS -conversion specifier, format, sprintf, string, substitution diff --git a/doc/gets.n b/doc/gets.n deleted file mode 100644 index 9a1c477..0000000 --- a/doc/gets.n +++ /dev/null @@ -1,50 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: gets.n,v 1.2 1998/09/14 18:39:52 stanton Exp $ -'\" -.so man.macros -.TH gets n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -gets \- Read a line from a channel -.SH SYNOPSIS -\fBgets \fIchannelId\fR ?\fIvarName\fR? -.BE - -.SH DESCRIPTION -.PP -This command reads the next line from \fIchannelId\fR, returns everything -in the line up to (but not including) the end-of-line character(s), and -discards the end-of-line character(s). -If \fIvarName\fR is omitted the line is returned as the result of the -command. -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 -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 -line of input available, the command returns an empty string and -does not consume any input. -If \fIvarName\fR is specified and an empty string is returned in -\fIvarName\fR because of end-of-file or because of insufficient -data in nonblocking mode, then the return count is -1. -Note that if \fIvarName\fR is not specified then the end-of-file -and no-full-line-available cases can -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. - -.SH "SEE ALSO" -eof(n), fblocked(n) - -.SH KEYWORDS -blocking, channel, end of file, end of line, line, nonblocking, read diff --git a/doc/glob.n b/doc/glob.n deleted file mode 100644 index 47c4e50..0000000 --- a/doc/glob.n +++ /dev/null @@ -1,93 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: glob.n,v 1.3 1999/04/16 00:46:35 stanton Exp $ -'\" -.so man.macros -.TH glob n 8.1 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -glob \- Return names of files that match patterns -.SH SYNOPSIS -\fBglob \fR?\fIswitches\fR? \fIpattern \fR?\fIpattern ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command performs file name ``globbing'' in a fashion similar to -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 -they are treated as switches. The following switches are -currently supported: -.TP 15 -\fB\-nocomplain\fR -Allows an empty list to be returned without error; without this -switch an error is returned if the result list would be empty. -.TP 15 -\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. -.PP -The \fIpattern\fR arguments may contain any of the following -special characters: -.TP 10 -\fB?\fR -Matches any single character. -.TP 10 -\fB*\fR -Matches any sequence of zero or more characters. -.TP 10 -\fB[\fIchars\fB]\fR -Matches any single character in \fIchars\fR. If \fIchars\fR -contains a sequence of the form \fIa\fB\-\fIb\fR then any -character between \fIa\fR and \fIb\fR (inclusive) will match. -.TP 10 -\fB\e\fIx\fR -Matches the character \fIx\fR. -.TP 10 -\fB{\fIa\fB,\fIb\fB,\fI...\fR} -Matches any of the strings \fIa\fR, \fIb\fR, etc. -.LP -As with csh, a ``.'' at the beginning of a file's name or just -after a ``/'' must be matched explicitly or with a {} construct. -In addition, all ``/'' characters must be matched explicitly. -.LP -If the first character in a \fIpattern\fR is ``~'' then it refers -to the home directory for the user whose name follows the ``~''. -If the ``~'' is followed immediately by ``/'' then the value of -the HOME environment variable is used. -.LP -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). -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. - -.SH PORTABILITY ISSUES -.PP -Unlike other Tcl commands that will accept both network and native -style names (see the \fBfilename\fR manual entry for details on how -native and network names are specified), the \fBglob\fR command only -accepts native names. -.VS 8.1 -.TP -\fBWindows\fR -. -For Windows UNC names, the servername and sharename components of the path -may not contain ?, *, or [] constructs. On Windows NT, if \fIpattern\fR is -of the form ``\fB~\fIusername\fB@\fIdomain\fR'' it refers to the home -directory of the user whose account information resides on the specified NT -domain server. Otherwise, user account information is obtained from -the local computer. -.VE - -.SH KEYWORDS -exist, file, glob, pattern diff --git a/doc/global.n b/doc/global.n deleted file mode 100644 index 252cbfb..0000000 --- a/doc/global.n +++ /dev/null @@ -1,35 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: global.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH global n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -global \- Access global variables -.SH SYNOPSIS -\fBglobal \fIvarname \fR?\fIvarname ...\fR? -.BE - -.SH DESCRIPTION -.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. -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, namespace, procedure, variable diff --git a/doc/history.n b/doc/history.n deleted file mode 100644 index 4e0716a..0000000 --- a/doc/history.n +++ /dev/null @@ -1,104 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: history.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH history n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -history \- Manipulate the history list -.SH SYNOPSIS -\fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBhistory\fR command performs one of several operations related to -recently-executed commands recorded in a history list. Each of -these recorded commands is referred to as an ``event''. When -specifying an event to the \fBhistory\fR command, the following -forms may be used: -.IP [1] -A number: if positive, it refers to the event with -that number (all events are numbered starting at 1). If the number -is negative, it selects an event relative to the current event -(\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and -so on). Event \fB0\fP refers to the current event. -.IP [2] -A string: selects the most recent event that matches the string. -An event is considered to match the string either if the string is -the same as the first characters of the event, or if the string -matches the event in the sense of the \fBstring match\fR command. -.PP -The \fBhistory\fR command can take any of the following forms: -.TP -\fBhistory\fR -Same -as \fBhistory info\fR, described below. -.TP -\fBhistory add\fI command \fR?\fBexec\fR? -Adds the \fIcommand\fR argument to the history list as a new event. If -\fBexec\fR is specified (or abbreviated) then the command is also -executed and its result is returned. If \fBexec\fR isn't specified -then an empty string is returned as result. -.TP -\fBhistory change\fI newValue\fR ?\fIevent\fR? -Replaces the value recorded for an event with \fInewValue\fR. \fIEvent\fR -specifies the event to replace, and -defaults to the \fIcurrent\fR event (not event \fB\-1\fR). This command -is intended for use in commands that implement new forms of history -substitution and wish to replace the current event (which invokes the -substitution) with the command created through substitution. The return -value is an empty string. -.TP -\fBhistory clear\fR -Erase the history list. The current keep limit is retained. -The history event numbers are reset. -.TP -\fBhistory event\fR ?\fIevent\fR? -Returns the value of the event given by \fIevent\fR. \fIEvent\fR -defaults to \fB\-1\fR. -.TP -\fBhistory info \fR?\fIcount\fR? -Returns a formatted string (intended for humans to read) giving -the event number and contents for each of the events in the history -list except the current event. If \fIcount\fR is specified -then only the most recent \fIcount\fR events are returned. -.TP -\fBhistory keep \fR?\fIcount\fR? -This command may be used to change the size of the history list to -\fIcount\fR events. Initially, 20 events are retained in the history -list. If \fIcount\fR is not specified, the current keep limit is returned. -.TP -\fBhistory nextid\fR -Returns the number of the next event to be recorded -in the history list. It is useful for things like printing the -event number in command-line prompts. -.TP -\fBhistory redo \fR?\fIevent\fR? -Re-executes the command indicated by \fIevent\fR and return its result. -\fIEvent\fR defaults to \fB\-1\fR. This command results in history -revision: see below for details. -.SH "HISTORY REVISION" -.PP -Pre-8.0 Tcl had a complex history revision mechanism. -The current mechanism is more limited, and the old -history operations \fBsubstitute\fP and \fBwords\fP have been removed. -(As a consolation, the \fBclear\fP operation was added.) -.PP -The history option \fBredo\fR results in much simpler ``history revision''. -When this option is invoked then the most recent event -is modified to eliminate the history command and replace it with -the result of the history command. -If you want to redo an event without modifying history, then use -the \fBevent\fP operation to retrieve some event, -and the \fBadd\fP operation to add it to history and execute it. - -.SH KEYWORDS -event, history, record diff --git a/doc/http.n b/doc/http.n deleted file mode 100644 index 7fd61ce..0000000 --- a/doc/http.n +++ /dev/null @@ -1,362 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: http.n,v 1.3 1999/04/16 00:46:35 stanton Exp $ -'\" -.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 ?2.0?\fP -.sp -\fB::http::config \fI?options?\fR -.sp -\fB::http::geturl \fIurl ?options?\fR -.sp -\fB::http::formatQuery \fIlist\fR -.sp -\fB::http::reset \fItoken\fR -.sp -\fB::http::wait \fItoken\fR -.sp -\fB::http::status \fItoken\fR -.sp -\fB::http::size \fItoken\fR -.sp -\fB::http::code \fItoken\fR -.sp -\fB::http::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 \fB::http::geturl\fR procedure does a HTTP transaction. -Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction -is performed. -The return value of \fB::http::geturl\fR is a token for the transaction. -The value is also the name of an array in the ::http namespace - 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. -\fB::http::geturl\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 \fB::http::wait\fR after calling -\fB::http::geturl\fR to start the event loop. -.SH COMMANDS -.TP -\fB::http::config\fP ?\fIoptions\fR? -The \fB::http::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 -\fB::http::geturl\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 2.0."\fR -.RE -.TP -\fB::http::geturl\fP \fIurl\fP ?\fIoptions\fP? -The \fB::http::geturl \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 \fB::http::geturl\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 \fB::http::geturl\fR command blocks until the operation -completes, unless the \fB\-command\fR option specifies a callback -that is invoked when the HTTP transaction completes. -\fB::http::geturl\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 \fB::http::geturl\fP to return immediately. -The \fIcallback\fP gets an additional argument that is the \fItoken\fR returned -from \fB::http::geturl\fR. This token is the name of an 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 -\fB::http::geturl\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 -\fB::http::geturl\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 \fB::http::geturl\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 \fB::http::formatQuery\fR procedure can be used to -do the formatting. -.TP -\fB\-timeout\fP \fImilliseconds\fP -If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout -to occur after the specified number of milliseconds. -A timeout results in a call to \fB::http::reset\fP and to -the \fB-command\fP callback, if specified. -The return value of \fB::http::status\fP is \fBtimeout\fP -after a timeout has occurred. -.TP -\fB\-validate\fP \fIboolean\fP -If \fIboolean\fR is non-zero, then \fB::http::geturl\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 -\fB::http::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 \fB::http::geturl\fR. -.TP -\fB::http::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 -\fB::http::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 -\fB::http::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 -\fB::http::status\fP \fItoken\fP -This is a convenience procedure that returns the \fBstatus\fP element of -the state array. -.TP -\fB::http::code\fP \fItoken\fP -This is a convenience procedure that returns the \fBhttp\fP element of the -state array. -.TP -\fB::http::size\fP \fItoken\fP -This is a convenience procedure that returns the \fBcurrentsize\fP -element of the state array. -.SH "STATE ARRAY" -The \fB::http::geturl\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 -Once the data associated with the url is no longer needed, the state -array should be unset to free up storage. 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 \fB::http::data\fP command. -.TP -\fBcurrentsize\fR -The current number of bytes fetched from the URL. -This value is returned by the \fB::http::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 \fB::http::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 -\fB::http::geturl\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 [geturl $url -channel $out -progress ::http::Progress \\ - -blocksize $chunk] - close $out - # This ends the line started by http::Progress - 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 [copy [string trim $value] $file $chunk] - } - } - incr max - foreach {name value} $state(meta) { - puts [format "%-*s %s" $max $name: $value] - } - - return $token -} -proc ::http::Progress {args} { - puts -nonewline stderr . ; flush stderr -} - -.DE -.SH "SEE ALSO" -safe(n), socket(n), safesock(n) -.SH KEYWORDS -security policy, socket - - diff --git a/doc/if.n b/doc/if.n deleted file mode 100644 index cebca19..0000000 --- a/doc/if.n +++ /dev/null @@ -1,43 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: if.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH if n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -if \- Execute scripts conditionally -.SH SYNOPSIS -\fBif \fIexpr1 \fR?\fBthen\fR? \fIbody1 \fBelseif \fIexpr2 \fR?\fBthen\fR? \fIbody2\fR \fBelseif\fR ... ?\fBelse\fR? ?\fIbodyN\fR? -.BE - -.SH DESCRIPTION -.PP -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 -(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); -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 -then \fBbody2\fR is executed, and so on. -If none of the expressions evaluates to true then \fIbodyN\fR is -executed. -The \fBthen\fR and \fBelse\fR arguments are optional -``noise words'' to make the command easier to read. -There may be any number of \fBelseif\fR clauses, including zero. -\fIBodyN\fR may also be omitted as long as \fBelse\fR is omitted too. -The return value from the command is the result of the body script -that was executed, or an empty string -if none of the expressions was non-zero and there was no \fIbodyN\fR. - -.SH KEYWORDS -boolean, conditional, else, false, if, true diff --git a/doc/incr.n b/doc/incr.n deleted file mode 100644 index 90c4740..0000000 --- a/doc/incr.n +++ /dev/null @@ -1,31 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: incr.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH incr n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -incr \- Increment the value of a variable -.SH SYNOPSIS -\fBincr \fIvarName \fR?\fIincrement\fR? -.BE - -.SH DESCRIPTION -.PP -Increments the value stored in the variable whose name is \fIvarName\fR. -The value of the variable must be an integer. -If \fIincrement\fR is supplied then its value (which must be an -integer) is added to the value of variable \fIvarName\fR; otherwise -1 is added to \fIvarName\fR. -The new value is stored as a decimal string in variable \fIvarName\fR -and also returned as result. - -.SH KEYWORDS -add, increment, variable, value diff --git a/doc/info.n b/doc/info.n deleted file mode 100644 index 79afb72..0000000 --- a/doc/info.n +++ /dev/null @@ -1,185 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" 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. -'\" -'\" RCS: @(#) $Id: info.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH info n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -info \- Return information about the state of the Tcl interpreter -.SH SYNOPSIS -\fBinfo \fIoption \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command provides information about various internals of the Tcl -interpreter. -The legal \fIoption\fR's (which may be abbreviated) are: -.TP -\fBinfo args \fIprocname\fR -Returns a list containing the names of the arguments to procedure -\fIprocname\fR, in order. \fIProcname\fR must be the name of a -Tcl command procedure. -.TP -\fBinfo body \fIprocname\fR -Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be -the name of a Tcl command procedure. -.TP -\fBinfo cmdcount\fR -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 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. -\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 -having no unclosed quotes, braces, brackets or array element names, -If the command doesn't appear to be complete then 0 is returned. -This command is typically used in line-oriented input environments -to allow users to type in commands that span multiple lines; if the -command isn't complete, the script can delay evaluating it until additional -lines have been typed to complete the command. -.TP -\fBinfo default \fIprocname arg varname\fR -\fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR -must be the name of an argument to that procedure. If \fIarg\fR -doesn't have a default value then the command returns \fB0\fR. -Otherwise it returns \fB1\fR and places the default value of \fIarg\fR -into variable \fIvarname\fR. -.TP -\fBinfo exists \fIvarName\fR -Returns \fB1\fR if the variable named \fIvarName\fR exists in the -current context (either as a global or local variable), returns \fB0\fR -otherwise. -.TP -\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. -.TP -\fBinfo hostname\fR -Returns the name of the computer on which this invocation is being -executed. -.TP -\fBinfo level\fR ?\fInumber\fR? -If \fInumber\fR is not specified, this command returns a number -giving the stack level of the invoking procedure, or 0 if the -command is invoked at top-level. If \fInumber\fR is specified, -then the result is a list consisting of the name and arguments for the -procedure call at level \fInumber\fR on the stack. If \fInumber\fR -is positive then it selects a particular stack level (1 refers -to the top-most active procedure, 2 to the procedure it called, and -so on); otherwise it gives a level relative to the current level -(0 refers to the current procedure, -1 to its caller, and so on). -See the \fBuplevel\fR command for more information on what stack -levels mean. -.TP -\fBinfo library\fR -Returns the name of the library directory in which standard Tcl -scripts are stored. -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. -.TP -\fBinfo loaded \fR?\fIinterp\fR? -Returns a list describing all of the packages that have been loaded into -\fIinterp\fR with the \fBload\fR command. -Each list element is a sub-list with two elements consisting of the -name of the file from which the package was loaded and the name of -the package. -For statically-loaded packages the file name will be an empty string. -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. -.TP -\fBinfo locals \fR?\fIpattern\fR? -If \fIpattern\fR isn't specified, returns a list of all the names -of currently-defined local variables, including arguments to the -current procedure, if any. -Variables defined with the \fBglobal\fR and \fBupvar\fR commands -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. -.TP -\fBinfo nameofexecutable\fR -Returns the full path name of the binary file from which the application -was invoked. If Tcl was unable to identify the file, then an empty -string is returned. -.TP -\fBinfo patchlevel\fR -Returns the value of the global variable \fBtcl_patchLevel\fR; see -the \fBtclvars\fR manual entry for more information. -.TP -\fBinfo procs \fR?\fIpattern\fR? -If \fIpattern\fR isn't specified, returns a list of all the -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 -If a Tcl script file is currently being evaluated (i.e. there is a -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. -.TP -\fBinfo sharedlibextension\fR -Returns the extension used on this platform for the names of files -containing shared libraries (for example, \fB.so\fR under Solaris). -If shared libraries aren't supported on this platform then an empty -string is returned. -.TP -\fBinfo tclversion\fR -Returns the value of the global variable \fBtcl_version\fR; see -the \fBtclvars\fR manual entry for more information. -.TP -\fBinfo vars\fR ?\fIpattern\fR? -If \fIpattern\fR isn't specified, -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, namespace, procedure, variable diff --git a/doc/interp.n b/doc/interp.n deleted file mode 100644 index d714f4d..0000000 --- a/doc/interp.n +++ /dev/null @@ -1,540 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: interp.n,v 1.3 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH interp n 7.6 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -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 -interpreters that co-exist with the creating interpreter in the -same application. The creating interpreter is called the \fImaster\fR -and the new interpreter is called a \fIslave\fR. -A master can create any number of slaves, and each slave can -itself create additional slaves for which it is master, resulting -in a hierarchy of interpreters. -.PP -Each interpreter is independent from the others: it has its own name -space for commands, procedures, and global variables. -A master interpreter may create connections between its slaves and -itself using a mechanism called an \fIalias\fR. An \fIalias\fR is -a command in a slave interpreter which, when invoked, causes a -command to be invoked in its master interpreter or in another slave -interpreter. The only other connections between interpreters are -through environment variables (the \fBenv\fR variable), which are -normally shared among all interpreters in the application. Note that the -name space for files (such as the names returned by the \fBopen\fR command) -is no longer shared between interpreters. Explicit commands are provided to -share files and to transfer references to open files from one interpreter -to another. -.PP -The \fBinterp\fR command also provides support for \fIsafe\fR -interpreters. A safe interpreter is a slave whose functions have -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 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 \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 \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, and to share or transfer -channels between interpreters. It can have any of several forms, depending -on the \fIoption\fR argument: -.TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR -Returns a Tcl list whose elements are the \fItargetCmd\fR and -\fIarg\fRs associated with the alias named \fIsrcCmd\fR -(all of these are the values specified when the alias was -created; it is possible that the actual source command in the -slave is different from \fIsrcCmd\fR if it was renamed). -.TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fB{}\fR -Deletes the alias for \fIsrcCmd\fR in the slave interpreter identified by -\fIsrcPath\fR. -\fIsrcCmd\fR refers to the name under which the alias -was created; if the source command has been renamed, the renamed -command will be deleted. -.TP -\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fItargetPath\fR \fItargetCmd \fR?\fIarg arg ...\fR? -This command creates an alias between one slave and another (see the -\fBalias\fR slave command below for creating aliases between a slave -and its master). In this command, either of the slave interpreters -may be anywhere in the hierarchy of interpreters under the interpreter -invoking the command. -\fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias. -\fISrcPath\fR is a Tcl list whose elements select a particular -interpreter. For example, ``\fBa b\fR'' identifies an interpreter -\fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave -of the invoking interpreter. An empty list specifies the interpreter -invoking the command. \fIsrcCmd\fR gives the name of a new -command, which will be created in the source interpreter. -\fITargetPath\fR and \fItargetCmd\fR specify a target interpreter -and command, and the \fIarg\fR arguments, if any, specify additional -arguments to \fItargetCmd\fR which are prepended to any arguments specified -in the invocation of \fIsrcCmd\fR. -\fITargetCmd\fR may be undefined at the time of this call, or it may -already exist; it is not created by this command. -The alias arranges for the given target command to be invoked -in the target interpreter whenever the given source command is -invoked in the source interpreter. See ALIAS INVOCATION below for -more details. -.TP -\fBinterp\fR \fBaliases \fR?\fIpath\fR? -This command returns a Tcl list of the names of all the source commands for -aliases defined in the interpreter identified by \fIpath\fR. -.TP -\fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? -Creates a slave interpreter identified by \fIpath\fR and a new command, -called a \fIslave command\fR. The name of the slave command is the last -component of \fIpath\fR. The new slave interpreter and the slave command -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 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 -interpreter and the slave command. If the \fB\-safe\fR switch is specified -(or if the master interpreter is a safe interpreter), the new slave -interpreter will be created as a safe interpreter with limited -functionality; otherwise the slave will include the full set of Tcl -built-in commands and variables. The \fB\-\|\-\fR switch can be used to -mark the end of switches; it may be needed if \fIpath\fR is an unusual -value such as \fB\-safe\fR. The result of the command is the name of the -new interpreter. The name of a slave interpreter must be unique among all -the slaves for its master; an error occurs if a slave interpreter by the -given name already exists in this master. -.TP -\fBinterp\fR \fBdelete \fR?\fIpath ...?\fR -Deletes zero or more interpreters given by the optional \fIpath\fR -arguments, and for each interpreter, it also deletes its slaves. The -command also deletes the slave command for each interpreter deleted. -For each \fIpath\fR argument, if no interpreter by that name -exists, the command raises an error. -.TP -\fBinterp\fR \fBeval\fR \fIpath arg \fR?\fIarg ...\fR? -This command concatenates all of the \fIarg\fR arguments in the same -fashion as the \fBconcat\fR command, then evaluates the resulting string as -a Tcl script in the slave interpreter identified by \fIpath\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. -.TP -\fBinterp exists \fIpath\fR -Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR -exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the -invoking interpreter is used. -.VS "" BR -.TP -\fBinterp expose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR? -Makes the hidden command \fIhiddenName\fR exposed, eventually bringing -it back under a new \fIexposedCmdName\fR name (this name is currently -accepted only if it is a valid global name space name without any ::), -in 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\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR? -Makes the exposed command \fIexposedCmdName\fR hidden, renaming -it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if -\fIhiddenCmdName\fR is not given, in the interpreter denoted -by \fIpath\fR. -If a hidden command with the targetted name already exists, this command -fails. -Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can -not contain namespace qualifiers, or an error is raised. -Commands to be hidden by \fBinterp hide\fR are looked up in the global -namespace even if the current namespace is not the global one. This -prevents slaves from fooling a master interpreter into hiding the wrong -command, by making the current namespace be different from the global one. -Hidden commands are explained in more detail in HIDDEN COMMANDS, below. -.TP -\fBinterp\fR \fBhidden\fR \fIpath\fR -Returns a list of the names of all hidden commands in the interpreter -identified by \fIpath\fR. -.TP -\fBinterp\fR \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 issafe\fR ?\fIpath\fR? -Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR -is safe, \fB0\fR otherwise. -.VS "" BR -.TP -\fBinterp marktrusted\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\fR \fBshare\fR \fIsrcPath channelId destPath\fR -Causes the IO channel identified by \fIchannelId\fR to become shared -between the interpreter identified by \fIsrcPath\fR and the interpreter -identified by \fIdestPath\fR. Both interpreters have the same permissions -on the IO channel. -Both interpreters must close it to close the underlying IO channel; IO -channels accessible in an interpreter are automatically closed when an -interpreter is destroyed. -.TP -\fBinterp\fR \fBslaves\fR ?\fIpath\fR? -Returns a Tcl list of the names of all the slave interpreters associated -with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, -the invoking interpreter is used. -.TP -\fBinterp\fR \fBtarget\fR \fIpath alias\fR -Returns a Tcl list describing the target interpreter for an alias. The -alias is specified with an interpreter path and source command name, just -as in \fBinterp alias\fR above. The name of the target interpreter is -returned as an interpreter path, relative to the invoking interpreter. -If the target interpreter for the alias is the invoking interpreter then an -empty list is returned. If the target interpreter for the alias is not the -invoking interpreter or one of its descendants then an error is generated. -The target command does not have to be defined at the time of this invocation. -.TP -\fBinterp\fR \fBtransfer\fR \fIsrcPath channelId destPath\fR -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 -new Tcl command is created in the master interpreter with the same -name as the new interpreter. This command may be used to invoke -various operations on the interpreter. It has the following -general form: -.CS -\fIslave command \fR?\fIarg arg ...\fR? -.CE -\fISlave\fR is the name of the interpreter, and \fIcommand\fR -and the \fIarg\fRs determine the exact behavior of the command. -The valid forms of this command are: -.TP -\fIslave \fBaliases\fR -Returns a Tcl list whose elements are the names of all the -aliases in \fIslave\fR. The names returned are the \fIsrcCmd\fR -values used when the aliases were created (which may not be the same -as the current names of the commands, if they have been -renamed). -.TP -\fIslave \fBalias \fIsrcCmd\fR -Returns a Tcl list whose elements are the \fItargetCmd\fR and -\fIarg\fRs associated with the alias named \fIsrcCmd\fR -(all of these are the values specified when the alias was -created; it is possible that the actual source command in the -slave is different from \fIsrcCmd\fR if it was renamed). -.TP -\fIslave \fBalias \fIsrcCmd \fB{}\fR -Deletes the alias for \fIsrcCmd\fR in the slave interpreter. -\fIsrcCmd\fR refers to the name under which the alias -was created; if the source command has been renamed, the renamed -command will be deleted. -.TP -\fIslave \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR? -Creates an alias such that whenever \fIsrcCmd\fR is invoked -in \fIslave\fR, \fItargetCmd\fR is invoked in the master. -The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional -arguments, prepended before any arguments passed in the invocation of -\fIsrcCmd\fR. -See ALIAS INVOCATION below for details. -.TP -\fIslave \fBeval \fIarg \fR?\fIarg ..\fR? -This command concatenates all of the \fIarg\fR arguments in -the same fashion as the \fBconcat\fR command, then evaluates -the resulting string as a Tcl script in \fIslave\fR. -The 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 \fIhiddenName \fR?\fIexposedCmdName\fR? -This command exposes the hidden command \fIhiddenName\fR, eventually bringing -it back under a new \fIexposedCmdName\fR name (this name is currently -accepted only if it is a valid global name space name without any ::), -in \fIslave\fR. -If an exposed command with the targetted 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, renaming it to -the hidden command \fIhiddenCmdName\fR, or keeping the same name if the -the argument is not given, in the \fIslave\fR interpreter. -If a hidden command with the targetted name already exists, this command -fails. -Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can -not contain namespace qualifiers, or an error is raised. -Commands to be hidden are looked up in the global -namespace even if the current namespace is not the global one. This -prevents slaves from fooling a master interpreter into hiding the wrong -command, by making the current namespace be different from the global one. -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 \fIhiddenName \fR?\fIarg ..\fR? -This command invokes the hidden command \fIhiddenName\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. -.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 -A safe interpreter is one with restricted functionality, so that -is safe to execute an arbitrary script from your worst enemy without -fear of that script damaging the enclosing application or the rest -of your computing environment. In order to make an interpreter -safe, certain commands and variables are removed from the interpreter. -For example, commands to create files on disk are removed, and the -\fBexec\fR command is removed, since it could be used to cause damage -through subprocesses. -Limited access to these facilities can be provided, by creating -aliases to the master interpreter which check their arguments carefully -and provide restricted access to a safe subset of facilities. -For example, file creation might be allowed in a particular subdirectory -and subprocess invocation might be allowed for a carefully selected and -fixed set of programs. -.PP -A safe interpreter is created by specifying the \fB\-safe\fR switch -to the \fBinterp create\fR command. Furthermore, any slave created -by a safe interpreter will also be safe. -.PP -A safe interpreter is created with exactly the following set of -built-in commands: -.DS -.ta 1.2i 2.4i 3.6i -\fBafter append array break -case catch clock close -concat continue eof error -eval expr fblocked fileevent -flush for foreach format -gets global history if -incr info interp join -lappend lindex linsert list -llength lower lrange lreplace -lsearch lsort package pid -proc puts read rename -return scan seek set -split string subst switch -tell trace unset update -uplevel upvar vwait while\fR -.DE -.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 -\fBenv\fR variable poses a security risk, because users can store -sensitive information in an environment variable. For example, the PGP -manual recommends storing the PGP private key protection password in -the environment variable \fIPGPPASS\fR. Making this variable available -to untrusted code executing in a safe interpreter would incur a -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 -\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 targetted 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. -.PP -Currently, the names of hidden commands cannot contain namespace -qualifiers, and you must first rename a command in a namespace to the -global namespace before you can hide it. -Commands to be hidden by \fBinterp hide\fR are looked up in the global -namespace even if the current namespace is not the global one. This -prevents slaves from fooling a master interpreter into hiding the wrong -command, by making the current namespace be different from the global one. -.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), safe(n), Tcl_CreateSlave(3) - -.SH KEYWORDS -alias, master interpreter, safe interpreter, slave interpreter diff --git a/doc/join.n b/doc/join.n deleted file mode 100644 index 76e41e3..0000000 --- a/doc/join.n +++ /dev/null @@ -1,29 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: join.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH join n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -join \- Create a string by joining together list elements -.SH SYNOPSIS -\fBjoin \fIlist \fR?\fIjoinString\fR? -.BE - -.SH DESCRIPTION -.PP -The \fIlist\fR argument must be a valid Tcl list. -This command returns the string -formed by joining all of the elements of \fIlist\fR together with -\fIjoinString\fR separating each adjacent pair of elements. -The \fIjoinString\fR argument defaults to a space character. - -.SH KEYWORDS -element, join, list, separator diff --git a/doc/lappend.n b/doc/lappend.n deleted file mode 100644 index c4af6e3..0000000 --- a/doc/lappend.n +++ /dev/null @@ -1,35 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: lappend.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH lappend n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -lappend \- Append list elements onto a variable -.SH SYNOPSIS -\fBlappend \fIvarName \fR?\fIvalue value value ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command treats the variable given by \fIvarName\fR as a list -and appends each of the \fIvalue\fR arguments to that list as a separate -element, with spaces between elements. -If \fIvarName\fR doesn't exist, it is created as a list with elements -given by the \fIvalue\fR arguments. -\fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs -are appended as list elements rather than raw text. -This command provides a relatively efficient way to build up -large lists. For example, ``\fBlappend a $b\fR'' is much -more efficient than ``\fBset a [concat $a [list $b]]\fR'' when -\fB$a\fR is long. - -.SH KEYWORDS -append, element, list, variable diff --git a/doc/library.n b/doc/library.n deleted file mode 100644 index eb20351..0000000 --- a/doc/library.n +++ /dev/null @@ -1,288 +0,0 @@ -'\" -'\" Copyright (c) 1991-1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: library.n,v 1.6 1999/04/16 00:46:35 stanton Exp $ -.so man.macros -.TH library n "8.0" Tcl "Tcl Built-In Commands" -.BS -.SH NAME -library \- standard library of Tcl procedures -.SH SYNOPSIS -.nf -\fBauto_execok \fIcmd\fR -\fBauto_load \fIcmd\fR -\fBauto_mkindex \fIdir pattern pattern ...\fR -\fBauto_mkindex_old \fIdir pattern pattern ...\fR -\fBauto_reset\fR -\fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\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 -.PP -Tcl includes a library of Tcl procedures for commonly-needed functions. -The procedures defined in the Tcl library are generic ones suitable -for use by many different applications. -The location of the Tcl library is returned by the \fBinfo library\fR -command. -In addition to the Tcl library, each application will normally have -its own library of support procedures as well; the location of this -library is normally given by the value of the \fB$\fIapp\fB_library\fR -global variable, where \fIapp\fR is the name of the application. -For example, the location of the Tk library is kept in the variable -\fB$tk_library\fR. -.PP -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 [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. -The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure -and arrange for the other procedures to be loaded on-demand using -the auto-load mechanism defined below. - -.SH "COMMAND PROCEDURES" -.PP -The following procedures are provided in the Tcl library: -.TP -\fBauto_execok \fIcmd\fR -Determines whether there is an executable file or shell builtin -by the name \fIcmd\fR. If so, it returns a list of arguments to be -passed to \fBexec\fR to execute the executable file or shell builtin -named by \fIcmd\fR. If not, it returns an empty string. This command -examines the directories in the current search path (given by the PATH -environment variable) in its search for an executable file named -\fIcmd\fR. On Windows platforms, the search is expanded with the same -directories and file extensions as used by \fBexec\fR. \fBAuto_exec\fR -remembers information about previous searches in an array named -\fBauto_execs\fR; this avoids the path search in future calls for the -same \fIcmd\fR. The command \fBauto_reset\fR may be used to force -\fBauto_execok\fR to forget its cached information. -.TP -\fBauto_load \fIcmd\fR -This command attempts to load the definition for a Tcl command named -\fIcmd\fR. -To do this, it searches an \fIauto-load path\fR, which is a list of -one or more directories. -The auto-load path is given by the global variable \fB$auto_path\fR -if it exists. -If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment -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 -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. -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 -or if the script didn't actually define \fIcmd\fR (e.g. because -index information is out of date). -If an error occurs while processing the script, then that error -is returned. -\fBAuto_load\fR only reads the index information once and saves it -in the array \fBauto_index\fR; future calls to \fBauto_load\fR -check for \fIcmd\fR in the array rather than re-reading the index -files. -The cached index information may be deleted with the command -\fBauto_reset\fR. -This will force the next \fBauto_load\fR command to reload the -index database from disk. -.TP -\fBauto_mkindex \fIdir pattern pattern ...\fR -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 -(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 -index information in a file named \fBtclIndex\fR in \fIdir\fR. -If no pattern is given a pattern of \fB*.tcl\fR will be assumed. -For example, the command -.RS -.CS -\fBauto_mkindex foo *.tcl\fR -.CE -.LP -will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR -and generate a new index file \fBfoo/tclIndex\fR. -.PP -\fBAuto_mkindex\fR parses the Tcl scripts by sourcing them -into a slave interpreter and monitoring the proc and -namespace commands that are executed. -Extensions can use the (undocumented) -auto_mkindex_parser package to register other commands that -can contribute to the auto_load index. -You will have to read through init.tcl to see how this works. -.PP -\fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively -unsophisticated way: if any line contains the word \fBproc\fR -as its first characters then it is assumed to be a procedure -definition and the next word of the line is taken as the -procedure's name. -Procedure definitions that don't appear in this way (e.g. they -have spaces before the \fBproc\fR) will not be indexed. -.RE -.TP -\fBauto_reset\fR -Destroys all the information cached by \fBauto_execok\fR and -\fBauto_load\fR. -This information will be re-read from disk the next time it is -needed. -\fBAuto_reset\fR also deletes any procedures listed in the auto-load -index, so that fresh copies of them will be loaded the next time -that they're used. -.TP -\fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR -This is a standard search procedure for use by extensions during -their initialization. They call this procedure to look for their -script library in several standard directories. -The last component of the name of the library directory is -normally \fIbasenameversion\fP -(e.g., tk8.0), but it might be "library" when in the build hierarchies. -The \fIinitScript\fR file will be sourced into the interpreter -once it is found. The directory in which this file is found is -stored into the global variable \fIvarName\fP. -If this variable is already defined (e.g., by C code during -application initialization) then no searching is done. -Otherwise the search looks in these directories: -the directory named by the environment variable \fIenVarName\fP; -relative to the Tcl library directory; -relative to the executable file in the standard installation -bin or bin/\fIarch\fP directory; -relative to the executable file in the current build tree; -relative to the executable file in a parallel build tree. -.TP -\fBparray \fIarrayName\fR -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 -The following global variables are defined or used by the procedures in -the Tcl library: -.TP -\fBauto_execs\fR -Used by \fBauto_execok\fR to record information about whether -particular commands exist as executable files. -.TP -\fBauto_index\fR -Used by \fBauto_load\fR to save the index information read from -disk. -.TP -\fBauto_noexec\fR -If set to any value, then \fBunknown\fR will not attempt to auto-exec -any commands. -.TP -\fBauto_noload\fR -If set to any value, then \fBunknown\fR will not attempt to auto-load -any commands. -.TP -\fBauto_path\fR -If set, then it must contain a valid Tcl list giving directories to -search during auto-load operations. -This variable is initialized during startup to contain, in order: -the directories listed in the TCLLIBPATH environment variable, -the directory named by the $tcl_library variable, -the parent directory of $tcl_library, -the directories listed in the $tcl_pkgPath variable. -.TP -\fBenv(TCL_LIBRARY)\fR -If set, then it specifies the location of the directory containing -library scripts (the value of this variable will be -assigned to the \fBtcl_library\fR variable and therefore returned by -the command \fBinfo library\fR). If this variable isn't set then -a default value is used. -.TP -\fBenv(TCLLIBPATH)\fR -If set, then it must contain a valid Tcl list giving directories to -search during auto-load operations. -This variable is only used when -initializing the \fBauto_path\fR variable. -.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 -infinitely. -The variable is unset before \fBunknown\fR returns. - -.SH KEYWORDS -auto-exec, auto-load, library, unknown, word, whitespace diff --git a/doc/lindex.n b/doc/lindex.n deleted file mode 100644 index 393ee78..0000000 --- a/doc/lindex.n +++ /dev/null @@ -1,35 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: lindex.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH lindex n 7.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -lindex \- Retrieve an element from a list -.SH SYNOPSIS -\fBlindex \fIlist index\fR -.BE - -.SH DESCRIPTION -.PP -This command treats \fIlist\fR as a Tcl list and returns the -\fIindex\fR'th element from it (0 refers to the first element of the list). -In extracting the element, \fIlindex\fR observes the same rules -concerning braces and quotes and backslashes as the Tcl command -interpreter; however, variable -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. -If \fIindex\fR has the value \fBend\fR, it refers to the last element -in the list. - -.SH KEYWORDS -element, index, list diff --git a/doc/linsert.n b/doc/linsert.n deleted file mode 100644 index 4877e03..0000000 --- a/doc/linsert.n +++ /dev/null @@ -1,33 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: linsert.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH linsert n 7.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -linsert \- Insert elements into a list -.SH SYNOPSIS -\fBlinsert \fIlist index element \fR?\fIelement element ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command produces a new list from \fIlist\fR by inserting all -of the \fIelement\fR arguments just before the \fIindex\fRth -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 -has the value \fBend\fR, -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. - -.SH KEYWORDS -element, insert, list diff --git a/doc/list.n b/doc/list.n deleted file mode 100644 index 9f25140..0000000 --- a/doc/list.n +++ /dev/null @@ -1,45 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: list.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH list n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -list \- Create a list -.SH SYNOPSIS -\fBlist \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command returns a list comprised of all the \fIarg\fRs, -or an empty string if no \fIarg\fRs are specified. -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 -\fIarg1\fR comprising the command's name and the other \fIarg\fRs comprising -its arguments. \fBList\fR produces slightly different results than -\fBconcat\fR: \fBconcat\fR removes one level of grouping before forming -the list, while \fBlist\fR works directly from the original arguments. -For example, the command -.CS -\fBlist a b {c d e} {f {g h}}\fR -.CE -will return -.CS -\fBa b {c d e} {f {g h}}\fR -.CE -while \fBconcat\fR with the same arguments will return -.CS -\fBa b c d e f {g h}\fR -.CE - -.SH KEYWORDS -element, list diff --git a/doc/llength.n b/doc/llength.n deleted file mode 100644 index 1a58fb7..0000000 --- a/doc/llength.n +++ /dev/null @@ -1,26 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: llength.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH llength n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -llength \- Count the number of elements in a list -.SH SYNOPSIS -\fBllength \fIlist\fR -.BE - -.SH DESCRIPTION -.PP -Treats \fIlist\fR as a list and returns a decimal string giving -the number of elements in it. - -.SH KEYWORDS -element, list, length diff --git a/doc/load.n b/doc/load.n deleted file mode 100644 index 9d3e1eb..0000000 --- a/doc/load.n +++ /dev/null @@ -1,120 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: load.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH load n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -load \- Load machine code and initialize new commands. -.SH SYNOPSIS -\fBload \fIfileName\fR -.br -\fBload \fIfileName packageName\fR -.br -\fBload \fIfileName packageName interp\fR -.BE - -.SH DESCRIPTION -.PP -This command loads binary code from a file into the -application's address space and calls an initialization procedure -in the package to incorporate it into an interpreter. \fIfileName\fR -is the name of the file containing the code; its exact form varies -from system to system but on most systems it is a shared library, -such as a \fB.so\fR file under Solaris or a DLL under Windows. -\fIpackageName\fR is the name of the package, and is used to -compute the name of an initialization procedure. -\fIinterp\fR is the path name of the interpreter into which to load -the package (see the \fBinterp\fR manual entry for details); -if \fIinterp\fR is omitted, it defaults to the -interpreter in which the \fBload\fR command was invoked. -.PP -Once the file has been loaded into the application's address space, -one of two initialization procedures will be invoked in the new code. -Typically the initialization procedure will add new commands to a -Tcl interpreter. -The name of the initialization procedure is determined by -\fIpackageName\fR and whether or not the target interpreter -is a safe one. For normal interpreters the name of the initialization -procedure will have the form \fIpkg\fB_Init\fR, where \fIpkg\fR -is the same as \fIpackageName\fR except that the first letter is -converted to upper case and all other letters -are converted to lower case. For example, if \fIpackageName\fR is -\fBfoo\fR or \fBFOo\fR, the initialization procedure's name will -be \fBFoo_Init\fR. -.PP -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 -typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); -.CE -The \fIinterp\fR argument identifies the interpreter in which the -package is to be loaded. The initialization procedure must return -\fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed -successfully; in the event of an error it should set \fIinterp->result\fR -to point to an error message. The result of the \fBload\fR command -will be the result returned by the initialization procedure. -.PP -The actual loading of a file will only be done once for each \fIfileName\fR -in an application. If a given \fIfileName\fR is loaded into multiple -interpreters, then the first \fBload\fR will load the code and -call the initialization procedure; subsequent \fBload\fRs will -call the initialization procedure without loading the code again. -It is not possible to unload or reload a package. -.PP -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. -.PP -If \fIpackageName\fR is omitted or specified as an empty string, -Tcl tries to guess the name of the package. -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 -.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 -If the same file is \fBload\fRed by different \fIfileName\fRs, it will -be loaded into the process's address space multiple times. The -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, safe(n) - -.SH KEYWORDS -binary code, loading, safe interpreter, shared library diff --git a/doc/lrange.n b/doc/lrange.n deleted file mode 100644 index 45d671d..0000000 --- a/doc/lrange.n +++ /dev/null @@ -1,39 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: lrange.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH lrange n 7.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -lrange \- Return one or more adjacent elements from a list -.SH SYNOPSIS -\fBlrange \fIlist first last\fR -.BE - -.SH DESCRIPTION -.PP -\fIList\fR must be a valid Tcl list. This command will -return a new list consisting of elements -\fIfirst\fR through \fIlast\fR, inclusive. -\fIFirst\fR or \fIlast\fR -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. -If \fIlast\fR is greater than or equal to the number of elements -in the list, then it is treated as if it were \fBend\fR. -If \fIfirst\fR is greater than \fIlast\fR then an empty string -is returned. -Note: ``\fBlrange \fIlist first first\fR'' does not always produce the -same result as ``\fBlindex \fIlist first\fR'' (although it often does -for simple fields that aren't enclosed in braces); it does, however, -produce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR'' - -.SH KEYWORDS -element, list, range, sublist diff --git a/doc/lreplace.n b/doc/lreplace.n deleted file mode 100644 index 9977a90..0000000 --- a/doc/lreplace.n +++ /dev/null @@ -1,43 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: lreplace.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH lreplace n 7.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -lreplace \- Replace elements in a list with new elements -.SH SYNOPSIS -\fBlreplace \fIlist first last \fR?\fIelement element ...\fR? -.BE - -.SH DESCRIPTION -.PP -\fBLreplace\fR returns a new list formed by replacing one or more elements of -\fIlist\fR with the \fIelement\fR arguments. -\fIFirst\fR gives the index in \fIlist\fR of the first element -to be replaced (0 refers to the first element). -If \fIfirst\fR is less than zero then it refers to the first -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. -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 -(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. -Each \fIelement\fR argument will become a separate element of -the list. -If no \fIelement\fR arguments are specified, then the elements -between \fIfirst\fR and \fIlast\fR are simply deleted. - -.SH KEYWORDS -element, list, replace diff --git a/doc/lsearch.n b/doc/lsearch.n deleted file mode 100644 index bcede70..0000000 --- a/doc/lsearch.n +++ /dev/null @@ -1,45 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: lsearch.n,v 1.2 1998/09/14 18:39:53 stanton Exp $ -'\" -.so man.macros -.TH lsearch n 7.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -lsearch \- See if a list contains a particular element -.SH SYNOPSIS -\fBlsearch \fR?\fImode\fR? \fIlist pattern\fR -.BE - -.SH DESCRIPTION -.PP -This command searches the elements of \fIlist\fR to see if one -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. -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: -.TP -\fB\-exact\fR -The list element must contain exactly the same string as \fIpattern\fR. -.TP -\fB\-glob\fR -\fIPattern\fR is a glob-style pattern which is matched against each list -element using the same rules as the \fBstring match\fR command. -.TP -\fB\-regexp\fR -\fIPattern\fR is treated as a regular expression and matched against -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. - -.SH KEYWORDS -list, match, pattern, regular expression, search, string diff --git a/doc/lsort.n b/doc/lsort.n deleted file mode 100644 index bc0b658..0000000 --- a/doc/lsort.n +++ /dev/null @@ -1,89 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 1999 Scriptics Corporation -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: lsort.n,v 1.4 1999/02/05 01:49:03 stanton Exp $ -'\" -.so man.macros -.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?\fIoptions\fR? \fIlist\fR -.BE - -.SH DESCRIPTION -.PP -This command sorts the elements of \fIlist\fR, returning a new -list in sorted order. The implementation of the \fBlsort\fR command -uses the merge\-sort algorithm which is a stable sort that has O(n log -n) performance characteristics. -.PP -By default ASCII sorting is used with the result returned in -increasing order. However, any of the 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 8.0 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. -.TP 20 -\fB\-real\fR -Convert list elements to floating-point values and use floating -comparison. -.TP 20 -\fB\-command\0\fIcommand\fR -Use \fIcommand\fR as a comparison command. -To compare two elements, evaluate a Tcl script consisting of -\fIcommand\fR with the two elements appended as additional -arguments. The script should return an integer less than, -equal to, or greater than zero if the first element is to -be considered less than, equal to, or greater than the second, -respectively. -.TP 20 -\fB\-increasing\fR -Sort the list in increasing order (``smallest'' items first). -This is the default. -.TP 20 -\fB\-decreasing\fR -Sort the list in decreasing order (``largest'' items first). -.VS 8.0 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/doc/man.macros b/doc/man.macros deleted file mode 100644 index bdf69ff..0000000 --- a/doc/man.macros +++ /dev/null @@ -1,236 +0,0 @@ -'\" The definitions below are for supplemental macros used in Tcl/Tk -'\" manual entries. -'\" -'\" .AP type name in/out ?indent? -'\" Start paragraph describing an argument to a library procedure. -'\" type is type of argument (int, etc.), in/out is either "in", "out", -'\" or "in/out" to describe whether procedure reads or modifies arg, -'\" and indent is equivalent to second arg of .IP (shouldn't ever be -'\" needed; use .AS below instead) -'\" -'\" .AS ?type? ?name? -'\" Give maximum sizes of arguments for setting tab stops. Type and -'\" name are examples of largest possible arguments that will be passed -'\" to .AP later. If args are omitted, default tab stops are used. -'\" -'\" .BS -'\" Start box enclosure. From here until next .BE, everything will be -'\" enclosed in one large box. -'\" -'\" .BE -'\" End of box enclosure. -'\" -'\" .CS -'\" Begin code excerpt. -'\" -'\" .CE -'\" End code excerpt. -'\" -'\" .VS ?version? ?br? -'\" Begin vertical sidebar, for use in marking newly-changed parts -'\" of man pages. The first argument is ignored and used for recording -'\" the version when the .VS was added, so that the sidebars can be -'\" found and removed when they reach a certain age. If another argument -'\" is present, then a line break is forced before starting the sidebar. -'\" -'\" .VE -'\" End of vertical sidebar. -'\" -'\" .DS -'\" Begin an indented unfilled display. -'\" -'\" .DE -'\" End of indented unfilled display. -'\" -'\" .SO -'\" Start of list of standard options for a Tk widget. The -'\" options follow on successive lines, in four columns separated -'\" by tabs. -'\" -'\" .SE -'\" End of list of standard options for a Tk widget. -'\" -'\" .OP cmdName dbName dbClass -'\" Start of description of a specific option. cmdName gives the -'\" option's name as specified in the class command, dbName gives -'\" the option's name in the option database, and dbClass gives -'\" the option's class in the option database. -'\" -'\" .UL arg1 arg2 -'\" Print arg1 underlined, then print arg2 normally. -'\" -'\" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $ -'\" -'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -'\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -'\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -'\" # BS - start boxed text -'\" # ^y = starting y location -'\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -'\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -'\" # VS - start vertical sidebar -'\" # ^Y = starting y location -'\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -'\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -'\" # Special macro to handle page bottom: finish off current -'\" # box/sidebar if in box/sidebar mode, then invoked standard -'\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -'\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -'\" # DE - end display -.de DE -.fi -.RE -.sp -.. -'\" # SO - start of list of standard options -.de SO -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 4c 8c 12c -.ft B -.. -'\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\fBoptions\\fR manual entry for details on the standard options. -.. -'\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -'\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -'\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.de UL -\\$1\l'|0\(ul'\\$2 -.. diff --git a/doc/msgcat.n b/doc/msgcat.n deleted file mode 100644 index e04d2a6..0000000 --- a/doc/msgcat.n +++ /dev/null @@ -1,207 +0,0 @@ -'\" -'\" Copyright (c) 1998 Mark Harrison. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" SCCS: @(#) msgcat.n -'\" -.so man.macros -.TH "msgcat" n 8.1 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -msgcat \- Tcl message catalog -.SH SYNOPSIS -\fB::msgcat::mc src-string\fR -.sp -\fB::msgcat::mclocale \fR?\fInewLocale\fR? -.sp -\fB::msgcat::mcpreferences\fR -.sp -\fB::msgcat::mcload \fIdirname\fR -.sp -\fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? -.sp -\fB::msgcat::mcunknown \fIlocale src-string\fR -.BE - -.SH DESCRIPTION -.PP -The \fBmsgcat\fR package provides a set of functions -that can be used to manage multi-lingual user interfaces. -Text strings are defined in a ``message catalog'' which -is independent from the application, and -which can be edited or localized without modifying -the application source code. New languages -or locales are provided by adding a new file to -the message catalog. -.PP -Use of the message catalog is optional by any application -or package, but is encouraged if the application or package -wishes to be enabled for multi-lingual applications. - -.SH COMMANDS -.TP -\fB::msgcat::mc src-string\fR -Returns a translation of \fIsrc-string\fR according to the -user's current locale. If no translation string -exists, \fB::msgcat::mcunknown\fR is called and the string -returned from \fB::msgcat::mcunknown\fR is returned. -.PP -\fB::msgcat::mc\fR is the main function used to localize an -application. Instead of using an English string directly, an -applicaton can pass the English string through \fB::msgcat::mc\fR and -use the result. If an application is written for a single language in -this fashion, then it is easy to add support for additional languages -later simply by defining new message catalog entries. -.TP -\fB::msgcat::mclocale \fR?\fInewLocale\fR? -This function sets the locale to \fInewLocale\fR. If \fInewLocale\fR -is omitted, the current locale is returned, otherwise the new locale -is returned. The initial locale defaults to the locale specified in -the user's environment. See \fBLOCALE AND SUBLOCALE SPECIFICATION\fR -below for a description of the locale string format. -.TP -\fB::msgcat::mcpreferences\fR -Returns an ordered list of the locales preferred by -the user, based on the user's language specification. -The list is ordered from most specific to least -preference. If the user has specified LANG=en_US_funky, -this procedure would return {en_US_funky en_US en}. -.TP -\fB::msgcat::mcload \fIdirname\fR -Searches the specified directory for files that match -the language specifications returned by \fB::msgcat::mcpreferences\fR. -Each file located is sourced. The file extension is ``.msg''. -The number of message files which matched the specification -and were loaded is returned. -.TP -\fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? -Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR -in the specified \fIlocale\fR. If \fItranslate-string\fR is not -specified, \fIsrc-string\fR is used for both. The function -return \fItranslate-string\fR. -.TP -\fB::msgcat::mcunknown \fIlocale src-string\fR -This routine is called by \fB::msgcat::mc\fR in the case when -a translation for \fIsrc-string\fR is not defined in the -current locale. The default action is to return -\fIsrc-string\fR. This procedure can be redefined by the -application, for example to log error messages for each unknown -string. The \fB::msgcat::mcunknown\fB procedure is invoked at the -same stack context as the call to \fB::msgcat::mc\fR. The return vaue -of \fB::msgcat::mcunknown\fB is used as the return vaue for the call -to \fB::msgcat::mc\fR. - -.SH "LOCALE AND SUBLOCALE SPECIFICATION" -.PP -The locale is specified by a locale string. -The locale string consists of -a language code, an optional country code, and an optional -system-specific code, each separated by ``_''. The country and language -codes are specified in standards ISO-639 and ISO-3166. -For example, the locale ``en'' specifies English and - ``en_US'' specifes U.S. English. -.PP -The locale defaults to the value in \fBenv(LANG)\fR at the time the -\fBmsgcat\fR package is loaded. If \fBenv(LANG)\fR is not defined, then the -locale defaults to ``C''. -.PP -When a locale is specified by the user, a ``best match'' search is -performed during string translation. For example, if a user specifies -en_UK_Funky, the locales ``en_UK_Funky'', ``en_UK'', and ``en'' are -searched in order until a matching translation string is found. If no -translation string is available, then \fB::msgcat::unknown\fR is -called. - -.SH "NAMESPACES AND MESSAGE CATALOGS" -.PP -Strings stored in the message catalog are stored relative -to the namespace from which they were added. This allows -multiple packages to use the same strings without fear -of collisions with other packages. It also allows the -source string to be shorter and less prone to typographical -error. -.PP -For example, executing the code -.CS -mcset en hello "hello from ::" -namespace eval foo {mcset en hello "hello from ::foo"} -puts [mc hello] -namespace eval foo {puts [mc hello]} -.CE -will print -.CS -hello from :: -hello from ::foo -.CE - -.SH "LOCATION AND FORMAT OF MESSAGE FILES" -.PP -Message files can be located in any directory, subject -to the following conditions: -.IP [1] -All message files for a package are in the same directory. -.IP [2] -The message file name is a locale specifier followed -by ``.msg''. For example: -.CS -es.msg -- spanish -en_UK.msg -- UK English -.CE -.IP [3] -The file contains a series of calls to mcset, setting the -necessary translation strings for the language. For example: -.CS -::msgcat::mcset es "Free Beer!" "Cerveza Gracias!" -.CE - -.SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" -.PP -If a package is installed into a subdirectory of the -\fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the -following procedure is recommended. -.IP [1] -During package installation, create a subdirectory -\fBmsgs\fR under your package directory. -.IP [2] -Copy your *.msg files into that directory. -.IP [3] - Add the following command to your package -initialization script: -.CS -# load language files, stored in msgs subdirectory -::msgcat::mcload [file join [file dirname [info script]] msgs] -.CE - -.SH "POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS" -.PP -It is possible that a message string used as an argument -to \fBformat\fR might have positionally dependent parameters that -might need to be repositioned. For example, it might be -syntactically desirable to rearrange the sentence structure -while translating. -.CS -format "We produced %d units in location %s" $num $city -format "In location %s we produced %d units" $city $num -.CE -.PP -This can be handled by using the positional -parameters: -.CS -format "We produced %1\\\\$d units in location %2\\\\$s" $num $city -format "In location %2\\\\$s we produced %1\\\\$d units" $num $city -.CE -.PP -Similarly, positional parameters can be used with \fBscan\fR to -extract values from internationalized strings. - -.SH "SEE ALSO" -format(n), scan(n), namespace(n), package(n) - -.SH CREDITS -.PP -The message catalog code was developed by Mark Harrison. -.SH KEYWORDS -internationalization, i18n, localization, l10n, message, text, translation diff --git a/doc/namespace.n b/doc/namespace.n deleted file mode 100644 index eeb45f5..0000000 --- a/doc/namespace.n +++ /dev/null @@ -1,563 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: namespace.n,v 1.3 1999/04/16 00:46:35 stanton Exp $ -'\" -.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 \fR?\fIoption\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 \fIoption\fR's are listed below. -Note that you can abbreviate the \fIoption\fR's. -.TP -\fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR? -Returns a list of all child namespaces that belong to the -namespace \fInamespace\fR. -If \fInamespace\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 \fInamespace\fR -(or the fully-qualified name of the current namespace) -is prepended onto the the pattern. -.TP -\fBnamespace code \fIscript\fR -Captures the current namespace context for later execution -of the script \fIscript\fR. -It returns a new script in which \fIscript\fR has been wrapped -in a \fBnamespace code\fR command. -The new script has two important properties. -First, it can be evaluated in any namespace and will cause -\fIscript\fR to be evaluated in the current namespace -(the one where the \fBnamespace code\fR command was invoked). -Second, additional arguments can be appended to the resulting script -and they will be passed to \fIscript\fR as additional arguments. -For example, suppose the command -\fBset script [namespace code {foo bar}]\fR -is invoked in namespace \fB::a::b\fR. -Then \fBeval "$script x y"\fR -can be executed in any namespace (assuming the value of -\fBscript\fR has been passed in properly) -and will have the same effect as the command -\fBnamespace eval ::a::b {foo bar x y}\fR. -This command is needed because -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. -.TP -\fBnamespace delete \fR?\fInamespace namespace ...\fR? -Each namespace \fInamespace\fR is deleted -and all variables, procedures, and child namespaces -contained in the namespace are deleted. -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 \fInamespace arg\fR ?\fIarg ...\fR? -Activates a namespace called \fInamespace\fR and evaluates some code -in that context. -If the namespace does not already exist, it is created. -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 \fBeval\fR command, -and the result is evaluated. -.br -.sp -If \fInamespace\fR has leading namespace qualifiers -and any leading namespaces do not exist, -they are automatically created. -.TP -\fBnamespace export \fR?\-\fBclear\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 \-\fBclear\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 \-\fBclear\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 qualified name such as -\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 commands. -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 currently 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 \-\fBforce\fR option is given, -imported commands will silently replace existing commands. -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 -at the time when the \fBnamespace import\fR command is executed. -If another command is defined and exported in this namespace later on, -it will not be imported. -.TP -\fBnamespace inscope\fR \fInamespace 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 \fIcommand\fR -Returns the fully-qualified name of the original command -to which the imported command \fIcommand\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 \fIcommand\fR does not refer to an imported command, -the command's own fully-qualified name is returned. -.TP -\fBnamespace parent\fR ?\fInamespace\fR? -Returns the fully-qualified name of the parent namespace -for namespace \fInamespace\fR. -If \fInamespace\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 ?\-\fBcommand\fR? ?\-\fBvariable\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 be different from 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. - -.SH "QUALIFIED NAMES" -.PP -Each namespace has a textual name such as -\fBhistory\fR or \fB::safe::interp\fR. -Since namespaces may nest, -qualified names are used to refer to -commands, variables, and child namespaces contained inside namespaces. -Qualified names are similar to the hierarchical path names for -Unix files or Tk widgets, -except that \fB::\fR is used as the separator -instead of \fB/\fR or \fB.\fR. -The topmost or global namespace has the name ``'' (i.e., an empty string), -although \fB::\fR is a synonym. -As an example, the name \fB::safe::interp::create\fR -refers to the command \fBcreate\fR in the namespace \fBinterp\fR -that is a child of of namespace \fB::safe\fR, -which in turn is a child of the global namespace \fB::\fR. -.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. -From the global namespace, -we might access the \fBCounter\fR procedures like this: -.CS -\fBCounter::bump 5 -Counter::Reset\fR -.CE -We could access the current count like this: -.CS -\fBputs "count = $Counter::num"\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 -.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. -Namespaces have nonempty names except for the global namespace. -\fB::\fR is disallowed in simple command, variable, and namespace 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 -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 -from 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 exported 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 -The \fBnamespace import\fR command only imports commands -from a namespace that that namespace exported -with a \fBnamespace export\fR command. -.PP -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 -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 "SEE ALSO" -variable(n) - -.SH KEYWORDS -exported, internal, variable diff --git a/doc/open.n b/doc/open.n deleted file mode 100644 index 03e4339..0000000 --- a/doc/open.n +++ /dev/null @@ -1,249 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: open.n,v 1.4 1999/04/16 00:46:35 stanton Exp $ -'\" -.so man.macros -.TH open n 7.6 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -open \- Open a file-based or command pipeline channel -.SH SYNOPSIS -.sp -\fBopen \fIfileName\fR -.br -\fBopen \fIfileName access\fR -.br -\fBopen \fIfileName access permissions\fR -.BE - -.SH DESCRIPTION -.PP -.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: -\fIfileName\fR gives the name of the file to open, and it must conform to the -conventions described in the \fBfilename\fR manual entry. -.PP -The \fIaccess\fR argument, if present, indicates the way in which the file -(or command pipeline) is to be accessed. -In the first form \fIaccess\fR may have any of the following values: -.TP 15 -\fBr\fR -Open the file for reading only; the file must already exist. This is the -default value if \fIaccess\fR is not specified. -.TP 15 -\fBr+\fR -Open the file for both reading and writing; the file must -already exist. -.TP 15 -\fBw\fR -Open the file for writing only. Truncate it if it exists. If it doesn't -exist, create a new file. -.TP 15 -\fBw+\fR -Open the file for reading and writing. Truncate it if it exists. -If it doesn't exist, create a new file. -.TP 15 -\fBa\fR -Open the file for writing only. The file must already exist, and the file -is positioned so that new data is appended to the file. -.TP 15 -\fBa+\fR -Open the file for reading and writing. If the file doesn't exist, -create a new empty file. -Set the initial access position to the end of the file. -.PP -In the second form, \fIaccess\fR consists of a list of any of the -following flags, all of which have the standard POSIX meanings. -One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR. -.TP 15 -\fBRDONLY\fR -Open the file for reading only. -.TP 15 -\fBWRONLY\fR -Open the file for writing only. -.TP 15 -\fBRDWR\fR -Open the file for both reading and writing. -.TP 15 -\fBAPPEND\fR -Set the file pointer to the end of the file prior to each write. -.TP 15 -\fBCREAT\fR -Create the file if it doesn't already exist (without this flag it -is an error for the file not to exist). -.TP 15 -\fBEXCL\fR -If \fBCREAT\fR is also specified, an error is returned if the -file already exists. -.TP 15 -\fBNOCTTY\fR -If the file is a terminal device, this flag prevents the file from -becoming the controlling terminal of the process. -.TP 15 -\fBNONBLOCK\fR -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 -(it is better to use the \fBfconfigure\fR command to put a file -in nonblocking mode). -For details refer to your system documentation on the \fBopen\fR system -call's \fBO_NONBLOCK\fR flag. -.TP 15 -\fBTRUNC\fR -If the file exists it is truncated to zero length. -.PP -If a new file is created as part of opening it, \fIpermissions\fR -(an integer) is used to set the permissions for the new file in -conjunction with the process's file mode creation mask. -\fIPermissions\fR defaults to 0666. -.SH "COMMAND PIPELINES" -.PP -If the first character of \fIfileName\fR is ``|'' then the -remaining characters of \fIfileName\fR are treated as a list of arguments -that describe a command pipeline to invoke, in the same style as the -arguments for \fBexec\fR. -In this case, the channel identifier returned by \fBopen\fR may be used -to write to the command's input pipe or read from its output pipe, -depending on the value of \fIaccess\fR. -If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then -standard output for the pipeline is directed to the current standard -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 "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, serial diff --git a/doc/package.n b/doc/package.n deleted file mode 100644 index f4d9f84..0000000 --- a/doc/package.n +++ /dev/null @@ -1,193 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: package.n,v 1.3 1999/03/10 05:52:45 stanton Exp $ -'\" -.so man.macros -.TH package n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -package \- Facilities for package loading and version control -.SH SYNOPSIS -.nf -\fBpackage forget \fIpackage\fR -\fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? -\fBpackage names\fR -\fBpackage present \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR? -\fBpackage provide \fIpackage \fR?\fIversion\fR? -\fBpackage require \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR? -\fBpackage unknown \fR?\fIcommand\fR? -\fBpackage vcompare \fIversion1 version2\fR -\fBpackage versions \fIpackage\fR -\fBpackage vsatisfies \fIversion1 version2\fR -.fi -.BE - -.SH DESCRIPTION -.PP -This command keeps a simple database of the packages available for -use by the current interpreter and how to load them into the -interpreter. -It supports multiple versions of each package and arranges -for the correct version of a package to be loaded based on what -is needed by the application. -This command also detects and reports version clashes. -Typically, only the \fBpackage require\fR and \fBpackage provide\fR -commands are invoked in normal Tcl scripts; the other commands are used -primarily by system scripts that maintain the package database. -.PP -The behavior of the \fBpackage\fR command is determined by its first argument. -The following forms are permitted: -.TP -\fBpackage forget \fIpackage\fR -Removes all information about \fIpackage\fR from this interpreter, -including information provided by both \fBpackage ifneeded\fR and -\fBpackage provide\fR. -.TP -\fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? -This command typically appears only in system configuration -scripts to set up the package database. -It indicates that a particular version of -a particular package is available if needed, and that the package -can be added to the interpreter by executing \fIscript\fR. -The script is saved in a database for use by subsequent -\fBpackage require\fR commands; typically, \fIscript\fR -sets up auto-loading for the commands in the package (or calls -\fBload\fR and/or \fBsource\fR directly), then invokes -\fBpackage provide\fR to indicate that the package is present. -There may be information in the database for several different -versions of a single package. -If the database already contains information for \fIpackage\fR -and \fIversion\fR, the new \fIscript\fR replaces the existing -one. -If the \fIscript\fR argument is omitted, the current script for -version \fIversion\fR of package \fIpackage\fR is returned, -or an empty string if no \fBpackage ifneeded\fR command has -been invoked for this \fIpackage\fR and \fIversion\fR. -.TP -\fBpackage names\fR -Returns a list of the names of all packages in the -interpreter for which a version has been provided (via -\fBpackage provide\fR) or for which a \fBpackage ifneeded\fR -script is available. -The order of elements in the list is arbitrary. -.TP -\fBpackage present \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR? -This command is equivalent to \fBpackage require\fR except that it -does not try and load the package if it is not already loaded. -.TP -\fBpackage provide \fIpackage \fR?\fIversion\fR? -This command is invoked to indicate that version \fIversion\fR -of package \fIpackage\fR is now present in the interpreter. -It is typically invoked once as part of an \fBifneeded\fR script, -and again by the package itself when it is finally loaded. -An error occurs if a different version of \fIpackage\fR has been -provided by a previous \fBpackage provide\fR command. -If the \fIversion\fR argument is omitted, then the command -returns the version number that is currently provided, or an -empty string if no \fBpackage provide\fR command has been -invoked for \fIpackage\fR in this interpreter. -.TP -\fBpackage require \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR? -This command is typically invoked by Tcl code that wishes to use -a particular version of a particular package. The arguments -indicate which package is wanted, and the command ensures that -a suitable version of the package is loaded into the interpreter. -If the command succeeds, it returns the version number that is -loaded; otherwise it generates an error. -If both the \fB\-exact\fR -switch and the \fIversion\fR argument are specified then only the -given version is acceptable. If \fB\-exact\fR is omitted but -\fIversion\fR is specified, then versions later than \fIversion\fR -are also acceptable as long as they have the same major version -number as \fIversion\fR. -If both \fB\-exact\fR and \fIversion\fR are omitted then any -version whatsoever is acceptable. -If a version of \fIpackage\fR has already been provided (by invoking -the \fBpackage provide\fR command), then its version number must -satisfy the criteria given by \fB\-exact\fR and \fIversion\fR and -the command returns immediately. -Otherwise, the command searches the database of information provided by -previous \fBpackage ifneeded\fR commands to see if an acceptable -version of the package is available. -If so, the script for the highest acceptable version number is invoked; -it must do whatever is necessary to load the package, -including calling \fBpackage provide\fR for the package. -If the \fBpackage ifneeded\fR database does not contain an acceptable -version of the package and a \fBpackage unknown\fR command has been -specified for the interpreter then that command is invoked; when -it completes, Tcl checks again to see if the package is now provided -or if there is a \fBpackage ifneeded\fR script for it. -If all of these steps fail to provide an acceptable version of the -package, then the command returns an error. -.TP -\fBpackage unknown \fR?\fIcommand\fR? -This command supplies a ``last resort'' command to invoke during -\fBpackage require\fR if no suitable version of a package can be found -in the \fBpackage ifneeded\fR database. -If the \fIcommand\fR argument is supplied, it contains the first part -of a command; when the command is invoked during a \fBpackage require\fR -command, Tcl appends two additional arguments giving the desired package -name and version. -For example, if \fIcommand\fR is \fBfoo bar\fR and later the command -\fBpackage require test 2.4\fR is invoked, then Tcl will execute -the command \fBfoo bar test 2.4\fR to load the package. -If no version number is supplied to the \fBpackage require\fR command, -then the version argument for the invoked command will be an empty string. -If the \fBpackage unknown\fR command is invoked without a \fIcommand\fR -argument, then the current \fBpackage unknown\fR script is returned, -or an empty string if there is none. -If \fIcommand\fR is specified as an empty string, then the current -\fBpackage unknown\fR script is removed, if there is one. -.TP -\fBpackage vcompare \fIversion1 version2\fR -Compares the two version numbers given by \fIversion1\fR and \fIversion2\fR. -Returns -1 if \fIversion1\fR is an earlier version than \fIversion2\fR, -0 if they are equal, and 1 if \fIversion1\fR is later than \fBversion2\fR. -.TP -\fBpackage versions \fIpackage\fR -Returns a list of all the version numbers of \fIpackage\fR -for which information has been provided by \fBpackage ifneeded\fR -commands. -.TP -\fBpackage vsatisfies \fIversion1 version2\fR -Returns 1 if scripts written for \fIversion2\fR will work unchanged -with \fIversion1\fR (i.e. \fIversion1\fR is equal to or greater -than \fIversion2\fR and they both have the same major version -number), 0 otherwise. - -.SH "VERSION NUMBERS" -.PP -Version numbers consist of one or more decimal numbers separated -by dots, such as 2 or 1.162 or 3.1.13.1. -The first number is called the major version number. -Larger numbers correspond to later versions of a package, with -leftmost numbers having greater significance. -For example, version 2.1 is later than 1.3 and version -3.4.6 is later than 3.3.5. -Missing fields are equivalent to zeroes: version 1.3 is the -same as version 1.3.0 and 1.3.0.0, so it is earlier than 1.3.1 or 1.3.0.2. -A later version number is assumed to be upwards compatible with -an earlier version number as long as both versions have the same -major version number. -For example, Tcl scripts written for version 2.3 of a package should -work unchanged under versions 2.3.2, 2.4, and 2.5.1. -Changes in the major version number signify incompatible changes: -if code is written to use version 2.1 of a package, it is not guaranteed -to work unmodified with either version 1.7.3 or version 3.1. - -.SH "PACKAGE INDICES" -.PP -The recommended way to use packages in Tcl is to invoke \fBpackage require\fR -and \fBpackage provide\fR commands in scripts, and use the procedure -\fBpkg_mkIndex\fR to create package index files. -Once you've done this, packages will be loaded automatically -in response to \fBpackage require\fR commands. -See the documentation for \fBpkg_mkIndex\fR for details. - -.SH KEYWORDS -package, version diff --git a/doc/pid.n b/doc/pid.n deleted file mode 100644 index 41f47ce..0000000 --- a/doc/pid.n +++ /dev/null @@ -1,34 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: pid.n,v 1.2 1998/09/14 18:39:54 stanton Exp $ -'\" -.so man.macros -.TH pid n 7.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pid \- Retrieve process id(s) -.SH SYNOPSIS -\fBpid \fR?\fIfileId\fR? -.BE - -.SH DESCRIPTION -.PP -If the \fIfileId\fR argument is given then it should normally -refer to a process pipeline created with the \fBopen\fR command. -In this case the \fBpid\fR command will return a list whose elements -are the process identifiers of all the processes in the pipeline, -in order. -The list will be empty if \fIfileId\fR refers to an open file -that isn't a process pipeline. -If no \fIfileId\fR argument is given then \fBpid\fR returns the process -identifier of the current process. -All process identifiers are returned as decimal strings. - -.SH KEYWORDS -file, pipeline, process identifier diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n deleted file mode 100644 index bf211e1..0000000 --- a/doc/pkgMkIndex.n +++ /dev/null @@ -1,240 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.6 1998/12/02 01:42:18 welch Exp $ -'\" -.so man.macros -.TH pkg_mkIndex n 8.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pkg_mkIndex \- Build an index for automatic loading of packages -.SH SYNOPSIS -.nf -.VS 8.0.3 -\fBpkg_mkIndex ?\fI-direct\fR? ?\fI-load pkgPat\fR? ?\fI-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR? -.VE -.fi -.BE - -.SH DESCRIPTION -.PP -\fBPkg_mkIndex\fR is a utility procedure that is part of the standard -Tcl library. -It is used to create index files that allow packages to be loaded -automatically when \fBpackage require\fR commands are executed. -To use \fBpkg_mkIndex\fR, follow these steps: -.IP [1] -Create the package(s). -Each package may consist of one or more Tcl script files or binary files. -Binary files must be suitable for loading with the \fBload\fR command -with a single argument; for example, if the file is \fBtest.so\fR it must -be possible to load this file with the command \fBload test.so\fR. -Each script file must contain a \fBpackage provide\fR command to declare -the package and version number, and each binary file must contain -a call to \fBTcl_PkgProvide\fR. -.IP [2] -Create the index by invoking \fBpkg_mkIndex\fR. -The \fIdir\fR argument gives the name of a directory and each -\fIpattern\fR argument is a \fBglob\fR-style pattern that selects -script or binary files in \fIdir\fR. -.VS 8.0.3 -The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR. -.VE -.sp 1 -\fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR -with package information about all the files given by the \fIpattern\fR -arguments. -It does this by loading each file into a slave -interpreter and seeing what packages -and new commands appear (this is why it is essential to have -\fBpackage provide\fR commands or \fBTcl_PkgProvide\fR calls -in the files, as described above). -If you have a package split among scripts and binary files, -or if you have dependencies among files, -you may have to use the \fB-load\fP option -or adjust the order in which \fBpkg_mkIndex\fR processes -the files. See COMPLEX CASES below. - -.IP [3] -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. -.sp 1 -If you install the package anywhere else, then you must ensure that -the directory containing 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; by default it -includes \fB$tcl_pkgPath\fR. -The package loader also checks all of the subdirectories of the -directories in \fBauto_path\fR. -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. -.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 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 -in \fBauto_path\fR, but only one will actually be loaded in a given -interpreter, based on the first call to \fBpackage require\fR. -Different versions of a package may be loaded in different -interpreters. - -.SH OPTIONS -The optional switches are: -.TP 15 -\fB\-direct\fR -The generated index -will manage to load the package immediately upon \fBpackage require\fR -instead of delaying loading until actual use of one of the commands. -.TP 15 -\fB\-load \fIpkgPat\fR -The index process will pre-load any packages that exist in the -current interpreter and match \fIpkgPat\fP into the slave interpreter used to -generate the index. The pattern match uses string match rules. -See COMPLEX CASES below. -.TP 15 -\fB\-verbose\fR -Generate output during the indexing process. Output is via -the \fBtclLog\fP procedure, which by default prints to stderr. -.TP 15 -\fB\-\-\fR -End of the flags, in case \fIdir\fP begins with a dash. - -.SH "PACKAGES AND THE AUTO-LOADER" -.PP -The package management facilities overlap somewhat with the auto-loader, -in that both arrange for files to be loaded on-demand. -However, package management is a higher-level mechanism that uses -the auto-loader for the last step in the loading process. -It is generally better to index a package with \fBpkg_mkIndex\fR -rather than \fBauto_mkindex\fR because the package mechanism provides -version control: several versions of a package can be made available -in the index files, with different applications using different -versions based on \fBpackage require\fR commands. -In contrast, \fBauto_mkindex\fR does not understand versions so -it can only handle a single version of each package. -It is probably not a good idea to index a given package with both -\fBpkg_mkIndex\fR and \fBauto_mkindex\fR. -If you use \fBpkg_mkIndex\fR to index a package, its commands cannot -be invoked until \fBpackage require\fR has been used to select a -version; in contrast, packages indexed with \fBauto_mkindex\fR -can be used immediately since there is no version control. - -.SH "HOW IT WORKS" -.PP -\fBPkg_mkIndex\fR depends on the \fBpackage unknown\fR command, -the \fBpackage ifneeded\fR command, and the auto-loader. -The first time a \fBpackage require\fR command is invoked, -the \fBpackage unknown\fR script is invoked. -This is set by Tcl initialization to a script that -evaluates all of the \fBpkgIndex.tcl\fR files in the -\fBauto_path\fR. -The \fBpkgIndex.tcl\fR files contain \fBpackage ifneeded\fR -commands for each version of each available package; these commands -invoke \fBpackage provide\fR commands to announce the -availability of the package, and they setup auto-loader -information to load the files of the package. -.VS 8.0.3 -Unless the \fI-direct\fR flag was provided when the \fBpkgIndex.tcl\fR -was generated, -.VE -a given file of a given version of a given package isn't -actually loaded until the first time one of its commands -is invoked. -Thus, after invoking \fBpackage require\fR you -.VS 8.0.3 -may -.VE -not see -the package's commands in the interpreter, but you will be able -to invoke the commands and they will be auto-loaded. - -.VS 8.0.3 -.SH "DIRECT LOADING" -.PP -Some packages, for instance packages which use namespaces and export -commands or those which require special initialization, might select -that their package files be loaded immediately upon \fBpackage require\fR -instead of delaying the actual loading to the first use of one of the -package's command. This mode is enabled when generating the package -index by specifying the \fI-direct\fR argument. -.VE - -.SH "COMPLEX CASES" -Most complex cases of dependencies among scripts -and binary files, and packages being split among scripts and -binary files are handled OK. However, you may have to adjust -the order in which files are processed by \fBpkg_mkIndex\fR. -These issues are described in detail below. -.PP -If each script or file contains one package, and packages -are only contained in one file, then things are easy. -You simply specify all files to be indexed in any order -with some glob patterns. -.PP -In general, it is OK for scripts to have dependencies on other -packages. -If scripts contain \fBpackage require\fP commands, these are -stubbed out in the interpreter used to process the scripts, -so these do not cause problems. -If scripts call into other packages in global code, -these calls are handled by a stub \fBunknown\fP command. -However, if scripts make variable references to other package's -variables in global code, these will cause errors. That is -also bad coding style. -.PP -If binary files have dependencies on other packages, things -can become tricky because it is not possible to stub out -C-level API's such as \fBTcl_PkgRequire\fP API -when loading a binary file. -For example, suppose the BLT package requires Tk, and expresses -this with a call to \fBTcl_PkgRequire\fP in its \fBBlt_Init\fP routine. -To support this, you must run \fBpkg_mkIndex\fR in an interpreter that -has Tk loaded. You can achieve this with the -\fB-load \fIpkgPat\fR option. If you specify this option, -\fBpkg_mkIndex\fR will load any packages listed by -\fBinfo loaded\fP and that match \fIpkgPat\fP -into the interpreter used to process files. -In most cases this will satisfy the \fBTcl_PkgRequire\fP calls -made by binary files. -.PP -If you are indexing two binary files and one depends on the other, -you should specify the one that has dependencies last. -This way the one without dependencies will get loaded and indexed, -and then the package it provides -will be available when the second file is processed. -You may also need to load the first package into the -temporary interpreter used to create the index by using -the \fB-load\fP flag; -it won't hurt to specify package patterns that are not yet loaded. -.PP -If you have a package that is split across scripts and a binary file, -then you should avoid the \fB-load\fP flag. The problem is that -if you load a package before computing the index it masks any -other files that provide part of the same package. -If you must use \fB-load\fP, -then you must specify the scripts first; otherwise the package loaded from -the binary file may mask the package defined by the scripts. - -.SH KEYWORDS -auto-load, index, package, version diff --git a/doc/proc.n b/doc/proc.n deleted file mode 100644 index 90b7709..0000000 --- a/doc/proc.n +++ /dev/null @@ -1,74 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: proc.n,v 1.2 1998/09/14 18:39:54 stanton Exp $ -'\" -.so man.macros -.TH proc n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -proc \- Create a Tcl procedure -.SH SYNOPSIS -\fBproc \fIname args body\fR -.BE - -.SH DESCRIPTION -.PP -The \fBproc\fR command creates a new Tcl procedure named -\fIname\fR, replacing -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 -one argument. Each argument specifier is also a list with either -one or two fields. If there is only a single field in the specifier -then it is the name of the argument; if there are two fields, then -the first is the argument name and the second is its default value. -.PP -When \fIname\fR is invoked a local variable -will be created for each of the formal arguments to the procedure; its -value will be the value of corresponding argument in the invoking command -or the argument's default value. -Arguments with default values need not be -specified in a procedure invocation. However, there must be enough -actual arguments for all the -formal arguments that don't have defaults, and there must not be any extra -actual arguments. There is one special case to permit procedures with -variable numbers of arguments. If the last formal argument has the name -\fBargs\fR, then a call to the procedure may contain more actual arguments -than the procedure has formals. In this case, all of the actual arguments -starting at the one that would be assigned to \fBargs\fR are combined into -a list (as if the \fBlist\fR command had been used); this combined value -is assigned to the local variable \fBargs\fR. -.PP -When \fIbody\fR is being executed, variable names normally refer to -local variables, which are created automatically when referenced and -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 -\fBreturn\fR command. If the procedure doesn't execute an explicit -\fBreturn\fR, then its return value is the value of the last command -executed in the procedure's body. -If an error occurs while executing the procedure -body, then the procedure-as-a-whole will return that same error. - -.SH KEYWORDS -argument, procedure diff --git a/doc/puts.n b/doc/puts.n deleted file mode 100644 index 99e61a4..0000000 --- a/doc/puts.n +++ /dev/null @@ -1,69 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: puts.n,v 1.3 1999/04/16 00:46:35 stanton Exp $ -'\" -.so man.macros -.TH puts n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -puts \- Write to a channel -.SH SYNOPSIS -\fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR -.BE - -.SH DESCRIPTION -.PP -Writes the characters given by \fIstring\fR to the channel given -by \fIchannelId\fR. -\fIChannelId\fR must be a channel identifier such as returned from a -previous invocation of \fBopen\fR or \fBsocket\fR. It must have been opened -for output. If no \fIchannelId\fR is specified then it defaults to -\fBstdout\fR. \fBPuts\fR normally outputs a newline character after -\fIstring\fR, but this feature may be suppressed by specifying the -\fB\-nonewline\fR switch. -.PP -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, -on PCs newlines are normally replaced with carriage-return-linefeed -sequences; on Macintoshes newlines are normally replaced with -carriage-returns). -See the \fBfconfigure\fR manual entry for a discussion on ways in -which \fBfconfigure\fR will alter output. -.PP -Tcl buffers output internally, so characters written with \fBputs\fR -may not appear immediately on the output file or device; Tcl will -normally delay output until the buffer is full or the channel is -closed. -You can force output to appear immediately with the \fBflush\fR -command. -.PP -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. -If \fIchannelId\fR is in nonblocking mode then the \fBputs\fR command -will not block even if the operating system cannot accept the data. -Instead, Tcl continues to buffer the data and writes it in the -background as fast as the underlying file or device can accept it. -The application must use the Tcl event loop for nonblocking output -to work; otherwise Tcl never finds out that the file or device is -ready for more output data. -It is possible for an arbitrarily large amount of data to be -buffered for a channel in nonblocking mode, which could consume a -large amount of memory. -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). - -.SH "SEE ALSO" -fileevent(n) - -.SH KEYWORDS -channel, newline, output, write diff --git a/doc/pwd.n b/doc/pwd.n deleted file mode 100644 index 8aa6611..0000000 --- a/doc/pwd.n +++ /dev/null @@ -1,25 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: pwd.n,v 1.2 1998/09/14 18:39:54 stanton Exp $ -'\" -.so man.macros -.TH pwd n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pwd \- Return the current working directory -.SH SYNOPSIS -\fBpwd\fR -.BE - -.SH DESCRIPTION -.PP -Returns the path name of the current working directory. - -.SH KEYWORDS -working directory diff --git a/doc/read.n b/doc/read.n deleted file mode 100644 index 21d9549..0000000 --- a/doc/read.n +++ /dev/null @@ -1,50 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: read.n,v 1.3 1999/04/16 00:46:35 stanton Exp $ -'\" -.so man.macros -.TH read n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -read \- Read from a channel -.SH SYNOPSIS -\fBread \fR?\fB\-nonewline\fR? \fIchannelId\fR -.sp -\fBread \fIchannelId numBytes\fR -.BE - -.SH DESCRIPTION -.PP -In the first form, the \fBread\fR command reads all of the data from -\fIchannelId\fR up to the end of the file. -If the \fB\-nonewline\fR switch is specified then the last character -of the file is discarded if it is a newline. -In the second form, the extra argument specifies how many bytes to -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 -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 -for more input. -The \fB\-nonewline\fR switch is ignored if the command returns -before reaching the end of the file. -.PP -\fBRead\fR translates end-of-line sequences in the input into -newline characters according to the \fB\-translation\fR option -for the channel. -See the \fBfconfigure\fR manual entry for a discussion on ways in -which \fBfconfigure\fR will alter input. - -.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/doc/regexp.n b/doc/regexp.n deleted file mode 100644 index 0d08dcf..0000000 --- a/doc/regexp.n +++ /dev/null @@ -1,1048 +0,0 @@ -'\" -'\" Copyright (c) 1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: regexp.n,v 1.3 1999/04/16 00:46:35 stanton Exp $ -'\" -.so man.macros -.TH regexp n 8.1 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -regexp \- Match a regular expression against a string - -.SH SYNOPSIS -\fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR? -.BE - -.SH DESCRIPTION -.PP -Determines whether the regular expression \fIexp\fR matches part or -all of \fIstring\fR and returns 1 if it does, 0 if it doesn't. -.LP -If additional arguments are specified after \fIstring\fR then they -are treated as the names of variables in which to return -information about which part(s) of \fIstring\fR matched \fIexp\fR. -\fIMatchVar\fR will be set to the range of \fIstring\fR that -matched all of \fIexp\fR. The first \fIsubMatchVar\fR will contain -the characters in \fIstring\fR that matched the leftmost parenthesized -subexpression within \fIexp\fR, the next \fIsubMatchVar\fR will -contain the characters that matched the next parenthesized -subexpression to the right in \fIexp\fR, and so on. -.PP -If the initial arguments to \fBregexp\fR start with \fB\-\fR then -they are treated as switches. The following switches are -currently supported: -.TP 15 -\fB\-nocase\fR -Causes upper-case characters in \fIstring\fR to be treated as -lower case during the matching process. -.TP 15 -\fB\-indices\fR -Changes what is stored in the \fIsubMatchVar\fRs. -Instead of storing the matching characters from \fIstring\fR, -each variable -will contain a list of two decimal strings giving the indices -in \fIstring\fR of the first and last characters in the matching -range of characters. -.VS 8.1 -.TP 15 -\fB\-expanded\fR -Enables use of the expanded regular expression syntax where -whitespace and comments are ignored. This is the same as specifying -the \fB(?x)\fR embedded option (see METASYNTAX, below). -.TP 15 -\fB\-line\fR -Enables newline-sensitive matching. By default, newline is a -completely ordinary character with no special meaning. With this -flag, `[^' bracket expressions and `.' never match newline, `^' -matches an empty string after any newline in addition to its normal -function, and `$' matches an empty string before any newline in -addition to its normal function. This flag is equivalent to -specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the -\fB(?n)\fR embedded option (see METASYNTAX, below). -.TP 15 -\fB\-linestop\fR -Changes the behavior of `[^' bracket expressions and `.' so that they -stop at newlines. This is the same as specifying the \fB(?p)\fR -embedded option (see METASYNTAX, below). -.TP 15 -\fB\-lineanchor\fR -Changes the behavior of `^' and `$' (the ``anchors'') so they match the -beginning and end of a line respectively. This is the same as -specifying the \fB(?w)\fR embedded option (see METASYNTAX, below). -.TP 15 -\fB\-about\fR -Instead of attempting to match the regular expression, returns a list -containing information about the regular expression. The first -element of the list is a subexpression count. The second element is a -list of property names that describe various attributes of the regular -expression. This switch is primarily intended for debugging purposes. -.VE 8.1 -.TP 15 -\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. -.PP -If there are more \fIsubMatchVar\fR's than parenthesized -subexpressions within \fIexp\fR, or if a particular subexpression -in \fIexp\fR doesn't match the string (e.g. because it was in a -portion of the expression that wasn't matched), then the corresponding -\fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR -has been specified or to an empty string otherwise. - -.SH "DIFFERENT FLAVORS OF REs" -.VS 8.1 -Regular expressions (``RE''s), as defined by POSIX, come in two -flavors: \fIextended\fR REs (``EREs'') and \fIbasic\fR REs (``BREs''). -EREs are roughly those of the traditional \fIegrep\fR, while BREs are -roughly those of the traditional \fIed\fR . This implementation adds -a third flavor, \fIadvanced\fR REs (``AREs''), basically EREs with -some significant extensions. -.PP -This manual page primarily describes AREs. BREs mostly exist for -backward compatibility in some old programs; they will be discussed at -the end. POSIX EREs are almost an exact subset of AREs. Features of -AREs that are not present in EREs will be indicated. - -.SH "REGULAR EXPRESSION SYNTAX" -.PP -Tcl regular expressions are implemented using the package written by -Henry Spencer, based on the 1003.2 spec and some (not quite all) of -the Perl5 extensions (thanks, Henry!). Much of the description of -regular expressions below is copied verbatim from his manual entry. -.PP -An ARE is one or more \fIbranches\fR, -separated by `\fB|\fR', -matching anything that matches any of the branches. -.PP -A branch is zero or more \fIconstraints\fR or \fIquantified atoms\fR, -concatenated. -It matches a match for the first, followed by a match for the second, etc; -an empty branch matches the empty string. -.PP -A quantified atom is an \fIatom\fR possibly followed -by a single \fIquantifier\fR. -Without a quantifier, it matches a match for the atom. -The quantifiers, -and what a so-quantified atom matches, are: -.RS 2 -.TP 6 -\fB*\fR -a sequence of 0 or more matches of the atom -.TP -\fB+\fR -a sequence of 1 or more matches of the atom -.TP -\fB?\fR -a sequence of 0 or 1 matches of the atom -.TP -\fB{\fIm\fB}\fR -a sequence of exactly \fIm\fR matches of the atom -.TP -\fB{\fIm\fB,}\fR -a sequence of \fIm\fR or more matches of the atom -.TP -\fB{\fIm\fB,\fIn\fB}\fR -a sequence of \fIm\fR through \fIn\fR (inclusive) matches of the atom; -\fIm\fR may not exceed \fIn\fR -.TP -\fB*? +? ?? {\fIm\fB}? {\fIm\fB,}? {\fIm\fB,\fIn\fB}?\fR -\fInon-greedy\fR quantifiers, -which match the same possibilities, -but prefer the smallest number rather than the largest number -of matches (see MATCHING) -.RE -.PP -The forms using -\fB{\fR and \fB}\fR -are known as \fIbound\fRs. -The numbers -\fIm\fR and \fIn\fR are unsigned decimal integers -with permissible values from 0 to 255 inclusive. -.PP -An atom is one of: -.RS 2 -.TP 6 -\fB(\fIre\fB)\fR -(where \fIre\fR is any regular expression) -matches a match for -\fIre\fR, with the match noted for possible reporting -.TP -\fB(?:\fIre\fB)\fR -as previous, -but does no reporting -(a ``non-capturing'' set of parentheses) -.TP -\fB()\fR -matches an empty string, -noted for possible reporting -.TP -\fB(?:)\fR -matches an empty string, -without reporting -.TP -\fB[\fIchars\fB]\fR -a \fIbracket expression\fR, -matching any one of the \fIchars\fR (see BRACKET EXPRESSIONS for more detail) -.TP - \fB.\fR -matches any single character -.TP -\fB\e\fIk\fR -(where \fIk\fR is a non-alphanumeric character) -matches that character taken as an ordinary character, -e.g. \e\e matches a backslash character -.TP -\fB\e\fIc\fR -where \fIc\fR is alphanumeric -(possibly followed by other characters), -an \fIescape\fR (AREs only), -see ESCAPES below -.TP -\fB{\fR -when followed by a character other than a digit, -matches the character -`\fB{\fR'; -when followed by a digit, it is the beginning of a -\fIbound\fR (see above) -.TP -\fIx\fR -where \fIx\fR is -a single character with no other significance, matches that character. -.RE -.PP -A \fIconstraint\fR matches an empty string when specific conditions -are met. -A constraint may not be followed by a quantifier. -The simple constraints are as follows; some more constraints are -described later, under ESCAPES. -.RS 2 -.TP 8 -\fB^\fR -matches at the beginning of a line -.TP -\fB$\fR -matches at the end of a line -.TP -\fB(?=\fIre\fB)\fR -\fIpositive lookahead\fR (AREs only), matches at any point -where a substring matching \fIre\fR begins -.TP -\fB(?!\fIre\fB)\fR -\fInegative lookahead\fR (AREs only), matches at any point -where no substring matching \fIre\fR begins -.RE -.PP -The lookahead constraints may not contain back references (see later), -and all parentheses within them are considered non-capturing. -.PP -An RE may not end with -`\fB\e\fR'. - -.SH "BRACKET EXPRESSIONS" -A \fIbracket expression\fR is a list of characters enclosed in -`\fB[\|]\fR'. -It normally matches any single character from the list (but see below). -If the list begins with -`\fB^\fR', -it matches any single character -(but see below) \fInot\fR from the rest of the list. -.PP -If two characters in the list are separated by -`\fB\-\fR', -this is shorthand -for the full \fIrange\fR of characters between those two (inclusive) in the -collating sequence, -e.g. -\fB[0\-9]\fR -in ASCII matches any decimal digit. -Two ranges may not share an -endpoint, so e.g. -\fBa\-c\-e\fR -is illegal. -Ranges are very collating-sequence-dependent, -and portable programs should avoid relying on them. -.PP -To include a literal -\fB]\fR -or -\fB\-\fR -in the list, -the simplest method is to -enclose it in -\fB[.\fR -and -\fB.]\fR -to make it a collating element (see below). -Alternatively, -make it the first character -(following a possible -`\fB^\fR'), -or (AREs only) precede it with -`\fB\e\fR'. -Alternatively, for -`\fB\-\fR', -make it the last character, -or the second endpoint of a range. -To use a literal -\fB\-\fR -as the first endpoint of a range, -make it a collating element -or (AREs only) precede it with -`\fB\e\fR'. -With the exception of these, some combinations using -\fB[\fR -(see next -paragraphs), and escapes, -all other special characters lose their -special significance within a bracket expression. -.PP -Within a bracket expression, a collating element (a character, -a multi-character sequence that collates as if it were a single character, -or a collating-sequence name for either) -enclosed in -\fB[.\fR -and -\fB.]\fR -stands for the -sequence of characters of that collating element. -The sequence is a single element of the bracket expression's list. -A bracket expression in a locale which has -multi-character collating elements -can thus match more than one character. -Most insidiously, if -\fB^\fR -is used, -this can happen even if no multi-character collating -elements appear in the bracket expression! -If the collating sequence includes a -\fBch\fR -multi-character collating element, -then the RE -\fB[[.ch.]]*c\fR -matches the first five characters -of -`\fBchchcc\fR', -and the RE -\fB[^c]b\fR -matches all of -`\fBchb\fR'. -.PP -Within a bracket expression, a collating element enclosed in -\fB[=\fR -and -\fB=]\fR -is an equivalence class, standing for the sequences of characters -of all collating elements equivalent to that one, including itself. -(If there are no other equivalent collating elements, -the treatment is as if the enclosing delimiters were -`\fB[.\fR'\& -and -`\fB.]\fR'.) -For example, if -\fBo\fR -and -\fB\o'o^'\fR -are the members of an equivalence class, -then -`\fB[[=o=]]\fR', -`\fB[[=\o'o^'=]]\fR', -and -`\fB[o\o'o^']\fR'\& -are all synonymous. -An equivalence class may not be an endpoint -of a range. -.PP -Within a bracket expression, the name of a \fIcharacter class\fR enclosed -in -\fB[:\fR -and -\fB:]\fR -stands for the list of all characters -(not all collating elements!) -belonging to that -class. -Standard character class names are: -.PP -.RS -.ne 5 -.nf -.ta 3c 6c 9c -\fBalnum digit punct -alpha graph space -blank lower upper -cntrl print xdigit\fR -.fi -.RE -.PP -These stand for the character classes defined in -\fIctype\fR(3). -A locale may provide others. -A character class may not be used as an endpoint of a range. -.PP -There are two special cases of bracket expressions: -the bracket expressions -\fB[[:<:]]\fR -and -\fB[[:>:]]\fR -are constraints, matching empty strings at -the beginning and end of a word respectively. -'\" note, discussion of escapes below references this definition of word -A word is defined as a sequence of -word characters -which is neither preceded nor followed by -word characters. -A word character is an -\fIalnum\fR -character (as defined by -\fIctype\fR(3)) -or an underscore -(\fB_\fR). -These special bracket expressions are deprecated; -users of AREs should use constraint escapes instead (see below). -.SH ESCAPES -Escapes (AREs only), which begin with a -\fB\e\fR -followed by an alphanumeric character, -come in several varieties: -character entry, class shorthands, constraint escapes, and back references. -A -\fB\e\fR -followed by an alphanumeric character but not constituting -a valid escape is illegal in AREs. -In EREs, there are no escapes: -outside a bracket expression, -a -\fB\e\fR -followed by an alphanumeric character merely stands for that -character as an ordinary character, -and inside a bracket expression, -\fB\e\fR -is an ordinary character. -(The latter is the one actual incompatibility between EREs and AREs.) -.PP -Character-entry escapes (AREs only) exist to make it easier to specify -non-printing and otherwise inconvenient characters in REs: -.RS 2 -.TP 5 -\fB\ea\fR -alert, aka bell, character, as in C -.TP -\fB\eb\fR -backspace, as in C -.TP -\fB\eB\fR -synonym for -\fB\e\fR -to help reduce backslash doubling in some -applications where there are multiple levels of backslash processing -.TP -\fB\ec\fIX\fR -(where X is any character) the character whose -low-order 5 bits are the same as those of -\fIX\fR, -and whose other bits are all zero -.TP -\fB\ee\fR -the character whose collating-sequence name -is -`\fBESC\fR', -or failing that, the character with octal value 033 -.TP -\fB\ef\fR -formfeed, as in C -.TP -\fB\en\fR -newline, as in C -.TP -\fB\er\fR -carriage return, as in C -.TP -\fB\et\fR -horizontal tab, as in C -.TP -\fB\eu\fIwxyz\fR -(where -\fIwxyz\fR -is exactly four hexadecimal digits) -the Unicode character -\fBU+\fIwxyz\fR -in the local byte ordering -.TP -\fB\eU\fIstuvwxyz\fR -(where -\fIstuvwxyz\fR -is exactly eight hexadecimal digits) -reserved for a somewhat-hypothetical Unicode extension to 32 bits -.TP -\fB\ev\fR -vertical tab, as in C -are all available. -.TP -\fB\ex\fIhhh\fR -(where -\fIhhh\fR -is any sequence of hexadecimal digits) -the character whose hexadecimal value is -\fB0x\fIhhh\fR -(a single character no matter how many hexadecimal digits are used). -.TP -\fB\e0\fR -the character whose value is -\fB0\fR -.TP -\fB\e\fIxy\fR -(where -\fIxy\fR -is exactly two octal digits, -and is not a -\fIback reference\fR (see below)) -the character whose octal value is -\fB0\fIxy\fR -.TP -\fB\e\fIxyz\fR -(where -\fIxyz\fR -is exactly three octal digits, -and is not a -back reference (see below)) -the character whose octal value is -\fB0\fIxyz\fR -.RE -.PP -Hexadecimal digits are -`\fB0\fR'-`\fB9\fR', -`\fBa\fR'-`\fBf\fR', -and -`\fBA\fR'-`\fBF\fR'. -Octal digits are -`\fB0\fR'-`\fB7\fR'. -.PP -The character-entry escapes are always taken as ordinary characters. -For example, -\fB\e135\fR -is -\fB]\fR -in ASCII, -but -\fB\e135\fR -does not terminate a bracket expression. -Beware, however, that some applications (e.g., C compilers) interpret -such sequences themselves before the regular-expression package -gets to see them, which may require doubling (quadrupling, etc.) the -`\fB\e\fR'. -.PP -Class-shorthand escapes (AREs only) provide shorthands for certain commonly-used -character classes: -.RS 2 -.TP 10 -\fB\ed\fR -\fB[[:digit:]]\fR -.TP -\fB\es\fR -\fB[[:space:]]\fR -.TP -\fB\ew\fR -\fB[[:alnum:]_]\fR -(note underscore) -.TP -\fB\eD\fR -\fB[^[:digit:]]\fR -.TP -\fB\eS\fR -\fB[^[:space:]]\fR -.TP -\fB\eW\fR -\fB[^[:alnum:]_]\fR -(note underscore) -.RE -.PP -Within bracket expressions, -`\fB\ed\fR', -`\fB\es\fR', -and -`\fB\ew\fR'\& -lose their outer brackets, -and -`\fB\eD\fR', -`\fB\eS\fR', -and -`\fB\eW\fR'\& -are illegal. -.PP -A constraint escape (AREs only) is a constraint, -matching the empty string if specific conditions are met, -written as an escape: -.RS 2 -.TP 6 -\fB\eA\fR -matches only at the beginning of the string -(see MATCHING, below, for how this differs from -`\fB^\fR') -.TP -\fB\em\fR -matches only at the beginning of a word -.TP -\fB\eM\fR -matches only at the end of a word -.TP -\fB\ey\fR -matches only at the beginning or end of a word -.TP -\fB\eY\fR -matches only at a point which is not the beginning or end of a word -.TP -\fB\eZ\fR -matches only at the end of the string -(see MATCHING, below, for how this differs from -`\fB$\fR') -.TP -\fB\e\fIm\fR -(where -\fIm\fR -is a nonzero digit) a \fIback reference\fR, see below -.TP -\fB\e\fImnn\fR -(where -\fIm\fR -is a nonzero digit, and -\fInn\fR -is some more digits, -and the decimal value -\fImnn\fR -is not greater than the number of closing capturing parentheses seen so far) -a \fIback reference\fR, see below -.RE -.PP -A word is defined as in the specification of -\fB[[:<:]]\fR -and -\fB[[:>:]]\fR -above. -Constraint escapes are illegal within bracket expressions. -.PP -A back reference (AREs only) matches the same string matched by the parenthesized -subexpression specified by the number, -so that (e.g.) -\fB([bc])\e1\fR -matches -\fBbb\fR -or -\fBcc\fR -but not -`\fBbc\fR'. -The subexpression must entirely precede the back reference in the RE. -Subexpressions are numbered in the order of their leading parentheses. -Non-capturing parentheses do not define subexpressions. -.PP -There is an inherent historical ambiguity between octal character-entry -escapes and back references, which is resolved by heuristics, -as hinted at above. -A leading zero always indicates an octal escape. -A single non-zero digit, not followed by another digit, -is always taken as a back reference. -A multi-digit sequence not starting with a zero is taken as a back -reference if it comes after a suitable subexpression -(i.e. the number is in the legal range for a back reference), -and otherwise is taken as octal. -.SH "METASYNTAX" -In addition to the main syntax described above, there are some special -forms and miscellaneous syntactic facilities available. -.PP -Normally the flavor of RE being used is specified by -application-dependent means. -However, this can be overridden by a \fIdirector\fR. -If an RE of any flavor begins with -`\fB***:\fR', -the rest of the RE is an ARE. -If an RE of any flavor begins with -`\fB***=\fR', -the rest of the RE is taken to be a literal string, -with all characters considered ordinary characters. -.PP -An ARE may begin with \fIembedded options\fR: -a sequence -\fB(?\fIxyz\fB)\fR -(where -\fIxyz\fR -is one or more alphabetic characters) -specifies options affecting the rest of the RE. -These supplement, and can override, -any options specified by the application. -The available option letters are: -.RS 2 -.TP 3 -\fBb\fR -rest of RE is a BRE -.TP 3 -\fBc\fR -case-sensitive matching (usual default) -.TP 3 -\fBe\fR -rest of RE is an ERE -.TP 3 -\fBi\fR -case-insensitive matching (see MATCHING, below) -.TP 3 -\fBm\fR -historical synonym for -\fBn\fR -.TP 3 -\fBn\fR -newline-sensitive matching (see MATCHING, below) -.TP 3 -\fBp\fR -partial newline-sensitive matching (see MATCHING, below) -.TP 3 -\fBq\fR -rest of RE is a literal (``quoted'') string, all ordinary characters -.TP 3 -\fBs\fR -non-newline-sensitive matching (usual default) -.TP 3 -\fBt\fR -tight syntax (usual default; see below) -.TP 3 -\fBw\fR -inverse partial newline-sensitive (``weird'') matching (see MATCHING, below) -.TP 3 -\fBx\fR -expanded syntax (see below) -.RE -.PP -Embedded options take effect at the -\fB)\fR -terminating the sequence. -They are available only at the start of an ARE, -and may not be used later within it. -.PP -In addition to the usual (\fItight\fR) RE syntax, in which all characters are -significant, there is an \fIexpanded\fR syntax, -available in all flavors of RE -with the \fB-expanded\fR switch, or in AREs with the embedded x option. -In the expanded syntax, -white-space characters are ignored -and all characters between a -\fB#\fR -and the following newline (or the end of the RE) are ignored, -permitting paragraphing and commenting a complex RE. -There are three exceptions to that basic rule: -.RS 2 -.PP -a white-space character or `\fB#\fR' preceded by `\fB\e\fR' is retained -.PP -white space or `\fB#\fR' within a bracket expression is retained -.PP -white space and comments are illegal within multi-character symbols -like the ARE `\fB(?:\fR' or the BRE `\fB\e(\fR' -.RE -.PP -Expanded-syntax -white-space characters are blank, tab, newline, etc. (any character -defined as \fIspace\fR by -\fIctype\fR(3)). -Exactly how a multi-line expanded-syntax RE -can be entered interactively by a user, -if at all, is application-specific; -expanded syntax is primarily a scripting facility. -.PP -Finally, in an ARE, -outside bracket expressions, the sequence -`\fB(?#\fIttt\fB)\fR' -(where -\fIttt\fR -is any text not containing a -`\fB)\fR') -is a comment, -completely ignored. -Again, this is not allowed between the characters of -multi-character symbols like -`\fB(?:\fR'. -Such comments are more a historical artifact than a useful facility, -and their use is deprecated; -use the expanded syntax instead. -.PP -\fINone\fR of these metasyntax extensions is available if the application -(or an initial -\fB***=\fR -director) -has specified that the user's input be treated as a literal string -rather than as an RE. -.SH MATCHING -In the event that an RE could match more than one substring of a given -string, -the RE matches the one starting earliest in the string. -If the RE could match more than one substring starting at that point, -its choice is determined by its \fIpreference\fR: -either the longest substring, or the shortest. -.PP -Most atoms, and all constraints, have no preference. -A parenthesized RE has the same preference (possibly none) as the RE. -A quantified atom with quantifier -\fB{\fIm\fB}\fR -or -\fB{\fIm\fB}?\fR -has the same preference (possibly none) as the atom itself. -A quantified atom with other normal quantifiers (including -\fB{\fIm\fB,\fIn\fB}\fR -with -\fIm\fR -equal to -\fIn\fR) -prefers longest match. -A quantified atom with other non-greedy quantifiers (including -\fB{\fIm\fB,\fIn\fB}?\fR -with -\fIm\fR -equal to -\fIn\fR) -prefers shortest match. -A branch has the same preference as the first quantified atom in it -which has a preference. -An RE consisting of two or more branches connected by the -\fB|\fR -operator prefers longest match. -.PP -Subject to the constraints imposed by the rules for matching the whole RE, -subexpressions also match the longest or shortest possible substrings, -based on their preferences, -with subexpressions starting earlier in the RE taking priority over -ones starting later. -Note that outer subexpressions thus take priority over -their component subexpressions. -.PP -Note that the quantifiers -\fB{1,1}\fR -and -\fB{1,1}?\fR -can be used to force longest and shortest preference, respectively, -on a subexpression or a whole RE. -.PP -Match lengths are measured in characters, not collating elements. -An empty string is considered longer than no match at all. -For example, -\fBbb*\fR -matches the three middle characters of -`\fBabbbc\fR', -\fB(week|wee)(night|knights)\fR -matches all ten characters of -`\fBweeknights\fR', -when -\fB(.*).*\fR -is matched against -\fBabc\fR -the parenthesized subexpression -matches all three characters, and -when -\fB(a*)*\fR -is matched against -\fBbc\fR -both the whole RE and the parenthesized -subexpression match an empty string. -.PP -If case-independent matching is specified, -the effect is much as if all case distinctions had vanished from the -alphabet. -When an alphabetic that exists in multiple cases appears as an -ordinary character outside a bracket expression, it is effectively -transformed into a bracket expression containing both cases, -so that -\fBx\fR -becomes -`\fB[xX]\fR'. -When it appears inside a bracket expression, all case counterparts -of it are added to the bracket expression, so that -\fB[x]\fR -becomes -\fB[xX]\fR -and -\fB[^x]\fR -becomes -`\fB[^xX]\fR'. -.PP -If newline-sensitive matching is specified, -\fB.\fR -and bracket expressions using -\fB^\fR -will never match the newline character -(so that matches will never cross newlines unless the RE -explicitly arranges it) -and -\fB^\fR -and -\fB$\fR -will match the empty string after and before a newline -respectively, in addition to matching at beginning and end of string -respectively. -ARE -\fB\eA\fR -and -\fB\eZ\fR -continue to match beginning or end of string \fIonly\fR. -.PP -If partial newline-sensitive matching is specified, -this affects -\fB.\fR -and bracket expressions -as with newline-sensitive matching, but not -\fB^\fR -and -`\fB$\fR'. -.PP -If inverse partial newline-sensitive matching is specified, -this affects -\fB^\fR -and -\fB$\fR -as with -newline-sensitive matching, -but not -\fB.\fR -and bracket expressions. -This isn't very useful but is provided for symmetry. -.SH "LIMITS AND COMPATIBILITY" -No particular limit is imposed on the length of REs. -Programs intended to be highly portable should not employ REs longer -than 256 bytes, -as a POSIX-compliant implementation can refuse to accept such REs. -.PP -The only feature of AREs that is actually incompatible with -POSIX EREs is that -\fB\e\fR -does not lose its special -significance inside bracket expressions. -All other ARE features use syntax which is illegal or has -undefined or unspecified effects in POSIX EREs; -the -\fB***\fR -syntax of directors likewise is outside the POSIX -syntax for both BREs and EREs. -.PP -Many of the ARE extensions are borrowed from Perl, but some have -been changed to clean them up, and a few Perl extensions are not present. -Incompatibilities of note include -`\fB\eb\fR', -`\fB\eB\fR', -the lack of special treatment for a trailing newline, -the addition of complemented bracket expressions to the things -affected by newline-sensitive matching, -the restrictions on parentheses and back references in lookahead constraints, -and the longest/shortest-match (rather than first-match) matching semantics. -.PP -The matching rules for REs containing both normal and non-greedy quantifiers -have changed since early beta-test versions of this package. -(The new rules are much simpler and cleaner, -but don't work as hard at guessing the user's real intentions.) -.PP -Henry Spencer's original 1986 \fIregexp\fR package, -still in widespread use (e.g., in pre-8.1 releases of Tcl), -implemented an early version of today's EREs. -There are four incompatibilities between \fIregexp\fR's near-EREs -(`RREs' for short) and AREs. -In roughly increasing order of significance: -.PP -.RS -In AREs, -\fB\e\fR -followed by an alphanumeric character is either an -escape or an error, -while in RREs, it was just another way of writing the -alphanumeric. -This should not be a problem because there was no reason to write -such a sequence in RREs. -.PP -\fB{\fR -followed by a digit in an ARE is the beginning of a bound, -while in RREs, -\fB{\fR -was always an ordinary character. -Such sequences should be rare, -and will often result in an error because following characters -will not look like a valid bound. -.PP -In AREs, -\fB\e\fR -remains a special character within -`\fB[\|]\fR', -so a literal -\fB\e\fR -within -\fB[\|]\fR -must be written -`\fB\e\e\fR'. -\fB\e\e\fR -also gives a literal -\fB\e\fR -within -\fB[\|]\fR -in RREs, -but only truly paranoid programmers routinely doubled the backslash. -.PP -AREs report the longest/shortest match for the RE, -rather than the first found in a specified search order. -This may affect some RREs which were written in the expectation that -the first match would be reported. -(The careful crafting of RREs to optimize the search order for fast -matching is obsolete (AREs examine all possible matches -in parallel, and their performance is largely insensitive to their -complexity) but cases where the search order was exploited to deliberately -find a match which was \fInot\fR the longest/shortest will need rewriting.) -.RE - -.SH "BASIC REGULAR EXPRESSIONS" -BREs differ from EREs in several respects. -`\fB|\fR', -`\fB+\fR', -and -\fB?\fR -are ordinary characters and there is no equivalent -for their functionality. -The delimiters for bounds are -\fB\e{\fR -and -`\fB\e}\fR', -with -\fB{\fR -and -\fB}\fR -by themselves ordinary characters. -The parentheses for nested subexpressions are -\fB\e(\fR -and -`\fB\e)\fR', -with -\fB(\fR -and -\fB)\fR -by themselves ordinary characters. -\fB^\fR -is an ordinary character except at the beginning of the -RE or the beginning of a parenthesized subexpression, -\fB$\fR -is an ordinary character except at the end of the -RE or the end of a parenthesized subexpression, -and -\fB*\fR -is an ordinary character if it appears at the beginning of the -RE or the beginning of a parenthesized subexpression -(after a possible leading -`\fB^\fR'). -Finally, -single-digit back references are available, -and -\fB\e<\fR -and -\fB\e>\fR -are synonyms for -\fB[[:<:]]\fR -and -\fB[[:>:]]\fR -respectively; -no other escapes are available. - -.VE 8.1 -.SH KEYWORDS -match, regular expression, string diff --git a/doc/registry.n b/doc/registry.n deleted file mode 100644 index f0e199f..0000000 --- a/doc/registry.n +++ /dev/null @@ -1,168 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: registry.n,v 1.4 1999/04/16 00:46:35 stanton Exp $ -'\" -.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, -.VS -\fBHKEY_CLASSES_ROOT\fR, \fBHKEY_CURRENT_USER\fR, -\fBHKEY_CURRENT_CONFIG\fR, \fBHKEY_PERFORMANCE_DATA\fR, or -\fBHKEY_DYN_DATA\fR. The \fIkeypath\fR can be one or more -.VE -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. If the -specified \fIkeyName\fR does not exist, then an error is generated. -.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. -.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/doc/regsub.n b/doc/regsub.n deleted file mode 100644 index 516a417..0000000 --- a/doc/regsub.n +++ /dev/null @@ -1,72 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: regsub.n,v 1.2 1998/09/14 18:39:54 stanton Exp $ -'\" -.so man.macros -.TH regsub n 7.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -regsub \- Perform substitutions based on regular expression pattern matching -.SH SYNOPSIS -\fBregsub \fR?\fIswitches\fR? \fIexp string subSpec varName\fR -.BE - -.SH DESCRIPTION -.PP -This command matches the regular expression \fIexp\fR against -\fIstring\fR, -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 -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 -matched \fIexp\fR. -If \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit -between 1 and 9, then it is replaced in the substitution with -the portion of \fIstring\fR that matched the \fIn\fR-th -parenthesized subexpression of \fIexp\fR. -Additional backslashes may be used in \fIsubSpec\fR to prevent special -interpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or -backslash. -The use of backslashes in \fIsubSpec\fR tends to interact badly -with the Tcl parser's use of backslashes, so it's generally -safest to enclose \fIsubSpec\fR in braces if it includes -backslashes. -.LP -If the initial arguments to \fBregexp\fR start with \fB\-\fR then -they are treated as switches. The following switches are -currently supported: -.TP 10 -\fB\-all\fR -All ranges in \fIstring\fR that match \fIexp\fR are found and -substitution is performed for each of these ranges. -Without this switch only the first -matching range is found and substituted. -If \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR'' -sequences are handled for each substitution using the information -from the corresponding match. -.TP 10 -\fB\-nocase\fR -Upper-case characters in \fIstring\fR will be converted to lower-case -before matching against \fIexp\fR; however, substitutions specified -by \fIsubSpec\fR use the original unconverted form of \fIstring\fR. -.TP 10 -\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. -.PP -The command returns a count of the number of matching ranges that -were found and replaced. -See the manual entry for \fBregexp\fR for details on the interpretation -of regular expressions. - -.SH KEYWORDS -match, pattern, regular expression, substitute diff --git a/doc/rename.n b/doc/rename.n deleted file mode 100644 index d7617e3..0000000 --- a/doc/rename.n +++ /dev/null @@ -1,32 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: rename.n,v 1.2 1998/09/14 18:39:54 stanton Exp $ -'\" -.so man.macros -.TH rename n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -rename \- Rename or delete a command -.SH SYNOPSIS -\fBrename \fIoldName newName\fR -.BE - -.SH DESCRIPTION -.PP -Rename the command that used to be called \fIoldName\fR so that it -is now called \fInewName\fR. -If \fInewName\fR is an empty string then \fIoldName\fR is deleted. -\fIoldName\fR and \fInewName\fR may include namespace qualifiers -(names of containing namespaces). -If a command is renamed into a different namespace, -future invocations of it will execute in the new namespace. -The \fBrename\fR command returns an empty string as result. - -.SH KEYWORDS -command, delete, namespace, rename diff --git a/doc/resource.n b/doc/resource.n deleted file mode 100644 index 428591b..0000000 --- a/doc/resource.n +++ /dev/null @@ -1,155 +0,0 @@ -'\" -'\" 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. -'\" RCS: @(#) $Id: resource.n,v 1.4 1999/04/16 00:46:36 stanton Exp $ -'\" -.so man.macros -.TH resource n 8.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -resource \- Manipulate Macintosh resources -.SH SYNOPSIS -\fBresource \fIoption\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBresource\fR command provides some generic operations for -dealing with Macintosh resources. This command is only supported on -the Macintosh platform. Each Macintosh file consists of two -\fIforks\fR: a \fIdata\fR fork and a \fIresource\fR fork. You use the -normal open, puts, close, etc. commands to manipulate the data fork. -You must use this command, however, to interact with the resource -fork. \fIOption\fR indicates what resource command to perform. Any -unique abbreviation for \fIoption\fR is acceptable. The valid options -are: -.TP -\fBresource close \fIrsrcRef\fR -Closes the given resource reference (obtained from \fBresource -open\fR). Resources from that resource file will no longer be -available. -.TP -\fBresource delete\fR ?\fIoptions\fR? \fIresourceType\fR -This command will delete the resource specified by \fIoptions\fR and -type \fIresourceType\fR (see RESOURCE TYPES below). The options -give you several ways to specify the resource to be deleted. -.RS -.TP -\fB\-id\fR \fIresourceId\fR -If the \fB-id\fR option is given the id \fIresourceId\fR (see RESOURCE -IDS below) is used to specify the resource to be deleted. The id must -be a number - to specify a name use the \fB\-name\fR option. -.TP -\fB\-name\fR \fIresourceName\fR -If \fB-name\fR is specified, the resource named -\fIresourceName\fR will be deleted. If the \fB-id\fR is also -provided, then there must be a resource with BOTH this name and -this id. If no name is provided, then the id will be used regardless -of the name of the actual resource. -.TP -\fB\-file\fR \fIresourceRef\fR -If the \fB-file\fR option is specified then the resource will be -deleted from the file pointed to by \fIresourceRef\fR. Otherwise the -first resource with the given \fIresourceName\fR and or -\fIresourceId\fR which is found on the resource file path will be -deleted. To inspect the file path, use the \fIresource files\fR command. -.RE -.TP -\fBresource files ?\fIresourceRef\fR? -If \fIresourceRef\fRis not provided, this command returns a Tcl list -of the resource references for all the currently open resource files. -The list is in the normal Macintosh search order for resources. If -\fIresourceRef\fR is specified, the command will -return the path to the file whose resource fork is represented by that -token. -.TP -\fBresource list \fIresourceType\fR ?\fIresourceRef\fR? -List all of the resources ids of type \fIresourceType\fR (see RESOURCE -TYPES below). If \fIresourceRef\fR is specified then the command will -limit the search to that particular resource file. Otherwise, all -resource files currently opened by the application will be searched. -A Tcl list of either the resource name's or resource id's of the found -resources will be returned. See the RESOURCE IDS section below for -more details about what a resource id is. -.TP -\fBresource open \fIfileName\fR ?\fIaccess\fR? -Open the resource for the file \fIfileName\fR. Standard file access -permissions may also be specified (see the manual entry for \fBopen\fR -for details). A resource reference (\fIresourceRef\fR) is returned -that can be used by the other resource commands. An error can occur -if the file doesn't exist or the file does not have a resource fork. -However, if you open the file with write permissions the file and/or -resource fork will be created instead of generating an error. -.TP -\fBresource read \fIresourceType\fR \fIresourceId\fR ?\fIresourceRef\fR? -Read the entire resource of type \fIresourceType\fR (see RESOURCE -TYPES below) and the name or id of \fIresourceId\fR (see RESOURCE IDS -below) into memory and return the result. If \fIresourceRef\fR is -specified we limit our search to that resource file, otherwise we -search all open resource forks in the application. It is important to -note that most Macintosh resource use a binary format and the data -returned from this command may have embedded NULLs or other non-ASCII -data. -.TP -\fBresource types ?\fIresourceRef\fR? -This command returns a Tcl list of all resource types (see RESOURCE -TYPES below) found in the resource file pointed to by -\fIresourceRef\fR. If \fIresourceRef\fR is not specified it will -return all the resource types found in every resource file currently -opened by the application. -.TP -\fBresource write\fR ?\fIoptions\fR? \fIresourceType\fR \fIdata\fR -This command will write the passed in \fIdata\fR as a new resource of -type \fIresourceType\fR (see RESOURCE TYPES below). Several options -are available that describe where and how the resource is stored. -.RS -.TP -\fB\-id\fR \fIresourceId\fR -If the \fB-id\fR option is given the id \fIresourceId\fR (see RESOURCE -IDS below) is used for the new resource, otherwise a unique id will be -generated that will not conflict with any existing resource. However, -the id must be a number - to specify a name use the \fB\-name\fR option. -.TP -\fB\-name\fR \fIresourceName\fR -If \fB-name\fR is specified the resource will be named -\fIresourceName\fR, otherwise it will have the empty string as the -name. -.TP -\fB\-file\fR \fIresourceRef\fR -If the \fB-file\fR option is specified then the resource will be -written in the file pointed to by \fIresourceRef\fR, otherwise the -most resently open resource will be used. -.TP -\fB\-force\fR -If the target resource already exists, then by default Tcl will not -overwrite it, but raise an error instead. Use the -force flag to -force overwriting the extant resource. -.RE - -.SH "RESOURCE TYPES" -Resource types are defined as a four character string that is then -mapped to an underlying id. For example, \fBTEXT\fR refers to the -Macintosh resource type for text. The type \fBSTR#\fR is a list of -counted strings. All Macintosh resources must be of some type. See -Macintosh documentation for a more complete list of resource types -that are commonly used. - -.SH "RESOURCE IDS" -For this command the notion of a resource id actually refers to two -ideas in Macintosh resources. Every place you can use a resource Id -you can use either the resource name or a resource number. Names are -always searched or returned in preference to numbers. For example, -the \fBresource list\fR command will return names if they exist or -numbers if the name is NULL. - -.SH "SEE ALSO" -open - -.SH "PORTABILITY ISSUES" -The resource command is only available on Macintosh. - -.SH KEYWORDS -open, resource diff --git a/doc/return.n b/doc/return.n deleted file mode 100644 index d3a3635..0000000 --- a/doc/return.n +++ /dev/null @@ -1,89 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: return.n,v 1.2 1998/09/14 18:39:54 stanton Exp $ -'\" -.so man.macros -.TH return n 7.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -return \- Return from a procedure -.SH SYNOPSIS -\fBreturn \fR?\fB\-code \fIcode\fR? ?\fB\-errorinfo \fIinfo\fR? ?\fB\-errorcode\fI code\fR? ?\fIstring\fR? -.BE - -.SH DESCRIPTION -.PP -Return immediately from the current procedure -(or top-level command or \fBsource\fR command), -with \fIstring\fR as the return value. If \fIstring\fR is not specified then -an empty string will be returned as result. - -.SH "EXCEPTIONAL RETURNS" -.PP -In the usual case where the \fB\-code\fR option isn't -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 -exceptional return from the procedure. -\fICode\fR may have any of the following values: -.TP 10 -\fBok\fR -Normal return: same as if the option is omitted. -.TP 10 -\fBerror\fR -Error return: same as if the \fBerror\fR command were used to -terminate the procedure, except for handling of \fBerrorInfo\fR -and \fBerrorCode\fR variables (see below). -.TP 10 -\fBreturn\fR -The current procedure will return with a completion code of -TCL_RETURN, so that the procedure that invoked it will return -also. -.TP 10 -\fBbreak\fR -The current procedure will return with a completion code of -TCL_BREAK, which will terminate the innermost nested loop in -the code that invoked the current procedure. -.TP 10 -\fBcontinue\fR -The current procedure will return with a completion code of -TCL_CONTINUE, which will terminate the current iteration of -the innermost nested loop in the code that invoked the current -procedure. -.TP 10 -\fIvalue\fR -\fIValue\fR must be an integer; it will be returned as the -completion code for the current procedure. -.LP -The \fB\-code\fR option is rarely used. -It is provided so that procedures that implement -new control structures can reflect exceptional conditions back to -their callers. -.PP -Two additional options, \fB\-errorinfo\fR and \fB\-errorcode\fR, -may be used to provide additional information during error -returns. -These options are ignored unless \fIcode\fR is \fBerror\fR. -.PP -The \fB\-errorinfo\fR option specifies an initial stack -trace for the \fBerrorInfo\fR variable; if it is not specified then -the stack trace left in \fBerrorInfo\fR will include the call to -the procedure and higher levels on the stack but it will not include -any information about the context of the error within the procedure. -Typically the \fIinfo\fR value is supplied from the value left -in \fBerrorInfo\fR after a \fBcatch\fR command trapped an error within -the procedure. -.PP -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. - -.SH KEYWORDS -break, continue, error, procedure, return diff --git a/doc/safe.n b/doc/safe.n deleted file mode 100644 index 749a57b..0000000 --- a/doc/safe.n +++ /dev/null @@ -1,350 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: safe.n,v 1.3 1999/04/16 00:46:36 stanton Exp $ -'\" -.so man.macros -.TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Safe\ Base \- A mechanism for creating and manipulating safe interpreters. -.SH SYNOPSIS -\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR? -.sp -\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR? -.sp -\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR? -.sp -\fB::safe::interpDelete\fR \fIslave\fR -.sp -\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR -.sp -\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR -.sp -\fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? -.SH OPTIONS -.PP -?\fB\-accessPath\fR \fIpathList\fR? -?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR? -?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR? -?\fB\-deleteHook\fR \fIscript\fR? -.BE - -.SH DESCRIPTION -Safe Tcl is a mechanism for executing untrusted Tcl scripts -safely and for providing mediated access by such scripts to -potentially dangerous functionality. -.PP -The Safe Base ensures that untrusted Tcl scripts cannot harm the -hosting application. -The Safe Base prevents integrity and privacy attacks. Untrusted Tcl -scripts are prevented from corrupting the state of the hosting -application or computer. Untrusted scripts are also prevented from -disclosing information stored on the hosting computer or in the -hosting application to any party. -.PP -The Safe Base allows a master interpreter to create safe, restricted -interpreters that contain a set of predefined aliases for the \fBsource\fR, -\fBload\fR, \fBfile\fR, \fBencoding\fR, and \fBexit\fR commands and -are able to use the auto-loading and package mechanisms. -.PP -No knowledge of the file system structure is leaked to the -safe interpreter, because it has access only to a virtualized path -containing tokens. When the safe interpreter requests to source a file, it -uses the token in the virtual path as part of the file name to source; the -master interpreter transparently -translates the token into a real directory name and executes the -requested operation (see the section \fBSECURITY\fR below for details). -Different levels of security can be selected by using the optional flags -of the commands described below. -.PP -All commands provided in the master interpreter by the Safe Base reside in -the \fBsafe\fR namespace: - -.SH COMMANDS -The following commands are provided in the master interpreter: -.TP -\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR? -Creates a safe interpreter, installs the aliases described in the section -\fBALIASES\fR and initializes the auto-loading and package mechanism as -specified by the supplied \fBoptions\fR. -See the \fBOPTIONS\fR section below for a description of the -optional arguments. -If the \fIslave\fR argument is omitted, a name will be generated. -\fB::safe::interpCreate\fR always returns the interpreter name. -.TP -\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR? -This command is similar to \fBinterpCreate\fR except it that does not -create the safe interpreter. \fIslave\fR must have been created by some -other means, like \fBinterp create \-safe\fR. -.TP -\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR? -If no \fIoptions\fR are given, returns the settings for all options for the -named safe interpreter as a list of options and their current values -for that \fIslave\fR. -If a single additional argument is provided, -it will return a list of 2 elements \fIname\fR and \fIvalue\fR where -\fIname\fR is the full name of that option and \fIvalue\fR the current value -for that option and the \fIslave\fR. -If more than two additional arguments are provided, it will reconfigure the -safe interpreter and change each and only the provided options. -See the section on \fBOPTIONS\fR below for options description. -Example of use: -.RS -.CS -# Create a new interp with the same configuration as "$i0" : -set i1 [eval safe::interpCreate [safe::interpConfigure $i0]] -# Get the current deleteHook -set dh [safe::interpConfigure $i0 \-del] -# Change (only) the statics loading ok attribute of an interp -# and its deleteHook (leaving the rest unchanged) : -safe::interpConfigure $i0 \-delete {foo bar} \-statics 0 ; -.CE -.RE -.TP -\fB::safe::interpDelete\fR \fIslave\fR -Deletes the safe interpreter and cleans up the corresponding -master interpreter data structures. -If a \fIdeleteHook\fR script was specified for this interpreter it is -evaluated before the interpreter is deleted, with the name of the -interpreter as an additional argument. -.TP -\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR -This command finds and returns the token for the real directory -\fIdirectory\fR in the safe interpreter's current virtual access path. -It generates an error if the directory is not found. -Example of use: -.RS -.CS -$slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]] -.CE -.RE -.TP -\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR -This command adds \fIdirectory\fR to the virtual path maintained for the -safe interpreter in the master, and returns the token that can be used in -the safe interpreter to obtain access to files in that directory. -If the directory is already in the virtual path, it only returns the token -without adding the directory to the virtual path again. -Example of use: -.RS -.CS -$slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]] -.CE -.RE -.TP -\fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? -This command installs a script that will be called when interesting -life cycle events occur for a safe interpreter. -When called with no arguments, it returns the currently installed script. -When called with one argument, an empty string, the currently installed -script is removed and logging is turned off. -The script will be invoked with one additional argument, a string -describing the event of interest. -The main purpose is to help in debugging safe interpreters. -Using this facility you can get complete error messages while the safe -interpreter gets only generic error messages. -This prevents a safe interpreter from seeing messages about failures -and other events that might contain sensitive information such as real -directory names. -.RS -Example of use: -.CS -::safe::setLogCmd puts stderr -.CE -Below is the output of a sample session in which a safe interpreter -attempted to source a file not found in its virtual access path. -Note that the safe interpreter only received an error message saying that -the file was not found: -.CS -NOTICE for slave interp10 : Created -NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=() -NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)} -ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory -.CE -.RE - -.SH OPTIONS -The following options are common to -\fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, -and \fB::safe::interpConfigure\fR. -Any option name can be abbreviated to its minimal -non-ambiguous name. -Option names are not case sensitive. -.TP -\fB\-accessPath\fR \fIdirectoryList\fR -This option sets the list of directories from which the safe interpreter -can \fBsource\fR and \fBload\fR files. -If this option is not specified, or if it is given as the -empty list, the safe interpreter will use the same directories as its -master for auto-loading. -See the section \fBSECURITY\fR below for more detail about virtual paths, -tokens and access control. -.TP -\fB\-statics\fR \fIboolean\fR -This option specifies if the safe interpreter will be allowed -to load statically linked packages (like \fBload {} Tk\fR). -The default value is \fBtrue\fR : -safe interpreters are allowed to load statically linked packages. -.TP -\fB\-noStatics\fR -This option is a convenience shortcut for \fB-statics false\fR and -thus specifies that the safe interpreter will not be allowed -to load statically linked packages. -.TP -\fB\-nested\fR \fIboolean\fR -This option specifies if the safe interpreter will be allowed -to load packages into its own sub-interpreters. -The default value is \fBfalse\fR : -safe interpreters are not allowed to load packages into -their own sub-interpreters. -.TP -\fB\-nestedLoadOk\fR -This option is a convenience shortcut for \fB-nested true\fR and -thus specifies the safe interpreter will be allowed -to load packages into its own sub-interpreters. -.TP -\fB\-deleteHook\fR \fIscript\fR -When this option is given an non empty \fIscript\fR, it will be -evaluated in the master with the name of -the safe interpreter as an additional argument -just before actually deleting the safe interpreter. -Giving an empty value removes any currently installed deletion hook -script for that safe interpreter. -The default value (\fB{}\fR) is not to have any deletion call back. -.SH ALIASES -The following aliases are provided in a safe interpreter: -.TP -\fBsource\fR \fIfileName\fR -The requested file, a Tcl source file, is sourced into the safe interpreter -if it is found. -The \fBsource\fR alias can only source files from directories in -the virtual path for the safe interpreter. The \fBsource\fR alias requires -the safe interpreter to -use one of the token names in its virtual path to denote the directory in -which the file to be sourced can be found. -See the section on \fBSECURITY\fR for more discussion of restrictions on -valid filenames. -.TP -\fBload\fR \fIfileName\fR -The requested file, a shared object file, is dynamically loaded into the -safe interpreter if it is found. -The filename must contain a token name mentioned in the virtual path for -the safe interpreter for it to be found successfully. -Additionally, the shared object file must contain a safe entry point; see -the manual page for the \fBload\fR command for more details. -.TP -\fBfile\fR ?\fIsubCmd args...\fR? -The \fBfile\fR alias provides access to a safe subset of the subcommands of -the \fBfile\fR command; it allows only \fBdirname\fR, \fBjoin\fR, -\fBextension\fR, \fBroot\fR, \fBtail\fR, \fBpathname\fR and \fBsplit\fR -subcommands. For more details on what these subcommands do see the manual -page for the \fBfile\fR command. -.TP -\fBencoding\fR ?\fIsubCmd args...\fR? -The \fBenconding\fR alias provides access to a safe subset of the -subcommands of the \fBencoding\fR command; it disallows setting of -the system encoding, but allows all other subcommands including -\fBsystem\fR to check the current encoding. -.TP -\fBexit\fR -The calling interpreter is deleted and its computation is stopped, but the -Tcl process in which this interpreter exists is not terminated. - -.SH SECURITY -The Safe Base does not attempt to completely prevent annoyance and -denial of service attacks. These forms of attack prevent the -application or user from temporarily using the computer to perform -useful work, for example by consuming all available CPU time or -all available screen real estate. -These attacks, while aggravating, are deemed to be of lesser importance -in general than integrity and privacy attacks that the Safe Base -is to prevent. -.PP -The commands available in a safe interpreter, in addition to -the safe set as defined in \fBinterp\fR manual page, are mediated aliases -for \fBsource\fR, \fBload\fR, \fBexit\fR, and safe subsets of -\fBfile\fR and \fBencoding\fR. The safe interpreter can also auto-load -code and it can request that packages be loaded. -.PP -Because some of these commands access the local file system, there is a -potential for information leakage about its directory structure. -To prevent this, commands that take file names as arguments in a safe -interpreter use tokens instead of the real directory names. -These tokens are translated to the real directory name while a request to, -e.g., source a file is mediated by the master interpreter. -This virtual path system is maintained in the master interpreter for each safe -interpreter created by \fB::safe::interpCreate\fR or initialized by -\fB::safe::interpInit\fR and -the path maps tokens accessible in the safe interpreter into real path -names on the local file system thus preventing safe interpreters -from gaining knowledge about the -structure of the file system of the host on which the interpreter is -executing. -The only valid file names arguments -for the \fBsource\fR and \fBload\fR aliases provided to the slave -are path in the form of -\fB[file join \fR\fItoken filename\fR\fB]\fR (ie, when using the -native file path formats: \fItoken\fR\fB/\fR\fIfilename\fR -on Unix, \fItoken\fR\fB\\\fIfilename\fR on Windows, -and \fItoken\fR\fB:\fR\fIfilename\fR on the Mac), -where \fItoken\fR is representing one of the directories -of the \fIaccessPath\fR list and \fIfilename\fR is -one file in that directory (no sub directories access are allowed). -.PP -When a token is used in a safe interpreter in a request to source or -load a file, the token is checked and -translated to a real path name and the file to be -sourced or loaded is located on the file system. -The safe interpreter never gains knowledge of the actual path name under -which the file is stored on the file system. -.PP -To further prevent potential information leakage from sensitive files that -are accidentally included in the set of files that can be sourced by a safe -interpreter, the \fBsource\fR alias restricts access to files -meeting the following constraints: the file name must -fourteen characters or shorter, must not contain more than one dot ("\fB.\fR"), -must end up with the extension \fB.tcl\fR or be called \fBtclIndex\fR. -.PP -Each element of the initial access path -list will be assigned a token that will be set in -the slave \fBauto_path\fR and the first element of that list will be set as -the \fBtcl_library\fR for that slave. -.PP -If the access path argument is not given or is the empty list, -the default behavior is to let the slave access the same packages -as the master has access to (Or to be more precise: -only packages written in Tcl (which by definition can't be dangerous -as they run in the slave interpreter) and C extensions that -provides a Safe_Init entry point). For that purpose, the master's -\fBauto_path\fR will be used to construct the slave access path. -In order that the slave successfully loads the Tcl library files -(which includes the auto-loading mechanism itself) the \fBtcl_library\fR will be -added or moved to the first position if necessary, in the -slave access path, so the slave -\fBtcl_library\fR will be the same as the master's (its real -path will still be invisible to the slave though). -In order that auto-loading works the same for the slave and -the master in this by default case, the first-level -sub directories of each directory in the master \fBauto_path\fR will -also be added (if not already included) to the slave access path. -You can always specify a more -restrictive path for which sub directories will never be searched by -explicitly specifying your directory list with the \fB\-accessPath\fR flag -instead of relying on this default mechanism. -.PP -When the \fIaccessPath\fR is changed after the first creation or -initialization (ie through \fBinterpConfigure -accessPath \fR\fIlist\fR), -an \fBauto_reset\fR is automatically evaluated in the safe interpreter -to synchronize its \fBauto_index\fR with the new token list. - -.SH "SEE ALSO" -interp(n), library(n), load(n), package(n), source(n), unknown(n) - -.SH KEYWORDS -alias, auto\-loading, auto_mkindex, load, master interpreter, safe -interpreter, slave interpreter, source diff --git a/doc/scan.n b/doc/scan.n deleted file mode 100644 index 123ec5b..0000000 --- a/doc/scan.n +++ /dev/null @@ -1,182 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: scan.n,v 1.3 1999/04/16 00:46:36 stanton Exp $ -'\" -.so man.macros -.TH scan n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -scan \- Parse string using conversion specifiers in the style of sscanf -.SH SYNOPSIS -\fBscan \fIstring format varName \fR?\fIvarName ...\fR? -.BE - -.SH INTRODUCTION -.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 -of conversions performed, or -1 if the end of the input string is -reached before any conversions have been performed. -\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 -scanned from \fIstring\fR the result is converted back into a string -and assigned to the corresponding variable. - -.SH "DETAILS ON SCANNING" -.PP -\fBScan\fR operates by scanning \fIstring\fR and \fIformat\fR together. -If the next character in \fIformat\fR is a blank or tab then it -matches any number of white space characters in \fIstring\fR (including -zero). -Otherwise, if it isn't a \fB%\fR character then it -must match the next character of \fIstring\fR. -When a \fB%\fR is encountered in \fIformat\fR, it indicates -the start of a conversion specifier. -A conversion specifier contains up to four fields after the \fB%\fR: -a \fB*\fR, which indicates that the converted value is to be discarded -.VS 8.1 -instead of assigned to a variable; a XPG3 position specifier; a number -.VE 8.1 -indicating a maximum field width; and a conversion character. -All of these fields are optional except for the conversion character. -The fields that are present must appear in the order given above. -.PP -When \fBscan\fR finds a conversion specifier in \fIformat\fR, it -first skips any white-space characters in \fIstring\fR (unless the -specifier is \fB[\fR or \fBc\fR). -Then it converts the next input characters according to the -conversion specifier and stores the result in the variable given -by the next argument to \fBscan\fR. -.VS 8.1 -.PP -If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in -``\fB%2$d\fR'', then the variable to use is not taken from the next -sequential argument. Instead, it is taken from the argument indicated -by the number, where 1 corresponds to the first \fIvarName\fR. If -there are any positional specifiers in \fIformat\fR then all of the -specifiers must be positional. Every \fIvarName\fR on the argument -list must correspond to exactly one conversion specifier or an error -is generated. -.VE 8.1 -.PP -The following conversion characters are supported: -.TP 10 -\fBd\fR -The input field must be a decimal integer. -It is read in and the value is stored in the variable as a decimal string. -.TP 10 -\fBo\fR -The input field must be an octal integer. It is read in and the -value is stored in the variable as a decimal string. -.TP 10 -\fBx\fR -The input field must be a hexadecimal integer. It is read in -and the value is stored in the variable as a decimal string. -.VS 8.1 -.TP 10 -\fBu\fR -The input field must be a decimal integer. The value is stored in the -variable as an unsigned decimal integer string. -.TP 10 -\fBi\fR -The input field must be an integer. The base (i.e. decimal, octal, or -hexadecimal) is determined in the same fashion as described in -\fBexpr\fR. The value is stored in the variable as a decimal string. -.VE 8.1 -.TP 10 -\fBc\fR -A single character is read in and its binary value is stored in -the variable as a decimal string. -Initial white space is not skipped in this case, so the input -field may be a white-space character. -This conversion is different from the ANSI standard in that the -input field always consists of a single character and no field -width may be specified. -.TP 10 -\fBs\fR -The input field consists of all the characters up to the next -white-space character; the characters are copied to the variable. -.TP 10 -\fBe\fR or \fBf\fR or \fBg\fR -The input field must be a floating-point number consisting -of an optional sign, a string of decimal digits possibly -containing a decimal point, and an optional exponent consisting -of an \fBe\fR or \fBE\fR followed by an optional sign and a string of -decimal digits. -It is read in and stored in the variable as a floating-point string. -.TP 10 -\fB[\fIchars\fB]\fR -The input field consists of any number of characters in -\fIchars\fR. -The matching string is stored in the variable. -If the first character between the brackets is a \fB]\fR then -it is treated as part of \fIchars\fR rather than the closing -bracket for the set. -.VS 8.1 -If \fIchars\fR -contains a sequence of the form \fIa\fB\-\fIb\fR then any -character between \fIa\fR and \fIb\fR (inclusive) will match. -If the first or last character between the brackets is a \fB\-\fR, then -it is treated as part of \fIchars\fR rather than indicating a range. -.VE 8.1 -.TP 10 -\fB[^\fIchars\fB]\fR -The input field consists of any number of characters not in -\fIchars\fR. -The matching string is stored in the variable. -If the character immediately following the \fB^\fR is a \fB]\fR then it is -treated as part of the set rather than the closing bracket for -the set. -.VS 8.1 -If \fIchars\fR -contains a sequence of the form \fIa\fB\-\fIb\fR then any -character between \fIa\fR and \fIb\fR (inclusive) will be excluded -from the set. -If the first or last character between the brackets is a \fB\-\fR, then -it is treated as part of \fIchars\fR rather than indicating a range. -.TP 10 -\fBn\fR -No input is consumed from the input string. Instead, the total number -of chacters scanned from the input string so far is stored in the variable. -.VE 8.1 -.LP -The number of characters read from the input for a conversion is the -largest number that makes sense for that particular conversion (e.g. -as many decimal digits as possible for \fB%d\fR, as -many octal digits as possible for \fB%o\fR, and so on). -The input field for a given conversion terminates either when a -white-space character is encountered or when the maximum field -width has been reached, whichever comes first. -If a \fB*\fR is present in the conversion specifier -then no variable is assigned and the next scan argument is not consumed. - -.SH "DIFFERENCES FROM ANSI SSCANF" -.PP -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: -.VS 8.1 -.IP [1] -\fB%p\fR conversion specifier is not currently -supported. -.VE 8.1 -.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] -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). - -.SH KEYWORDS -conversion specifier, parse, scan diff --git a/doc/seek.n b/doc/seek.n deleted file mode 100644 index 3620e83..0000000 --- a/doc/seek.n +++ /dev/null @@ -1,55 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: seek.n,v 1.2 1998/09/14 18:39:55 stanton Exp $ -'\" -.so man.macros -.TH seek n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -seek \- Change the access position for an open channel -.SH SYNOPSIS -\fBseek \fIchannelId offset \fR?\fIorigin\fR? -.BE - -.SH DESCRIPTION -.PP -Changes the current access position for \fIchannelId\fR. -\fIChannelId\fR must be a channel identifier such as returned from a -previous invocation of \fBopen\fR or \fBsocket\fR. -The \fIoffset\fR and \fIorigin\fR -arguments specify the position at which the next read or write will occur -for \fIchannelId\fR. \fIOffset\fR must be an integer (which may be -negative) and \fIorigin\fR must be one of the following: -.TP 10 -\fBstart\fR -The new access position will be \fIoffset\fR bytes from the start -of the underlying file or device. -.TP 10 -\fBcurrent\fR -The new access position will be \fIoffset\fR bytes from the current -access position; a negative \fIoffset\fR moves the access position -backwards in the underlying file or device. -.TP 10 -\fBend\fR -The new access position will be \fIoffset\fR bytes from the end of -the file or device. A negative \fIoffset\fR places the access position -before the end of file, and a positive \fIoffset\fR places the access -position after the end of file. -.LP -The \fIorigin\fR argument defaults to \fBstart\fR. -.PP -The command flushes all buffered output for the channel before the command -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 -file or device does not support seeking. - -.SH KEYWORDS -access position, file, seek diff --git a/doc/set.n b/doc/set.n deleted file mode 100644 index b9d1bb5..0000000 --- a/doc/set.n +++ /dev/null @@ -1,48 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: set.n,v 1.2 1998/09/14 18:39:55 stanton Exp $ -'\" -.so man.macros -.TH set n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -set \- Read and write variables -.SH SYNOPSIS -\fBset \fIvarName \fR?\fIvalue\fR? -.BE - -.SH DESCRIPTION -.PP -Returns the value of variable \fIvarName\fR. -If \fIvalue\fR is specified, then set -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. -Otherwise \fIvarName\fR refers to a scalar 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 \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/doc/socket.n b/doc/socket.n deleted file mode 100644 index d73883f..0000000 --- a/doc/socket.n +++ /dev/null @@ -1,134 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998-1999 by Scriptics Corporation. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: socket.n,v 1.4 1999/04/16 00:46:36 stanton Exp $ -.so man.macros -.TH socket n 8.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -socket \- Open a TCP network connection -.SH SYNOPSIS -.sp -\fBsocket \fR?\fIoptions\fR? \fIhost port\fR -.sp -\fBsocket\fR \fB\-server \fIcommand\fR ?\fIoptions\fR? \fIport\fR -.BE - -.SH DESCRIPTION -.PP -This command opens a network socket and returns a channel -identifier that may be used in future invocations of commands like -\fBread\fR, \fBputs\fR and \fBflush\fR. -At present only the TCP network protocol is supported; future -releases may include support for additional protocols. -The \fBsocket\fR command may be used to open either the client or -server side of a connection, depending on whether the \fB\-server\fR -switch is specified. - -.SH "CLIENT SOCKETS" -.PP -If the \fB\-server\fR option is not specified, then the client side of a -connection is opened and the command returns a channel identifier -that can be used for both reading and writing. -\fIPort\fR and \fIhost\fR specify a port -to connect to; there must be a server accepting connections on -this port. \fIPort\fR is an integer port number and \fIhost\fR -is either a domain-style name such as \fBwww.sunlabs.com\fR or -a numerical IP address such as \fB127.0.0.1\fR. -Use \fIlocalhost\fR to refer to the host on which the command is invoked. -.PP -The following options may also be present before \fIhost\fR -to specify additional information about the connection: -.TP -\fB\-myaddr\fI addr\fR -\fIAddr\fR gives the domain-style name or numerical IP address of -the client-side network interface to use for the connection. -This option may be useful if the client machine has multiple network -interfaces. If the option is omitted then the client-side interface -will be chosen by the system software. -.TP -\fB\-myport\fI port\fR -\fIPort\fR specifies an integer port number to use for the client's -side of the connection. If this option is omitted, the client's -port number will be chosen at random by the system software. -.TP -\fB\-async\fR -The \fB\-async\fR option will cause the client socket to be connected -asynchronously. This means that the socket will be created immediately but -may not yet be connected to the server, when the call to \fBsocket\fR -returns. When a \fBgets\fR or \fBflush\fR is done on the socket before the -connection attempt succeeds or fails, if the socket is in blocking mode, the -operation will wait until the connection is completed or fails. If the -socket is in nonblocking mode and a \fBgets\fR or \fBflush\fR is done on -the socket before the connection attempt succeeds or fails, the operation -returns immediately and \fBfblocked\fR on the socket returns 1. - -.SH "SERVER SOCKETS" -.PP -If the \fB\-server\fR option is specified then the new socket -will be a server for the port given by \fIport\fR. -Tcl will automatically accept connections to the given port. -For each connection Tcl will create a new channel that may be used to -communicate with the client. Tcl then invokes \fIcommand\fR -with three additional arguments: the name of the new channel, the -address, in network address notation, of the client's host, and -the client's port number. -.PP -The following additional option may also be specified before \fIhost\fR: -.TP -\fB\-myaddr\fI addr\fR -\fIAddr\fR gives the domain-style name or numerical IP address of -the server-side network interface to use for the connection. -This option may be useful if the server machine has multiple network -interfaces. If the option is omitted then the server socket is bound -to the special address INADDR_ANY so that it can accept connections from -any interface. -.PP -Server channels cannot be used for input or output; their sole use is to -accept new client connections. The channels created for each incoming -client connection are opened for input and output. Closing the server -channel shuts down the server so that no new connections will be -accepted; however, existing connections will be unaffected. -.PP -Server sockets depend on the Tcl event mechanism to find out when -new connections are opened. If the application doesn't enter the -event loop, for example by invoking the \fBvwait\fR command or -calling the C procedure \fBTcl_DoOneEvent\fR, then no connections -will be accepted. - -.SH CONFIGURATION OPTIONS -The \fBfconfigure\fR command can be used to query several readonly -configuration options for socket channels: -.VS 8.0.5 -.TP -\fB\-error\fR -This option gets the current error status of the given socket. This -is useful when you need to determine if an asynchronous connect -operation succeeded. If there was an error, the error message is -returned. If there was no error, an empty string is returned. -.VE 8.0.5 -.TP -\fB\-sockname\fR -This option returns a list of three elements, the address, the host name -and the port number for the socket. If the host name cannot be computed, -the second element is identical to the address, the first element of the -list. -.TP -\fB\-peername\fR -This option is not supported by server sockets. For client and accepted -sockets, this option returns a list of three elements; these are the -address, the host name and the port to which the peer socket is connected -or bound. If the host name cannot be computed, the second element of the -list is identical to the address, its first element. -.PP - -.SH "SEE ALSO" -flush(n), open(n), read(n) - -.SH KEYWORDS -bind, channel, connection, domain name, host, network address, socket, tcp diff --git a/doc/source.n b/doc/source.n deleted file mode 100644 index 024ab7b..0000000 --- a/doc/source.n +++ /dev/null @@ -1,44 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: source.n,v 1.2 1998/09/14 18:39:55 stanton Exp $ -'\" -.so man.macros -.TH source n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -source \- Evaluate a file or resource as a Tcl script -.SH SYNOPSIS -\fBsource \fIfileName\fR -.sp -\fBsource\fR \fB\-rsrc \fIresourceName \fR?\fIfileName\fR? -.sp -\fBsource\fR \fB\-rsrcid \fIresourceId \fR?\fIfileName\fR? -.BE - -.SH DESCRIPTION -.PP -This command takes the contents of the specified file or resource -and passes it to the Tcl interpreter as a text script. The return -value from \fBsource\fR is the return value of the last command -executed in the script. If an error occurs in evaluating the contents -of the script then the \fBsource\fR command will return that error. -If a \fBreturn\fR command is invoked from within the script then the -remainder of the file will be skipped and the \fBsource\fR command -will return normally with the result from the \fBreturn\fR command. - -The \fI\-rsrc\fR and \fI\-rsrcid\fR forms of this command are only -available on Macintosh computers. These versions of the command -allow you to source a script from a \fBTEXT\fR resource. You may specify -what \fBTEXT\fR resource to source by either name or id. By default Tcl -searches all open resource files, which include the current -application and any loaded C extensions. Alternatively, you may -specify the \fIfileName\fR where the \fBTEXT\fR resource can be found. - -.SH KEYWORDS -file, script diff --git a/doc/split.n b/doc/split.n deleted file mode 100644 index 04773b0..0000000 --- a/doc/split.n +++ /dev/null @@ -1,44 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: split.n,v 1.2 1998/09/14 18:39:55 stanton Exp $ -'\" -.so man.macros -.TH split n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -split \- Split a string into a proper Tcl list -.SH SYNOPSIS -\fBsplit \fIstring \fR?\fIsplitChars\fR? -.BE - -.SH DESCRIPTION -.PP -Returns a list created by splitting \fIstring\fR at each character -that is in the \fIsplitChars\fR argument. -Each element of the result list will consist of the -characters from \fIstring\fR that lie between instances of the -characters in \fIsplitChars\fR. -Empty list elements will be generated if \fIstring\fR contains -adjacent characters in \fIsplitChars\fR, or if the first or last -character of \fIstring\fR is in \fIsplitChars\fR. -If \fIsplitChars\fR is an empty string then each character of -\fIstring\fR becomes a separate element of the result list. -\fISplitChars\fR defaults to the standard white-space characters. -For example, -.CS -\fBsplit "comp.unix.misc" .\fR -.CE -returns \fB"comp unix misc"\fR and -.CS -\fBsplit "Hello world" {}\fR -.CE -returns \fB"H e l l o { } w o r l d"\fR. - -.SH KEYWORDS -list, split, string diff --git a/doc/string.n b/doc/string.n deleted file mode 100644 index 42d6e0b..0000000 --- a/doc/string.n +++ /dev/null @@ -1,143 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: string.n,v 1.3 1999/04/16 00:46:36 stanton Exp $ -'\" -.so man.macros -.TH string n 7.6 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -string \- Manipulate strings -.SH SYNOPSIS -\fBstring \fIoption arg \fR?\fIarg ...?\fR -.BE - -.SH DESCRIPTION -.PP -Performs one of several string operations, depending on \fIoption\fR. -The legal \fIoption\fRs (which may be abbreviated) are: -.TP -\fBstring compare \fIstring1 string2\fR -Perform a character-by-character comparison of strings \fIstring1\fR and -\fIstring2\fR in the same way as the C \fBstrcmp\fR procedure. Return -\-1, 0, or 1, depending on whether \fIstring1\fR is lexicographically -less than, equal to, or greater than \fIstring2\fR. -.TP -\fBstring first \fIstring1 string2\fR -Search \fIstring2\fR for a sequence of characters that exactly match -the characters in \fIstring1\fR. If found, return the index of the -first character in the first such match within \fIstring2\fR. If not -found, return \-1. -.TP -\fBstring index \fIstring charIndex\fR -Returns the \fIcharIndex\fR'th character of the \fIstring\fR -argument. A \fIcharIndex\fR of 0 corresponds to the first -character of the string. -If \fIcharIndex\fR is less than 0 or greater than -or equal to the length of the string then an empty string is -returned. -.TP -\fBstring last \fIstring1 string2\fR -Search \fIstring2\fR for a sequence of characters that exactly match -the characters in \fIstring1\fR. If found, return the index of the -first character in the last such match within \fIstring2\fR. If there -is no match, then return \-1. -.TP -\fBstring length \fIstring\fR -Returns a decimal string giving the number of characters in \fIstring\fR. -.TP -\fBstring match \fIpattern\fR \fIstring\fR -See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 -if it doesn't. Matching is done in a fashion similar to that -used by the C-shell. For the two strings to match, their contents -must be identical except that the following special sequences -may appear in \fIpattern\fR: -.RS -.IP \fB*\fR 10 -Matches any sequence of characters in \fIstring\fR, -including a null string. -.IP \fB?\fR 10 -Matches any single character in \fIstring\fR. -.IP \fB[\fIchars\fB]\fR 10 -Matches any character in the set given by \fIchars\fR. If a sequence -of the form -\fIx\fB\-\fIy\fR appears in \fIchars\fR, then any character -between \fIx\fR and \fIy\fR, inclusive, will match. -.IP \fB\e\fIx\fR 10 -Matches the single character \fIx\fR. This provides a way of -avoiding the special interpretation of the characters -\fB*?[]\e\fR in \fIpattern\fR. -.RE -.TP -\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. -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 -\fIlast\fR then an empty string is returned. -.VS -.TP -\fBstring tolower \fIstring\fR -Returns a value equal to \fIstring\fR except that all upper (or title) -case letters have been converted to lower case. -.TP -\fBstring totitle \fIstring\fR -Returns a value equal to \fIstring\fR except that the first character -in \fIstring\fR is converted to its Unicode title case variant (or upper -case if there is no title case variant) and the rest of the string is -converted to lower case. -.TP -\fBstring toupper \fIstring\fR -Returns a value equal to \fIstring\fR except that all lower (or title) -case letters have been converted to upper case. -.VE -.TP -\fBstring trim \fIstring\fR ?\fIchars\fR? -Returns a value equal to \fIstring\fR except that any leading -or trailing characters from the set given by \fIchars\fR are -removed. -If \fIchars\fR is not specified then white space is removed -(spaces, tabs, newlines, and carriage returns). -.TP -\fBstring trimleft \fIstring\fR ?\fIchars\fR? -Returns a value equal to \fIstring\fR except that any -leading characters from the set given by \fIchars\fR are -removed. -If \fIchars\fR is not specified then white space is removed -(spaces, tabs, newlines, and carriage returns). -.TP -\fBstring trimright \fIstring\fR ?\fIchars\fR? -Returns a value equal to \fIstring\fR except that any -trailing characters from the set given by \fIchars\fR are -removed. -If \fIchars\fR is not specified then white space is removed -(spaces, tabs, newlines, and carriage returns). -.VS -.TP -\fBstring wordend \fIstring index\fR -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 (Unicode letters -or decimal digits) or underscore (Unicode connector punctuation) -characters, or any single character other than these. -.TP -\fBstring wordstart \fIstring index\fR -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 (Unicode letters or decimal digits) -or underscore (Unicode connector punctuation) characters, or any -single character other than these. -.VE - -.SH KEYWORDS -case conversion, compare, index, match, pattern, string, word diff --git a/doc/subst.n b/doc/subst.n deleted file mode 100644 index 8675c22..0000000 --- a/doc/subst.n +++ /dev/null @@ -1,48 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: subst.n,v 1.2 1998/09/14 18:39:55 stanton Exp $ -'\" -.so man.macros -.TH subst n 7.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -subst \- Perform backslash, command, and variable substitutions -.SH SYNOPSIS -\fBsubst \fR?\fB\-nobackslashes\fR? ?\fB\-nocommands\fR? ?\fB\-novariables\fR? \fIstring\fR -.BE - -.SH DESCRIPTION -.PP -This command performs variable substitutions, command substitutions, -and backslash substitutions on its \fIstring\fR argument and -returns the fully-substituted result. -The substitutions are performed in exactly the same way as for -Tcl commands. -As a result, the \fIstring\fR argument is actually substituted twice, -once by the Tcl parser in the usual fashion for Tcl commands, and -again by the \fIsubst\fR command. -.PP -If any of the \fB\-nobackslashes\fR, \fB\-nocommands\fR, or -\fB\-novariables\fR are specified, then the corresponding substitutions -are not performed. -For example, if \fB\-nocommands\fR is specified, no command substitution -is performed: open and close brackets are treated as ordinary characters -with no special interpretation. -.PP -Note: when it performs its substitutions, \fIsubst\fR does not -give any special treatment to double quotes or curly braces. For -example, the script -.CS -\fBset a 44 -subst {xyz {$a}}\fR -.CE -returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''. - -.SH KEYWORDS -backslash substitution, command substitution, variable substitution diff --git a/doc/switch.n b/doc/switch.n deleted file mode 100644 index 503a5ba..0000000 --- a/doc/switch.n +++ /dev/null @@ -1,107 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: switch.n,v 1.2 1998/09/14 18:39:55 stanton Exp $ -'\" -.so man.macros -.TH switch n 7.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -switch \- Evaluate one of several scripts, depending on a given value -.SH SYNOPSIS -\fBswitch \fR?\fIoptions\fR?\fI string pattern body \fR?\fIpattern body \fR...? -.sp -\fBswitch \fR?\fIoptions\fR?\fI string \fR{\fIpattern body \fR?\fIpattern body \fR...?} -.BE - -.SH DESCRIPTION -.PP -The \fBswitch\fR command matches its \fIstring\fR argument against each of -the \fIpattern\fR arguments in order. -As soon as it finds a \fIpattern\fR that matches \fIstring\fR it -evaluates the following \fIbody\fR argument by passing it recursively -to the Tcl interpreter and returns the result of that evaluation. -If the last \fIpattern\fR argument is \fBdefault\fR then it matches -anything. -If no \fIpattern\fR argument -matches \fIstring\fR and no default is given, then the \fBswitch\fR -command returns an empty string. -.PP -If the initial arguments to \fBswitch\fR start with \fB\-\fR then -they are treated as options. The following options are -currently supported: -.TP 10 -\fB\-exact\fR -Use exact matching when comparing \fIstring\fR to a pattern. This -is the default. -.TP 10 -\fB\-glob\fR -When matching \fIstring\fR to the patterns, use glob-style matching -(i.e. the same as implemented by the \fBstring match\fR command). -.TP 10 -\fB\-regexp\fR -When matching \fIstring\fR to the patterns, use regular -expression matching -(i.e. the same as implemented by the \fBregexp\fR command). -.TP 10 -\fB\-\|\-\fR -Marks the end of options. The argument following this one will -be treated as \fIstring\fR even if it starts with a \fB\-\fR. -.PP -Two syntaxes are provided for the \fIpattern\fR and \fIbody\fR arguments. -The first uses a separate argument for each of the patterns and commands; -this form is convenient if substitutions are desired on some of the -patterns or commands. -The second form places all of the patterns and commands together into -a single argument; the argument must have proper list structure, with -the elements of the list being the patterns and commands. -The second form makes it easy to construct multi-line switch commands, -since the braces around the whole list make it unnecessary to include a -backslash at the end of each line. -Since the \fIpattern\fR arguments are in braces in the second form, -no command or variable substitutions are performed on them; this makes -the behavior of the second form different than the first form in some -cases. -.PP -If a \fIbody\fR is specified as ``\fB\-\fR'' it means that the \fIbody\fR -for the next pattern should also be used as the body for this -pattern (if the next pattern also has a body of ``\fB\-\fR'' -then the body after that is used, and so on). -This feature makes it possible to share a single \fIbody\fR among -several patterns. -.PP -Below are some examples of \fBswitch\fR commands: -.CS -\fBswitch\0abc\0a\0\-\0b\0{format 1}\0abc\0{format 2}\0default\0{format 3}\fR -.CE -will return \fB2\fR, -.CS -\fBswitch\0\-regexp\0aaab { - ^a.*b$\0\- - b\0{format 1} - a*\0{format 2} - default\0{format 3} -}\fR -.CE -will return \fB1\fR, and -.CS -\fBswitch\0xyz { - a - \- - b - {format 1} - a* - {format 2} - default - {format 3} -}\fR -.CE -will return \fB3\fR. - -.SH KEYWORDS -switch, match, regular expression diff --git a/doc/tclsh.1 b/doc/tclsh.1 deleted file mode 100644 index 8918a23..0000000 --- a/doc/tclsh.1 +++ /dev/null @@ -1,118 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: tclsh.1,v 1.2 1998/09/14 18:39:55 stanton Exp $ -'\" -.so man.macros -.TH tclsh 1 "" Tcl "Tcl Applications" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tclsh \- Simple shell containing Tcl interpreter -.SH SYNOPSIS -\fBtclsh\fR ?\fIfileName arg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -\fBTclsh\fR is a shell-like application that reads Tcl commands -from its standard input or from a file and evaluates them. -If invoked with no arguments then it runs interactively, reading -Tcl commands from standard input and printing command results and -error messages to standard output. -It runs until the \fBexit\fR command is invoked or until it -reaches end-of-file on its standard input. -If there exists a file \fB.tclshrc\fR in the home directory of -the user, \fBtclsh\fR evaluates the file as a Tcl script -just before reading the first command from standard input. - -.SH "SCRIPT FILES" -.PP -If \fBtclsh\fR is invoked with arguments then the first argument -is the name of a script file and any additional arguments -are made available to the script as variables (see below). -Instead of reading commands from standard input \fBtclsh\fR will -read Tcl commands from the named file; \fBtclsh\fR will exit -when it reaches the end of the file. -There is no automatic evaluation of \fB.tclshrc\fR in this -case, but the script file can always \fBsource\fR it if desired. -.PP -If you create a Tcl script in a file whose first line is -.CS -\fB#!/usr/local/bin/tclsh\fR -.CE -then you can invoke the script file directly from your shell if -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. -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. -.PP -An even better approach is to start your script files with the -following three lines: -.CS -\fB#!/bin/sh -# the next line restarts using tclsh \e -exec tclsh "$0" "$@"\fR -.CE -This approach has three advantages over the approach in the previous -paragraph. First, the location of the \fBtclsh\fR binary doesn't have -to be hard-wired into the script: it can be anywhere in your shell -search path. Second, it gets around the 30-character file name limit -in the previous approach. -Third, this approach will work even if \fBtclsh\fR is -itself a shell script (this is done on some systems in order to -handle multiple architectures or operating systems: the \fBtclsh\fR -script selects one of several binaries to run). The three lines -cause both \fBsh\fR and \fBtclsh\fR to process the script, but the -\fBexec\fR is only executed by \fBsh\fR. -\fBsh\fR processes the script first; it treats the second -line as a comment and executes the third line. -The \fBexec\fR statement cause the shell to stop processing and -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. - -.SH "VARIABLES" -.PP -\fBTclsh\fR sets the following Tcl variables: -.TP 15 -\fBargc\fR -Contains a count of the number of \fIarg\fR arguments (0 if none), -not including the name of the script file. -.TP 15 -\fBargv\fR -Contains a Tcl list whose elements are the \fIarg\fR arguments, -in order, or an empty string if there are no \fIarg\fR arguments. -.TP 15 -\fBargv0\fR -Contains \fIfileName\fR if it was specified. -Otherwise, contains the name by which \fBtclsh\fR was invoked. -.TP 15 -\fBtcl_interactive\fR -Contains 1 if \fBtclsh\fR is running interactively (no -\fIfileName\fR was specified and standard input is a terminal-like -device), 0 otherwise. - -.SH PROMPTS -.PP -When \fBtclsh\fR is invoked interactively it normally prompts for each -command with ``\fB% \fR''. You can change the prompt by setting the -variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR. If variable -\fBtcl_prompt1\fR exists then it must consist of a Tcl script -to output a prompt; instead of outputting a prompt \fBtclsh\fR -will evaluate the script in \fBtcl_prompt1\fR. -The variable \fBtcl_prompt2\fR is used in a similar way when -a newline is typed but the current command isn't yet complete; -if \fBtcl_prompt2\fR isn't set then no prompt is output for -incomplete commands. - -.SH KEYWORDS -argument, interpreter, prompt, script file, shell diff --git a/doc/tclvars.n b/doc/tclvars.n deleted file mode 100644 index 2e68519..0000000 --- a/doc/tclvars.n +++ /dev/null @@ -1,367 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: tclvars.n,v 1.3 1999/04/16 00:46:36 stanton Exp $ -'\" -.so man.macros -.TH tclvars n 8.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tclvars \- Variables used by Tcl -.BE - -.SH DESCRIPTION -.PP -The following global variables are created and managed automatically -by the Tcl library. Except where noted below, these variables should -normally be treated as read-only by application-specific code and by users. -.TP -\fBenv\fR -This variable is maintained by Tcl as an array -whose elements are the environment variables for the process. -Reading an element will return the value of the corresponding -environment variable. -Setting an element of the array will modify the corresponding -environment variable or create a new one if it doesn't already -exist. -Unsetting an element of \fBenv\fR will remove the corresponding -environment variable. -Changes to the \fBenv\fR array will affect the environment -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 -.VS 8.0 -Under Windows, the environment variables PATH and COMSPEC 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. -.VE -.RE -.RS -On the Macintosh, the environment variable is constructed by Tcl as no -global environment variable exists. The environment variables that -are created for Tcl include: -.TP -\fBLOGIN\fR -This holds the Chooser name of the Macintosh. -.TP -\fBUSER\fR -This also holds the Chooser name of the Macintosh. -.TP -\fBSYS_FOLDER\fR -The path to the system directory. -.TP -\fBAPPLE_M_FOLDER\fR -The path to the Apple Menu directory. -.TP -\fBCP_FOLDER\fR -The path to the control panels directory. -.TP -\fBDESK_FOLDER\fR -The path to the desk top directory. -.TP -\fBEXT_FOLDER\fR -The path to the system extensions directory. -.TP -\fBPREF_FOLDER\fR -The path to the preferences directory. -.TP -\fBPRINT_MON_FOLDER\fR -The path to the print monitor directory. -.TP -\fBSHARED_TRASH_FOLDER\fR -The path to the network trash directory. -.TP -\fBTRASH_FOLDER\fR -The path to the trash directory. -.TP -\fBSTART_UP_FOLDER\fR -The path to the start up directory. -.TP -\fBPWD\fR -The path to the application's default directory. -.PP -You can also create your own environment variables for the Macintosh. -A file named \fITcl Environment Variables\fR may be placed in the -preferences folder in the Mac system folder. Each line of this file -should be of the form \fIVAR_NAME=var_data\fR. -.PP -The last alternative is to place environment variables in a 'STR#' -resource named \fITcl Environment Variables\fR of the application. This -is considered a little more ``Mac like'' than a Unix style Environment -Variable file. Each entry in the 'STR#' resource has the same format -as above. The source code file \fItclMacEnv.c\fR contains the -implementation of the env mechanisms. This file contains many -#define's that allow customization of the env mechanisms to fit your -applications needs. -.RE -.TP -\fBerrorCode\fR -After an error has occurred, this variable will be set to hold -additional information about the error in a form that is easy -to process with programs. -\fBerrorCode\fR consists of a Tcl list with one or more elements. -The first element of the list identifies a general class of -errors, and determines the format of the rest of the list. -The following formats for \fBerrorCode\fR are used by the -Tcl core; individual applications may define additional formats. -.RS -.TP -\fBARITH\fI code msg\fR -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 -human-readable description of the error. \fICode\fR will be either -DIVZERO (for an attempt to divide by zero), -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). -.TP -\fBCHILDKILLED\fI pid sigName msg\fR -This format is used when a child process has been killed because of -a signal. The second element of \fBerrorCode\fR will be the -process's identifier (in decimal). -The third element will be the symbolic name of the signal that caused -the process to terminate; it will be one of the names from the -include file signal.h, such as \fBSIGPIPE\fR. -The fourth element will be a short human-readable message -describing the signal, such as ``write on pipe with no readers'' -for \fBSIGPIPE\fR. -.TP -\fBCHILDSTATUS\fI pid code\fR -This format is used when a child process has exited with a non-zero -exit status. The second element of \fBerrorCode\fR will be the -process's identifier (in decimal) and the third element will be the exit -code returned by the process (also in decimal). -.TP -\fBCHILDSUSP\fI pid sigName msg\fR -This format is used when a child process has been suspended because -of a signal. -The second element of \fBerrorCode\fR will be the process's identifier, -in decimal. -The third element will be the symbolic name of the signal that caused -the process to suspend; this will be one of the names from the -include file signal.h, such as \fBSIGTTIN\fR. -The fourth element will be a short human-readable message -describing the signal, such as ``background tty read'' -for \fBSIGTTIN\fR. -.TP -\fBNONE\fR -This format is used for errors where no additional information is -available for an error besides the message returned with the -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 -If the first element of \fBerrorCode\fR is \fBPOSIX\fR, then -the error occurred during a POSIX kernel call. -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. -The third element of the list will be a human-readable -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 \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 -the next error. -.RE -.TP -\fBerrorInfo\fR -After an error has occurred, this string will contain one or more lines -identifying the Tcl commands and procedures that were being executed -when the most recent error occurred. -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 -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 -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 -\fB$\fIapp\fB_library\fR (where \fIapp\fR is the application's name) -to hold the network file name for that application's library directory. -The initial value of \fBtcl_library\fR is set when an interpreter -is created by searching several different directories until one is -found that contains an appropriate Tcl startup script. -If the \fBTCL_LIBRARY\fR environment variable exists, then -the directory it names is checked first. -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. -.TP -\fBtcl_patchLevel\fR -When an interpreter is created Tcl initializes this variable to -hold a string giving the current patch level for Tcl, such as -\fB7.3p2\fR for Tcl 7.3 with the first two official patches, or -\fB7.4b4\fR for the fourth beta release of Tcl 7.4. -The value of this variable is returned by the \fBinfo patchlevel\fR -command. -.VS 8.0 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 -the operating system, its current release number, and the machine's -instruction set. The elements listed below will always -be defined, but they may have empty strings as values if Tcl couldn't -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 -\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 \fBWindows 95\fR, \fBWindows NT\fR, \fBMacOS\fR, or \fBSunOS\fR. -On UNIX machines, this is the value returned by \fBuname -s\fR. -On Windows 95 and Windows 98, the value returned will be \fBWindows -95\fR to provide better backwards compatibility to Windows 95; to -distinguish between the two, check the \fBosVersion\fR. -.TP -\fBosVersion\fR -The version number for the operating system running on this machine. -On UNIX machines, this is the value returned by \fBuname -r\fR. On -Windows 95, the version will be 4.0; on Windows 98, the version will -be 4.10. -.TP -\fBplatform\fR -Either \fBwindows\fR, \fBmacintosh\fR, or \fBunix\fR. This identifies the -general operating environment of the machine. -.TP -\fBuser\fR -Either \fBwindows\fR, \fBmacintosh\fR, or \fBunix\fR. This identifies the -current user based on the login information available on the platform. -This comes from the USER or LOGNAME environment variable on Unix, -and the value from GetUserName on Windows and Macintosh. -.RE -.TP -\fBtcl_precision\fR -.VS -This variable controls the number of digits to generate -when converting floating-point values to strings. It defaults -to 12. -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 information. However, using 17 digits prevents -any rounding, which produces longer, less intuitive results. For example, -\fBexpr 1.4\fR returns 1.3999999999999999 with \fBtcl_precision\fR -set to 17, vs. 1.4 if \fBtcl_precision\fR is 12. -.RS -All interpreters in a process share a single \fBtcl_precision\fR value: -changing it in one interpreter will affect all other interpreters as -well. However, safe interpreters are not allowed to modify the -variable. -.RE -.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 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 -hold the version number for this version of Tcl in the form \fIx.y\fR. -Changes to \fIx\fR represent major changes with probable -incompatibilities and changes to \fIy\fR represent small enhancements and -bug fixes that retain backward compatibility. -The value of this variable is returned by the \fBinfo tclversion\fR -command. - -.SH KEYWORDS -arithmetic, bytecode, compiler, error, environment, POSIX, precision, subprocess, variables diff --git a/doc/tell.n b/doc/tell.n deleted file mode 100644 index fbbef62..0000000 --- a/doc/tell.n +++ /dev/null @@ -1,28 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: tell.n,v 1.2 1998/09/14 18:39:55 stanton Exp $ -'\" -.so man.macros -.TH tell n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tell \- Return current access position for an open channel -.SH SYNOPSIS -\fBtell \fIchannelId\fR -.BE - -.SH DESCRIPTION -.PP -Returns a decimal string giving the current access position in -\fIchannelId\fR. -The value returned is -1 for channels that do not support -seeking. - -.SH KEYWORDS -access position, channel, seeking diff --git a/doc/time.n b/doc/time.n deleted file mode 100644 index f08505a..0000000 --- a/doc/time.n +++ /dev/null @@ -1,33 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: time.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH time n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -time \- Time the execution of a script -.SH SYNOPSIS -\fBtime \fIscript\fR ?\fIcount\fR? -.BE - -.SH DESCRIPTION -.PP -This command will call the Tcl interpreter \fIcount\fR -times to evaluate \fIscript\fR (or once if \fIcount\fR isn't -specified). It will then return a string of the form -.CS -\fB503 microseconds per iteration\fR -.CE -which indicates the average amount of time required per iteration, -in microseconds. -Time is measured in elapsed time, not CPU time. - -.SH KEYWORDS -script, time diff --git a/doc/trace.n b/doc/trace.n deleted file mode 100644 index 317205a..0000000 --- a/doc/trace.n +++ /dev/null @@ -1,158 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: trace.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH trace n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -trace \- Monitor variable accesses -.SH SYNOPSIS -\fBtrace \fIoption\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command causes Tcl commands to be executed whenever certain operations are -invoked. At present, only variable tracing is implemented. The -legal \fIoption\fR's (which may be abbreviated) are: -.TP -\fBtrace variable \fIname ops command\fR -Arrange for \fIcommand\fR to be executed whenever variable \fIname\fR -is accessed in one of the ways given by \fIops\fR. \fIName\fR may -refer to a normal variable, an element of an array, or to an array -as a whole (i.e. \fIname\fR may be just the name of an array, with no -parenthesized index). If \fIname\fR refers to a whole array, then -\fIcommand\fR is invoked whenever any element of the array is -manipulated. -.RS -.PP -\fIOps\fR indicates which operations are of interest, and consists of -one or more of the following letters: -.TP -\fBr\fR -Invoke \fIcommand\fR whenever the variable is read. -.TP -\fBw\fR -Invoke \fIcommand\fR whenever the variable is written. -.TP -\fBu\fR -Invoke \fIcommand\fR whenever the variable is unset. Variables -can be unset explicitly with the \fBunset\fR command, or -implicitly when procedures return (all of their local variables -are unset). Variables are also unset when interpreters are -deleted, but traces will not be invoked because there is no -interpreter in which to execute them. -.PP -When the trace triggers, three arguments are appended to -\fIcommand\fR so that the actual command is as follows: -.CS -\fIcommand name1 name2 op\fR -.CE -\fIName1\fR and \fIname2\fR give the name(s) for the variable -being accessed: if the variable is a scalar then \fIname1\fR -gives the variable's name and \fIname2\fR is an empty string; -if the variable is an array element then \fIname1\fR gives the -name of the array and name2 gives the index into the array; -if an entire array is being deleted and the trace was registered -on the overall array, rather than a single element, then \fIname1\fR -gives the array name and \fIname2\fR is an empty string. -\fIName1\fR and \fIname2\fR are not necessarily the same as the -name used in the \fBtrace variable\fR command: the \fBupvar\fR -command allows a procedure to reference a variable under a -different name. -\fIOp\fR indicates what operation is being performed on the -variable, and is one of \fBr\fR, \fBw\fR, or \fBu\fR as -defined above. -.PP -\fICommand\fR executes in the same context as the code that invoked -the traced operation: if the variable was accessed as part of a -Tcl procedure, then \fIcommand\fR will have access to the same -local variables as code in the procedure. This context may be -different than the context in which the trace was created. -If \fIcommand\fR invokes a procedure (which it normally does) then -the procedure will have to use \fBupvar\fR or \fBuplevel\fR if it -wishes to access the traced variable. -Note also that \fIname1\fR may not necessarily be the same as the name -used to set the trace on the variable; differences can occur if -the access is made through a variable defined with the \fBupvar\fR -command. -.PP -For read and write traces, \fIcommand\fR can modify -the variable to affect the result of the traced operation. -If \fIcommand\fR modifies the value of a variable during a -read or write trace, then the new value will be returned as the -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 -the same error message returned by the trace command -(this mechanism can be used to implement read-only variables, for -example). -For write traces, \fIcommand\fR is invoked after the variable's -value has been changed; it can write a new value into the variable -to override the original value specified in the write operation. -To implement read-only variables, \fIcommand\fR will have to restore -the old value of the variable. -.PP -While \fIcommand\fR is executing during a read or write trace, traces -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. -However, if \fIcommand\fR unsets the variable then unset traces -will be invoked. -.PP -When an unset trace is invoked, the variable has already been -deleted: it will appear to be undefined with no traces. -If an unset occurs because of a procedure return, then the -trace will be invoked in the variable context of the procedure -being returned to: the stack frame of the returning procedure -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. -Any errors in unset traces are ignored. -.PP -If there are multiple traces on a variable they are invoked -in order of creation, most-recent first. -If one trace returns an error, then no further traces are -invoked for the variable. -If an array element has a trace set, and there is also a trace -set on the array as a whole, the trace on the overall array -is invoked before the one on the element. -.PP -Once created, the trace remains in effect either until the -trace is removed with the \fBtrace vdelete\fR command described -below, until the variable is unset, or until the interpreter -is deleted. -Unsetting an element of array will remove any traces on that -element, but will not remove traces on the overall array. -.PP -This command returns an empty string. -.RE -.TP -\fBtrace vdelete \fIname ops command\fR -If there is a trace set on variable \fIname\fR with the -operations and command given by \fIops\fR and \fIcommand\fR, -then the trace is removed, so that \fIcommand\fR will never -again be invoked. -Returns an empty string. -.TP -\fBtrace vinfo \fIname\fR -Returns a list containing one element for each trace -currently set on variable \fIname\fR. -Each element of the list is itself a list containing two -elements, which are the \fIops\fR and \fIcommand\fR associated -with the trace. -If \fIname\fR doesn't exist or doesn't have any traces set, then -the result of the command will be an empty string. - -.SH KEYWORDS -read, variable, write, trace, unset diff --git a/doc/unknown.n b/doc/unknown.n deleted file mode 100644 index 19f5ac1..0000000 --- a/doc/unknown.n +++ /dev/null @@ -1,75 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: unknown.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH unknown n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -unknown \- Handle attempts to use non-existent commands -.SH SYNOPSIS -\fBunknown \fIcmdName \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command is invoked by the Tcl interpreter whenever a script -tries to invoke a command that doesn't exist. The implementation -of \fBunknown\fR isn't part of the Tcl core; instead, it is a -library procedure defined by default when Tcl starts up. You -can override the default \fBunknown\fR to change its functionality. -.PP -If the Tcl interpreter encounters a command name for which there -is not a defined command, then Tcl checks for the existence of -a command named \fBunknown\fR. -If there is no such command, then the interpreter returns an -error. -If the \fBunknown\fR command exists, then it is invoked with -arguments consisting of the fully-substituted name and arguments -for the original non-existent command. -The \fBunknown\fR command typically does things like searching -through library directories for a command procedure with the name -\fIcmdName\fR, or expanding abbreviated command names to full-length, -or automatically executing unknown commands as sub-processes. -In some cases (such as expanding abbreviations) \fBunknown\fR will -change the original command slightly and then (re-)execute it. -The result of the \fBunknown\fR command is used as the result for -the original non-existent command. -.PP -The default implementation of \fBunknown\fR behaves as follows. -It first calls the \fBauto_load\fR library procedure to load the command. -If this succeeds, then it executes the original command with its -original arguments. -If the auto-load fails then \fBunknown\fR calls \fBauto_execok\fR -to see if there is an executable file by the name \fIcmd\fR. -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 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 -in the same way that \fBcsh\fR would for these constructs. -Finally, \fBunknown\fR checks to see if \fIcmd\fR is -a unique abbreviation for an existing Tcl command. -If so, it expands the command name and executes the command with -the original arguments. -If none of the above efforts has been able to execute -the command, \fBunknown\fR generates an error return. -If the global variable \fBauto_noload\fR is defined, then the auto-load -step is skipped. -If the global variable \fBauto_noexec\fR is defined then the -auto-exec step is skipped. -Under normal circumstances the return value from \fBunknown\fR -is the return value from the command that was eventually -executed. - -.SH KEYWORDS -error, non-existent command diff --git a/doc/unset.n b/doc/unset.n deleted file mode 100644 index ef93132..0000000 --- a/doc/unset.n +++ /dev/null @@ -1,34 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: unset.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH unset n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -unset \- Delete variables -.SH SYNOPSIS -\fBunset \fIname \fR?\fIname name ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command removes one or more variables. -Each \fIname\fR is a variable name, specified in any of the -ways acceptable to the \fBset\fR command. -If a \fIname\fR refers to an element of an array then that -element is removed without affecting the rest of the array. -If a \fIname\fR consists of an array name with no parenthesized -index, then the entire array is deleted. -The \fBunset\fR command returns an empty string as result. -An error occurs if any of the variables doesn't exist, and any variables -after the non-existent one are not deleted. - -.SH KEYWORDS -remove, variable diff --git a/doc/update.n b/doc/update.n deleted file mode 100644 index 863e8c8..0000000 --- a/doc/update.n +++ /dev/null @@ -1,48 +0,0 @@ -'\" -'\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-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. -'\" -'\" RCS: @(#) $Id: update.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH update n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -update \- Process pending events and idle callbacks -.SH SYNOPSIS -\fBupdate\fR ?\fBidletasks\fR? -.BE - -.SH DESCRIPTION -.PP -This command is used to bring the application ``up to date'' -by entering the event loop repeated until all pending events -(including idle callbacks) have been processed. -.PP -If the \fBidletasks\fR keyword is specified as an argument to the -command, then no new events or errors are processed; only idle -callbacks are invoked. -This causes operations that are normally deferred, such as display -updates and window layout calculations, to be performed immediately. -.PP -The \fBupdate idletasks\fR command is useful in scripts where -changes have been made to the application's state and you want those -changes to appear on the display immediately, rather than waiting -for the script to complete. Most display updates are performed as -idle callbacks, so \fBupdate idletasks\fR will cause them to run. -However, there are some kinds of updates that only happen in -response to events, such as those triggered by window size changes; -these updates will not occur in \fBupdate idletasks\fR. -.PP -The \fBupdate\fR command with no options is useful in scripts where -you are performing a long-running computation but you still want -the application to respond to events such as user interactions; if -you occasionally call \fBupdate\fR then user input will be processed -during the next call to \fBupdate\fR. - -.SH KEYWORDS -event, flush, handler, idle, update diff --git a/doc/uplevel.n b/doc/uplevel.n deleted file mode 100644 index 83290d3..0000000 --- a/doc/uplevel.n +++ /dev/null @@ -1,80 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: uplevel.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH uplevel n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -uplevel \- Execute a script in a different stack frame -.SH SYNOPSIS -\fBuplevel \fR?\fIlevel\fR?\fI arg \fR?\fIarg ...\fR? -.BE - -.SH DESCRIPTION -.PP -All of the \fIarg\fR arguments are concatenated as if they had -been passed to \fBconcat\fR; the result is then evaluated in the -variable context indicated by \fIlevel\fR. \fBUplevel\fR returns -the result of that evaluation. -.PP -If \fIlevel\fR is an integer then -it gives a distance (up the procedure calling stack) to move before -executing the command. If \fIlevel\fR consists of \fB#\fR followed by -a number then the number gives an absolute level number. If \fIlevel\fR -is omitted then it defaults to \fB1\fR. \fILevel\fR cannot be -defaulted if the first \fIcommand\fR argument starts with a digit or \fB#\fR. -.PP -For example, suppose that procedure \fBa\fR was invoked -from top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR. -Suppose that \fBc\fR invokes the \fBuplevel\fR command. If \fIlevel\fR -is \fB1\fR or \fB#2\fR or omitted, then the command will be executed -in the variable context of \fBb\fR. If \fIlevel\fR is \fB2\fR or \fB#1\fR -then the command will be executed in the variable context of \fBa\fR. -If \fIlevel\fR is \fB3\fR or \fB#0\fR then the command will be executed -at top-level (only global variables will be visible). -.PP -The \fBuplevel\fR command causes the invoking procedure to disappear -from the procedure calling stack while the command is being executed. -In the above example, suppose \fBc\fR invokes the command -.CS -\fBuplevel 1 {set x 43; d}\fR -.CE -where \fBd\fR is another Tcl procedure. The \fBset\fR command will -modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute -at level 3, as if called from \fBb\fR. If it in turn executes -the command -.CS -\fBuplevel {set x 42}\fR -.CE -then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's -context: the procedure \fBc\fR does not appear to be on the call stack -when \fBd\fR is executing. The command ``\fBinfo level\fR'' may -be used to obtain the level of the current procedure. -.PP -\fBUplevel\fR makes it possible to implement new control -constructs as Tcl procedures (for example, \fBuplevel\fR could -be used to implement the \fBwhile\fR construct as a Tcl procedure). -.PP -\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). - -.SH "SEE ALSO" -namespace(n) - -.SH KEYWORDS -context, level, namespace, stack frame, variables diff --git a/doc/upvar.n b/doc/upvar.n deleted file mode 100644 index f62d646..0000000 --- a/doc/upvar.n +++ /dev/null @@ -1,92 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: upvar.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH upvar n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -upvar \- Create link to variable in a different stack frame -.SH SYNOPSIS -\fBupvar \fR?\fIlevel\fR? \fIotherVar myVar \fR?\fIotherVar myVar \fR...? -.BE - -.SH DESCRIPTION -.PP -This command arranges for one or more local variables in the current -procedure to refer to variables in an enclosing procedure call or -to global variables. -\fILevel\fR may have any of the forms permitted for the \fBuplevel\fR -command, and may be omitted if the first letter of the first \fIotherVar\fR -isn't \fB#\fR or a digit (it defaults to \fB1\fR). -For each \fIotherVar\fR argument, \fBupvar\fR makes the variable -by that name in the procedure frame given by \fIlevel\fR (or at -global level, if \fIlevel\fR is \fB#0\fR) accessible -in the current procedure by the name given in the corresponding -\fImyVar\fR argument. -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. -\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. -\fBUpvar\fR returns an empty string. -.PP -The \fBupvar\fR command simplifies the implementation of call-by-name -procedure calling and also makes it easier to build new control constructs -as Tcl procedures. -For example, consider the following procedure: -.CS -\fBproc add2 name { - upvar $name x - set x [expr $x+2] -}\fR -.CE -\fBAdd2\fR is invoked with an argument giving the name of a variable, -and it adds two to the value of that variable. -Although \fBadd2\fR could have been implemented using \fBuplevel\fR -instead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fBadd2\fR -to access the variable in the caller's procedure frame. -.PP -\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). -.PP -.VS -If an upvar variable is unset (e.g. \fBx\fR in \fBadd2\fR above), the -\fBunset\fR operation affects the variable it is linked to, not the -upvar variable. There is no way to unset an upvar variable except -by exiting the procedure in which it is defined. However, it is -possible to retarget an upvar variable by executing another \fBupvar\fR -command. - -.SH BUGS -.PP -If \fIotherVar\fR refers to an element of an array, then variable -traces set for the entire array will not be invoked when \fImyVar\fR -is accessed (but traces on the particular element will still be -invoked). In particular, if the array is \fBenv\fR, then changes -made to \fImyVar\fR will not be passed to subprocesses correctly. -.VE - -.SH "SEE ALSO" -namespace(n) - -.SH KEYWORDS -context, frame, global, level, namespace, procedure, variable diff --git a/doc/variable.n b/doc/variable.n deleted file mode 100644 index 3b742a9..0000000 --- a/doc/variable.n +++ /dev/null @@ -1,63 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: variable.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.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. -In this case, if \fIvalue\fR is specified, -it is assigned to the newly created variable. -If no \fIvalue\fR is specified, the new variable is left undefined. -If the variable already exists, -it is set to \fIvalue\fR if \fIvalue\fR is specified -or left unchanged if no \fIvalue\fR is given. -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. - -.SH "SEE ALSO" -global(n), namespace(n) - -.SH KEYWORDS -global, namespace, procedure, variable diff --git a/doc/vwait.n b/doc/vwait.n deleted file mode 100644 index a355b54..0000000 --- a/doc/vwait.n +++ /dev/null @@ -1,38 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: vwait.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH vwait n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -vwait \- Process events until a variable is written -.SH SYNOPSIS -\fBvwait\fR \fIvarName\fR -.BE - -.SH DESCRIPTION -.PP -This command enters the Tcl event loop to process events, blocking -the application if no events are ready. It continues processing -events until some event handler sets the value of variable -\fIvarName\fR. Once \fIvarName\fR has been set, the \fBvwait\fR -command will return as soon as the event handler that modified -\fIvarName\fR completes. -.PP -In some cases the \fBvwait\fR command may not return immediately -after \fIvarName\fR is set. This can happen if the event handler -that sets \fIvarName\fR does not complete immediately. For example, -if an event handler sets \fIvarName\fR and then itself calls -\fBvwait\fR to wait for a different variable, then it may not return -for a long time. During this time the top-level \fBvwait\fR is -blocked waiting for the event handler to complete, so it cannot -return either. - -.SH KEYWORDS -event, variable, wait diff --git a/doc/while.n b/doc/while.n deleted file mode 100644 index dabe116..0000000 --- a/doc/while.n +++ /dev/null @@ -1,55 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: while.n,v 1.2 1998/09/14 18:39:56 stanton Exp $ -'\" -.so man.macros -.TH while n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -while \- Execute script repeatedly as long as a condition is met -.SH SYNOPSIS -\fBwhile \fItest body\fR -.BE - -.SH DESCRIPTION -.PP -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 -then \fIbody\fR is executed by passing it to the Tcl interpreter. -Once \fIbody\fR has been executed then \fItest\fR is evaluated -again, and the process repeats until eventually \fItest\fR -evaluates to a false boolean value. \fBContinue\fR -commands may be executed inside \fIbody\fR to terminate the current -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 |