diff options
93 files changed, 2689 insertions, 2481 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 7195d8f..d5f6b5f 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: AddErrInfo.3,v 1.16 2007/10/27 13:52:02 msofer Exp $ +'\" RCS: @(#) $Id: AddErrInfo.3,v 1.17 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" @@ -138,7 +138,7 @@ if ((objc % 2) == 0) { /* explicit result argument */ } return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1)); .CE -(It's not really implemented that way. Internal access +(It is not really implemented that way. Internal access privileges allow for a more efficient alternative that meshes better with the bytecode compiler.) .PP diff --git a/doc/AppInit.3 b/doc/AppInit.3 index 52f5d62..f933122 100644 --- a/doc/AppInit.3 +++ b/doc/AppInit.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: AppInit.3,v 1.7 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: AppInit.3,v 1.8 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures" @@ -26,7 +26,9 @@ Interpreter for the application. .SH DESCRIPTION .PP -\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by +\fBTcl_AppInit\fR is a +.QW 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. @@ -60,7 +62,7 @@ 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 +This means that you do not 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). diff --git a/doc/Async.3 b/doc/Async.3 index 9122536..772f4fe 100644 --- a/doc/Async.3 +++ b/doc/Async.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Async.3,v 1.10 2007/04/13 09:06:06 dkf Exp $ +'\" RCS: @(#) $Id: Async.3,v 1.11 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures" @@ -50,9 +50,9 @@ or 0 if \fIinterp\fR is NULL. 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 +evaluated then it is not safe to take any substantive action to process the event. -For example, it isn't safe to evaluate a Tcl script since the +For example, it is not 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. diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3 index 3817319..fcc18bf 100644 --- a/doc/BackgdErr.3 +++ b/doc/BackgdErr.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: BackgdErr.3,v 1.6 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: BackgdErr.3,v 1.7 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures" @@ -26,7 +26,8 @@ Interpreter in which the error occurred. .SH DESCRIPTION .PP This procedure is typically invoked when a Tcl error occurs during -``background processing'' such as executing an event handler. +.QW "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. diff --git a/doc/Backslash.3 b/doc/Backslash.3 index 57b73e9..f8b6c69 100644 --- a/doc/Backslash.3 +++ b/doc/Backslash.3 @@ -1,49 +1,49 @@ -'\" -'\" 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.7 2005/05/10 18:33:54 kennykb 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 out -.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 -The use of \fBTcl_Backslash\fR is deprecated in favor of -\fBTcl_UtfBackslash\fR. -.PP -This is a utility procedure provided for backwards compatibility with -non-internationalized Tcl extensions. It parses a backslash sequence and -returns the low byte of the Unicode character corresponding to the sequence. -\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. -.SH "SEE ALSO" -Tcl(n), Tcl_UtfBackslash(3) - -.SH KEYWORDS -backslash, parse +'\"
+'\" 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.8 2007/10/28 14:17:38 dkf 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 out
+.AP char *src in
+Pointer to a string starting with a backslash.
+.AP int *countPtr out
+If \fIcountPtr\fR is not NULL, \fI*countPtr\fR gets filled
+in with number of characters in the backslash sequence, including
+the backslash character.
+.BE
+
+.SH DESCRIPTION
+.PP
+The use of \fBTcl_Backslash\fR is deprecated in favor of
+\fBTcl_UtfBackslash\fR.
+.PP
+This is a utility procedure provided for backwards compatibility with
+non-internationalized Tcl extensions. It parses a backslash sequence and
+returns the low byte of the Unicode character corresponding to the sequence.
+\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.
+.SH "SEE ALSO"
+Tcl(n), Tcl_UtfBackslash(3)
+
+.SH KEYWORDS
+backslash, parse
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3 index da85372..28b3159 100644 --- a/doc/BoolObj.3 +++ b/doc/BoolObj.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: BoolObj.3,v 1.9 2005/05/18 19:09:07 dgp Exp $ +'\" RCS: @(#) $Id: BoolObj.3,v 1.10 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures" @@ -83,7 +83,9 @@ Note that the routines \fBTcl_GetBooleanFromObj\fR and The set of values for which \fBTcl_GetBooleanFromObj\fR will return \fBTCL_OK\fR is strictly larger than the set of values for which \fBTcl_GetBoolean\fR will do the same. -For example, the value "5" passed to \fBTcl_GetBooleanFromObj\fR +For example, the value +.QW 5 +passed to \fBTcl_GetBooleanFromObj\fR will lead to a \fBTCL_OK\fR return (and the boolean value 1), while the same value passed to \fBTcl_GetBoolean\fR will lead to a \fBTCL_ERROR\fR return. diff --git a/doc/CallDel.3 b/doc/CallDel.3 index b72658a..a4baa0c 100644 --- a/doc/CallDel.3 +++ b/doc/CallDel.3 @@ -1,63 +1,63 @@ -'\" -'\" 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.3 2004/10/07 14:44:31 dkf 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 +'\"
+'\" 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.4 2007/10/28 14:17:38 dkf 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 will not 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/CrtChannel.3 b/doc/CrtChannel.3 index e7fb800..42c2cbd 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtChannel.3,v 1.37 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: CrtChannel.3,v 1.38 2007/10/28 14:17:38 dkf Exp $ .so man.macros .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -155,7 +155,8 @@ Current interpreter. (can be NULL) .AP "const char" *optionName in Name of the invalid option. .AP "const char" *optionList in -Specific options list (space separated words, without "-") +Specific options list (space separated words, without +.QW \- ) to append to the standard generic options list. Can be NULL for generic options error message only. @@ -850,7 +851,9 @@ These values can be retrieved with \fBTcl_ChannelTruncateProc\fR, which returns a pointer to the function. .SH TCL_BADCHANNELOPTION .PP -This procedure generates a "bad option" error message in an +This procedure generates a +.QW "bad option" +error message in an (optional) interpreter. It is used by channel drivers when an invalid Set/Get option is requested. Its purpose is to concatenate the generic options list to the specific ones and factorize @@ -871,12 +874,17 @@ so you get for instance: -buffering, -buffersize, -eofchar, -translation, -peername, or -sockname .CE -when called with \fIoptionList\fR="peername sockname" +when called with \fIoptionList\fR equal to +.QW "peername sockname" .PP -``blah'' is the \fIoptionName\fR argument and ``<specific options>'' +.QW blah +is the \fIoptionName\fR argument and +.QW "<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. +each option, commas after, and an +.QW or +before the last option. .SH "OLD CHANNEL TYPES" The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains the following fields: diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3 index 8988c63..8a9409b 100644 --- a/doc/CrtChnlHdlr.3 +++ b/doc/CrtChnlHdlr.3 @@ -1,92 +1,92 @@ -'\" -'\" 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.3 2004/10/07 14:44:31 dkf 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. +'\"
+'\" 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.4 2007/10/28 14:17:38 dkf 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 do not
+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/CrtFileHdlr.3 b/doc/CrtFileHdlr.3 index 9f504e6..27bd621 100644 --- a/doc/CrtFileHdlr.3 +++ b/doc/CrtFileHdlr.3 @@ -1,92 +1,92 @@ -'\" -'\" 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.5 2005/05/10 18:33:54 kennykb 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 -.sp -\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR) -.sp -\fBTcl_DeleteFileHandler\fR(\fIfd\fR) -.SH ARGUMENTS -.AS Tcl_FileProc clientData -.AP int fd in -Unix file descriptor for an open file or device. -.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 -\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 -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 -Note that these interfaces are only supported by the Unix -implementation of the Tcl notifier. - -.SH KEYWORDS -callback, file, handler +'\"
+'\" 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.6 2007/10/28 14:17:38 dkf 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
+.sp
+\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
+.sp
+\fBTcl_DeleteFileHandler\fR(\fIfd\fR)
+.SH ARGUMENTS
+.AS Tcl_FileProc clientData
+.AP int fd in
+Unix file descriptor for an open file or device.
+.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
+\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
+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 will not 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
+Note that these interfaces are only supported by the Unix
+implementation of the Tcl notifier.
+
+.SH KEYWORDS
+callback, file, handler
diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3 index a0a2e5a..1ade285 100644 --- a/doc/CrtMathFnc.3 +++ b/doc/CrtMathFnc.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.14 2007/10/27 14:01:41 msofer Exp $ +'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.15 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures" @@ -74,7 +74,7 @@ in the \fBtcl::mathfunc\fR namespace. .PP In the \fBTcl_CreateMathFunc\fR interface, \fIName\fR is the name of the function as it will appear in expressions. -If \fIname\fR doesn't already exist in the \fB::tcl::mathfunc\fR +If \fIname\fR does not already exist in the \fB::tcl::mathfunc\fR namespace, then a new command is created in that namespace. If \fIname\fR does exist, then the existing function is replaced. \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function. diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index bb125e0..60201dc 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.15 2006/11/15 09:23:01 dkf Exp $ +'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.16 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures" @@ -171,7 +171,7 @@ argument passed to \fBTcl_CreateObjCommand\fR. \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 +If \fIcmdName\fR is not 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 @@ -280,7 +280,7 @@ 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 +command is not deleted or renamed; callers should copy the string if they need to keep it for a long time. .PP \fBTcl_GetCommandFullName\fR produces the fully qualified name diff --git a/doc/CrtSlave.3 b/doc/CrtSlave.3 index 3485841..d891ac3 100644 --- a/doc/CrtSlave.3 +++ b/doc/CrtSlave.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtSlave.3,v 1.18 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: CrtSlave.3,v 1.19 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures" @@ -61,7 +61,9 @@ Interpreter in which to execute the specified command. .AP "const 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 +If non-zero, a +.QW safe +slave that is suitable for running untrusted code is created, otherwise a trusted slave is created. .AP Tcl_Interp *slaveInterp in Interpreter to use for creating the source command for an alias (see @@ -126,16 +128,21 @@ 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 it is \fB1\fR, the command creates a +.QW safe +slave in which Tcl code has access only to set of Tcl commands defined as +.QW "Safe Tcl" ; +see the manual entry for the Tcl \fBinterp\fR command for details. If the creation of the new slave interpreter failed, \fBNULL\fR is returned. .PP -\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created -with the \fBTCL_SAFE_INTERPRETER\fR flag specified), +\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is +.QW safe +(was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified), \fB0\fR otherwise. .PP -\fBTcl_MakeSafe\fR marks \fIinterp\fR as ``safe'', so that future +\fBTcl_MakeSafe\fR marks \fIinterp\fR as +.QW safe , +so that future calls to \fBTcl_IsSafe\fR will return 1. It also removes all known potentially-unsafe core functionality (both commands and variables) from \fIinterp\fR. However, it cannot know what parts of an extension diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3 index 57a3a7f..8509e26 100644 --- a/doc/CrtTimerHdlr.3 +++ b/doc/CrtTimerHdlr.3 @@ -1,75 +1,75 @@ -'\" -'\" 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.3 2004/09/06 09:44:56 dkf 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 +'\"
+'\" 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.4 2007/10/28 14:17:38 dkf 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 is not
+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 index 63db967..80d2b47 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -1,187 +1,187 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 2002 by Kevin B. Kenny. All rights reserved. -'\" -'\" 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.10 2004/10/07 15:37:43 dkf Exp $ -'\" -.so man.macros -.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateTrace, Tcl_CreateObjTrace, 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 -Tcl_Trace -\fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR) -.sp -\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) -.SH ARGUMENTS -.AS Tcl_CmdObjTraceDeleteProc *deleteProc -.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 unless -0 is specified. 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. -A value of 0 means that commands at any level are traced. -.AP int flags in -Flags governing the trace execution. See below for details. -.AP Tcl_CmdObjTraceProc *objProc in -Procedure to call for each command that's executed. See below for -details of the calling sequence. -.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 \fIobjProc\fR or \fIproc\fR. -.AP Tcl_CmdObjTraceDeleteProc *deleteProc in -Procedure to call when the trace is deleted. See below for details of -the calling sequence. A NULL pointer is permissible and results in no -callback when the trace is deleted. -.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_CreateObjTrace\fR arranges for command tracing. After it is -called, \fIobjProc\fR will be invoked before the Tcl interpreter calls -any command procedure when evaluating commands in \fIinterp\fR. -The return value from \fBTcl_CreateObjTrace\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 -interpreter. -.PP -\fIobjProc\fR should have arguments and result that match the type, -\fBTcl_CmdObjTraceProc\fR: -.CS -typedef int \fBTcl_CmdObjTraceProc\fR( - \fBClientData\fR \fIclientData\fR, - \fBTcl_Interp\fR* \fIinterp\fR, - int \fIlevel\fR, - const char *\fIcommand\fR, - \fBTcl_Command\fR \fIcommandToken\fR, - int \fIobjc\fR, - \fBTcl_Obj\fR *const \fIobjv\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 \fIobjProc\fR is invoked. The -\fIlevel\fR parameter 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). The \fIcommand\fR parameter -points to a string containing the text of the command, before any -argument substitution. The \fIcommandToken\fR parameter is a Tcl -command token that identifies the command to be invoked. The token -may be passed to \fBTcl_GetCommandName\fR, -\fBTcl_GetCommandTokenInfo\fR, or \fBTcl_SetCommandTokenInfo\fR to -manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR -parameters designate the final parameter count and parameter vector -that will be passed to the command, and have had all substitutions -performed. -.PP -The \fIobjProc\fR callback is expected to return a standard Tcl status -return code. If this code is \fBTCL_OK\fR (the normal case), then -the Tcl interpreter will invoke the command. Any other return code -is treated as if the command returned that status, and the command is -\fInot\fR invoked. -.PP -The \fIobjProc\fR callback must not modify \fIobjv\fR in any way. It -is, however, permissible to change the command by calling -\fBTcl_SetCommandTokenInfo\fR prior to returning. Any such change -takes effect immediately, and the command is invoked with the new -information. -.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 \fIobjProc\fR will always be less than or equal to the -\fIlevel\fR parameter to \fBTcl_CreateTrace\fR). -.PP -Tracing has a significant effect on runtime performance because it -causes the bytecode compiler to refrain from generating in-line code -for Tcl commands such as \fBif\fR and \fBwhile\fR in order that they -may be traced. If traces for the built-in commands are not required, -the \fIflags\fR parameter may be set to the constant value -\fBTCL_ALLOW_INLINE_COMPILATION\fR. In this case, traces on built-in -commands may or may not result in trace callbacks, depending on the -state of the interpreter, but run-time performance will be improved -significantly. (This functionality is desirable, for example, when -using \fBTcl_CreateObjTrace\fR to implement an execution time -profiler.) -.PP -Calls to \fIobjProc\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 \fIobjProc\fR will occur, -one for each command. -.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. -.PP -When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the -\fIdeleteProc\fR that was passed as a parameter to -\fBTcl_CreateObjTrace\fR. The \fIdeleteProc\fR must match the type, -\fBTcl_CmdObjTraceDeleteProc\fR: -.CS -typedef void \fBTcl_CmdObjTraceDeleteProc\fR( - \fBClientData\fR \fIclientData\fR); -.CE -The \fIclientData\fR parameter will be the same as the -\fIclientData\fR parameter that was originally passed to -\fBTcl_CreateObjTrace\fR. -.PP -\fBTcl_CreateTrace\fR is an alternative interface for command tracing, -\fInot recommended for new applications\fR. It is provided for backward -compatibility with code that was developed for older versions of the -Tcl interpreter. It is similar to \fBTcl_CreateObjTrace\fR, except -that its \fIproc\fR parameter 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, - const char *\fIargv\fR[]); -.CE -The parameters to the \fIproc\fR callback are similar to those of the -\fIobjProc\fR callback above. The \fIcommandToken\fR is -replaced with \fIcmdProc\fR, a pointer to the (string-based) command -procedure that will be invoked; and \fIcmdClientData\fR, the client -data that will be passed to the procedure. The \fIobjc\fR parameter -is replaced with an \fIargv\fR parameter, that gives the arguments to -the command as character strings. -\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings. -.PP -If a trace created with \fBTcl_CreateTrace\fR is in effect, inline -compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always -disabled. There is no notification when a trace created with -\fBTcl_CreateTrace\fR is deleted. -There is no way to be notified when the trace created by -\fBTcl_CreateTrace\fR is deleted. There is no way for the \fIproc\fR -associated with a call to \fBTcl_CreateTrace\fR to abort execution of -\fIcommand\fR. -.SH KEYWORDS -command, create, delete, interpreter, trace +'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2002 by Kevin B. Kenny. All rights reserved.
+'\"
+'\" 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.11 2007/10/28 14:17:38 dkf Exp $
+'\"
+.so man.macros
+.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateTrace, Tcl_CreateObjTrace, 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
+Tcl_Trace
+\fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR)
+.sp
+\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
+.SH ARGUMENTS
+.AS Tcl_CmdObjTraceDeleteProc *deleteProc
+.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 unless
+0 is specified. 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.
+A value of 0 means that commands at any level are traced.
+.AP int flags in
+Flags governing the trace execution. See below for details.
+.AP Tcl_CmdObjTraceProc *objProc in
+Procedure to call for each command that is executed. See below for
+details of the calling sequence.
+.AP Tcl_CmdTraceProc *proc in
+Procedure to call for each command that is executed. See below for
+details on the calling sequence.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
+.AP Tcl_CmdObjTraceDeleteProc *deleteProc in
+Procedure to call when the trace is deleted. See below for details of
+the calling sequence. A NULL pointer is permissible and results in no
+callback when the trace is deleted.
+.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_CreateObjTrace\fR arranges for command tracing. After it is
+called, \fIobjProc\fR will be invoked before the Tcl interpreter calls
+any command procedure when evaluating commands in \fIinterp\fR.
+The return value from \fBTcl_CreateObjTrace\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
+interpreter.
+.PP
+\fIobjProc\fR should have arguments and result that match the type,
+\fBTcl_CmdObjTraceProc\fR:
+.CS
+typedef int \fBTcl_CmdObjTraceProc\fR(
+ \fBClientData\fR \fIclientData\fR,
+ \fBTcl_Interp\fR* \fIinterp\fR,
+ int \fIlevel\fR,
+ const char *\fIcommand\fR,
+ \fBTcl_Command\fR \fIcommandToken\fR,
+ int \fIobjc\fR,
+ \fBTcl_Obj\fR *const \fIobjv\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 \fIobjProc\fR is invoked. The
+\fIlevel\fR parameter 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). The \fIcommand\fR parameter
+points to a string containing the text of the command, before any
+argument substitution. The \fIcommandToken\fR parameter is a Tcl
+command token that identifies the command to be invoked. The token
+may be passed to \fBTcl_GetCommandName\fR,
+\fBTcl_GetCommandTokenInfo\fR, or \fBTcl_SetCommandTokenInfo\fR to
+manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR
+parameters designate the final parameter count and parameter vector
+that will be passed to the command, and have had all substitutions
+performed.
+.PP
+The \fIobjProc\fR callback is expected to return a standard Tcl status
+return code. If this code is \fBTCL_OK\fR (the normal case), then
+the Tcl interpreter will invoke the command. Any other return code
+is treated as if the command returned that status, and the command is
+\fInot\fR invoked.
+.PP
+The \fIobjProc\fR callback must not modify \fIobjv\fR in any way. It
+is, however, permissible to change the command by calling
+\fBTcl_SetCommandTokenInfo\fR prior to returning. Any such change
+takes effect immediately, and the command is invoked with the new
+information.
+.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 \fIobjProc\fR will always be less than or equal to the
+\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
+.PP
+Tracing has a significant effect on runtime performance because it
+causes the bytecode compiler to refrain from generating in-line code
+for Tcl commands such as \fBif\fR and \fBwhile\fR in order that they
+may be traced. If traces for the built-in commands are not required,
+the \fIflags\fR parameter may be set to the constant value
+\fBTCL_ALLOW_INLINE_COMPILATION\fR. In this case, traces on built-in
+commands may or may not result in trace callbacks, depending on the
+state of the interpreter, but run-time performance will be improved
+significantly. (This functionality is desirable, for example, when
+using \fBTcl_CreateObjTrace\fR to implement an execution time
+profiler.)
+.PP
+Calls to \fIobjProc\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 \fIobjProc\fR will occur,
+one for each command.
+.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.
+.PP
+When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
+\fIdeleteProc\fR that was passed as a parameter to
+\fBTcl_CreateObjTrace\fR. The \fIdeleteProc\fR must match the type,
+\fBTcl_CmdObjTraceDeleteProc\fR:
+.CS
+typedef void \fBTcl_CmdObjTraceDeleteProc\fR(
+ \fBClientData\fR \fIclientData\fR);
+.CE
+The \fIclientData\fR parameter will be the same as the
+\fIclientData\fR parameter that was originally passed to
+\fBTcl_CreateObjTrace\fR.
+.PP
+\fBTcl_CreateTrace\fR is an alternative interface for command tracing,
+\fInot recommended for new applications\fR. It is provided for backward
+compatibility with code that was developed for older versions of the
+Tcl interpreter. It is similar to \fBTcl_CreateObjTrace\fR, except
+that its \fIproc\fR parameter 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,
+ const char *\fIargv\fR[]);
+.CE
+The parameters to the \fIproc\fR callback are similar to those of the
+\fIobjProc\fR callback above. The \fIcommandToken\fR is
+replaced with \fIcmdProc\fR, a pointer to the (string-based) command
+procedure that will be invoked; and \fIcmdClientData\fR, the client
+data that will be passed to the procedure. The \fIobjc\fR parameter
+is replaced with an \fIargv\fR parameter, that gives the arguments to
+the command as character strings.
+\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
+.PP
+If a trace created with \fBTcl_CreateTrace\fR is in effect, inline
+compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always
+disabled. There is no notification when a trace created with
+\fBTcl_CreateTrace\fR is deleted.
+There is no way to be notified when the trace created by
+\fBTcl_CreateTrace\fR is deleted. There is no way for the \fIproc\fR
+associated with a call to \fBTcl_CreateTrace\fR to abort execution of
+\fIcommand\fR.
+.SH KEYWORDS
+command, create, delete, interpreter, trace
diff --git a/doc/DString.3 b/doc/DString.3 index ec15bcc..c20e3c9 100644 --- a/doc/DString.3 +++ b/doc/DString.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DString.3,v 1.15 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: DString.3,v 1.16 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures" @@ -87,14 +87,16 @@ 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 +except that it does not take a \fIlength\fR argument (it appends all of \fIelement\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 `` {''). +contains the single character +.QW { , +or the last two characters of the current string are +.QW " {" ). \fBTcl_DStringAppendElement\fR returns a pointer to the characters of the new string. .PP @@ -132,7 +134,7 @@ will still need to be called. This procedure is now deprecated. \fBTcl_DStringSetLength\fR should be used instead. .PP -\fBTcl_DStringFree\fR should be called when you're finished using +\fBTcl_DStringFree\fR should be called when you are 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 diff --git a/doc/DetachPids.3 b/doc/DetachPids.3 index 91535a9..3ab4fe1 100644 --- a/doc/DetachPids.3 +++ b/doc/DetachPids.3 @@ -1,77 +1,77 @@ -'\" -'\" 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.4 2004/10/07 14:44:32 dkf Exp $ -'\" -.so man.macros -.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR) -.sp -\fBTcl_ReapDetachedProcs\fR() -.sp -Tcl_Pid -\fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR) -.SH ARGUMENTS -.AS Tcl_Pid *statusPtr out -.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. -.AP Tcl_Pid pid in -The id of the process (pipe) to wait for. -.AP int *statusPtr out -The result of waiting on a process (pipe). Either 0 or ECHILD. -.AP int options in -The options controlling the wait. WNOHANG specifies not to wait when -checking the process. -.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. -.PP -\fBTcl_WaitPid\fR is a thin wrapper around the facilities provided by -the operating system to wait on the end of a spawned process and to -check a whether spawned process is still running. It is used by -\fBTcl_ReapDetachedProcs\fR and the channel system to portably access -the operating system. - -.SH KEYWORDS -background, child, detach, process, wait +'\"
+'\" 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.5 2007/10/28 14:17:38 dkf Exp $
+'\"
+.so man.macros
+.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
+.sp
+\fBTcl_ReapDetachedProcs\fR()
+.sp
+Tcl_Pid
+\fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR)
+.SH ARGUMENTS
+.AS Tcl_Pid *statusPtr out
+.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.
+.AP Tcl_Pid pid in
+The id of the process (pipe) to wait for.
+.AP int *statusPtr out
+The result of waiting on a process (pipe). Either 0 or ECHILD.
+.AP int options in
+The options controlling the wait. WNOHANG specifies not to wait when
+checking the process.
+.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 does not
+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 has not exited yet,
+\fBTcl_ReapDetachedProcs\fR does not 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 is not 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.
+.PP
+\fBTcl_WaitPid\fR is a thin wrapper around the facilities provided by
+the operating system to wait on the end of a spawned process and to
+check a whether spawned process is still running. It is used by
+\fBTcl_ReapDetachedProcs\fR and the channel system to portably access
+the operating system.
+
+.SH KEYWORDS
+background, child, detach, process, wait
diff --git a/doc/DoOneEvent.3 b/doc/DoOneEvent.3 index dc3d6e6..a027c80 100644 --- a/doc/DoOneEvent.3 +++ b/doc/DoOneEvent.3 @@ -1,108 +1,108 @@ -'\" -'\" 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.3 2004/09/18 17:01:05 dkf 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: -\fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR, -\fBTCL_TIMER_EVENTS\fR, \fBTCL_IDLE_EVENTS\fR, \fBTCL_ALL_EVENTS\fR, -or \fBTCL_DONT_WAIT\fR. -.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 +'\"
+'\" 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.4 2007/10/28 14:17:38 dkf 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:
+\fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,
+\fBTCL_TIMER_EVENTS\fR, \fBTCL_IDLE_EVENTS\fR, \fBTCL_ALL_EVENTS\fR,
+or \fBTCL_DONT_WAIT\fR.
+.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 \-
+Do not 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 index 90a6aa7..239878e 100644 --- a/doc/DoWhenIdle.3 +++ b/doc/DoWhenIdle.3 @@ -1,86 +1,86 @@ -'\" -'\" 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 +'\"
+'\" 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.3 2007/10/28 14:17:38 dkf 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, could not 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 is
+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/Encoding.3 b/doc/Encoding.3 index 40fe886..890ae54 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Encoding.3,v 1.27 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: Encoding.3,v 1.28 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" @@ -118,7 +118,7 @@ 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. \fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should -return immediately upon reading a source character that doesn't exist in +return immediately upon reading a source character that does not exist in the target encoding; otherwise a default fallback character will automatically be substituted. .AP Tcl_EncodingState *statePtr in/out @@ -277,18 +277,25 @@ is filled with the corresponding number of bytes that were stored in Windows-only convenience functions for converting between UTF-8 and Windows strings. On Windows 95 (as with the Unix operating system), -all strings exchanged between Tcl and the operating system are "char" +all strings exchanged between Tcl and the operating system are +.QW "char" based. On Windows NT, some strings exchanged between Tcl and the -operating system are "char" oriented while others are in Unicode. By +operating system are +.QW "char" +oriented while others are in Unicode. By convention, in Windows a TCHAR is a character in the ANSI code page on Windows 95 and a Unicode character on Windows NT. .PP -If you planned to use the same "char" based interfaces on both Windows +If you planned to use the same +.QW "char" +based interfaces on both Windows 95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and \fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an encoding of NULL (the current system encoding). On the other hand, if you planned to use the Unicode interface when running on Windows NT -and the "char" interfaces when running on Windows 95, you would have +and the +.QW "char" +interfaces when running on Windows 95, you would have to perform the following type of test over and over in your program (as represented in pseudo-code): .CS @@ -457,8 +464,9 @@ are obsolete interfaces best replaced with calls to \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR. They are called to access and set the first element of the \fIsearchPath\fR list. Since Tcl searches \fIsearchPath\fR for encoding data files in -list order, these routines establish the ``default'' directory in which -to find encoding data files. +list order, these routines establish the +.QW default +directory in which to find encoding data files. .VE 8.5 .SH "ENCODING FILES" Space would prohibit precompiling into Tcl every possible encoding @@ -471,7 +479,9 @@ 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 +initial line of the file, beginning with a +.QW # +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: @@ -557,7 +567,7 @@ and 0x8163 in \fBshiftjis\fR map to 203E and 2026 in Unicode, respectively. 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. +Unicode character 0000, it means that the character does not 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 @@ -569,13 +579,13 @@ encoding: E init {} final {} -iso8859-1 \\x1b(B -jis0201 \\x1b(J -jis0208 \\x1b$@ -jis0208 \\x1b$B -jis0212 \\x1b$(D -gb2312 \\x1b$A -ksc5601 \\x1b$(C +iso8859-1 \ex1b(B +jis0201 \ex1b(J +jis0208 \ex1b$@ +jis0208 \ex1b$B +jis0212 \ex1b$(D +gb2312 \ex1b$A +ksc5601 \ex1b$(C .CE .PP In the file, the first column represents an option and the second column @@ -584,8 +594,11 @@ 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. +example, for instance, +.QW \fB{}\fR +represents the empty string and +.QW \fB\ex1b\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 @@ -6,7 +6,7 @@ '\" 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.25 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: Eval.3,v 1.26 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" @@ -98,12 +98,18 @@ result; it can be retrieved using \fBTcl_GetObjResult\fR. \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. -The eofchar for files is '\\32' (^Z) for all platforms. -If you require a ``^Z'' in code for string comparison, you can use -``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl -interpreter into ``^Z''. +If the file could not be read then a Tcl error is returned to describe +why the file could not be read. +The eofchar for files is +.QW \e32 +(^Z) for all platforms. If you require a +.QW ^Z +in code for string comparison, you can use +.QW \e032 +or +.QW \eu001a , +which will be safely substituted by the Tcl interpreter into +.QW ^Z . .PP \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a script. The \fIobjc\fR and \fIobjv\fR arguments contain the values @@ -128,7 +134,7 @@ executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR. Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to \fIinterp->result\fR (use is deprecated) where it can be accessed directly. This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which -doesn't do the copy. +does not 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 @@ -165,8 +171,8 @@ 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. +bytecodes will not be reused in a future execution. In this case, +it is 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 diff --git a/doc/ExprLong.3 b/doc/ExprLong.3 index 46a5783..4cdf547 100644 --- a/doc/ExprLong.3 +++ b/doc/ExprLong.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ExprLong.3,v 1.13 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: ExprLong.3,v 1.14 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures" @@ -92,7 +92,11 @@ 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. +such as +.QW yes +or +.QW no , +or else an error occurs. .PP \fBTcl_ExprString\fR returns the value of the expression as a string stored in the interpreter's result. diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3 index d39ab65..8a89344 100644 --- a/doc/ExprLongObj.3 +++ b/doc/ExprLongObj.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ExprLongObj.3,v 1.7 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: ExprLongObj.3,v 1.8 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures" @@ -88,7 +88,11 @@ 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. +such as +.QW yes +or +.QW no , +or else an error occurs. .PP If \fBTcl_ExprObj\fR successfully evaluates the expression, it stores a pointer to the Tcl object diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index 77345bd..3498a9b 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: FileSystem.3,v 1.59 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: FileSystem.3,v 1.60 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" @@ -252,27 +252,38 @@ rather than calling system level functions like \fBaccess\fR and extension which calls them should work unmodified on Unix and Windows. Second, the Windows implementation of some of these functions fixes some bugs in the system level calls. Third, these function calls -deal with any 'Utf to platform-native' path conversions which may be +deal with any +.QW "Utf to platform-native" +path conversions which may be required (and may cache the results of such conversions for greater efficiency on subsequent calls). Fourth, and perhaps most importantly, -all of these functions are 'virtual filesystem aware'. Any virtual -filesystem (VFS for short) which has been registered (through +all of these functions are +.QW "virtual filesystem aware" . +Any virtual filesystem (VFS for short) which has been registered (through \fBTcl_FSRegister\fR) may reroute file access to alternative media or access methods. This means that all of these functions (and therefore the corresponding \fBfile\fR, \fBglob\fR, \fBpwd\fR, \fBcd\fR, -\fBopen\fR, etc. Tcl commands) may be operate on 'files' which are not +\fBopen\fR, etc. Tcl commands) may be operate on +.QW files +which are not native files in the native filesystem. This also means that any Tcl extension which accesses the filesystem (FS for short) through this API is -automatically 'virtual filesystem aware'. Of course, if an extension +automatically +.QW "virtual filesystem aware" . +Of course, if an extension accesses the native filesystem directly (through platform-specific APIs, for example), then Tcl cannot intercept such calls. .PP -If appropriate VFSes have been registered, the 'files' may, to give two +If appropriate VFSes have been registered, the +.QW files +may, to give two examples, be remote (e.g. situated on a remote ftp server) or archived (e.g. lying inside a .zip archive). Such registered filesystems provide a lookup table of functions to implement all or some of the functionality listed here. Finally, the \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR calls -abstract away from what the 'struct stat' buffer is actually +abstract away from what the +.QW "struct stat" +buffer is actually declared to be, allowing the same code to be used both on systems with and systems without support for files larger than 2GB in size. .PP @@ -304,41 +315,56 @@ function with such an object will result in no action being taken. \fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths given lie in the same filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that -filesystem's 'copy file' function is called (if it is non-NULL). +filesystem's +.QW "copy file" +function is called (if it is non-NULL). Otherwise the function returns -1 and sets the \fBerrno\fR global C -variable to the 'EXDEV' -POSIX error code (which signifies a 'cross-domain link'). +variable to the +.QW EXDEV +POSIX error code (which signifies a +.QW "cross-domain link" ). .PP \fBTcl_FSCopyDirectory\fR attempts to copy the directory given by \fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths given lie in the same filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that -filesystem's 'copy file' function is called (if it is non-NULL). +filesystem's +.QW "copy file" +function is called (if it is non-NULL). Otherwise the function returns -1 and sets the \fBerrno\fR global C -variable to the 'EXDEV' -POSIX error code (which signifies a 'cross-domain link'). +variable to the +.QW EXDEV +POSIX error code (which signifies a +.QW "cross-domain link" ). .PP \fBTcl_FSCreateDirectory\fR attempts to create the directory given by -\fIpathPtr\fR by calling the owning filesystem's 'create directory' +\fIpathPtr\fR by calling the owning filesystem's +.QW "create directory" function. .PP \fBTcl_FSDeleteFile\fR attempts to delete the file given by -\fIpathPtr\fR by calling the owning filesystem's 'delete file' +\fIpathPtr\fR by calling the owning filesystem's +.QW "delete file" function. .PP \fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by -\fIpathPtr\fR by calling the owning filesystem's 'remove directory' +\fIpathPtr\fR by calling the owning filesystem's +.QW "remove directory" function. .PP \fBTcl_FSRenameFile\fR attempts to rename the file or directory given by \fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths given lie in the same filesystem (according to -\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's 'rename file' +\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's +.QW "rename file" function is called (if it is non-NULL). Otherwise the function returns -1 -and sets the \fBerrno\fR global C variable to the 'EXDEV' POSIX error -code (which signifies a 'cross-domain link'). -.PP -\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL 'list -volumes' function and asks them to return their list of root volumes. It +and sets the \fBerrno\fR global C variable to the +.QW EXDEV +POSIX error code (which signifies a +.QW "cross-domain link" ). +.PP +\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL +.QW "list volumes" +function and asks them to return their list of root volumes. It accumulates the return values in a list which is returned to the caller (with a reference count of 0). .PP @@ -349,12 +375,19 @@ its contents as a Tcl script. It returns the same information as \fBTcl_EvalObjEx\fR. If \fIencodingName\fR is NULL, the system encoding is used for reading the file contents. -If the file couldn't be read then a Tcl error is returned to describe -why the file couldn't be read. -The eofchar for files is '\\32' (^Z) for all platforms. -If you require a ``^Z'' in code for string comparison, you can use -``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl -interpreter into ``^Z''. +If the file could not be read then a Tcl error is returned to describe +why the file could not be read. +The eofchar for files is +.QW \e32 +(^Z) for all platforms. +If you require a +.QW ^Z +in code for string comparison, you can use +.QW \e032 +or +.QW \eu001a , +which will be safely substituted by the Tcl interpreter into +.QW ^Z . \fBTcl_FSEvalFile\fR is a simpler version of \fBTcl_FSEvalFileEx\fR that always uses the system encoding when reading the file. @@ -391,7 +424,9 @@ that the path needs to be checked only for the correct type. extends it to support the creation of links. The appropriate function for the filesystem to which \fIlinkNamePtr\fR belongs will be called. .PP -If the \fItoPtr\fR is NULL, a 'read link' action is performed. The result +If the \fItoPtr\fR is NULL, a +.QW "read link" +action is performed. The result is a Tcl_Obj specifying the contents of the symbolic link given by \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned by the caller, which should call Tcl_DecrRefCount when the result is no @@ -421,7 +456,11 @@ given. .PP This returns 0 on success and -1 on error (as per the \fButime\fR documentation). If successful, the function -will update the 'atime' and 'mtime' values of the file given. +will update the +.QW atime +and +.QW mtime +values of the file given. .PP \fBTcl_FSFileAttrsGet\fR implements read access for the hookable \fBfile attributes\fR subcommand. The appropriate function for the filesystem to @@ -584,8 +623,11 @@ of zero, they will be freed when this function returns. \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid Tcl path type, taking account of the fact that the cwd may have changed even if this object is already supposedly of the correct type. -The filename may begin with "~" (to indicate current user's home -directory) or "~<user>" (to indicate any user's home directory). +The filename may begin with +.QW ~ +(to indicate current user's home directory) or +.QW ~<user> +(to indicate any user's home directory). .PP If the conversion succeeds (i.e. the object is a valid path in one of the current filesystems), then \fBTCL_OK\fR is returned. Otherwise @@ -607,8 +649,13 @@ from the given Tcl_Obj. .PP If the translation succeeds (i.e. the object is a valid path), then it is returned. Otherwise NULL will be returned, and an error message may be -left in the interpreter. A "translated" path is one which contains no -"~" or "~user" sequences (these have been expanded to their current +left in the interpreter. A +.QW translated +path is one which contains no +.QW ~ +or +.QW ~user +sequences (these have been expanded to their current representation in the filesystem). The object returned is owned by the caller, which must store it or call Tcl_DecrRefCount to ensure memory is freed. This function is of little practical use, and @@ -628,8 +675,10 @@ in native form (from, e.g. \fBreadlink\fR or a native dialog), and that path is to be used at the Tcl level, then calling this function is an efficient way of creating the appropriate path object type. .PP -The resulting object is a pure 'path' object, which will only receive -a Utf-8 string representation if that is required by some Tcl code. +The resulting object is a pure +.QW path +object, which will only receive +a UTF-8 string representation if that is required by some Tcl code. .PP \fBTcl_FSGetNativePath\fR is for use by the Win/Unix native filesystems, so that they can easily retrieve the native (char* or @@ -656,8 +705,13 @@ passed in (unless that is a relative path, in which case the native representation may be freed any time the cwd changes). .PP \fBTcl_FSFileSystemInfo\fR returns a list of two elements. The first -element is the name of the filesystem (e.g. "native" or "vfs" or "zip" -or "prowrap", perhaps), and the second is the particular type of the +element is the name of the filesystem (e.g. +.QW native , +.QW vfs , +.QW zip , +or +.QW prowrap , +perhaps), and the second is the particular type of the given path within that filesystem (which is filesystem dependent). The second element may be empty if the filesystem does not provide a further categorization of files. @@ -781,8 +835,9 @@ designed to support efficient, cached conversion of these UTF\-8 paths to other native representations. .SS "EXAMPLE FILESYSTEM DEFINITION" .PP -Here is the filesystem lookup table used by the "vfs" extension which -allows filesystem actions to be implemented in Tcl. +Here is the filesystem lookup table used by the +.QW vfs +extension which allows filesystem actions to be implemented in Tcl. .CS static Tcl_Filesystem vfsFilesystem = { "tclvfs", @@ -845,7 +900,10 @@ representations. .PP The \fItypeName\fR field contains a null-terminated string that identifies the type of the filesystem implemented, e.g. -``native'' or ``zip'' or ```vfs''. +.QW native , +.QW zip +or +.QW vfs . .SS "STRUCTURE LENGTH" .PP The \fIstructureLength\fR field is generally implemented as @@ -923,12 +981,17 @@ typedef ClientData Tcl_FSCreateInternalRepProc( .PP Function to normalize a path. Should be implemented for all filesystems which can have multiple string representations for the same -path object. In Tcl, every 'path' must have a single unique 'normalized' +path object. In Tcl, every +.QW path +must have a single unique +.QW normalized string representation. Depending on the filesystem, there may be more than one unnormalized string representation which refers to that path (e.g. a relative path, a path with different character case if the filesystem is case insensitive, a path contain a -reference to a home directory such as '~', a path containing symbolic +reference to a home directory such as +.QW ~ , +a path containing symbolic links, etc). If the very last component in the path is a symbolic link, it should not be converted into the object it points to (but its case or other aspects should be made unique). All other path @@ -964,10 +1027,16 @@ etc. The Tcl core expects filesystems to behave in this way). .PP Function to determine the type of a path in this filesystem. May be NULL, in which case no type information will be available to users of -the filesystem. The 'type' is used only for informational purposes, +the filesystem. The +.QW type +is used only for informational purposes, and should be returned as the string representation of the Tcl_Obj -which is returned. A typical return value might be "networked", "zip" -or "ftp". The Tcl_Obj result is owned by the filesystem and so Tcl will +which is returned. A typical return value might be +.QW networked , +.QW zip +or +.QW ftp . +The Tcl_Obj result is owned by the filesystem and so Tcl will increment the refCount of that object if it wishes to retain a reference to it. .PP @@ -979,7 +1048,9 @@ typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc( .PP Function to return the separator character(s) for this filesystem. This need only be implemented if the filesystem wishes to use a -different separator than the standard string "/". Amongst other +different separator than the standard string +.QW / . +Amongst other uses, it is returned by the \fBfile separator\fR command. The return value should be an object with refCount of zero. .PP @@ -1190,7 +1261,9 @@ NULL (or an empty list) if no volumes are provided. The result object is considered to be owned by the filesystem (not by Tcl's core), but should be given a refCount for Tcl. Tcl will use the contents of the list and then decrement that refCount. This allows filesystems to -choose whether they actually want to retain a 'master list' of volumes +choose whether they actually want to retain a +.QW "master list" +of volumes or not (if not, they generate the list on the fly and pass it to Tcl with a refCount of 1 and then forget about the list, if yes, then they simply increment the refCount of their master list and pass it @@ -1287,7 +1360,9 @@ occurred in the process. If successful, the directory specified by \fIpathPtr\fR should have been removed from the filesystem. If the \fIrecursive\fR flag is given, then a non-empty directory should be deleted without error. If this flag is not given, then and the -directory is non-empty a POSIX 'EEXIST' error should be signalled. If an +directory is non-empty a POSIX +.QW EEXIST +error should be signalled. If an error does occur, the name of the file or directory which caused the error should be placed in \fIerrorPtr\fR. .SS DELETEFILEPROC diff --git a/doc/GetCwd.3 b/doc/GetCwd.3 index 554d6e3..48eddf7 100755 --- a/doc/GetCwd.3 +++ b/doc/GetCwd.3 @@ -1,54 +1,54 @@ -'\" -'\" Copyright (c) 1998-1999 Scriptics Corporation -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: GetCwd.3,v 1.6 2004/10/07 14:44:32 dkf 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 in/out -.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 +'\"
+'\" Copyright (c) 1998-1999 Scriptics Corporation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" RCS: @(#) $Id: GetCwd.3,v 1.7 2007/10/28 14:17:38 dkf 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 in/out
+.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 \fIinterp\fR'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 index f77705c..460f259 100644 --- a/doc/GetIndex.3 +++ b/doc/GetIndex.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: GetIndex.3,v 1.20 2006/11/15 09:23:01 dkf Exp $ +'\" RCS: @(#) $Id: GetIndex.3,v 1.21 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures" @@ -68,10 +68,10 @@ and \fBTCL_OK\fR is returned. .PP If there is no matching entry, \fBTCL_ERROR\fR 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 +result if \fIinterp\fR is not 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. +.QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" . .PP If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the internal representation of \fIobjPtr\fR to hold the address of diff --git a/doc/GetInt.3 b/doc/GetInt.3 index b1c658e..d07097b 100644 --- a/doc/GetInt.3 +++ b/doc/GetInt.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: GetInt.3,v 1.12 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: GetInt.3,v 1.13 2007/10/28 14:17:38 dkf Exp $ '\" .so man.macros .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures" @@ -47,7 +47,7 @@ integers). Each of the procedures takes a \fIsrc\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 -\fBTCL_OK\fR. If \fIsrc\fR doesn't have the proper syntax for the +\fBTCL_OK\fR. If \fIsrc\fR does not have the proper syntax for the desired type then \fBTCL_ERROR\fR is returned, an error message is left in the interpreter's result, and nothing is stored at *\fIintPtr\fR or *\fIdoublePtr\fR or *\fIboolPtr\fR. @@ -55,20 +55,25 @@ or *\fIdoublePtr\fR or *\fIboolPtr\fR. \fBTcl_GetInt\fR expects \fIsrc\fR to consist of a collection of integer digits, optionally signed and optionally preceded by white space. If the first two characters of \fIsrc\fR -after the optional white space and sign are ``0x'' +after the optional white space and sign are +.QW 0x then \fIsrc\fR is expected to be in hexadecimal form; otherwise, -if the first such character is ``0'' then \fIsrc\fR +if the first such character is +.QW 0 +then \fIsrc\fR is expected to be in octal form; otherwise, \fIsrc\fR is expected to be in decimal form. .PP \fBTcl_GetDouble\fR expects \fIsrc\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''; a -signed decimal exponent ; and more white space. +decimal point; a sequence of digits; the letter +.QW e ; +a signed decimal exponent; and more white space. 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. +and if the +.QW e +is present then it must be followed by the exponent number. .PP \fBTcl_GetBoolean\fR expects \fIsrc\fR to specify a boolean value. If \fIsrc\fR is any of \fB0\fR, \fBfalse\fR, diff --git a/doc/GetOpnFl.3 b/doc/GetOpnFl.3 index 7524aeb..06023e1 100644 --- a/doc/GetOpnFl.3 +++ b/doc/GetOpnFl.3 @@ -1,59 +1,59 @@ -'\" -'\" 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.11 2005/05/10 18:33:56 kennykb Exp $ -.so man.macros -.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpreter (Unix only) -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_GetOpenFile\fR(\fIinterp, chanID, write, checkUsage, filePtr\fR) -.sp -.SH ARGUMENTS -.AS Tcl_Interp checkUsage out -.AP Tcl_Interp *interp in -Tcl interpreter from which file handle is to be obtained. -.AP "const char" *chanID 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 \fIchanID\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 \fBTCL_OK\fR. -If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIchanID\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 \fBTCL_ERROR\fR is returned -and the interpreter's result will contain an error message. -In the current implementation \fIcheckUsage\fR is ignored and consistency -checks are always performed. -.PP -Note that this interface is only supported on the Unix platform. - -.SH KEYWORDS -channel, file handle, permissions, pipeline, read, write +'\"
+'\" 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.12 2007/10/28 14:17:39 dkf Exp $
+.so man.macros
+.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpreter (Unix only)
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_GetOpenFile\fR(\fIinterp, chanID, write, checkUsage, filePtr\fR)
+.sp
+.SH ARGUMENTS
+.AS Tcl_Interp checkUsage out
+.AP Tcl_Interp *interp in
+Tcl interpreter from which file handle is to be obtained.
+.AP "const char" *chanID 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 was not 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 \fIchanID\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 \fBTCL_OK\fR.
+If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIchanID\fR did not
+make any sense or \fIcheckUsage\fR was set and the file was not opened
+for the access specified by \fIwrite\fR) then \fBTCL_ERROR\fR is returned
+and the interpreter's result will contain an error message.
+In the current implementation \fIcheckUsage\fR is ignored and consistency
+checks are always performed.
+.PP
+Note that this interface is only supported on the Unix platform.
+
+.SH KEYWORDS
+channel, file handle, permissions, pipeline, read, write
diff --git a/doc/GetTime.3 b/doc/GetTime.3 index dac3faa..e15d3f3 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -26,7 +26,7 @@ Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time Points to memory in which to store the date and time information. .AS "Tcl_GetTimeProc *" getProc in .AP "Tcl_GetTimeProc *" getProc in -Pointer to handler function replacing Tcl_GetTime's access to the OS. +Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS. .AS "Tcl_ScaleTimeProc *" scaleProc in .AP "Tcl_ScaleTimeProc *" scaleProc in Pointer to handler function for the conversion of time delays in the @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Hash.3,v 1.23 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: Hash.3,v 1.24 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" @@ -88,7 +88,9 @@ STRUCTURE\fR below). 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 +space as a +.QW "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. @@ -124,8 +126,10 @@ 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) +and stored in hash table entries as +.QW "char *" +values. +The pointer value is the key; it need not (and usually does not) actually point to a string. .IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25 Keys are of arbitrary type, and are stored in the entry. Hashing @@ -140,7 +144,9 @@ structure is described in the section .IP \fIother\fR 25 If \fIkeyType\fR is not one of the above, then it must be an integer value greater than 1. -In this case the keys will be arrays of ``int'' values, where +In this case the keys will be arrays of +.QW 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. @@ -161,7 +167,7 @@ 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. +was not 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 @@ -177,28 +183,34 @@ 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; +except that it does not 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 +Values are stored and retrieved as type +.QW 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 +either as a pointer to a string, a one-word +.PQ "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 *''. +.QW "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, +A structure of type +.QW 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 @@ -253,9 +265,9 @@ to \fBTCL_HASH_KEY_TYPE_VERSION\fR. .PP The \fIflags\fR member is 0 or one or more of the following values OR'ed together: .IP \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR 25 -There are some things, pointers for example which don't hash well +There are some things, pointers for example which do not hash well because they do not use the lower bits. If this flag is set then the -hash table will attempt to rectify this by randomizing the bits and +hash table will attempt to rectify this by randomizing the bits and then using the upper N bits as the index into the table. .IP \fBTCL_HASH_KEY_SYSTEM_HASH\fR 25 .VS 8.5 @@ -287,7 +299,7 @@ typedef int (Tcl_CompareHashKeysProc) ( Tcl_HashEntry *\fIhPtr\fR); .CE If this is NULL then the \fIkeyPtr\fR pointers are compared. -If the keys don't match then the function returns 0, otherwise +If the keys do not match then the function returns 0, otherwise it returns 1. .PP The \fIallocEntryProc\fR member contains the address of a function @@ -1,36 +1,36 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id: Init.3,v 1.3 2004/10/07 15:37:43 dkf Exp $ -'\" -.so man.macros -.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Init \- find and source initialization script -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_Init\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Interpreter to initialize. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fR's the -\fBinit.tcl\fR script, which should exist somewhere on the Tcl library -path. -.PP -\fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures. - -.SH "SEE ALSO" -Tcl_AppInit, Tcl_Main - -.SH KEYWORDS -application, initialization, interpreter +'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\"
+'\" RCS: @(#) $Id: Init.3,v 1.4 2007/10/28 14:17:39 dkf Exp $
+'\"
+.so man.macros
+.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_Init \- find and source initialization script
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_Init\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp
+.AP Tcl_Interp *interp in
+Interpreter to initialize.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fRs the
+\fBinit.tcl\fR script, which should exist somewhere on the Tcl library
+path.
+.PP
+\fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures.
+
+.SH "SEE ALSO"
+Tcl_AppInit, Tcl_Main
+
+.SH KEYWORDS
+application, initialization, interpreter
diff --git a/doc/Interp.3 b/doc/Interp.3 index c61ae40..9ee66f9 100644 --- a/doc/Interp.3 +++ b/doc/Interp.3 @@ -1,125 +1,125 @@ -'\" -'\" 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.9 2005/05/10 18:33:56 kennykb 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 fields -that are used by Tcl, but only three that may be accessed by -clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR. -.PP -\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR -\fBdeprecated.\fR Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead. -.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. -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. -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. -In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever -used for \fIfreeProc\fR. -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. The direct use of -\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR). -.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 +'\"
+'\" 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.10 2007/10/28 14:17:39 dkf 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 fields
+that are used by Tcl, but only three that may be accessed by
+clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
+.PP
+\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR
+\fBdeprecated.\fR Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead.
+.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 is not 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.
+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.
+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.
+In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
+used for \fIfreeProc\fR.
+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. The direct use of
+\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR).
+.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 index a3a3b62..5a03942 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: LinkVar.3,v 1.14 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: LinkVar.3,v 1.15 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" @@ -159,15 +159,17 @@ it.) Any value written into the Tcl variable must have a proper unsigned integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be cast to unsigned); -'\" FIXME! Use bignums instead. +.\" FIXME! Use bignums instead. attempts to write non-integer values into \fIvarName\fR will be rejected with Tcl errors. .VE 8.5 .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''. +If its value is zero then it will read from Tcl as +.QW 0 ; +otherwise it will read from Tcl as +.QW 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 @@ -183,7 +185,8 @@ 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''. +will read as +.QW NULL . .PP If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the variable will be read-only from Tcl, so that its value can only be diff --git a/doc/Notifier.3 b/doc/Notifier.3 index b1aec3f..15eae60 100644 --- a/doc/Notifier.3 +++ b/doc/Notifier.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Notifier.3,v 1.19 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: Notifier.3,v 1.20 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Notifier 3 8.1 Tcl "Tcl Library Procedures" @@ -107,8 +107,8 @@ Indicates whether events should be serviced by \fBTcl_ServiceAll\fR. Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR. .AP Tcl_NotifierProcs* notifierProcPtr in Structure of function pointers describing notifier procedures that are -to replace the ones installed in the executable. See "REPLACING THE -NOTIFIER" for details. +to replace the ones installed in the executable. See +\fBREPLACING THE NOTIFIER\fR for details. .BE .SH INTRODUCTION @@ -243,7 +243,7 @@ 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 +if the bit corresponding to this event source is not set, the event source should return immediately without doing anything. For example, the file event source checks for the \fBTCL_FILE_EVENTS\fR bit. @@ -385,7 +385,7 @@ 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. +\fBTCL_FILE_EVENTS\fR bit is not 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. @@ -409,8 +409,9 @@ Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR procedure. (A thread would then need to pass this identifier to other threads for those threads to be able to add events to its queue.) After adding an event to another thread's queue, you then typically -need to call \fBTcl_ThreadAlert\fR to "wake up" that thread's notifier to -alert it to the new event. +need to call \fBTcl_ThreadAlert\fR to +.QW "wake up" +that thread's notifier to alert it to the new event. .PP \fBTcl_DeleteEvents\fR can be used to explicitly remove one or more events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR @@ -454,7 +455,9 @@ procedure when initializing a Tcl interpreter. Similarly, called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter. .PP \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier; -it is responsible for waiting for an ``interesting'' event to occur or +it is responsible for waiting for an +.QW 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 @@ -468,13 +471,13 @@ 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; +However, on some platforms (such as Windows) this is not 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 +events still pending that have not 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 @@ -489,7 +492,9 @@ forever because there were no active event sources and the timeout was infinite. .PP \fBTcl_AlertNotifier\fR is used in multithreaded applications to allow -any thread to "wake up" the notifier to alert it to new events on its +any thread to +.QW "wake up" +the notifier to alert it to new events on its queue. \fBTcl_AlertNotifier\fR requires as an argument the notifier handle returned by \fBTcl_InitNotifier\fR. .PP @@ -499,7 +504,7 @@ 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 +because \fBTcl_WaitForEvent\fR is not 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. diff --git a/doc/Object.3 b/doc/Object.3 index 2d3a206..3fba327 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Object.3,v 1.16 2007/07/04 15:24:45 dkf Exp $ +'\" RCS: @(#) $Id: Object.3,v 1.17 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures" @@ -284,7 +284,7 @@ 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 accidentally. +it will not be freed too early or have its value change accidentally. .PP As an example, the bytecode interpreter shares argument objects between calling and called Tcl procedures to avoid having to copy objects. @@ -300,7 +300,7 @@ When an object's reference count drops less than or equal 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. +and do not 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. @@ -315,7 +315,9 @@ 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. +the command procedure +.QW "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 diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index 3101ffa..ec388ec 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ObjectType.3,v 1.14 2007/07/04 15:24:45 dkf Exp $ +'\" RCS: @(#) $Id: ObjectType.3,v 1.15 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures" @@ -117,7 +117,7 @@ typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR); .CE .PP -If an internal representation can't be created from the string, +If an internal representation cannot 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. diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index a5caee4..ebd4d8d 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.32 2005/06/06 23:45:42 dkf Exp $ +'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.33 2007/10/28 14:17:39 dkf Exp $ .so man.macros .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" .BS @@ -458,7 +458,7 @@ 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 +\fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it does not 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 @@ -510,9 +510,11 @@ at either the head or tail of the queue. The pointer \fIinput\fR points to the data that is to be added. The length of the input to add is given by \fIinputLen\fR. A non-zero value of \fIaddAtEnd\fR indicates that the data is to be added at the end of queue; otherwise it will be added at the -head of the queue. If \fIchannel\fR has a "sticky" EOF set, no data will be +head of the queue. If \fIchannel\fR has a +.QW sticky +EOF set, no data will be added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or --1 if an error occurs. +\-1 if an error occurs. .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE" .PP @@ -552,7 +554,7 @@ 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 +\fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it does not 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 diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index e32077f..aac5cf7 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ParseCmd.3,v 1.24 2006/11/03 00:34:51 hobbs Exp $ +'\" RCS: @(#) $Id: ParseCmd.3,v 1.25 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures" @@ -92,7 +92,7 @@ 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 +leave an error message in \fIinterp\fR's result (if \fIinterp\fR is not NULL), and leave nothing in \fIparsePtr\fR. .PP @@ -119,7 +119,7 @@ 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 +\fB{hello}\fR or \fB{string \et with \et tabs}\fR from the beginning of its argument \fIstart\fR. The first character of \fIstart\fR must be \fB{\fR. If the braced string was parsed successfully, @@ -137,13 +137,13 @@ and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR. \fBTcl_ParseQuotedString\fR parses a double-quoted string such as \fB"sum is [expr {$a+$b}]"\fR from the beginning of the argument \fIstart\fR. -The first character of \fIstart\fR must be \fB"\fR. +The first character of \fIstart\fR must be \fB\N'34'\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 +and stores a pointer to the character just after the terminating \fB\N'34'\fR in the location given by \fI*termPtr\fR. If an error occurs while parsing the string then \fBTCL_ERROR\fR is returned, diff --git a/doc/Preserve.3 b/doc/Preserve.3 index b0197db..cae4b51 100644 --- a/doc/Preserve.3 +++ b/doc/Preserve.3 @@ -5,13 +5,13 @@ '\" 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.4 2002/02/26 02:22:20 hobbs Exp $ +'\" RCS: @(#) $Id: Preserve.3,v 1.5 2007/10/28 14:17:39 dkf 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 +Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it is being used .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -38,7 +38,7 @@ 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 +However, it is 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 diff --git a/doc/PrintDbl.3 b/doc/PrintDbl.3 index d0614d9..358ad44 100644 --- a/doc/PrintDbl.3 +++ b/doc/PrintDbl.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: PrintDbl.3,v 1.9 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: PrintDbl.3,v 1.10 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures" @@ -36,10 +36,13 @@ least \fBTCL_DOUBLE_SPACE\fR characters of storage. \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''. +special twist: the string is guaranteed to contain either a +.QW . +or an +.QW e +so that it does not look like an integer. Where \fB%g\fR would +generate an integer with no decimal point, \fBTcl_PrintDouble\fR adds +.QW .0 . .VS 8.5 .PP If the \fBtcl_precision\fR value is non-zero, the result will have diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3 index 742524c..05bd6da 100644 --- a/doc/RecEvalObj.3 +++ b/doc/RecEvalObj.3 @@ -1,55 +1,55 @@ -'\" -'\" 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.5 2004/09/18 17:01:06 dkf 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. \fBTCL_NO_EVAL\fR means record the -command but don't evaluate it. \fBTCL_EVAL_GLOBAL\fR 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_EvalObjEx\fR -(or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set -in \fIflags\fR). -It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\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_EvalObjEx\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 \fBTCL_NO_EVAL\fR bit then -the command is recorded without being evaluated. - -.SH "SEE ALSO" -Tcl_EvalObjEx, Tcl_GetObjResult - -.SH KEYWORDS -command, event, execute, history, interpreter, object, record +'\"
+'\" 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.6 2007/10/28 14:17:39 dkf 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. \fBTCL_NO_EVAL\fR means record the
+command but do not evaluate it. \fBTCL_EVAL_GLOBAL\fR 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_EvalObjEx\fR
+(or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set
+in \fIflags\fR).
+It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\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 do not want the command recorded on the history list then
+you should invoke \fBTcl_EvalObjEx\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 \fBTCL_NO_EVAL\fR bit then
+the command is recorded without being evaluated.
+
+.SH "SEE ALSO"
+Tcl_EvalObjEx, Tcl_GetObjResult
+
+.SH KEYWORDS
+command, event, execute, history, interpreter, object, record
diff --git a/doc/RecordEval.3 b/doc/RecordEval.3 index 68cdd9a..afea09d 100644 --- a/doc/RecordEval.3 +++ b/doc/RecordEval.3 @@ -1,57 +1,57 @@ -'\" -'\" 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.7 2004/10/07 15:15:47 dkf 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 "const char" *cmd in -Command (or sequence of commands) to execute. -.AP int flags in -An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the -command but don't evaluate it. \fBTCL_EVAL_GLOBAL\fR 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 \fBTCL_EVAL_GLOBAL\fR bit is set in \fIflags\fR). -It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_Eval\fR -and it leaves information in the interpreter's result. -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 \fBTCL_NO_EVAL\fR 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 +'\"
+'\" 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.8 2007/10/28 14:17:39 dkf 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 "const char" *cmd in
+Command (or sequence of commands) to execute.
+.AP int flags in
+An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the
+command but do not evaluate it. \fBTCL_EVAL_GLOBAL\fR 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 \fBTCL_EVAL_GLOBAL\fR bit is set in \fIflags\fR).
+It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_Eval\fR
+and it leaves information in the interpreter's result.
+If you do not 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 \fBTCL_NO_EVAL\fR 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/RegConfig.3 b/doc/RegConfig.3 index 908c2ec..2e01a58 100644 --- a/doc/RegConfig.3 +++ b/doc/RegConfig.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: RegConfig.3,v 1.6 2004/10/07 15:15:47 dkf Exp $ +'\" RCS: @(#) $Id: RegConfig.3,v 1.7 2007/10/28 14:17:39 dkf Exp $ .so man.macros .TH Tcl_RegisterConfig 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -72,9 +72,9 @@ NULL. The function makes \fBno\fR copy of the \fIconfiguration\fR array. This means that the caller has to make sure that the memory holding this array is never released. This is the meaning behind the word \fBnon-volatile\fR used earlier. The easiest way to accomplish -this is to define a global static array of Tcl_Config entries. See the -file "generic/tclPkgConfig.c" in the sources of the Tcl core for an -example. +this is to define a global static array of Tcl_Config entries. See the file +.QW generic/tclPkgConfig.c +in the sources of the Tcl core for an example. .PP When called \fBTcl_RegisterConfig\fR will .IP (1) @@ -97,20 +97,17 @@ Returns a list containing the names of all defined keys. Returns the configuration value associated with the specified \fIkey\fR. .RE - .SH TCL_CONFIG - +.PP The \fBTcl_Config\fR structure contains the following fields: .PP .CS typedef struct Tcl_Config { - const char* key; - const char* value; + const char* key; + const char* value; } Tcl_Config; .CE - -'\" No cross references yet. -'\" .SH "SEE ALSO" - +.\" No cross references yet. +.\" .SH "SEE ALSO" .SH KEYWORDS embedding, configuration, bianry library diff --git a/doc/RegExp.3 b/doc/RegExp.3 index 3270bcd..e27459e 100644 --- a/doc/RegExp.3 +++ b/doc/RegExp.3 @@ -6,7 +6,7 @@ '\" 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.25 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: RegExp.3,v 1.26 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures" @@ -63,8 +63,9 @@ by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR. .AP char *start in If \fItext\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 \fItext\fR, then no \fB^\fR matches -will be allowed. +If it is not the same as \fItext\fR, then no +.QW \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 @@ -139,7 +140,9 @@ For example, when searching for the second occurrence of a match, the \fItext\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. +so that it does not allow +.QW \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 \fItext\fR. \fIStart\fR will be less than or equal to \fItext\fR; if it @@ -186,17 +189,23 @@ zero or more of the following flags that control the compilation of .RS 2 .TP \fBTCL_REG_ADVANCED\fR -Compile advanced regular expressions (`AREs'). This mode corresponds to +Compile advanced regular expressions +.PQ ARE s . +This mode corresponds to the normal regular expression syntax accepted by the Tcl \fBregexp\fR and \fBregsub\fR commands. .TP \fBTCL_REG_EXTENDED\fR -Compile extended regular expressions (`EREs'). This mode corresponds +Compile extended regular expressions +.PQ ERE s . +This mode corresponds to the regular expression syntax recognized by Tcl 8.0 and earlier versions. .TP \fBTCL_REG_BASIC\fR -Compile basic regular expressions (`BREs'). This mode corresponds +Compile basic regular expressions +.PQ BRE s . +This mode corresponds to the regular expression syntax recognized by common Unix utilities like \fBsed\fR and \fBgrep\fR. This is the default if no flags are specified. @@ -216,9 +225,16 @@ Compile for matching that ignores upper/lower case distinctions. \fBTCL_REG_NEWLINE\fR Compile for newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning in either -regular expressions or strings. With this flag, `[^' bracket -expressions and `.' never match newline, `^' matches an empty string -after any newline in addition to its normal function, and `$' matches +regular expressions or strings. With this flag, +.QW [^ +bracket expressions and +.QW . +never match newline, +.QW ^ +matches an empty string +after any newline in addition to its normal function, and +.QW $ +matches an empty string before any newline in addition to its normal function. \fBREG_NEWLINE\fR is the bit-wise OR of \fBREG_NLSTOP\fR and \fBREG_NLANCH\fR. @@ -226,16 +242,37 @@ an empty string before any newline in addition to its normal function. \fBTCL_REG_NLSTOP\fR Compile for partial newline-sensitive matching, with the behavior of -`[^' bracket expressions and `.' affected, -but not the behavior of `^' and `$'. In this mode, `[^' bracket -expressions and `.' never match newline. +.QW [^ +bracket expressions and +.QW . +affected, but not the behavior of +.QW ^ +and +.QW $ . +In this mode, +.QW [^ +bracket expressions and +.QW . +never match newline. .TP \fBTCL_REG_NLANCH\fR Compile for inverse partial newline-sensitive matching, -with the behavior -of `^' and `$' (the ``anchors'') affected, but not the behavior of -`[^' bracket expressions and `.'. In this mode `^' matches an empty string -after any newline in addition to its normal function, and `$' matches +with the behavior of +.QW ^ +and +.QW $ +(the +.QW anchors ) +affected, but not the behavior of +.QW [^ +bracket expressions and +.QW . . +In this mode +.QW ^ +matches an empty string +after any newline in addition to its normal function, and +.QW $ +matches an empty string before any newline in addition to its normal function. .TP \fBTCL_REG_NOSUB\fR @@ -275,13 +312,21 @@ zero or more of the following flags: .TP \fBTCL_REG_NOTBOL\fR The starting character will not be treated as the beginning of a -line or the beginning of the string, so `^' will not match there. -Note that this flag has no effect on how `\fB\eA\fR' matches. +line or the beginning of the string, so +.QW ^ +will not match there. +Note that this flag has no effect on how +.QW \fB\eA\fR +matches. .TP \fBTCL_REG_NOTEOL\fR The last character in the string will not be treated as the end of a -line or the end of the string, so '$' will not match there. -Note that this flag has no effect on how `\fB\eZ\fR' matches. +line or the end of the string, so +.QW $ +will not match there. +Note that this flag has no effect on how +.QW \fB\eZ\fR +matches. .RE .PP \fBTcl_RegExpGetInfo\fR retrieves information about the last match diff --git a/doc/SetErrno.3 b/doc/SetErrno.3 index 133353e..df0bf93 100644 --- a/doc/SetErrno.3 +++ b/doc/SetErrno.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SetErrno.3,v 1.7 2004/10/07 15:15:48 dkf Exp $ +'\" RCS: @(#) $Id: SetErrno.3,v 1.8 2007/10/28 14:17:39 dkf Exp $ .so man.macros .TH Tcl_SetErrno 3 8.3 Tcl "Tcl Library Procedures" .BS @@ -53,9 +53,11 @@ instead of accessing \fBerrno\fR directly. \fBTcl_ErrnoId\fR and \fBTcl_ErrnoMsg\fR return string representations of \fBerrno\fR values. \fBTcl_ErrnoId\fR returns a machine-readable textual identifier such as -"EACCES" that corresponds to the current value of \fBerrno\fR. +.QW EACCES +that corresponds to the current value of \fBerrno\fR. \fBTcl_ErrnoMsg\fR returns a human-readable string such as -"permission denied" that corresponds to the value of its +.QW "permission denied" +that corresponds to the value of its \fIerrorCode\fR argument. The \fIerrorCode\fR argument is typically the value returned by \fBTcl_GetErrno\fR. The strings returned by these functions are diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 9dceecc..7176ba1 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SetResult.3,v 1.16 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: SetResult.3,v 1.17 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures" @@ -55,7 +55,6 @@ Address of procedure to call to release storage at An argument list which must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. .BE - .SH DESCRIPTION .PP The procedures described here are utilities for manipulating the @@ -140,7 +139,6 @@ 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. - .SH "OLD STRING PROCEDURES" .PP Use of the following procedures (is deprecated @@ -163,17 +161,19 @@ 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. +single character +.QW { , +or ends in the characters +.QW " {" ) +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 +It also sets \fIinterp->freeProc\fR to zero, but does not 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 @@ -184,7 +184,6 @@ 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 @@ -209,7 +208,7 @@ 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, +If \fIfreeProc\fR is not 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. @@ -221,9 +220,7 @@ typedef void Tcl_FreeProc(char *\fIblockPtr\fR); .CE When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to the value of \fIresult\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 index 025d810..7f4b7c2 100644 --- a/doc/SetVar.3 +++ b/doc/SetVar.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SetVar.3,v 1.14 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: SetVar.3,v 1.15 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures" @@ -119,7 +119,7 @@ returned as a pointer to a Tcl_Obj. For \fBTcl_GetVar\fR and usually less efficient, so \fBTcl_GetVar2Ex\fR or \fBTcl_ObjGetVar2\fR are preferred. If an error occurs while reading the variable (e.g. the variable -doesn't exist or an array element is specified for a scalar +does not 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. @@ -130,7 +130,7 @@ 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 \fBTCL_OK\fR is returned. -If the variable cannot be removed because it doesn't exist then +If the variable cannot be removed because it does not exist then \fBTCL_ERROR\fR 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. @@ -150,7 +150,7 @@ 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 +If \fIvarName\fR does not 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 @@ -192,7 +192,7 @@ 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 +If this flag bit is not set then no error message is left and the interpreter's result will not be modified. .TP \fBTCL_APPEND_VALUE\fR @@ -207,7 +207,10 @@ 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 `` }''). +the single character +.QW { , +or ends in +.QW " }" ). When appending, the original value of the variable must also be a valid list, so that the operation is the appending of a new list element onto a list. @@ -225,7 +228,7 @@ and \fBTCL_LEAVE_ERR_MSG\fR, 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 +does not 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 @@ -234,7 +237,7 @@ 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 \fBTCL_OK\fR is returned. -If the variable cannot be removed because it doesn't exist then +If the variable cannot be removed because it does not exist then \fBTCL_ERROR\fR is returned. If an array element is specified, the given element is removed but the array remains. diff --git a/doc/Signal.3 b/doc/Signal.3 index a28a680..eec983e 100644 --- a/doc/Signal.3 +++ b/doc/Signal.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Signal.3,v 1.4 2004/10/07 15:15:48 dkf Exp $ +'\" RCS: @(#) $Id: Signal.3,v 1.5 2007/10/28 14:17:39 dkf Exp $ .so man.macros .TH Tcl_SignalId 3 8.3 Tcl "Tcl Library Procedures" .BS @@ -31,8 +31,11 @@ A POSIX signal number such as \fBSIGPIPE\fR. \fBTcl_SignalId\fR and \fBTcl_SignalMsg\fR return a string representation of the provided signal number (\fIsig\fR). \fBTcl_SignalId\fR returns a machine-readable textual identifier such -as "SIGPIPE". \fBTcl_SignalMsg\fR returns a human-readable string such -as "bus error". The strings returned by these functions are +as +.QW SIGPIPE . +\fBTcl_SignalMsg\fR returns a human-readable string such as +.QW "bus error" . +The strings returned by these functions are statically allocated and the caller must not free or modify them. .SH KEYWORDS diff --git a/doc/Sleep.3 b/doc/Sleep.3 index a76d671..ab650be 100644 --- a/doc/Sleep.3 +++ b/doc/Sleep.3 @@ -1,38 +1,36 @@ -'\" -'\" 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.3 2004/10/07 14:44:34 dkf 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 -.AS int ms -.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 +'\"
+'\" 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.4 2007/10/28 14:17:39 dkf 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
+.AS int ms
+.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 need not 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 index 798989a..d72b59e 100644 --- a/doc/SplitList.3 +++ b/doc/SplitList.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SplitList.3,v 1.11 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: SplitList.3,v 1.12 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures" @@ -153,7 +153,7 @@ include spaces between adjacent list elements. \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, +This produces clean-looking output, but cannot 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. @@ -169,7 +169,9 @@ the command not to be parsed correctly. .VS 8.5 By default, \fBTcl_ConvertElement\fR will use quoting in its output to be sure the first character of an element is not the hash -character (``#''). This is to be sure the first element of any list +character +.PQ # . +This is to be sure the first element of any list passed to \fBeval\fR is not mis-parsed as the beginning of a comment. When a list element is not the first element of a list, this quoting is not necessary. When the caller can be sure that the element is diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 index 0947202..49d9f52 100644 --- a/doc/StaticPkg.3 +++ b/doc/StaticPkg.3 @@ -1,69 +1,69 @@ -'\" -'\" 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.6 2004/10/07 15:15:48 dkf 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 `load' 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 "const 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 the interpreter's result 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 +'\"
+'\" 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.7 2007/10/28 14:17:39 dkf 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 'load' 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
+has not yet been incorporated into any interpreter.
+.AP "const 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
+cannot 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 the interpreter's result 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/StdChannels.3 b/doc/StdChannels.3 index 5483ef1..5fdf160 100644 --- a/doc/StdChannels.3 +++ b/doc/StdChannels.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StdChannels.3,v 1.12 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: StdChannels.3,v 1.13 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH "Standard Channels" 3 7.5 Tcl "Tcl Library Procedures" @@ -42,7 +42,9 @@ channel information, or when implicitly required during registration of a new channel. .PP These cases differ in how they handle unavailable platform- specific -standard channels. (A channel is not ``available'' if it could not be +standard channels. (A channel is not +.QW available +if it could not be successfully opened; for example, in a Tcl application run as a Windows NT service.) .TP diff --git a/doc/StrMatch.3 b/doc/StrMatch.3 index c9e7a16..2372c46 100644 --- a/doc/StrMatch.3 +++ b/doc/StrMatch.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StrMatch.3,v 1.11 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: StrMatch.3,v 1.12 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_StringMatch 3 8.1 Tcl "Tcl Library Procedures" @@ -38,7 +38,7 @@ case-insensitive (1). 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'' +used for matching is the same algorithm used in the \fBstring match\fR Tcl command and is similar to the algorithm used by the C-shell for file name matching; see the Tcl manual entry for details. .PP diff --git a/doc/StringObj.3 b/doc/StringObj.3 index f326315..78b801e 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -1,272 +1,272 @@ -'\" -'\" 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.20 2005/09/13 21:23:51 dgp Exp $ -'\" -.so man.macros -.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Obj * -\fBTcl_NewStringObj\fR(\fIbytes, length\fR) -.sp -Tcl_Obj * -\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR) -.sp -void -\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR) -.sp -void -\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR) -.sp -char * -\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR) -.sp -char * -\fBTcl_GetString\fR(\fIobjPtr\fR) -.sp -Tcl_UniChar * -\fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR) -.sp -Tcl_UniChar * -\fBTcl_GetUnicode\fR(\fIobjPtr\fR) -.sp -Tcl_UniChar -\fBTcl_GetUniChar\fR(\fIobjPtr, index\fR) -.sp -int -\fBTcl_GetCharLength\fR(\fIobjPtr\fR) -.sp -Tcl_Obj * -\fBTcl_GetRange\fR(\fIobjPtr, first, last\fR) -.sp -void -\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR) -.sp -void -\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR) -.sp -void -\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR) -.sp -void -\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR) -.sp -void -\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) -.sp -void -\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) -.sp -int -\fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR) -.sp -Tcl_Obj * -\fBTcl_ConcatObj\fR(\fIobjc, objv\fR) -.SH ARGUMENTS -.AS "const Tcl_UniChar" *appendObjPtr in/out -.AP "const char" *bytes in -Points to the first byte of an array of UTF-8-encoded bytes -used to set or append to a string object. -This byte array may contain embedded null characters -unless \fInumChars\fR is negative. (Applications needing null bytes -should represent them as the two-byte sequence \fI\\700\\600\fR, use -\fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if -the string is a collection of uninterpreted bytes.) -.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 "const Tcl_UniChar" *unicode in -Points to the first byte of an array of Unicode characters -used to set or append to a string object. -This byte array may contain embedded null characters -unless \fInumChars\fR is negative. -.AP int numChars in -The number of Unicode characters to copy from \fIunicode\fR when -initializing, setting, or appending to a string object. -If negative, all characters up to the first null character are used. -.AP int index in -The index of the Unicode character to return. -.AP int first in -The index of the first Unicode character in the Unicode range to be -returned as a new object. -.AP int last in -The index of the last Unicode character in the Unicode range to be -returned as a new object. -.AP Tcl_Obj *objPtr in/out -Points to an object to manipulate. -.AP Tcl_Obj *appendObjPtr in -The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. -.AP int *lengthPtr out -If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store -the length of an object's string representation. -.AP "const 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 -\fBva_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. -Also, indexing and length computations are optimized because the -Unicode string representation is calculated and cached as needed. -When using the \fBTcl_Append*\fR family of functions where the -interpreter's result is the object being appended to, it is important -to call Tcl_ResetResult first to ensure you are not unintentionally -appending to existing data in the result object. -.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_NewUnicodeObj\fR and -\fBTcl_SetUnicodeObj\fR create a new object or modify an existing -object to hold a copy of the Unicode string given by \fIunicode\fR and -\fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR -return a pointer to a newly created object with reference count zero. -All four procedures set the object to hold a copy of the specified -string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free 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 UTF 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. It is passed back as a writable -pointer so that extension author creating their own \fBTcl_ObjType\fR -will be able to modify the string representation within the -\fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that -limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR -or \fBTcl_GetString\fR should be treated as read-only. It is -recommended that this pointer be assigned to a (const char *) variable. -Even in the limited situations where writing to this pointer is -acceptable, one should take care to respect the copy-on-write -semantics required by \fBTcl_Obj\fR's, with appropriate calls -to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any -in-place modification of the string representation. -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_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's -value as a Unicode string. This is given by the returned pointer and -(for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in -\fIlengthPtr\fR if it is non-NULL. 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_GetUnicode\fR is used in the common case -where the caller does not need the length of the unicode string -representation. -.PP -\fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the -object's Unicode representation. -.PP -\fBTcl_GetRange\fR returns a newly created object comprised of the -characters between \fIfirst\fR and \fIlast\fR (inclusive) in the -object's Unicode representation. If the object's Unicode -representation is invalid, the Unicode representation is regenerated -from the object's string representation. -.PP -\fBTcl_GetCharLength\fR returns the number of characters (as opposed -to bytes) in the string object. -.PP -\fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and -\fIlength\fR to the string representation of the object specified by -\fIobjPtr\fR. If the object has an invalid string representation, -then an attempt is made to convert \fIbytes\fR is to the Unicode -format. If the conversion is successful, then the converted form of -\fIbytes\fR is appended to the object's Unicode representation. -Otherwise, the object's Unicode representation is invalidated and -converted to the UTF format, and \fIbytes\fR is appended to the -object's new string representation. -.PP -\fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by -\fIunicode\fR and \fInumChars\fR to the object specified by -\fIobjPtr\fR. If the object has an invalid Unicode representation, -then \fIunicode\fR is converted to the UTF format and appended to the -object's string representation. Appends are optimized to handle -repeated appends relatively efficiently (it overallocates the string -or Unicode space to avoid repeated reallocations and copies of -object's string value). -.PP -\fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it -appends the string or Unicode value (whichever exists and is best -suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to -\fIobjPtr\fR. -.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 -\fBTcl_AttemptSetObjLength\fR is identical in function to -\fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the -request cannot be allocated, it does not cause the Tcl interpreter to -\fBpanic\fR. Thus, if \fInewLength\fR is greater than the space -allocated for the object's string, and there is not enough memory -available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take -no action and return 0 to indicate failure. If there is enough memory -to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like -\fBTcl_SetObjLength\fR and returns 1 to indicate success. -.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, unicode +'\"
+'\" 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.21 2007/10/28 14:17:39 dkf Exp $
+'\"
+.so man.macros
+.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewStringObj\fR(\fIbytes, length\fR)
+.sp
+Tcl_Obj *
+\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)
+.sp
+void
+\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
+.sp
+void
+\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)
+.sp
+char *
+\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
+.sp
+char *
+\fBTcl_GetString\fR(\fIobjPtr\fR)
+.sp
+Tcl_UniChar *
+\fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR)
+.sp
+Tcl_UniChar *
+\fBTcl_GetUnicode\fR(\fIobjPtr\fR)
+.sp
+Tcl_UniChar
+\fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
+.sp
+int
+\fBTcl_GetCharLength\fR(\fIobjPtr\fR)
+.sp
+Tcl_Obj *
+\fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
+.sp
+void
+\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
+.sp
+void
+\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
+.sp
+void
+\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
+.sp
+void
+\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
+.sp
+void
+\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
+.sp
+void
+\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
+.sp
+int
+\fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
+.SH ARGUMENTS
+.AS "const Tcl_UniChar" *appendObjPtr in/out
+.AP "const char" *bytes in
+Points to the first byte of an array of UTF-8-encoded bytes
+used to set or append to a string object.
+This byte array may contain embedded null characters
+unless \fInumChars\fR is negative. (Applications needing null bytes
+should represent them as the two-byte sequence \fI\e700\e600\fR, use
+\fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
+the string is a collection of uninterpreted bytes.)
+.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 "const Tcl_UniChar" *unicode in
+Points to the first byte of an array of Unicode characters
+used to set or append to a string object.
+This byte array may contain embedded null characters
+unless \fInumChars\fR is negative.
+.AP int numChars in
+The number of Unicode characters to copy from \fIunicode\fR when
+initializing, setting, or appending to a string object.
+If negative, all characters up to the first null character are used.
+.AP int index in
+The index of the Unicode character to return.
+.AP int first in
+The index of the first Unicode character in the Unicode range to be
+returned as a new object.
+.AP int last in
+The index of the last Unicode character in the Unicode range to be
+returned as a new object.
+.AP Tcl_Obj *objPtr in/out
+Points to an object to manipulate.
+.AP Tcl_Obj *appendObjPtr in
+The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
+.AP int *lengthPtr out
+If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
+the length of an object's string representation.
+.AP "const 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
+\fBva_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 does not have to be copied for each append.
+Also, indexing and length computations are optimized because the
+Unicode string representation is calculated and cached as needed.
+When using the \fBTcl_Append*\fR family of functions where the
+interpreter's result is the object being appended to, it is important
+to call Tcl_ResetResult first to ensure you are not unintentionally
+appending to existing data in the result object.
+.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_NewUnicodeObj\fR and
+\fBTcl_SetUnicodeObj\fR create a new object or modify an existing
+object to hold a copy of the Unicode string given by \fIunicode\fR and
+\fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR
+return a pointer to a newly created object with reference count zero.
+All four procedures set the object to hold a copy of the specified
+string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free 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 UTF 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. It is passed back as a writable
+pointer so that extension author creating their own \fBTcl_ObjType\fR
+will be able to modify the string representation within the
+\fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that
+limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR
+or \fBTcl_GetString\fR should be treated as read-only. It is
+recommended that this pointer be assigned to a (const char *) variable.
+Even in the limited situations where writing to this pointer is
+acceptable, one should take care to respect the copy-on-write
+semantics required by \fBTcl_Obj\fR's, with appropriate calls
+to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any
+in-place modification of the string representation.
+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_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's
+value as a Unicode string. This is given by the returned pointer and
+(for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in
+\fIlengthPtr\fR if it is non-NULL. 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_GetUnicode\fR is used in the common case
+where the caller does not need the length of the unicode string
+representation.
+.PP
+\fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
+object's Unicode representation.
+.PP
+\fBTcl_GetRange\fR returns a newly created object comprised of the
+characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
+object's Unicode representation. If the object's Unicode
+representation is invalid, the Unicode representation is regenerated
+from the object's string representation.
+.PP
+\fBTcl_GetCharLength\fR returns the number of characters (as opposed
+to bytes) in the string object.
+.PP
+\fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
+\fIlength\fR to the string representation of the object specified by
+\fIobjPtr\fR. If the object has an invalid string representation,
+then an attempt is made to convert \fIbytes\fR is to the Unicode
+format. If the conversion is successful, then the converted form of
+\fIbytes\fR is appended to the object's Unicode representation.
+Otherwise, the object's Unicode representation is invalidated and
+converted to the UTF format, and \fIbytes\fR is appended to the
+object's new string representation.
+.PP
+\fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by
+\fIunicode\fR and \fInumChars\fR to the object specified by
+\fIobjPtr\fR. If the object has an invalid Unicode representation,
+then \fIunicode\fR is converted to the UTF format and appended to the
+object's string representation. Appends are optimized to handle
+repeated appends relatively efficiently (it overallocates the string
+or Unicode space to avoid repeated reallocations and copies of
+object's string value).
+.PP
+\fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it
+appends the string or Unicode value (whichever exists and is best
+suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to
+\fIobjPtr\fR.
+.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
+\fBTcl_AttemptSetObjLength\fR is identical in function to
+\fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the
+request cannot be allocated, it does not cause the Tcl interpreter to
+\fBpanic\fR. Thus, if \fInewLength\fR is greater than the space
+allocated for the object's string, and there is not enough memory
+available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take
+no action and return 0 to indicate failure. If there is enough memory
+to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like
+\fBTcl_SetObjLength\fR and returns 1 to indicate success.
+.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, unicode
diff --git a/doc/SubstObj.3 b/doc/SubstObj.3 index 368519e..3bb007e 100644 --- a/doc/SubstObj.3 +++ b/doc/SubstObj.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SubstObj.3,v 1.5 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: SubstObj.3,v 1.6 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_SubstObj 3 8.4 Tcl "Tcl Library Procedures" @@ -32,7 +32,6 @@ perform. The flags \fBTCL_SUBST_COMMANDS\fR, currently supported, and \fBTCL_SUBST_ALL\fR is provided as a convenience for the common case where all substitutions are desired. .BE - .SH DESCRIPTION .PP The \fBTcl_SubstObj\fR function is used to perform substitutions on @@ -55,17 +54,17 @@ replaced by the contents of the named variable. .PP When the \fBTCL_SUBST_COMMANDS\fR bit is set in \fIflags\fR, sequences that look like command substitutions for Tcl commands are replaced by -the result of evaluating that script. Where an uncaught `continue -exception' occurs during the evaluation of a command substitution, an -empty string is substituted for the command. Where an uncaught `break -exception' occurs during the evaluation of a command substitution, the +the result of evaluating that script. Where an uncaught +.QW "continue exception" +occurs during the evaluation of a command substitution, an +empty string is substituted for the command. Where an uncaught +.QW "break exception" +occurs during the evaluation of a command substitution, the result of the whole substitution on \fIobjPtr\fR will be truncated at the point immediately before the start of the command substitution, and no characters will be added to the result or substitutions performed after that point. - .SH "SEE ALSO" subst(n) - .SH KEYWORDS backslash substitution, command substitution, variable substitution diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3 index a0b87c2..d76cd91 100644 --- a/doc/TCL_MEM_DEBUG.3 +++ b/doc/TCL_MEM_DEBUG.3 @@ -3,7 +3,7 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.9 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.10 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures" @@ -11,14 +11,12 @@ .SH NAME TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging .BE - .SH DESCRIPTION When Tcl is compiled with \fBTCL_MEM_DEBUG\fR defined, a powerful set of memory debugging aids is included in the compiled binary. This includes C and Tcl functions which can aid with debugging memory leaks, memory allocation overruns, and other memory related errors. - .SH "ENABLING MEMORY DEBUGGING" .PP To enable memory debugging, Tcl should be recompiled from scratch with @@ -36,28 +34,31 @@ Once memory debugging support has been compiled into Tcl, the C functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR, and the Tcl \fBmemory\fR command can be used to validate and examine memory usage. - .SH "GUARD ZONES" .PP When memory debugging is enabled, whenever a call to \fBckalloc\fR is -made, slightly more memory than requested is allocated so the memory debugging -code can keep track of the allocated memory, and eight-byte ``guard -zones'' are placed in front of and behind the space that will be +made, slightly more memory than requested is allocated so the memory +debugging code can keep track of the allocated memory, and eight-byte +.QW "guard zones" +are placed in front of and behind the space that will be returned to the caller. (The sizes of the guard zones are defined by the C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR -in the file \fIgeneric/tclCkalloc.c\fR -- it can +in the file \fIgeneric/tclCkalloc.c\fR \(em it can be extended if you suspect large overwrite problems, at some cost in performance.) A known pattern is written into the guard zones and, on a call to \fBckfree\fR, the guard zones of the space being freed are checked to see if either zone has been modified in any way. If one has been, the guard bytes and their new contents are identified, and a -``low guard failed'' or ``high guard failed'' message is issued. The -``guard failed'' message includes the address of the memory packet and +.QW "low guard failed" +or +.QW "high guard failed" +message is issued. The +.QW "guard failed" +message includes the address of the memory packet and the file name and line number of the code that called \fBckfree\fR. This allows you to detect the common sorts of one-off problems, where not enough space was allocated to contain the data written, for example. - .SH "DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS" .PP Normally, Tcl compiled with memory debugging enabled will make it easy @@ -70,16 +71,12 @@ This will enable memory validation from the first call to \fBckalloc\fR, again, at a large performance impact. .PP If you are desperate and validating memory on every call to -\fBckalloc\fR and \fBckfree\fR isn't enough, you can explicitly call +\fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call \fBTcl_ValidateAllMemory\fR directly at any point. It takes a \fIchar *\fR and an \fIint\fR which are normally the filename and line number of the caller, but they can actually be anything you want. Remember to remove the calls after you find the problem. - .SH "SEE ALSO" ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory - .SH KEYWORDS memory, debug - - @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Tcl.n,v 1.16 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: Tcl.n,v 1.17 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl n "8.5" Tcl "Tcl Built-In Commands" @@ -41,8 +41,9 @@ Different commands interpret their words differently. Words of a command are separated by white space (except for newlines, which are command separators). .IP "[4] \fBDouble quotes.\fR" -If the first character of a word is double-quote (``"'') then -the word is terminated by the next double-quote character. +If the first character of a word is double-quote +.PQ \N'34' +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. @@ -51,18 +52,25 @@ are performed on the characters between the quotes as described below. The double-quotes are not retained as part of the word. .VS 8.5 br .IP "[5] \fBArgument expansion.\fR" -If a word starts with the string ``{*}'' followed by a -non-whitespace character, then the leading ``{*}'' is removed -and the rest of the word is parsed and substituted as any other +If a word starts with the string +.QW {*} +followed by a non-whitespace character, then the leading +.QW {*} +is removed +and the rest of the word is parsed and substituted as any other word. After substitution, the word is parsed again without substitutions, and its words are added to the command being -substituted. For instance, ``cmd a {*}{b c} d {*}{e f}'' is -equivalent to ``cmd a b c d e f''. +substituted. For instance, +.QW "cmd a {*}{b c} d {*}{e f}" +is equivalent to +.QW "cmd a b c d e f" . .VE 8.5 .IP "[6] \fBBraces.\fR" -If the first character of a word is an open brace (``{'') and -rule [5] does not apply, then -the word is terminated by the matching close brace (``}''). +If the first character of a word is an open brace +.PQ { +and rule [5] does not apply, then +the word is terminated by the matching close brace +.PQ } "" . 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 @@ -75,19 +83,23 @@ 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 "[7] \fBCommand substitution.\fR" -If a word contains an open bracket (``['') then Tcl performs -\fIcommand substitution\fR. +If a word contains an open bracket +.PQ [ +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 (``]''). +by a close bracket +.PQ ] "" . 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 "[8] \fBVariable substitution.\fR" -If a word contains a dollar-sign (``$'') followed by one of the forms +If a word contains a dollar-sign +.PQ $ +followed by one of the forms described below, then Tcl performs \fIvariable substitution\fR: the dollar-sign and the following characters are replaced in the word by the value of a variable. @@ -115,8 +127,9 @@ There may be any number of variable substitutions in a single word. Variable substitution is not performed on words enclosed in braces. .RE .IP "[9] \fBBackslash substitution.\fR" -If a backslash (``\e'') appears within a word then -\fIbackslash substitution\fR occurs. +If a backslash +.PQ \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. @@ -154,11 +167,12 @@ 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 +and the resulting space will be treated as a word separator if it is not in braces or quotes. .TP 7 \e\e -Backslash (``\e''). +Backslash +.PQ \e "" . .TP 7 \e\fIooo\fR . @@ -184,7 +198,9 @@ Backslash substitution is not performed on words enclosed in braces, except for backslash-newline as described above. .RE .IP "[10] \fBComments.\fR" -If a hash character (``#'') appears at a point where Tcl is +If a hash character +.PQ # +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. diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index d9f0e98..cc8ffe3 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.3 @@ -6,7 +6,7 @@ '\" 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.13 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: Tcl_Main.3,v 1.14 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures" @@ -36,7 +36,9 @@ Address of an application-specific event loop procedure. .SH DESCRIPTION .PP \fBTcl_Main\fR can serve as the main program for Tcl-based shell -applications. A ``shell application'' is a program +applications. A +.QW "shell application" +is a program like tclsh or wish that supports both interactive interpretation of Tcl and evaluation of a script contained in a file given as a command line argument. \fBTcl_Main\fR is offered as a convenience @@ -91,8 +93,9 @@ the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and .PP When it 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 of the interpreter +\fIappInitProc\fR argument. This procedure provides a +.QW hook +for the application to perform its own initialization of the interpreter created by \fBTcl_Main\fR, such as defining application-specific commands. The procedure must have an interface that matches the type \fBTcl_AppInitProc\fR: diff --git a/doc/Thread.3 b/doc/Thread.3 index 7a236b8..6ed54b0 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -1,197 +1,197 @@ -'\" -'\" Copyright (c) 1999 Scriptics Corporation -'\" 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.24 2005/05/10 18:33:57 kennykb Exp $ -'\" -.so man.macros -.TH Threads 3 "8.1" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread 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_ConditionFinalize\fR(\fIcondPtr\fR) -.sp -Void * -\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR) -.sp -void -\fBTcl_MutexLock\fR(\fImutexPtr\fR) -.sp -void -\fBTcl_MutexUnlock\fR(\fImutexPtr\fR) -.sp -void -\fBTcl_MutexFinalize\fR(\fImutexPtr\fR) -.sp -int -\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR) -.sp -int -\fBTcl_JoinThread\fR(\fIid, result\fR) -.SH ARGUMENTS -.AS Tcl_CreateThreadProc threadProc out -.AP Tcl_Condition *condPtr in -A condition variable, which must be associated with a mutex lock. -.AP Tcl_Mutex *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. -.AP Tcl_ThreadId *idPtr out -The referred storage will contain the id of the newly created thread as -returned by the operating system. -.AP Tcl_ThreadId id in -Id of the thread waited upon. -.AP Tcl_ThreadCreateProc threadProc in -This procedure will act as the \fBmain()\fR of the newly created -thread. The specified \fIclientData\fR will be its sole argument. -.AP ClientData clientData in -Arbitrary information. Passed as sole argument to the \fIthreadProc\fR. -.AP int stackSize in -The size of the stack given to the new thread. -.AP int flags in -Bitmask containing flags allowing the caller to modify behaviour of -the new thread. -.AP int *result out -The referred storage is used to place the exit code of the thread -waited upon into it. -.BE -.SH INTRODUCTION -Beginning with the 8.1 release, the Tcl core is thread safe, which -allows you to incorporate Tcl into multithreaded applications without -customizing the Tcl core. To enable Tcl multithreading support, -you must include the \fB--enable-threads\fR option to \fBconfigure\fR -when you configure and compile your Tcl core. -.PP -An important constraint of the Tcl threads implementation is that -\fIonly the thread that created a Tcl interpreter can use that -interpreter\fR. In other words, multiple threads can not access -the same Tcl interpreter. (However, a single thread can safely create -and use multiple interpreters.) -.SH DESCRIPTION -Tcl provides \fBTcl_CreateThread\fR for creating threads. The -caller can determine the size of the stack given to the new thread and -modify the behaviour through the supplied \fIflags\fR. The value -\fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that -the default size as specified by the operating system is to be used -for the new thread. As for the flags, currently only the values -\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The -first of them invokes the default behaviour with no -specialties. Using the second value marks the new thread as -\fIjoinable\fR. This means that another thread can wait for the such -marked thread to exit and join it. -.PP -Restrictions: On some UNIX systems the pthread-library does not -contain the functionality to specify the stack size of a thread. The -specified value for the stack size is ignored on these systems. -Windows currently does not support joinable threads. This -flag value is therefore ignored on this platform. -.PP -Tcl provides the \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR functions -for terminating threads and invoking optional per-thread exit -handlers. See the \fBTcl_Exit\fR page for more information on these -procedures. -.PP -The \fBTcl_JoinThread\fR function is provided to allow threads to wait -upon the exit of another thread, which must have been marked as -joinable through usage of the \fBTCL_THREAD_JOINABLE\fR-flag during -its creation via \fBTcl_CreateThread\fR. -.PP -Trying to wait for the exit of a non-joinable thread or a thread which -is already waited upon will result in an error. Waiting for a joinable -thread which already exited is possible, the system will retain the -necessary information until after the call to \fBTcl_JoinThread\fR. -This means that not calling \fBTcl_JoinThread\fR for a joinable thread -will cause a memory leak. -.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. -.SS "SYNCHRONIZATION AND COMMUNICATION" -Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR -for handling event queuing in multithreaded applications. See -the \fBNotifier\fR manual page for more information on these procedures. -.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. -A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR. -The result of locking a mutex twice from the same thread is undefined. -On some platforms it will result in a deadlock. -The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR -procedures are defined as empty macros if not compiling with threads enabled. -For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used. -This macro assures correct mutex handling even when the core is compiled -without 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 -A condition variable can be destroyed after its use by calling -\fBTcl_ConditionFinalize\fR. -.PP -The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and -\fBTcl_ConditionFinalize\fR procedures are defined as empty macros if -not compiling with threads enabled. -.SS INITIALIZATION -.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 -either cleaned up by process exit handlers (if living that long) or -explicitly by calls to \fBTcl_MutexFinalize\fR or -\fBTcl_ConditionFinalize\fR. -Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR. -.SH "SCRIPT-LEVEL ACCESS TO THREADS" -.VS 8.5 -Tcl provides no built-in commands for scripts to use to create, -manage, or join threads, nor any script-level access to mutex or -condition variables. It provides such facilities only via C -interfaces, and leaves it up to packages to expose these matters to -the script level. One such package is the \fBThread\fR package. -.VE 8.5 -.SH "SEE ALSO" -Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3), -Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3), -Tcl_DeleteThreadExitHandler(3), Thread -.SH KEYWORDS -thread, mutex, condition variable, thread local storage +'\"
+'\" Copyright (c) 1999 Scriptics Corporation
+'\" 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.25 2007/10/28 14:17:39 dkf Exp $
+'\"
+.so man.macros
+.TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread 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_ConditionFinalize\fR(\fIcondPtr\fR)
+.sp
+Void *
+\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR)
+.sp
+void
+\fBTcl_MutexLock\fR(\fImutexPtr\fR)
+.sp
+void
+\fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
+.sp
+void
+\fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
+.sp
+int
+\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR)
+.sp
+int
+\fBTcl_JoinThread\fR(\fIid, result\fR)
+.SH ARGUMENTS
+.AS Tcl_CreateThreadProc threadProc out
+.AP Tcl_Condition *condPtr in
+A condition variable, which must be associated with a mutex lock.
+.AP Tcl_Mutex *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 does not 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.
+.AP Tcl_ThreadId *idPtr out
+The referred storage will contain the id of the newly created thread as
+returned by the operating system.
+.AP Tcl_ThreadId id in
+Id of the thread waited upon.
+.AP Tcl_ThreadCreateProc threadProc in
+This procedure will act as the \fBmain()\fR of the newly created
+thread. The specified \fIclientData\fR will be its sole argument.
+.AP ClientData clientData in
+Arbitrary information. Passed as sole argument to the \fIthreadProc\fR.
+.AP int stackSize in
+The size of the stack given to the new thread.
+.AP int flags in
+Bitmask containing flags allowing the caller to modify behaviour of
+the new thread.
+.AP int *result out
+The referred storage is used to place the exit code of the thread
+waited upon into it.
+.BE
+.SH INTRODUCTION
+Beginning with the 8.1 release, the Tcl core is thread safe, which
+allows you to incorporate Tcl into multithreaded applications without
+customizing the Tcl core. To enable Tcl multithreading support,
+you must include the \fB--enable-threads\fR option to \fBconfigure\fR
+when you configure and compile your Tcl core.
+.PP
+An important constraint of the Tcl threads implementation is that
+\fIonly the thread that created a Tcl interpreter can use that
+interpreter\fR. In other words, multiple threads can not access
+the same Tcl interpreter. (However, a single thread can safely create
+and use multiple interpreters.)
+.SH DESCRIPTION
+Tcl provides \fBTcl_CreateThread\fR for creating threads. The
+caller can determine the size of the stack given to the new thread and
+modify the behaviour through the supplied \fIflags\fR. The value
+\fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that
+the default size as specified by the operating system is to be used
+for the new thread. As for the flags, currently only the values
+\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The
+first of them invokes the default behaviour with no
+specialties. Using the second value marks the new thread as
+\fIjoinable\fR. This means that another thread can wait for the such
+marked thread to exit and join it.
+.PP
+Restrictions: On some UNIX systems the pthread-library does not
+contain the functionality to specify the stack size of a thread. The
+specified value for the stack size is ignored on these systems.
+Windows currently does not support joinable threads. This
+flag value is therefore ignored on this platform.
+.PP
+Tcl provides the \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR functions
+for terminating threads and invoking optional per-thread exit
+handlers. See the \fBTcl_Exit\fR page for more information on these
+procedures.
+.PP
+The \fBTcl_JoinThread\fR function is provided to allow threads to wait
+upon the exit of another thread, which must have been marked as
+joinable through usage of the \fBTCL_THREAD_JOINABLE\fR-flag during
+its creation via \fBTcl_CreateThread\fR.
+.PP
+Trying to wait for the exit of a non-joinable thread or a thread which
+is already waited upon will result in an error. Waiting for a joinable
+thread which already exited is possible, the system will retain the
+necessary information until after the call to \fBTcl_JoinThread\fR.
+This means that not calling \fBTcl_JoinThread\fR for a joinable thread
+will cause a memory leak.
+.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.
+.SS "SYNCHRONIZATION AND COMMUNICATION"
+Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR
+for handling event queuing in multithreaded applications. See
+the \fBNotifier\fR manual page for more information on these procedures.
+.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.
+A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
+The result of locking a mutex twice from the same thread is undefined.
+On some platforms it will result in a deadlock.
+The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
+procedures are defined as empty macros if not compiling with threads enabled.
+For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
+This macro assures correct mutex handling even when the core is compiled
+without 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
+A condition variable can be destroyed after its use by calling
+\fBTcl_ConditionFinalize\fR.
+.PP
+The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and
+\fBTcl_ConditionFinalize\fR procedures are defined as empty macros if
+not compiling with threads enabled.
+.SS INITIALIZATION
+.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
+either cleaned up by process exit handlers (if living that long) or
+explicitly by calls to \fBTcl_MutexFinalize\fR or
+\fBTcl_ConditionFinalize\fR.
+Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
+.SH "SCRIPT-LEVEL ACCESS TO THREADS"
+.VS 8.5
+Tcl provides no built-in commands for scripts to use to create,
+manage, or join threads, nor any script-level access to mutex or
+condition variables. It provides such facilities only via C
+interfaces, and leaves it up to packages to expose these matters to
+the script level. One such package is the \fBThread\fR package.
+.VE 8.5
+.SH "SEE ALSO"
+Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3),
+Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3),
+Tcl_DeleteThreadExitHandler(3), Thread
+.SH KEYWORDS
+thread, mutex, condition variable, thread local storage
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index 10714a1..1278269 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.3 @@ -1,171 +1,163 @@ -'\" -'\" Copyright (c) 2002 Donal K. Fellows -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" CVS: @(#) $Id: TraceCmd.3,v 1.8 2004/10/07 15:15:48 dkf Exp $ -'\" -.so man.macros -.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -ClientData -\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR -.sp -int -\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR -.sp -void -\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR -.SH ARGUMENTS -.AS Tcl_CommandTraceProc prevClientData -.AP Tcl_Interp *interp in -Interpreter containing the command. -.AP "const char" *cmdName in -Name of command. -.AP int flags in -OR-ed collection of the values \fBTCL_TRACE_RENAME\fR and -\fBTCL_TRACE_DELETE\fR. -.AP Tcl_CommandTraceProc *proc in -Procedure to call when specified operations occur to \fIcmdName\fR. -.AP ClientData clientData in -Arbitrary argument to pass to \fIproc\fR. -.AP ClientData prevClientData in -If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\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_TraceCommand\fR allows a C procedure to monitor operations -performed on a Tcl command, so that the C procedure is invoked -whenever the command is renamed or deleted. If the trace is created -successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error -occurred (e.g. \fIcmdName\fR specifies a non-existent command) then -\fBTCL_ERROR\fR is returned and an error message is left in the -interpreter's result. -.PP -The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the -trace procedure is to be invoked. It consists of an OR-ed combination -of any of the following values: -.TP -\fBTCL_TRACE_RENAME\fR -Invoke \fIproc\fR whenever the command is renamed. -.TP -\fBTCL_TRACE_DELETE\fR -Invoke \fIproc\fR when the command is deleted. -.PP -Whenever one of the specified operations occurs to the command, -\fIproc\fR will be invoked. It should have arguments and result that -match the type \fBTcl_CommandTraceProc\fR: -.CS -typedef void Tcl_CommandTraceProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - const char *\fIoldName\fR, - const char *\fInewName\fR, - int \fIflags\fR); -.CE -The \fIclientData\fR and \fIinterp\fR parameters will have the same -values as those passed to \fBTcl_TraceCommand\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. -\fIOldName\fR gives the name of the command being renamed, and -\fInewName\fR gives the name that the command is being renamed to (or -an empty string or NULL when the command is being deleted.) -\fIFlags\fR is an OR-ed combination of bits potentially providing -several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and -\fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which -operation is being performed on the command. The bit -\fBTCL_TRACE_DESTROYED\fR 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 -\fBTCL_TRACE_DESTROYED\fR below for more details). Lastly, the bit -\fBTCL_INTERP_DESTROYED\fR 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 \fBTCL_INTERP_DESTROYED\fR -below). -.PP -\fBTcl_UntraceCommand\fR may be used to remove a trace. If the -command specified by \fIinterp\fR, \fIcmdName\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_UntraceCommand\fR has no effect. The same bits are -valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR. -.PP -\fBTcl_CommandTraceInfo\fR may be used to retrieve information about -traces set on a given command. -The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR -associated with a particular trace. -The trace must be on the command specified by the \fIinterp\fR, -\fIcmdName\fR, and \fIflags\fR arguments (note that currently the -flags are ignored; \fIflags\fR should be set to 0 for future -compatibility) 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_CommandTraceInfo\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 command that have the same \fIproc\fR. - -.SH "CALLING COMMANDS DURING TRACES" -.PP -During rename traces, the command being renamed is visible with both -names simultaneously, and the command still exists during delete -traces (if \fBTCL_INTERP_DESTROYED\fR is not set). However, there is no -mechanism for signaling that an error occurred in a trace procedure, -so great care should be taken that errors do not get silently lost. - -.SH "MULTIPLE TRACES" -.PP -It is possible for multiple traces to exist on the same command. -When this happens, all of the trace procedures will be invoked on each -access, in order from most-recently-created to least-recently-created. -Attempts to delete the command during a delete trace will fail -silently, since the command is already scheduled for deletion anyway. -If the command being renamed is renamed by one of its rename traces, -that renaming takes precedence over the one that triggered the trace -and the collection of traces will not be reexecuted; if several traces -rename the command, the last renaming takes precedence. - -.SH "TCL_TRACE_DESTROYED FLAG" -.PP -In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit -is set in \fIflags\fR. - -'\" Perhaps need some more comments here? - DKF - -.SH "TCL_INTERP_DESTROYED" -.PP -When an interpreter is destroyed, unset traces are called for -all of its commands. -The \fBTCL_INTERP_DESTROYED\fR 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 \fBTCL_INTERP_DESTROYED\fR 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 \fBTCL_INTERP_DESTROYED\fR -set. - -.SH KEYWORDS -clientData, trace, command +'\"
+'\" Copyright (c) 2002 Donal K. Fellows
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" CVS: @(#) $Id: TraceCmd.3,v 1.9 2007/10/28 14:17:40 dkf Exp $
+'\"
+.so man.macros
+.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+ClientData
+\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR
+.sp
+int
+\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
+.sp
+void
+\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
+.SH ARGUMENTS
+.AS Tcl_CommandTraceProc prevClientData
+.AP Tcl_Interp *interp in
+Interpreter containing the command.
+.AP "const char" *cmdName in
+Name of command.
+.AP int flags in
+OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
+\fBTCL_TRACE_DELETE\fR.
+.AP Tcl_CommandTraceProc *proc in
+Procedure to call when specified operations occur to \fIcmdName\fR.
+.AP ClientData clientData in
+Arbitrary argument to pass to \fIproc\fR.
+.AP ClientData prevClientData in
+If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\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_TraceCommand\fR allows a C procedure to monitor operations
+performed on a Tcl command, so that the C procedure is invoked
+whenever the command is renamed or deleted. If the trace is created
+successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error
+occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
+\fBTCL_ERROR\fR is returned and an error message is left in the
+interpreter's result.
+.PP
+The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the
+trace procedure is to be invoked. It consists of an OR'ed combination
+of any of the following values:
+.TP
+\fBTCL_TRACE_RENAME\fR
+Invoke \fIproc\fR whenever the command is renamed.
+.TP
+\fBTCL_TRACE_DELETE\fR
+Invoke \fIproc\fR when the command is deleted.
+.PP
+Whenever one of the specified operations occurs to the command,
+\fIproc\fR will be invoked. It should have arguments and result that
+match the type \fBTcl_CommandTraceProc\fR:
+.CS
+typedef void Tcl_CommandTraceProc(
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ const char *\fIoldName\fR,
+ const char *\fInewName\fR,
+ int \fIflags\fR);
+.CE
+The \fIclientData\fR and \fIinterp\fR parameters will have the same
+values as those passed to \fBTcl_TraceCommand\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.
+\fIOldName\fR gives the name of the command being renamed, and
+\fInewName\fR gives the name that the command is being renamed to (or
+an empty string or NULL when the command is being deleted.)
+\fIFlags\fR is an OR'ed combination of bits potentially providing
+several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and
+\fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
+operation is being performed on the command. The bit
+\fBTCL_TRACE_DESTROYED\fR 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
+\fBTCL_TRACE_DESTROYED\fR below for more details). Lastly, the bit
+\fBTCL_INTERP_DESTROYED\fR 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 \fBTCL_INTERP_DESTROYED\fR
+below).
+.PP
+\fBTcl_UntraceCommand\fR may be used to remove a trace. If the
+command specified by \fIinterp\fR, \fIcmdName\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_UntraceCommand\fR has no effect. The same bits are
+valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR.
+.PP
+\fBTcl_CommandTraceInfo\fR may be used to retrieve information about
+traces set on a given command.
+The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR
+associated with a particular trace.
+The trace must be on the command specified by the \fIinterp\fR,
+\fIcmdName\fR, and \fIflags\fR arguments (note that currently the
+flags are ignored; \fIflags\fR should be set to 0 for future
+compatibility) 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 is not NULL, then it should
+be the return value from a previous call to \fBTcl_CommandTraceInfo\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 command that have the same \fIproc\fR.
+.SH "CALLING COMMANDS DURING TRACES"
+.PP
+During rename traces, the command being renamed is visible with both
+names simultaneously, and the command still exists during delete
+traces (if \fBTCL_INTERP_DESTROYED\fR is not set). However, there is no
+mechanism for signaling that an error occurred in a trace procedure,
+so great care should be taken that errors do not get silently lost.
+.SH "MULTIPLE TRACES"
+.PP
+It is possible for multiple traces to exist on the same command.
+When this happens, all of the trace procedures will be invoked on each
+access, in order from most-recently-created to least-recently-created.
+Attempts to delete the command during a delete trace will fail
+silently, since the command is already scheduled for deletion anyway.
+If the command being renamed is renamed by one of its rename traces,
+that renaming takes precedence over the one that triggered the trace
+and the collection of traces will not be reexecuted; if several traces
+rename the command, the last renaming takes precedence.
+.SH "TCL_TRACE_DESTROYED FLAG"
+.PP
+In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
+is set in \fIflags\fR.
+.\" Perhaps need some more comments here? - DKF
+.SH "TCL_INTERP_DESTROYED"
+.PP
+When an interpreter is destroyed, unset traces are called for
+all of its commands.
+The \fBTCL_INTERP_DESTROYED\fR 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 \fBTCL_INTERP_DESTROYED\fR 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 does not do any error checking to prevent trace procedures
+from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
+set.
+.SH KEYWORDS
+clientData, trace, command
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index 1e56ef4..b85453d 100644 --- a/doc/TraceVar.3 +++ b/doc/TraceVar.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: TraceVar.3,v 1.17 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: TraceVar.3,v 1.18 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" @@ -62,7 +62,6 @@ If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or 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 @@ -70,7 +69,7 @@ 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 \fBTCL_OK\fR. If an error occurred (e.g. \fIvarName\fR specifies an element -of an array, but the actual variable isn't an array) then \fBTCL_ERROR\fR +of an array, but the actual variable is not an array) then \fBTCL_ERROR\fR is returned and an error message is left in the interpreter's result. .PP The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the @@ -188,7 +187,7 @@ 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 +If the \fIprevClientData\fR argument is not 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 @@ -196,7 +195,6 @@ matching trace after the one whose \fIclientData\fR matches 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 @@ -213,13 +211,10 @@ 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 -it means that either the variable is +to an array element 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 @@ -245,7 +240,6 @@ 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 @@ -285,7 +279,6 @@ 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 @@ -298,7 +291,6 @@ 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. @@ -310,7 +302,6 @@ 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 @@ -337,7 +328,6 @@ 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 @@ -346,26 +336,24 @@ 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. - +with an error +.PQ "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 \fBTCL_TRACE_DESTROYED\fR 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 \fBTCL_TRACE_DESTROYED\fR isn't set is for +is deleted; the only time \fBTCL_TRACE_DESTROYED\fR is not 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 @@ -378,15 +366,13 @@ 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 +Tcl does not do any error checking to prevent trace procedures from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR set. .PP -Array traces are not yet integrated with the Tcl "info exists" command, +Array traces are not yet integrated with the Tcl \fBinfo exists\fR 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 index 9620c12..4a8c091 100644 --- a/doc/Translate.3 +++ b/doc/Translate.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Translate.3,v 1.11 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: Translate.3,v 1.12 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures" @@ -23,7 +23,8 @@ char * .AP Tcl_Interp *interp in Interpreter in which to report an error, if any. .AP "const char" *name in -File name, which may start with a ``~''. +File name, which may start with a +.QW ~ . .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 @@ -55,7 +56,7 @@ 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 +initializes \fI*bufferPtr\fR even if it does not 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 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Utf.3,v 1.23 2005/05/10 18:33:58 kennykb Exp $ +'\" RCS: @(#) $Id: Utf.3,v 1.24 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH Utf 3 "8.1" Tcl "Tcl Library Procedures" @@ -156,8 +156,9 @@ end of the \fBTcl_DString\fR. \fBTcl_UtfToUniCharDString\fR converts the given UTF-8 string to Unicode, storing the result in the previously initialized \fBTcl_DString\fR. In the argument \fIlength\fR, you may either specify the length of -the given UTF-8 string in bytes or "-1", in which -case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to +the given UTF-8 string in bytes or +.QW \-1 , +in which case \fBTcl_UtfToUniCharDString\fR uses \fBstrlen\fR to calculate the length. The return value is a pointer to the Unicode representation of the UTF-8 string. Storage for the return value is appended to the end of the \fBTcl_DString\fR. The Unicode string diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3 index d2febb4..ff94baa 100644 --- a/doc/WrongNumArgs.3 +++ b/doc/WrongNumArgs.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.10 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.11 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures" @@ -41,7 +41,8 @@ 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'' +\fIobjc\fR is 1, and \fImessage\fR is +.QW "\fBfileName count\fR" then \fIinterp\fR's result object will be set to the following string: .CS diff --git a/doc/apply.n b/doc/apply.n index 91e6bf0..fea6a5f 100644 --- a/doc/apply.n +++ b/doc/apply.n @@ -49,7 +49,7 @@ The semantics of \fBapply\fR can also be described by: proc apply {fun args} { set len [llength $fun] if {($len < 2) || ($len > 3)} { - error "can't interpret \\"$fun\\" as anonymous function" + error "can't interpret \e"$fun\e" as anonymous function" } lassign $fun argList body ns set name ::$ns::[getGloballyUniqueName] @@ -84,7 +84,7 @@ The \fBapply\fR command is also useful for defining callbacks for use in the set vbl "123abc" trace add variable vbl write {\fBapply\fR {{v1 v2 op} { upvar 1 $v1 v - puts "updated variable to \\"$v\\"" + puts "updated variable to \e"$v\e"" }}} set vbl 123 set vbl abc diff --git a/doc/binary.n b/doc/binary.n index 5f79036..df990b4 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: binary.n,v 1.32 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.33 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -68,7 +68,7 @@ the following characters: Stores a byte string of length \fIcount\fR in the output string. Every character is taken as modulo 256 (i.e. the low byte of every character is used, and the high byte discarded) so when storing -character strings not wholly expressible using the characters \\u0000-\\u00ff, +character strings not wholly expressible using the characters \eu0000-\eu00ff, the \fBencoding convertto\fR command should be used first if this truncation is not desired (i.e. if the characters are not part of the ISO 8859-1 character set.) @@ -82,11 +82,11 @@ formatted. For example, .CS \fBbinary format\fR a7a*a alpha bravo charlie .CE -will return a string equivalent to \fBalpha\\000\\000bravoc\fR and +will return a string equivalent to \fBalpha\e000\e000bravoc\fR and .CS -\fBbinary format\fR a* [encoding convertto utf-8 \\u20ac] +\fBbinary format\fR a* [encoding convertto utf-8 \eu20ac] .CE -will return a string equivalent to \fB\\342\\202\\254\fR (which is the +will return a string equivalent to \fB\e342\e202\e254\fR (which is the UTF-8 byte sequence for a Euro-currency character). .RE .IP \fBA\fR 5 @@ -115,7 +115,7 @@ will be zeros. For example, .CS \fBbinary format\fR b5b* 11100 111000011010 .CE -will return a string equivalent to \fB\\x07\\x87\\x05\fR. +will return a string equivalent to \fB\ex07\ex87\ex05\fR. .RE .IP \fBB\fR 5 This form is the same as \fBb\fR except that the bits are stored in @@ -124,7 +124,7 @@ high-to-low order within each byte. For example, .CS \fBbinary format\fR B5B* 11100 111000011010 .CE -will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR. +will return a string equivalent to \fB\exe0\exe1\exa0\fR. .RE .IP \fBh\fR 5 Stores a string of \fIcount\fR hexadecimal digits in low-to-high @@ -143,7 +143,7 @@ remaining bits of the last byte will be zeros. For example, .CS \fBbinary format\fR h3h* AB def .CE -will return a string equivalent to \fB\\xba\\x00\\xed\\x0f\fR. +will return a string equivalent to \fB\exba\ex00\exed\ex0f\fR. .RE .IP \fBH\fR 5 This form is the same as \fBh\fR except that the digits are stored in @@ -152,7 +152,7 @@ high-to-low order within each byte. For example, .CS \fBbinary format\fR H3H* ab DEF .CE -will return a string equivalent to \fB\\xab\\x00\\xde\\xf0\fR. +will return a string equivalent to \fB\exab\ex00\exde\exf0\fR. .RE .IP \fBc\fR 5 Stores one or more 8-bit integer values in the output string. If no @@ -169,7 +169,7 @@ than \fIcount\fR, then the extra elements are ignored. For example, \fBbinary format\fR c3cc* {3 -3 128 1} 260 {2 5} .CE will return a string equivalent to -\fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR, whereas +\fB\ex03\exfd\ex80\ex04\ex02\ex05\fR, whereas .CS \fBbinary format\fR c {2 5} .CE @@ -186,7 +186,7 @@ example, \fBbinary format\fR s3 {3 -3 258 1} .CE will return a string equivalent to -\fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR. +\fB\ex03\ex00\exfd\exff\ex02\ex01\fR. .RE .IP \fBS\fR 5 This form is the same as \fBs\fR except that it stores one or more @@ -197,7 +197,7 @@ example, \fBbinary format\fR S3 {3 -3 258 1} .CE will return a string equivalent to -\fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR. +\fB\ex00\ex03\exff\exfd\ex01\ex02\fR. .RE .IP \fBt\fR 5 .VS 8.5 @@ -218,7 +218,7 @@ example, \fBbinary format\fR i3 {3 -3 65536 1} .CE will return a string equivalent to -\fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR +\fB\ex03\ex00\ex00\ex00\exfd\exff\exff\exff\ex00\ex00\ex01\ex00\fR .RE .IP \fBI\fR 5 This form is the same as \fBi\fR except that it stores one or more one @@ -229,7 +229,7 @@ For example, \fBbinary format\fR I3 {3 -3 65536 1} .CE will return a string equivalent to -\fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR +\fB\ex00\ex00\ex00\ex03\exff\exff\exff\exfd\ex00\ex01\ex00\ex00\fR .RE .IP \fBn\fR 5 .VS 8.5 @@ -289,7 +289,7 @@ on a Windows system running on an Intel Pentium processor, \fBbinary format\fR f2 {1.6 3.4} .CE will return a string equivalent to -\fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR. +\fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR. .RE .IP \fBr\fR 5 .VS 8.5 @@ -314,7 +314,7 @@ Windows system running on an Intel Pentium processor, \fBbinary format\fR d1 {1.6} .CE will return a string equivalent to -\fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR. +\fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR. .RE .IP \fBq\fR 5 .VS 8.5 @@ -338,7 +338,7 @@ example, .CS \fBbinary format\fR a3xa3x2a3 abc def ghi .CE -will return a string equivalent to \fBabc\\000def\\000\\000ghi\fR. +will return a string equivalent to \fBabc\e000def\e000\e000ghi\fR. .RE .IP \fBX\fR 5 Moves the cursor back \fIcount\fR bytes in the output string. If @@ -366,7 +366,7 @@ generated. This type does not consume an argument. For example, .CS \fBbinary format\fR a5@2a1@*a3@10a1 abcde f ghi j .CE -will return \fBabfdeghi\\000\\000j\fR. +will return \fBabfdeghi\e000\e000j\fR. .RE .SH "BINARY SCAN" .PP @@ -451,14 +451,14 @@ 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 byte will be scanned. All bytes scanned will be interpreted as being characters in the -range \\u0000-\\u00ff so the \fBencoding convertfrom\fR command might be +range \eu0000-\eu00ff so the \fBencoding convertfrom\fR command might be needed if the string is not an ISO 8859\-1 string. For example, .RS .CS -\fBbinary scan\fR abcde\\000fghi a6a10 var1 var2 +\fBbinary scan\fR abcde\e000fghi a6a10 var1 var2 .CE -will return \fB1\fR with the string equivalent to \fBabcde\\000\fR +will return \fB1\fR with the string equivalent to \fBabcde\e000\fR stored in \fIvar1\fR and \fIvar2\fR left unmodified. .RE .IP \fBA\fR 5 @@ -466,7 +466,7 @@ This form is the same as \fBa\fR, except trailing blanks and nulls are stripped the scanned value before it is stored in the variable. For example, .RS .CS -\fBbinary scan\fR "abc efghi \\000" A* var1 +\fBbinary scan\fR "abc efghi \e000" A* var1 .CE will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR. .RE @@ -480,7 +480,7 @@ all of the remaining bits in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one bit will be scanned. For example, .RS .CS -\fBbinary scan\fR \\x07\\x87\\x05 b5b* var1 var2 +\fBbinary scan\fR \ex07\ex87\ex05 b5b* var1 var2 .CE will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and \fB1110000110100000\fR stored in \fIvar2\fR. @@ -490,7 +490,7 @@ 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\fR \\x70\\x87\\x05 B5B* var1 var2 +\fBbinary scan\fR \ex70\ex87\ex05 B5B* var1 var2 .CE will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and \fB1000011100000101\fR stored in \fIvar2\fR. @@ -506,7 +506,7 @@ scanned. If \fIcount\fR is omitted, then one hex digit will be scanned. For example, .RS .CS -\fBbinary scan\fR \\x07\\x86\\x05\\x12\\x34 H3H* var1 var2 +\fBbinary scan\fR \ex07\ex86\ex05\ex12\ex34 H3H* var1 var2 .CE will return \fB2\fR with \fB078\fR stored in \fIvar1\fR and \fB051234\fR stored in \fIvar2\fR. @@ -516,7 +516,7 @@ This form is the same as \fBH\fR, except the digits are taken in reverse (low-to-high) order within each byte. For example, .RS .CS -\fBbinary scan\fR \\x07\\x86\\x05\\x12\\x34 h3h* var1 var2 +\fBbinary scan\fR \ex07\ex86\ex05\ex12\ex34 h3h* var1 var2 .CE will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and \fB502143\fR stored in \fIvar2\fR. @@ -531,7 +531,7 @@ then all of the remaining bytes in \fIstring\fR will be scanned. If example, .RS .CS -\fBbinary scan\fR \\x07\\x86\\x05 c2c* var1 var2 +\fBbinary scan\fR \ex07\ex86\ex05 c2c* var1 var2 .CE will return \fB2\fR with \fB7 -122\fR stored in \fIvar1\fR and \fB5\fR stored in \fIvar2\fR. Note that the integers returned are signed, but @@ -550,7 +550,7 @@ all of the remaining bytes in \fIstring\fR will be scanned. If example, .RS .CS -\fBbinary scan\fR \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2 +\fBbinary scan\fR \ex05\ex00\ex07\ex00\exf0\exff s2s* var1 var2 .CE will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR stored in \fIvar2\fR. Note that the integers returned are signed, but @@ -566,7 +566,7 @@ as \fIcount\fR 16-bit signed integers represented in big-endian byte order. For example, .RS .CS -\fBbinary scan\fR \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2 +\fBbinary scan\fR \ex00\ex05\ex00\ex07\exff\exf0 S2S* var1 var2 .CE will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR stored in \fIvar2\fR. @@ -588,7 +588,7 @@ all of the remaining bytes in \fIstring\fR will be scanned. If example, .RS .CS -set str \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff +set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff \fBbinary scan\fR $str i2i* var1 var2 .CE will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR @@ -605,7 +605,7 @@ as \fIcount\fR 32-bit signed integers represented in big-endian byte order. For example, .RS .CS -set str \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 +set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0 \fBbinary scan\fR $str I2I* var1 var2 .CE will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR @@ -628,7 +628,7 @@ all of the remaining bytes in \fIstring\fR will be scanned. If example, .RS .CS -set str \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff +set str \ex05\ex00\ex00\ex00\ex07\ex00\ex00\ex00\exf0\exff\exff\exff \fBbinary scan\fR $str wi* var1 var2 .CE will return \fB2\fR with \fB30064771077\fR stored in \fIvar1\fR and @@ -641,7 +641,7 @@ as \fIcount\fR 64-bit signed integers represented in big-endian byte order. For example, .RS .CS -set str \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 +set str \ex00\ex00\ex00\ex05\ex00\ex00\ex00\ex07\exff\exff\exff\exf0 \fBbinary scan\fR $str WI* var1 var2 .CE will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB-16\fR @@ -669,7 +669,7 @@ compiler dependent. For example, on a Windows system running on an Intel Pentium processor, .RS .CS -\fBbinary scan\fR \\x3f\\xcc\\xcc\\xcd f var1 +\fBbinary scan\fR \ex3f\excc\excc\excd f var1 .CE will return \fB1\fR with \fB1.6000000238418579\fR stored in \fIvar1\fR. @@ -695,7 +695,7 @@ machine's native representation. For example, on a Windows system running on an Intel Pentium processor, .RS .CS -\fBbinary scan\fR \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1 +\fBbinary scan\fR \ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f d var1 .CE will return \fB1\fR with \fB1.6000000000000001\fR stored in \fIvar1\fR. @@ -723,7 +723,7 @@ cursor is moved forward one byte. Note that this type does not consume an argument. For example, .RS .CS -\fBbinary scan\fR \\x01\\x02\\x03\\x04 x2H* var1 +\fBbinary scan\fR \ex01\ex02\ex03\ex04 x2H* var1 .CE will return \fB1\fR with \fB0304\fR stored in \fIvar1\fR. .RE @@ -736,7 +736,7 @@ 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\fR \\x01\\x02\\x03\\x04 c2XH* var1 var2 +\fBbinary scan\fR \ex01\ex02\ex03\ex04 c2XH* var1 var2 .CE will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR stored in \fIvar2\fR. @@ -749,7 +749,7 @@ by \fIcount\fR. Note that position 0 refers to the first byte in \fIcount\fR is omitted, then an error will be generated. For example, .RS .CS -\fBbinary scan\fR \\x01\\x02\\x03\\x04 c2@1H* var1 var2 +\fBbinary scan\fR \ex01\ex02\ex03\ex04 c2@1H* var1 var2 .CE will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR stored in \fIvar2\fR. diff --git a/doc/catch.n b/doc/catch.n index ffdbc8b..ddadd34 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -6,7 +6,7 @@ '\" 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.15 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: catch.n,v 1.16 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH catch n "8.5" Tcl "Tcl Built-In Commands" @@ -83,7 +83,7 @@ The \fBcatch\fR command may be used in an \fBif\fR to branch based on the success of a script. .CS if { [\fBcatch\fR {open $someFile w} fid] } { - puts stderr "Could not open $someFile for writing\\n$fid" + puts stderr "Could not open $someFile for writing\en$fid" exit 1 } .CE diff --git a/doc/clock.n b/doc/clock.n index 0f85a7d..f2bf2a8 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -190,11 +190,11 @@ that observe summer time (Daylight Saving Time). For example, the following code sets the value of \fBx\fR to \fB04:00:00\fR because the clock has changed in the interval in question. .CS -set s [\fBclock scan\fR {2004-10-30 05:00:00} \\ - -format {%Y-%m-%d %H:%M:%S} \\ +set s [\fBclock scan\fR {2004-10-30 05:00:00} \e + -format {%Y-%m-%d %H:%M:%S} \e -timezone :America/New_York] set a [\fBclock add\fR $s 24 hours -timezone :America/New_York] -set x [\fBclock format\fR $a \\ +set x [\fBclock format\fR $a \e -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -210,11 +210,11 @@ the time changes at the start or end of summer time (Daylight Saving Time) results in the \fIsame local time\fR on the day in question. For instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR. .CS -set s [\fBclock scan\fR {2004-10-30 05:00:00} \\ - -format {%Y-%m-%d %H:%M:%S} \\ +set s [\fBclock scan\fR {2004-10-30 05:00:00} \e + -format {%Y-%m-%d %H:%M:%S} \e -timezone :America/New_York] set a [\fBclock add\fR $s 1 day -timezone :America/New_York] -set x [\fBclock format\fR $a \\ +set x [\fBclock format\fR $a \e -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -225,11 +225,11 @@ Daylight Saving Time change using US rules), the time is converted as if the clock had not changed. Thus, the following code will set the value of \fBx\fR to \fB03:30:00\fR. .CS -set s [\fBclock scan\fR {2004-04-03 02:30:00} \\ - -format {%Y-%m-%d %H:%M:%S} \\ +set s [\fBclock scan\fR {2004-04-03 02:30:00} \e + -format {%Y-%m-%d %H:%M:%S} \e -timezone :America/New_York] set a [\fBclock add\fR $s 1 day -timezone :America/New_York] -set x [\fBclock format\fR $a \\ +set x [\fBclock format\fR $a \e -format {%H:%M:%S} -timezone :America/New_York] .CE .PP diff --git a/doc/encoding.n b/doc/encoding.n index 4016b83..0ebc35a 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: encoding.n,v 1.12 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: encoding.n,v 1.13 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH encoding n "8.1" Tcl "Tcl Built-In Commands" @@ -82,9 +82,9 @@ 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 [\fBencoding convertfrom\fR euc-jp "\\xA4\\xCF"] +set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"] .CE -would return the Unicode string "\\u306F", which is the Hiragana +would return the Unicode string "\eu306F", which is the Hiragana letter HA. .SH "SEE ALSO" diff --git a/doc/fcopy.n b/doc/fcopy.n index 766cca2..7441b66 100644 --- a/doc/fcopy.n +++ b/doc/fcopy.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: fcopy.n,v 1.14 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: fcopy.n,v 1.15 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH fcopy n 8.0 Tcl "Tcl Built-In Commands" @@ -132,7 +132,7 @@ proc CopyMore {in out chunk bytes {error {}}} { close $in close $out } else { - \fBfcopy\fR $in $out -size $chunk \\ + \fBfcopy\fR $in $out -size $chunk \e -command [list CopyMore $in $out $chunk] } } @@ -140,7 +140,7 @@ set in [open $file1] set out [socket $server $port] set chunk 1024 set total 0 -\fBfcopy\fR $in $out -size $chunk \\ +\fBfcopy\fR $in $out -size $chunk \e -command [list CopyMore $in $out $chunk] vwait done .CE diff --git a/doc/foreach.n b/doc/foreach.n index 5d3a631..824cd1c 100644 --- a/doc/foreach.n +++ b/doc/foreach.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: foreach.n,v 1.8 2006/11/15 09:23:01 dkf Exp $ +'\" RCS: @(#) $Id: foreach.n,v 1.9 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH foreach n "" Tcl "Tcl Built-In Commands" @@ -57,9 +57,9 @@ cube of the value: '\" Maintainers: notice the tab hacking below! .ta 3i set values {1 3 5 7 2 4 6 8} ;# Odd numbers first, for fun! -puts "Value\\tSquare\\tCube" ;# Neat-looking header +puts "Value\etSquare\etCube" ;# Neat-looking header \fBforeach\fR x $values { ;# Now loop and print... - puts " $x\\t [expr {$x**2}]\\t [expr {$x**3}]" + puts " $x\et [expr {$x**2}]\et [expr {$x**3}]" } .CE .PP diff --git a/doc/format.n b/doc/format.n index 3ba307c..eae486d 100644 --- a/doc/format.n +++ b/doc/format.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: format.n,v 1.17 2007/10/26 20:11:52 dgp Exp $ +'\" RCS: @(#) $Id: format.n,v 1.18 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH format n 8.1 Tcl "Tcl Built-In Commands" @@ -228,7 +228,7 @@ reordering the data values passed to \fBformat\fR: set fmt1 "Today, %d shares in %s were bought at $%.2f each" puts [\fBformat\fR $fmt1 123 "Global BigCorp" 19.37] -set fmt2 "Bought %2\\$s equity ($%3$.2f x %1\\$d) today" +set fmt2 "Bought %2\e$s equity ($%3$.2f x %1\e$d) today" puts [\fBformat\fR $fmt2 123 "Global BigCorp" 19.37] .CE .PP diff --git a/doc/global.n b/doc/global.n index a11e88b..2294dee 100644 --- a/doc/global.n +++ b/doc/global.n @@ -1,59 +1,59 @@ -'\" -'\" 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.9 2004/10/27 12:53:22 dkf 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 has no effect unless executed in the context of a proc body. -If the \fBglobal\fR command is executed in the context of a proc body, it -creates local variables linked to the corresponding global variables (and -therefore these variables are listed by info locals). -.PP -If \fIvarname\fR contains namespace qualifiers, the local variable's name is -the unqualified name of the global variable, as determined by the -\fBnamespace tail\fR command. -.PP -\fIvarname\fR is always treated as the name of a variable, not an -array element. An error is returned if the name looks like an array element, -such as \fBa(b)\fR. -.SH EXAMPLES -This procedure sets the namespace variable \fI::a::x\fR -.CS -proc reset {} { - \fBglobal\fR a::x - set x 0 -} -.CE -.PP -This procedure accumulates the strings passed to it in a global -buffer, separated by newlines. It is useful for situations when you -want to build a message piece-by-piece (as if with \fBputs\fR) but -send that full message in a single piece (e.g. over a connection -opened with \fBsocket\fR or as part of a counted HTTP response). -.CS -proc accum {string} { - \fBglobal\fR accumulator - append accumulator $string \\n -} -.CE - -.SH "SEE ALSO" -namespace(n), upvar(n), variable(n) - -.SH KEYWORDS -global, namespace, procedure, variable +'\"
+'\" 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.10 2007/10/28 14:17:40 dkf 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 has no effect unless executed in the context of a proc body.
+If the \fBglobal\fR command is executed in the context of a proc body, it
+creates local variables linked to the corresponding global variables (and
+therefore these variables are listed by info locals).
+.PP
+If \fIvarname\fR contains namespace qualifiers, the local variable's name is
+the unqualified name of the global variable, as determined by the
+\fBnamespace tail\fR command.
+.PP
+\fIvarname\fR is always treated as the name of a variable, not an
+array element. An error is returned if the name looks like an array element,
+such as \fBa(b)\fR.
+.SH EXAMPLES
+This procedure sets the namespace variable \fI::a::x\fR
+.CS
+proc reset {} {
+ \fBglobal\fR a::x
+ set x 0
+}
+.CE
+.PP
+This procedure accumulates the strings passed to it in a global
+buffer, separated by newlines. It is useful for situations when you
+want to build a message piece-by-piece (as if with \fBputs\fR) but
+send that full message in a single piece (e.g. over a connection
+opened with \fBsocket\fR or as part of a counted HTTP response).
+.CS
+proc accum {string} {
+ \fBglobal\fR accumulator
+ append accumulator $string \en
+}
+.CE
+
+.SH "SEE ALSO"
+namespace(n), upvar(n), variable(n)
+
+.SH KEYWORDS
+global, namespace, procedure, variable
@@ -6,7 +6,7 @@ '\" 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.27 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: http.n,v 1.28 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH "http" n 2.5 http "Tcl Bundled Packages" @@ -503,7 +503,7 @@ The requested URL. # Copy a URL to a file and print meta-data proc httpcopy { url file {chunk 4096} } { set out [open $file w] - set token [\fB::http::geturl\fR $url -channel $out \\ + set token [\fB::http::geturl\fR $url -channel $out \e -progress httpCopyProgress -blocksize $chunk] close $out @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: load.n,v 1.19 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: load.n,v 1.20 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH load n 7.5 Tcl "Tcl Built-In Commands" @@ -134,7 +134,7 @@ The following is a minimal extension: #include <stdio.h> static int fooCmd(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) { - printf("called with %d arguments\\n", objc); + printf("called with %d arguments\en", objc); return TCL_OK; } int Foo_Init(Tcl_Interp *interp) { diff --git a/doc/lsort.n b/doc/lsort.n index c2c1be8..da516b5 100644 --- a/doc/lsort.n +++ b/doc/lsort.n @@ -7,7 +7,7 @@ '\" 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.24 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: lsort.n,v 1.25 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH lsort n 8.5 Tcl "Tcl Built-In Commands" @@ -83,7 +83,7 @@ each sublist For example, .RS .CS -lsort -integer -index 1 \\ +lsort -integer -index 1 \e {{First 24} {Second 18} {Third 30}} .CE returns \fB{Second 18} {First 24} {Third 30}\fR, and @@ -91,7 +91,7 @@ returns \fB{Second 18} {First 24} {Third 30}\fR, and '\" This example is from the test suite! '\" .CS -lsort -index end-1 \\ +lsort -index end-1 \e {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} .CE returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR, @@ -194,7 +194,7 @@ More complex sorting using a comparison function: } return [string compare [lindex $a 1] [lindex $b 1]] } -% \fBlsort\fR -command compare \\ +% \fBlsort\fR -command compare \e {{3 apple} {0x2 carrot} {1 dingo} {2 banana}} {1 dingo} {2 banana} {0x2 carrot} {3 apple} .CE diff --git a/doc/msgcat.n b/doc/msgcat.n index 7bff211..9a3a8fd 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -289,8 +289,8 @@ format "In location %s we produced %d units" $city $num 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 +format "We produced %1\e$d units in location %2\e$s" $num $city +format "In location %2\e$s we produced %1\e$d units" $num $city .CE .PP Similarly, positional parameters can be used with \fBscan\fR to @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: read.n,v 1.13 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: read.n,v 1.14 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH read n 8.1 Tcl "Tcl Built-In Commands" @@ -78,7 +78,7 @@ with each line in the file corresponding to an element in the list: set fl [open /proc/meminfo] set data [\fBread\fR $fl] close $fl -set lines [split $data \\n] +set lines [split $data \en] .CE .SH "SEE ALSO" diff --git a/doc/regexp.n b/doc/regexp.n index bf0e0aa..d626e37 100644 --- a/doc/regexp.n +++ b/doc/regexp.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: regexp.n,v 1.23 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: regexp.n,v 1.24 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH regexp n 8.3 Tcl "Tcl Built-In Commands" @@ -99,9 +99,9 @@ always returned. For each match iteration, the command will append the overall match data, plus one element for each subexpression in the regular expression. Examples are: .CS - regexp -inline -- {\\w(\\w)} " inlined " + regexp -inline -- {\ew(\ew)} " inlined " => {in n} - regexp -all -inline -- {\\w(\\w)} " inlined " + regexp -all -inline -- {\ew(\ew)} " inlined " => {in n li i ne e} .CE .TP 15 @@ -113,7 +113,7 @@ The \fIindex\fR value is interpreted in the same manner as the \fIindex\fR argument to \fBstring index\fR. .VE 8.5 When using this switch, `^' -will not match the beginning of the line, and \\A will still +will not match the beginning of the line, and \eA will still match the start of the string at \fIindex\fR. If \fB\-indices\fR is specified, the indices will be indexed starting from the absolute beginning of the input string. @@ -134,7 +134,7 @@ Find the first occurrence of a word starting with \fBfoo\fR in a string that is not actually an instance of \fBfoobar\fR, and get the letters following it up to the end of the word into a variable: .CS -\fBregexp\fR {\\<foo(?!bar\\>)(\\w*)} $string \-> restOfWord +\fBregexp\fR {\e<foo(?!bar\e>)(\ew*)} $string \-> restOfWord .CE Note that the whole matched substring has been placed in the variable \fB\->\fR which is a name chosen to look nice given that we are not @@ -143,7 +143,7 @@ actually interested in its contents. Find the index of the word \fBbadger\fR (in any case) within a string and store that in the variable \fBlocation\fR: .CS -\fBregexp\fR \-indices {(?i)\\<badger\\>} $string location +\fBregexp\fR \-indices {(?i)\e<badger\e>} $string location .CE .PP Count the number of octal digits in a string: @@ -154,7 +154,7 @@ Count the number of octal digits in a string: List all words (consisting of all sequences of non-whitespace characters) in a string: .CS -\fBregexp\fR \-all \-inline {\\S+} $string +\fBregexp\fR \-all \-inline {\eS+} $string .CE .SH "SEE ALSO" diff --git a/doc/registry.n b/doc/registry.n index 46c88b7..f5e839e 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: registry.n,v 1.17 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: registry.n,v 1.18 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH registry n 1.1 registry "Tcl Bundled Packages" @@ -68,7 +68,7 @@ set regPath [join { Control {Session Manager} Environment -} "\\\\"] +} "\e\e"] set curPath [\fBregistry get\fR $regPath "Path"] \fBregistry set\fR $regPath "Path" "$curPath;$addPath" \fBregistry broadcast\fR "Environment" diff --git a/doc/regsub.n b/doc/regsub.n index 4dcf8a5..fecc357 100644 --- a/doc/regsub.n +++ b/doc/regsub.n @@ -6,7 +6,7 @@ '\" 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.19 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: regsub.n,v 1.20 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH regsub n 8.3 Tcl "Tcl Built-In Commands" @@ -98,7 +98,7 @@ The \fIindex\fR value is interpreted in the same manner as the \fIindex\fR argument to \fBstring index\fR. .VE 8.5 When using this switch, `^' -will not match the beginning of the line, and \\A will still +will not match the beginning of the line, and \eA will still match the start of the string at \fIindex\fR. \fIindex\fR will be constrained to the bounds of the input string. .TP 10 diff --git a/doc/return.n b/doc/return.n index ea3f362..a38f40a 100644 --- a/doc/return.n +++ b/doc/return.n @@ -6,7 +6,7 @@ '\" 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.14 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: return.n,v 1.15 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH return n 8.5 Tcl "Tcl Built-In Commands" @@ -228,9 +228,9 @@ to report invalid arguments. .CS proc factorial {n} { if {![string is integer $n] || ($n < 0)} { - \fBreturn\fR -code error \\ - "expected non-negative integer,\\ - but got \\"$n\\"" + \fBreturn\fR -code error \e + "expected non-negative integer,\e + but got \e"$n\e"" } if {$n < 2} { \fBreturn\fR 1 @@ -242,7 +242,7 @@ proc factorial {n} { } set product [expr {$n * $factor}] if {$product < 0} { - \fBreturn\fR -code error \\ + \fBreturn\fR -code error \e "overflow computing factorial of $n" } \fBreturn\fR $product @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: safe.n,v 1.8 2007/07/04 14:45:19 dkf Exp $ +'\" RCS: @(#) $Id: safe.n,v 1.9 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands" @@ -123,7 +123,7 @@ Example of use: .RS .PP .CS -$slave eval [list set tk_library \\ +$slave eval [list set tk_library \e [::safe::interpFindInAccessPath $name $tk_library]] .CE .RE @@ -138,7 +138,7 @@ Example of use: .RS .PP .CS -$slave eval [list set tk_library \\ +$slave eval [list set tk_library \e [::safe::interpAddToAccessPath $name $tk_library]] .CE .RE @@ -297,7 +297,7 @@ 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 (i.e. when using the native file path formats: \fItoken\fR\fB/\fR\fIfilename\fR -on Unix and \fItoken\fR\fB\\\fIfilename\fR on Windows), +on Unix and \fItoken\fR\fB\e\fIfilename\fR on Windows), 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). @@ -6,7 +6,7 @@ '\" 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.21 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: scan.n,v 1.22 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH scan n 8.4 Tcl "Tcl Built-In Commands" @@ -239,7 +239,7 @@ looking for the terminating character explicitly: set string "(5.2,-4e-2)" # Note that the spaces before the literal parts of # the scan pattern are significant, and that ")" is -# the Unicode character \\u0029 +# the Unicode character \eu0029 if { [\fBscan\fR $string " (%f ,%f %c" x y last] != 3 || $last != 0x0029 diff --git a/doc/source.n b/doc/source.n index c12efff..8269734 100644 --- a/doc/source.n +++ b/doc/source.n @@ -6,7 +6,7 @@ '\" 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.14 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: source.n,v 1.15 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH source n "" Tcl "Tcl Built-In Commands" @@ -33,12 +33,12 @@ 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. .PP -The end-of-file character for files is '\\32' (^Z) for all platforms. +The end-of-file character for files is '\e32' (^Z) for all platforms. The source command will read files up to this character. This restriction does not exist for the \fBread\fR or \fBgets\fR commands, allowing for files containing code and data segments (scripted documents). If you require a ``^Z'' in code for string comparison, you can use -``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl +``\e032'' or ``\eu001a'', which will be safely substituted by the Tcl interpreter into ``^Z''. .PP .VS 8.5 diff --git a/doc/split.n b/doc/split.n index 48a83cf..d3970d1 100644 --- a/doc/split.n +++ b/doc/split.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: split.n,v 1.7 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: split.n,v 1.8 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH split n "" Tcl "Tcl Built-In Commands" @@ -48,7 +48,7 @@ careful: Extract the list words from a string that is not a well-formed list: .CS \fBsplit\fR "Example with {unbalanced brace character" - \fI=> Example with \\{unbalanced brace character\fR + \fI=> Example with \e{unbalanced brace character\fR .CE .PP Split a string into its constituent characters @@ -66,7 +66,7 @@ set content [read $fid] close $fid ## Split into records on newlines -set records [\fBsplit\fR $content "\\n"] +set records [\fBsplit\fR $content "\en"] ## Iterate over the records foreach rec $records { @@ -75,7 +75,7 @@ foreach rec $records { set fields [\fBsplit\fR $rec ":"] ## Assign fields to variables and print some out... - lassign $fields \\ + lassign $fields \e userName password uid grp longName homeDir shell puts "$longName uses [file tail $shell] for a login shell" } diff --git a/doc/string.n b/doc/string.n index 9745caf..6c6761a 100644 --- a/doc/string.n +++ b/doc/string.n @@ -5,7 +5,7 @@ .\" See the file "license.terms" for information on usage and redistribution .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. .\" -.\" RCS: @(#) $Id: string.n,v 1.38 2007/10/26 20:11:53 dgp Exp $ +.\" RCS: @(#) $Id: string.n,v 1.39 2007/10/28 14:17:40 dkf Exp $ .\" .so man.macros .TH string n 8.1 Tcl "Tcl Built-In Commands" @@ -120,7 +120,7 @@ Any Unicode alphabet or digit character. .IP \fBalpha\fR 12 Any Unicode alphabet character. .IP \fBascii\fR 12 -Any character with a value less than \\u0080 (those that are in the +Any character with a value less than \eu0080 (those that are in the 7\-bit ascii range). .IP \fBboolean\fR 12 Any of the forms allowed to \fBTcl_GetBoolean\fR. diff --git a/doc/subst.n b/doc/subst.n index 34c82a9..f52a155 100644 --- a/doc/subst.n +++ b/doc/subst.n @@ -6,7 +6,7 @@ '\" 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.12 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: subst.n,v 1.13 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH subst n 7.4 Tcl "Tcl Built-In Commands" @@ -70,10 +70,10 @@ set a 44 returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR'' and the script .CS -set a "p\\} q \\{r" +set a "p\e} q \e{r" \fBsubst\fR {xyz {$a}} .CE -return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\fR''. +return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\e} q \e{r}\fR''. .PP When command substitution is performed, it includes any variable substitution necessary to evaluate the script. diff --git a/doc/switch.n b/doc/switch.n index 40e5918..c446aff 100644 --- a/doc/switch.n +++ b/doc/switch.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: switch.n,v 1.12 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: switch.n,v 1.13 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH switch n 8.5 Tcl "Tcl Built-In Commands" @@ -159,7 +159,7 @@ exactly matched is easily obtained using the \fB\-matchvar\fR option: puts "Found [string length [lindex $foo 1]] 'b's" } d(e*)f(g*)h { - puts "Found [string length [lindex $foo 1]] 'e's and\\ + puts "Found [string length [lindex $foo 1]] 'e's and\e [string length [lindex $foo 2]] 'g's" } } diff --git a/doc/tclsh.1 b/doc/tclsh.1 index c9b3cf8..81392bc 100644 --- a/doc/tclsh.1 +++ b/doc/tclsh.1 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tclsh.1,v 1.12 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: tclsh.1,v 1.13 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH tclsh 1 "" Tcl "Tcl Applications" @@ -44,12 +44,17 @@ 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. The end of the file may be marked either by the physical end of -the medium, or by the character, '\\032' ('\\u001a', control-Z). +the medium, or by the character, +.QW \e032 +.PQ \eu001a ", control-Z" . If this character is present in the file, the \fBtclsh\fR application will read text up to but not including the character. An application that requires this character in the file may safely encode it as -``\\032'', ``\\x1a'', or ``\\u001a''; or may generate it by use of commands -such as \fBformat\fR or \fBbinary\fR. +.QW \e032 , +.QW \ex1a , +or +.QW \eu001a ; +or may generate it by use of commands such as \fBformat\fR or \fBbinary\fR. There is no automatic evaluation of \fB.tclshrc\fR when the name of a script file is presented on the \fBtclsh\fR command line, but the script file can always \fBsource\fR it if desired. @@ -61,8 +66,8 @@ If you create a Tcl script in a file whose first line is 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. +location in /usr/local/bin; if it is installed somewhere else +then you will 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. @@ -75,7 +80,7 @@ following three lines: 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 +paragraph. First, the location of the \fBtclsh\fR binary does not 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. @@ -123,14 +128,16 @@ 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 +command with +.QW "\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 +a newline is typed but the current command is not yet complete; +if \fBtcl_prompt2\fR is not set then no prompt is output for incomplete commands. .SH "STANDARD CHANNELS" diff --git a/doc/tcltest.n b/doc/tcltest.n index 91d145e..db841f6 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -8,7 +8,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tcltest.n,v 1.51 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: tcltest.n,v 1.52 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages" @@ -1033,7 +1033,7 @@ Here is a sketch of a sample test suite master script: package require Tcl 8.4 package require tcltest 2.2 package require example -\fB::tcltest::configure\fR -testdir \\ +\fB::tcltest::configure\fR -testdir \e [file dirname [file normalize [info script]]] eval \fB::tcltest::configure\fR $argv \fB::tcltest::runAllTests\fR diff --git a/doc/tclvars.n b/doc/tclvars.n index 4a4a16e..d664784 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tclvars.n,v 1.29 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: tclvars.n,v 1.30 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH tclvars n 8.0 Tcl "Tcl Built-In Commands" @@ -336,16 +336,16 @@ This variable and functionality only exist if The value of this variable is a regular expression that can be set to control what are considered ``word'' characters, for instances like selecting a word by double-clicking in text in Tk. It is platform -dependent. On Windows, it defaults to \fB\\S\fR, meaning anything -but a Unicode space character. Otherwise it defaults to \fB\\w\fR, +dependent. On Windows, it defaults to \fB\eS\fR, meaning anything +but a Unicode space character. Otherwise it defaults to \fB\ew\fR, which is any Unicode word character (number, letter, or underscore). .TP \fBtcl_nonwordchars\fR The value of this variable is a regular expression that can be set to control what are considered ``non-word'' characters, for instances like selecting a word by double-clicking in text in Tk. It is platform -dependent. On Windows, it defaults to \fB\\s\fR, meaning any Unicode space -character. Otherwise it defaults to \fB\\W\fR, which is anything but a +dependent. On Windows, it defaults to \fB\es\fR, meaning any Unicode space +character. Otherwise it defaults to \fB\eW\fR, which is anything but a Unicode word character (number, letter, or underscore). .TP \fBtcl_version\fR @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tm.n,v 1.9 2007/10/26 20:11:53 dgp Exp $ +'\" RCS: @(#) $Id: tm.n,v 1.10 2007/10/28 14:17:40 dkf Exp $ '\" .so man.macros .TH tm n 8.5 Tcl "Tcl Built-In Commands" @@ -87,7 +87,7 @@ package. .PP The name of a module file has to match the regular expression: .CS -([[:alpha:]][:[:alnum:]]*)-([[:digit:]].*)\\.tm +([[:alpha:]][:[:alnum:]]*)-([[:digit:]].*)\e.tm .CE .PP The first capturing parentheses provides the name of the package, the |