diff options
42 files changed, 293 insertions, 67 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 161de0c..ae535d7 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.21 2008/06/29 22:28:21 dkf Exp $ +'\" RCS: @(#) $Id: AddErrInfo.3,v 1.22 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" @@ -140,6 +140,7 @@ if ((objc % 2) == 0) { /* explicit result argument */ } return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1)); .CE +.PP (It is not really implemented that way. Internal access privileges allow for a more efficient alternative that meshes better with the bytecode compiler.) diff --git a/doc/AppInit.3 b/doc/AppInit.3 index 99e1555..15d5635 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.9 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: AppInit.3,v 1.10 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures" @@ -57,9 +57,11 @@ for the interpreter's result; otherwise the result is ignored. .PP In addition to \fBTcl_AppInit\fR, your application should also contain a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows: +.PP .CS Tcl_Main(argc, argv, Tcl_AppInit); .CE +.PP The third argument to \fBTcl_Main\fR gives the address of the application-specific initialization procedure to invoke. This means that you do not have to use the name \fBTcl_AppInit\fR diff --git a/doc/AssocData.3 b/doc/AssocData.3 index 2b85137..6366cdf 100644 --- a/doc/AssocData.3 +++ b/doc/AssocData.3 @@ -5,7 +5,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" -'\" RCS: @(#) $Id: AssocData.3,v 1.8 2008/06/29 22:28:23 dkf Exp $ +'\" RCS: @(#) $Id: AssocData.3,v 1.9 2008/10/15 10:43:37 dkf Exp $ .so man.macros .TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures" .BS @@ -63,11 +63,13 @@ If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a procedure to invoke if the interpreter is deleted before the association is deleted. \fIDeleteProc\fR should have arguments and result that match the type \fBTcl_InterpDeleteProc\fR: +.PP .CS typedef void \fBTcl_InterpDeleteProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE +.PP When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR arguments will be the same as the corresponding arguments passed to \fBTcl_SetAssocData\fR. diff --git a/doc/Async.3 b/doc/Async.3 index 346a26c..dba4400 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.13 2008/06/29 22:28:23 dkf Exp $ +'\" RCS: @(#) $Id: Async.3,v 1.14 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures" @@ -83,12 +83,14 @@ the world is in a safe state, and \fIproc\fR can then carry out the actions associated with the asynchronous event. \fIProc\fR should have arguments and result that match the type \fBTcl_AsyncProc\fR: +.PP .CS typedef int \fBTcl_AsyncProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIcode\fR); .CE +.PP The \fIclientData\fR will be the same as the \fIclientData\fR argument passed to \fBTcl_AsyncCreate\fR when the handler was created. diff --git a/doc/CallDel.3 b/doc/CallDel.3 index 9c225e0..0dbed27 100644 --- a/doc/CallDel.3 +++ b/doc/CallDel.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: CallDel.3,v 1.7 2008/06/29 22:28:23 dkf Exp $ +'\" RCS: @(#) $Id: CallDel.3,v 1.8 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures" @@ -28,7 +28,6 @@ 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 @@ -38,11 +37,13 @@ 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: +.PP .CS typedef void \fBTcl_InterpDeleteProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE +.PP The \fIclientData\fR and \fIinterp\fR parameters are copies of the \fIclientData\fR and \fIinterp\fR arguments given to \fBTcl_CallWhenDeleted\fR. @@ -58,6 +59,11 @@ 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. - +.PP +Note that if the callback is being used to delete a resource that \fImust\fR +be released on exit, \fBTcl_CreateExitHandler\fR should be used to ensure that +a callback is received even if the application terminates without deleting the interpreter. +.SH "SEE ALSO" +Tcl_CreateExitHandler(3), Tcl_CreateThreadExitHandler(3) .SH KEYWORDS -callback, delete, interpreter +callback, cleanup, delete, interpreter diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3 index d9aab23..02081bf 100644 --- a/doc/CrtCommand.3 +++ b/doc/CrtCommand.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: CrtCommand.3,v 1.15 2008/06/29 22:28:23 dkf Exp $ +'\" RCS: @(#) $Id: CrtCommand.3,v 1.16 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures" @@ -76,6 +76,7 @@ the process of being deleted, then it does not create a new command and it returns NULL. \fIProc\fR should have arguments and result that match the type \fBTcl_CmdProc\fR: +.PP .CS typedef int \fBTcl_CmdProc\fR( ClientData \fIclientData\fR, @@ -83,6 +84,7 @@ typedef int \fBTcl_CmdProc\fR( int \fIargc\fR, const char *\fIargv\fR[]); .CE +.PP When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR parameters will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to \fBTcl_CreateCommand\fR. @@ -130,10 +132,12 @@ or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR. application an opportunity to release any structures associated with the command. \fIDeleteProc\fR should have arguments and result that match the type \fBTcl_CmdDeleteProc\fR: +.PP .CS typedef void \fBTcl_CmdDeleteProc\fR( ClientData \fIclientData\fR); .CE +.PP The \fIclientData\fR argument will be the same as the \fIclientData\fR argument passed to \fBTcl_CreateCommand\fR. .SH "SEE ALSO" diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3 index 4b352ba..00a6a48 100644 --- a/doc/CrtFileHdlr.3 +++ b/doc/CrtFileHdlr.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: CrtFileHdlr.3,v 1.9 2008/06/29 22:28:23 dkf Exp $ +'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.10 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures" @@ -50,11 +50,13 @@ as \fBvwait\fR. .PP \fIProc\fR should have arguments and result that match the type \fBTcl_FileProc\fR: +.PP .CS typedef void \fBTcl_FileProc\fR( ClientData \fIclientData\fR, int \fImask\fR); .CE +.PP The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTcl_CreateFileHandler\fR when the callback @@ -65,7 +67,6 @@ 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 @@ -86,5 +87,7 @@ blocking or nonblocking mode as required. .PP Note that these interfaces are only supported by the Unix implementation of the Tcl notifier. +.SH "SEE ALSO" +fileevent(n), Tcl_CreateTimerHandler(3), Tcl_DoWhenIdle(3) .SH KEYWORDS callback, file, handler diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index 2e30de9..43a855b 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.18 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.19 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures" @@ -90,6 +90,7 @@ the process of being deleted, then it does not create a new command and it returns NULL. \fIproc\fR should have arguments and result that match the type \fBTcl_ObjCmdProc\fR: +.PP .CS typedef int \fBTcl_ObjCmdProc\fR( ClientData \fIclientData\fR, @@ -97,6 +98,7 @@ typedef int \fBTcl_ObjCmdProc\fR( int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[]); .CE +.PP When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to \fBTcl_CreateObjCommand\fR. Typically, \fIclientData\fR points to an @@ -161,10 +163,12 @@ or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR. application an opportunity to release any structures associated with the command. \fIDeleteProc\fR should have arguments and result that match the type \fBTcl_CmdDeleteProc\fR: +.PP .CS typedef void \fBTcl_CmdDeleteProc\fR( ClientData \fIclientData\fR); .CE +.PP The \fIclientData\fR argument will be the same as the \fIclientData\fR argument passed to \fBTcl_CreateObjCommand\fR. .PP @@ -199,6 +203,7 @@ Otherwise it places information about the command in the \fBTcl_CmdInfo\fR structure pointed to by \fIinfoPtr\fR and returns 1. A \fBTcl_CmdInfo\fR structure has the following fields: +.PP .CS typedef struct Tcl_CmdInfo { int \fIisNativeObjectProc\fR; @@ -211,6 +216,7 @@ typedef struct Tcl_CmdInfo { Tcl_Namespace *\fInamespacePtr\fR; } \fBTcl_CmdInfo\fR; .CE +.PP The \fIisNativeObjectProc\fR field has the value 1 if \fBTcl_CreateObjCommand\fR was called to register the command; it is 0 if only \fBTcl_CreateCommand\fR was called. @@ -293,6 +299,6 @@ specified by the name in a \fBTcl_Obj\fR. The command name is resolved relative to the current namespace. Returns NULL if the command is not found. .SH "SEE ALSO" -Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult +Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3) .SH KEYWORDS bind, command, create, delete, namespace, object diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3 index 7e0368f..841b465 100644 --- a/doc/CrtTimerHdlr.3 +++ b/doc/CrtTimerHdlr.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.7 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.8 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures" @@ -50,10 +50,12 @@ are other pending events to process before the call to .PP \fIProc\fR should have arguments and return value that match the type \fBTcl_TimerProc\fR: +.PP .CS typedef void \fBTcl_TimerProc\fR( ClientData \fIclientData\fR); .CE +.PP The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTcl_CreateTimerHandler\fR when the callback @@ -70,5 +72,7 @@ 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 "SEE ALSO" +after(n), Tcl_CreateFileHandler(3), Tcl_DoWhenIdle(3) .SH KEYWORDS callback, clock, handler, timer diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index 1248619..0c02776 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.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: CrtTrace.3,v 1.15 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: CrtTrace.3,v 1.16 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" @@ -65,6 +65,7 @@ interpreter. .PP \fIobjProc\fR should have arguments and result that match the type, \fBTcl_CmdObjTraceProc\fR: +.PP .CS typedef int \fBTcl_CmdObjTraceProc\fR( \fBClientData\fR \fIclientData\fR, @@ -75,6 +76,7 @@ typedef int \fBTcl_CmdObjTraceProc\fR( int \fIobjc\fR, \fBTcl_Obj\fR *const \fIobjv\fR[]); .CE +.PP 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 @@ -141,10 +143,12 @@ 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: +.PP .CS typedef void \fBTcl_CmdObjTraceDeleteProc\fR( \fBClientData\fR \fIclientData\fR); .CE +.PP The \fIclientData\fR parameter will be the same as the \fIclientData\fR parameter that was originally passed to \fBTcl_CreateObjTrace\fR. @@ -155,6 +159,7 @@ 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: +.PP .CS typedef void \fBTcl_CmdTraceProc\fR( ClientData \fIclientData\fR, @@ -166,6 +171,7 @@ typedef void \fBTcl_CmdTraceProc\fR( int \fIargc\fR, const char *\fIargv\fR[]); .CE +.PP 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 diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3 index b75de55..37b4cec 100644 --- a/doc/DoWhenIdle.3 +++ b/doc/DoWhenIdle.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.6 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.7 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures" @@ -42,10 +42,12 @@ use \fBTcl_DoOneEvent\fR to dispatch events. .PP \fIProc\fR should have arguments and result that match the type \fBTcl_IdleProc\fR: +.PP .CS typedef void \fBTcl_IdleProc\fR( ClientData \fIclientData\fR); .CE +.PP 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 @@ -81,5 +83,7 @@ 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 "SEE ALSO" +after(n), Tcl_CreateFileHandler(3), Tcl_CreateTimerHandler(3) .SH KEYWORDS callback, defer, idle callback diff --git a/doc/Encoding.3 b/doc/Encoding.3 index a824b2f..5fadc44 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.30 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: Encoding.3,v 1.31 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" @@ -282,6 +282,7 @@ and the 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): +.PP .CS if (running NT) { encoding <- Tcl_GetEncoding("unicode"); @@ -291,6 +292,7 @@ if (running NT) { nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer); } .CE +.PP \fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically handle this test and use the proper encoding based on the current operating system. \fBTcl_WinUtfToTChar\fR returns a pointer to @@ -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: Exit.3,v 1.8 2008/08/01 18:22:29 hobbs Exp $ +'\" RCS: @(#) $Id: Exit.3,v 1.9 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures" @@ -92,10 +92,12 @@ by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR. This provides a hook for cleanup operations such as flushing buffers and freeing global memory. \fIProc\fR should match the type \fBTcl_ExitProc\fR: +.PP .CS typedef void \fBTcl_ExitProc\fR( ClientData \fIclientData\fR); .CE +.PP The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index b3baf8f..bec5e23 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.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: FileSystem.3,v 1.66 2008/10/05 22:25:35 nijtmans Exp $ +'\" RCS: @(#) $Id: FileSystem.3,v 1.67 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" @@ -1583,7 +1583,7 @@ cleanup action required. typedef void \fBTcl_FSUnloadFileProc\fR( Tcl_LoadHandle \fIloadHandle\fR); .CE -.SS GETCWDPROC +.SS GETCWDPROC .PP Function to process a \fBTcl_FSGetCwd\fR call. Most filesystems need not implement this. It will usually only be called once, if \fBgetcwd\fR is diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3 index 074d237..fb91517 100644 --- a/doc/GetStdChan.3 +++ b/doc/GetStdChan.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: GetStdChan.3,v 1.8 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: GetStdChan.3,v 1.9 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures" @@ -55,9 +55,11 @@ set to NULL. .PP If a non-NULL value for \fIchannel\fR is passed to \fBTcl_SetStdChannel\fR, then that same value should be passed to \fBTcl_RegisterChannel\fR, like so: +.PP .CS Tcl_RegisterChannel(NULL, channel); .CE +.PP This is a workaround for a misfeature in \fBTcl_SetStdChannel\fR that it fails to do some reference counting housekeeping. This misfeature cannot be corrected without contradicting the assumptions of some existing diff --git a/doc/GetTime.3 b/doc/GetTime.3 index c3f7134..a180860 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -80,6 +80,7 @@ of the OS. The arguments to the function are allowed to be NULL; and any argument which is NULL is ignored and not set. .PP The signatures of the handler functions are as follows: +.PP .CS typedef void \fBTcl_GetTimeProc\fR( Tcl_Time *\fItimebuf\fR, @@ -88,6 +89,7 @@ typedef void \fBTcl_ScaleTimeProc\fR( Tcl_Time *\fItimebuf\fR, ClientData \fIclientData\fR); .CE +.PP The \fItimebuf\fR fields contain the time to manipulate, and the \fIclientData\fR fields contain a pointer supplied at the time the handler functions were registered. @@ -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.28 2008/10/04 11:51:25 nijtmans Exp $ +'\" RCS: @(#) $Id: Hash.3,v 1.29 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" @@ -280,31 +280,37 @@ circular dependency. .PP The \fIhashKeyProc\fR member contains the address of a function called to calculate a hash value for the key. +.PP .CS typedef unsigned int \fBTcl_HashKeyProc\fR( Tcl_HashTable *\fItablePtr\fR, void *\fIkeyPtr\fR); .CE +.PP If this is NULL then \fIkeyPtr\fR is used and \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR is assumed. .PP The \fIcompareKeysProc\fR member contains the address of a function called to compare two keys. +.PP .CS typedef int \fBTcl_CompareHashKeysProc\fR( void *\fIkeyPtr\fR, Tcl_HashEntry *\fIhPtr\fR); .CE +.PP If this is NULL then the \fIkeyPtr\fR pointers are compared. 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 called to allocate space for an entry and initialize the key and clientData. +.PP .CS typedef Tcl_HashEntry *\fBTcl_AllocHashEntryProc\fR( Tcl_HashTable *\fItablePtr\fR, void *\fIkeyPtr\fR); .CE +.PP If this is NULL then Tcl_Alloc is used to allocate enough space for a Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the clientData is set to NULL. String keys and array keys use this function to @@ -316,10 +322,12 @@ object. .PP The \fIfreeEntryProc\fR member contains the address of a function called to free space for an entry. +.PP .CS typedef void \fBTcl_FreeHashEntryProc\fR( Tcl_HashEntry *\fIhPtr\fR); .CE +.PP If this is NULL then Tcl_Free is used to free the space for the entry. Tcl_Obj* keys use this function to decrement the reference count on the object. diff --git a/doc/Notifier.3 b/doc/Notifier.3 index 4eddc54..74aa77b 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.23 2008/07/24 21:54:43 nijtmans Exp $ +'\" RCS: @(#) $Id: Notifier.3,v 1.24 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Notifier 3 8.1 Tcl "Tcl Library Procedures" @@ -229,11 +229,13 @@ The procedure \fBTcl_CreateEventSource\fR creates a new event source. Its arguments specify the setup procedure and check procedure for the event source. \fISetupProc\fR should match the following prototype: +.PP .CS typedef void \fBTcl_EventSetupProc\fR( ClientData \fIclientData\fR, int \fIflags\fR); .CE +.PP The \fIclientData\fR argument will be the same as the \fIclientData\fR argument to \fBTcl_CreateEventSource\fR; it is typically used to point to private information managed by the event source. @@ -268,12 +270,14 @@ connection. The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to a structure that describes a time interval in seconds and microseconds: +.PP .CS typedef struct Tcl_Time { long \fIsec\fR; long \fIusec\fR; } \fBTcl_Time\fR; .CE +.PP The \fIusec\fR field should be less than 1000000. .PP Information provided to \fBTcl_SetMaxBlockTime\fR @@ -303,11 +307,13 @@ The second procedure provided by each event source is its check procedure, indicated by the \fIcheckProc\fR argument to \fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the following prototype: +.PP .CS typedef void \fBTcl_EventCheckProc\fR( ClientData \fIclientData\fR, int \fIflags\fR); .CE +.PP The arguments to this procedure are the same as those for \fIsetupProc\fR. \fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited for events. Presumably at least one event source is now prepared to @@ -326,12 +332,14 @@ to that event source. However, the first element of the structure must be a structure of type \fBTcl_Event\fR, and the address of this structure is used when communicating between the event source and the rest of the notifier. A \fBTcl_Event\fR has the following definition: +.PP .CS typedef struct { Tcl_EventProc *\fIproc\fR; struct Tcl_Event *\fInextPtr\fR; } \fBTcl_Event\fR; .CE +.PP The event source must fill in the \fIproc\fR field of the event before calling \fBTcl_QueueEvent\fR. The \fInextPtr\fR is used to link together the events in the queue @@ -359,11 +367,13 @@ When it is time to handle an event from the queue (steps 1 and 4 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified in the first queued \fBTcl_Event\fR structure. \fIProc\fR must match the following prototype: +.PP .CS typedef int \fBTcl_EventProc\fR( Tcl_Event *\fIevPtr\fR, int \fIflags\fR); .CE +.PP The first argument to \fIproc\fR is a pointer to the event, which will be the same as the first argument to the \fBTcl_QueueEvent\fR call that added the event to the queue. @@ -416,11 +426,13 @@ events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR for each event in the queue, deleting those for with the procedure returns 1. Events for which the procedure returns 0 are left in the queue. \fIProc\fR should match the following prototype: +.PP .CS typedef int \fBTcl_EventDeleteProc\fR( Tcl_Event *\fIevPtr\fR, ClientData \fIclientData\fR); .CE +.PP The \fIclientData\fR argument will be the same as the \fIclientData\fR argument to \fBTcl_DeleteEvents\fR; it is typically used to point to private information managed by the event source. The \fIevPtr\fR will @@ -537,6 +549,7 @@ to another program, such as a Web browser plugin. To do this, the extension makes a call to \fBTcl_SetNotifier\fR passing a pointer to a \fBTcl_NotifierProcs\fR data structure. The structure has the following layout: +.PP .CS typedef struct Tcl_NotifierProcs { Tcl_SetTimerProc *setTimerProc; @@ -549,6 +562,7 @@ typedef struct Tcl_NotifierProcs { Tcl_ServiceModeHookProc *serviceModeHookProc; } \fBTcl_NotifierProcs\fR; .CE +.PP Following the call to \fBTcl_SetNotifier\fR, the pointers given in the \fBTcl_NotifierProcs\fR structure replace whatever notifier had been installed in the process. diff --git a/doc/Object.3 b/doc/Object.3 index 3b6abc8..00b4cec 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.21 2008/07/27 22:18:21 nijtmans Exp $ +'\" RCS: @(#) $Id: Object.3,v 1.22 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures" @@ -109,6 +109,7 @@ by defining their own \fBTcl_ObjType\fR structs. .PP Each Tcl object is represented by a \fBTcl_Obj\fR structure which is defined as follows. +.PP .CS typedef struct Tcl_Obj { int \fIrefCount\fR; @@ -131,6 +132,7 @@ typedef struct Tcl_Obj { } \fIinternalRep\fR; } \fBTcl_Obj\fR; .CE +.PP The \fIbytes\fR and the \fIlength\fR members together hold an object's UTF-8 string representation, which is a \fIcounted string\fR not containing null bytes (UTF-8 null @@ -232,20 +234,26 @@ to see how to create a new object type. .PP As an example of the lifetime of an object, consider the following sequence of commands: +.PP .CS \fBset x 123\fR .CE +.PP This assigns to \fIx\fR an untyped object whose \fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3. The object's \fItypePtr\fR member is NULL. +.PP .CS \fBputs "x is $x"\fR .CE +.PP \fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL) and is fetched for the command. +.PP .CS \fBincr x\fR .CE +.PP The \fBincr\fR command first gets an integer from \fIx\fR's object by calling \fBTcl_GetIntFromObj\fR. This procedure checks whether the object is already an integer object. @@ -260,9 +268,11 @@ then invalidates its string representation (by calling \fBTcl_InvalidateStringRep\fR) since the string representation no longer corresponds to the internal representation. +.PP .CS \fBputs "x is now $x"\fR .CE +.PP The string representation of \fIx\fR's object is needed and is recomputed. The string representation is now \fB124\fR diff --git a/doc/Preserve.3 b/doc/Preserve.3 index e4ae2dc..1a48a56 100644 --- a/doc/Preserve.3 +++ b/doc/Preserve.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: Preserve.3,v 1.7 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: Preserve.3,v 1.8 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures" @@ -79,10 +79,12 @@ calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by All the work of freeing the object is carried out by \fIfreeProc\fR. \fIFreeProc\fR must have arguments and result that match the type \fBTcl_FreeProc\fR: +.PP .CS typedef void \fBTcl_FreeProc\fR( char *\fIblockPtr\fR); .CE +.PP The \fIblockPtr\fR argument to \fIfreeProc\fR will be the same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR. The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 0c7f1ec..da3b3f9 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.19 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: SetResult.3,v 1.20 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures" @@ -215,10 +215,12 @@ This allows applications to use non-standard storage allocators. When Tcl no longer needs the storage for the string, it will call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and result that match the type \fBTcl_FreeProc\fR: +.PP .CS typedef void \fBTcl_FreeProc\fR( char *\fIblockPtr\fR); .CE +.PP 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" diff --git a/doc/SplitList.3 b/doc/SplitList.3 index 04986d5..e70199a 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.14 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: SplitList.3,v 1.15 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures" @@ -81,15 +81,18 @@ also holds copies of all the list elements. It is the caller's responsibility to free up all of this storage. For example, suppose that you have called \fBTcl_SplitList\fR with the following code: +.PP .CS int argc, code; char *string; char **argv; \&... code = Tcl_SplitList(interp, string, &argc, &argv); +.PP .CE Then you should eventually free the storage with a call like the following: +.PP .CS Tcl_Free((char *) argv); .CE diff --git a/doc/SplitPath.3 b/doc/SplitPath.3 index d7380de..e992db4 100644 --- a/doc/SplitPath.3 +++ b/doc/SplitPath.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: SplitPath.3,v 1.9 2004/10/07 15:15:48 dkf Exp $ +'\" RCS: @(#) $Id: SplitPath.3,v 1.10 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures" @@ -61,6 +61,7 @@ holds copies of all the path elements. It is the caller's responsibility to free all of this storage. For example, suppose that you have called \fBTcl_SplitPath\fR with the following code: +.PP .CS int argc; char *path; @@ -68,8 +69,10 @@ char **argv; \&... Tcl_SplitPath(string, &argc, &argv); .CE +.PP Then you should eventually free the storage with a call like the following: +.PP .CS Tcl_Free((char *) argv); .CE diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 index ad50fa6..975b961 100644 --- a/doc/StaticPkg.3 +++ b/doc/StaticPkg.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: StaticPkg.3,v 1.10 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: StaticPkg.3,v 1.11 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" @@ -53,10 +53,12 @@ be invoked, depending on whether the target interpreter is safe or not. \fIinitProc\fR and \fIsafeInitProc\fR must both match the following prototype: +.PP .CS typedef int \fBTcl_PackageInitProc\fR( Tcl_Interp *\fIinterp\fR); .CE +.PP 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 diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 99bfdfb..5e08d8e 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.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: StringObj.3,v 1.28 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: StringObj.3,v 1.29 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" @@ -275,9 +275,11 @@ bytes is necessary to append only whole multi-byte characters. \fBTcl_Format\fR is the C-level interface to the engine of the \fBformat\fR command. The actual command procedure for \fBformat\fR is little more than +.PP .CS Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2); .CE +.PP The \fIobjc\fR Tcl_Obj values in \fIobjv\fR are formatted into a string according to the conversion specification in \fIformat\fR argument, following the documentation for the \fBformat\fR command. The resulting formatted @@ -287,22 +289,26 @@ returned, and an error message is recorded in \fIinterp\fR, if \fIinterp\fR is non-NULL. .PP \fBTcl_AppendFormatToObj\fR is an appending alternative form -of \fBTcl_Format\fR with functionality equivalent to +of \fBTcl_Format\fR with functionality equivalent to: +.PP .CS Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv); if (newPtr == NULL) return TCL_ERROR; Tcl_AppendObjToObj(objPtr, newPtr); return TCL_OK; .CE +.PP but with greater convenience and efficiency when the appending functionality is needed. .PP \fBTcl_ObjPrintf\fR serves as a replacement for the common sequence +.PP .CS char buf[SOME_SUITABLE_LENGTH]; sprintf(buf, format, ...); Tcl_NewStringObj(buf, -1); .CE +.PP but with greater convenience and no need to determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same core formatting engine used by \fBTcl_Format\fR. This means the set of @@ -316,19 +322,23 @@ passing around than the number of encoded characters those bytes happen to represent. The variable number of arguments passed in should be of the types that would be suitable for passing to \fBsprintf\fR. Note in this example usage, \fIx\fR is of type \fBlong\fR. +.PP .CS long x = 5; Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x); .CE +.PP If the value of \fIformat\fR contains internal inconsistencies or invalid specifier formats, the formatted string result produced by \fBTcl_ObjPrintf\fR will be an error message describing the error. .PP \fBTcl_AppendPrintfToObj\fR is an appending alternative form of \fBTcl_ObjPrintf\fR with functionality equivalent to +.PP .CS Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...)); .CE +.PP but with greater convenience and efficiency when the appending functionality is needed. .PP @@ -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.19 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: Tcl.n,v 1.20 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl n "8.5" Tcl "Tcl Built-In Commands" @@ -123,7 +123,7 @@ substitutions are performed on the characters of \fIindex\fR. . \fIName\fR is the name of a scalar variable. It may contain any characters whatsoever except for close braces. -.LP +.PP There may be any number of variable substitutions in a single word. Variable substitution is not performed on words enclosed in braces. .RE @@ -194,7 +194,7 @@ be 0. The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a sixteen-bit hexadecimal value for the Unicode character that will be inserted. -.LP +.PP Backslash substitution is not performed on words enclosed in braces, except for backslash-newline as described above. .RE @@ -219,13 +219,15 @@ no substitutions are performed before making the recursive call and no additional substitutions are performed on the result of the nested script. .RS -.LP +.PP Substitutions take place from left to right, and each substitution is evaluated completely before attempting to evaluate the next. Thus, a sequence like +.PP .CS set y [set x 0][incr x][incr x] .CE +.PP will always set the variable \fIy\fR to the value, \fI012\fR. .RE .IP "[12] \fBSubstitution and word boundaries.\fR" diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index 813f6a1..ee8198f 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.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. '\" -'\" CVS: @(#) $Id: TraceCmd.3,v 1.12 2008/06/29 22:28:24 dkf Exp $ +'\" CVS: @(#) $Id: TraceCmd.3,v 1.13 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" @@ -64,6 +64,7 @@ Invoke \fIproc\fR when the command is deleted. 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: +.PP .CS typedef void \fBTcl_CommandTraceProc\fR( ClientData \fIclientData\fR, @@ -72,6 +73,7 @@ typedef void \fBTcl_CommandTraceProc\fR( const char *\fInewName\fR, int \fIflags\fR); .CE +.PP 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 diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index 02e4c0d..65fa9a7 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.20 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: TraceVar.3,v 1.21 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" @@ -123,6 +123,7 @@ Whenever one of the specified operations occurs on the variable, \fIproc\fR will be invoked. It should have arguments and result that match the type \fBTcl_VarTraceProc\fR: +.PP .CS typedef char *\fBTcl_VarTraceProc\fR( ClientData \fIclientData\fR, @@ -131,6 +132,7 @@ typedef char *\fBTcl_VarTraceProc\fR( char *\fIname2\fR, int \fIflags\fR); .CE +.PP The \fIclientData\fR and \fIinterp\fR parameters will have the same values as those passed to \fBTcl_TraceVar\fR when the trace was created. diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3 index daa729c..323ad40 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.12 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.13 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures" @@ -31,7 +31,6 @@ Additional error information to print after leading arguments from \fIobjv\fR. This typically gives the acceptable syntax of the command. This argument may be NULL. .BE - .SH DESCRIPTION .PP \fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by @@ -45,13 +44,17 @@ elements of \fIobjv\fR plus \fImessage\fR. For example, if .QW "\fBfileName count\fR" then \fIinterp\fR's result object will be set to the following string: +.PP .CS wrong # args: should be "foo fileName count" .CE +.PP If \fIobjc\fR is 2, the result will be set to the following string: +.PP .CS wrong # args: should be "foo bar fileName count" .CE +.PP \fIObjc\fR is usually 1, but may be 2 or more for commands like \fBstring\fR and the Tk widget commands, which use the first argument as a subcommand. @@ -68,12 +71,11 @@ originally passed in. Using the above example, let us assume that \fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object is now an indexObject because it was passed to \fBTcl_GetIndexFromObj\fR. In this case the error message would be: +.PP .CS wrong # args: should be "foo barfly fileName count" .CE - .SH "SEE ALSO" -Tcl_GetIndexFromObj - +Tcl_GetIndexFromObj(3) .SH KEYWORDS command, error message, wrong number of arguments diff --git a/doc/after.n b/doc/after.n index 4e5dfdd..e6d2dd0 100644 --- a/doc/after.n +++ b/doc/after.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: after.n,v 1.11 2008/06/13 05:45:07 mistachkin Exp $ +'\" RCS: @(#) $Id: after.n,v 1.12 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH after n 7.5 Tcl "Tcl Built-In Commands" @@ -26,7 +26,6 @@ after \- Execute a command after a time delay .sp \fBafter info \fR?\fIid\fR? .BE - .SH DESCRIPTION .PP This command is used to delay execution of the program or to execute @@ -34,12 +33,14 @@ a command in background sometime in the future. It has several forms, depending on the first argument to the command: .TP \fBafter \fIms\fR +. \fIMs\fR must be an integer giving a time in milliseconds. The command sleeps for \fIms\fR milliseconds and then returns. While the command is sleeping the application does not respond to events. .TP \fBafter \fIms \fR?\fIscript script script ...\fR? +. In this form the command returns immediately, but it arranges for a Tcl command to be executed \fIms\fR milliseconds later as an event handler. @@ -55,6 +56,7 @@ The \fBafter\fR command returns an identifier that can be used to cancel the delayed command using \fBafter cancel\fR. .TP \fBafter cancel \fIid\fR +. Cancels the execution of a delayed command that was previously scheduled. \fIId\fR indicates which command should be canceled; it must have @@ -63,6 +65,7 @@ If the command given by \fIid\fR has already been executed then the \fBafter cancel\fR command has no effect. .TP \fBafter cancel \fIscript script ...\fR +. This command also cancels the execution of a delayed command. The \fIscript\fR arguments are concatenated together with space separators (just as in the \fBconcat\fR command). @@ -71,6 +74,7 @@ canceled and will never be executed; if no such command is currently pending then the \fBafter cancel\fR command has no effect. .TP \fBafter idle \fIscript \fR?\fIscript script ...\fR? +. Concatenates the \fIscript\fR arguments together with space separators (just as in the \fBconcat\fR command), and arranges for the resulting script to be evaluated later as an idle callback. @@ -83,6 +87,7 @@ background error will be reported by the command registered with \fB interp bgerror\fR. .TP \fBafter info \fR?\fIid\fR? +. This command returns information about existing event handlers. If no \fIid\fR argument is supplied, the command returns a list of the identifiers for all existing @@ -106,6 +111,7 @@ and \fBupdate\fR commands. .SH "EXAMPLES" This defines a command to make Tcl do nothing at all for \fIN\fR seconds: +.PP .CS proc sleep {N} { \fBafter\fR [expr {int($N * 1000)}] @@ -114,6 +120,7 @@ proc sleep {N} { .PP This arranges for the command \fIwake_up\fR to be run in eight hours (providing the event loop is active at that time): +.PP .CS \fBafter\fR [expr {1000 * 60 * 60 * 8}] wake_up .CE @@ -128,6 +135,7 @@ processing steps (arranging for the next step to be done using an already-triggered timer event only when the event queue has been drained) and is useful when you want to ensure that a Tk GUI remains responsive during a slow task. +.PP .CS proc doOneStep {} { if {[::my_calc::one_step]} { @@ -136,9 +144,10 @@ proc doOneStep {} { } doOneStep .CE - .SH "SEE ALSO" concat(n), interp(n), update(n), vwait(n) - .SH KEYWORDS cancel, delay, idle callback, sleep, time +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/append.n b/doc/append.n index 5bf99e4..c044c08 100644 --- a/doc/append.n +++ b/doc/append.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: append.n,v 1.10 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: append.n,v 1.11 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH append n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ append \- Append to variable .SH SYNOPSIS \fBappend \fIvarName \fR?\fIvalue value value ...\fR? .BE - .SH DESCRIPTION .PP Append all of the \fIvalue\fR arguments to the current value @@ -34,6 +33,7 @@ is much more efficient than if \fB$a\fR is long. .SH EXAMPLE Building a string of comma-separated numbers piecemeal using a loop. +.PP .CS set var 0 for {set i 1} {$i<=10} {incr i} { @@ -42,9 +42,10 @@ for {set i 1} {$i<=10} {incr i} { puts $var # Prints 0,1,2,3,4,5,6,7,8,9,10 .CE - .SH "SEE ALSO" concat(n), lappend(n) - .SH KEYWORDS append, variable +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -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: chan.n,v 1.21 2008/10/14 14:02:55 dkf Exp $ +'\" RCS: @(#) $Id: chan.n,v 1.22 2008/10/15 10:43:37 dkf Exp $ .so man.macros .TH chan n 8.5 Tcl "Tcl Built-In Commands" .BS @@ -655,9 +655,11 @@ in which \fBchan configure\fR will alter input). .PP When reading from a serial port, most applications should configure the serial port channel to be nonblocking, like this: +.PP .CS \fBchan configure \fIchannelId \fB\-blocking \fI0\fR. .CE +.PP Then \fBchan read\fR behaves much like described above. Note that most serial ports are comparatively slow; it is entirely possible to get a \fBreadable\fR event for each character read from them. Care diff --git a/doc/clock.n b/doc/clock.n index 600722b..d4bb1b9 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -754,6 +754,7 @@ The C library's idea of the local time zone, as defined by the .PP In case [1] \fIonly,\fR the string is tested to see if it is one of the strings: +.PP .CS gmt ut utc bst wet wat at nft nst ndt ast adt est edt @@ -765,6 +766,7 @@ of the strings: cadt east eadt gst nzt nzst nzdt idle .CE +.PP If it is a string in the above list, it designates a known time zone, and is interpreted as such. .PP @@ -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: dict.n,v 1.18 2007/12/31 00:17:44 dkf Exp $ +'\" RCS: @(#) $Id: dict.n,v 1.19 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH dict n 8.5 Tcl "Tcl Built-In Commands" @@ -23,33 +23,39 @@ below for a description), depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: .TP \fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR? +. This appends the given string (or strings) to the value that the given key maps to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. Non-existent keys are treated as if they map to an empty string. .TP \fBdict create \fR?\fIkey value ...\fR? +. Create a new dictionary that contains each of the key/value mappings listed as arguments (keys and values alternating, with each key being followed by its associated value.) .TP \fBdict exists \fIdictionaryValue key \fR?\fIkey ...\fR? +. This returns a boolean value indicating whether the given key (or path of keys through a set of nested dictionaries) exists in the given dictionary value. This returns a true value exactly when \fBdict get\fR on that path will succeed. .TP \fBdict filter \fIdictionaryValue filterType arg \fR?\fIarg ...\fR? +. This takes a dictionary value and returns a new dictionary that contains just those key/value pairs that match the specified filter type (which may be abbreviated.) Supported filter types are: .RS .TP \fBdict filter \fIdictionaryValue \fBkey \fIglobPattern\fR +. The key rule only matches those key/value pairs whose keys match the given pattern (in the style of \fBstring match\fR.) .TP \fBdict filter \fIdictionaryValue \fBscript {\fIkeyVar valueVar\fB} \fIscript\fR +. The script rule tests for matching by assigning the key to the \fIkeyVar\fR and the value to the \fIvalueVar\fR, and then evaluating the given script which should return a boolean value (with the @@ -63,11 +69,13 @@ result. The key/value pairs are tested in the order in which the keys were inserted into the dictionary. .TP \fBdict filter \fIdictionaryValue \fBvalue \fIglobPattern\fR +. The value rule only matches those key/value pairs whose values match the given pattern (in the style of \fBstring match\fR.) .RE .TP \fBdict for {\fIkeyVar valueVar\fB} \fIdictionaryValue body\fR +. This command takes three arguments, the first a two-element list of variable names (for the key and value respectively of each mapping in the dictionary), the second the dictionary value to iterate across, @@ -82,6 +90,7 @@ normal \fBTCL_OK\fR result. The order of iteration is the order in which the keys were inserted into the dictionary. .TP \fBdict get \fIdictionaryValue \fR?\fIkey ...\fR? +. Given a dictionary value (first argument) and a key (second argument), this will retrieve the value for that key. Where several keys are supplied, the behaviour of the command shall be as if the result of @@ -90,20 +99,23 @@ supplied, the behaviour of the command shall be as if the result of subsequent) arguments. This facilitates lookups in nested dictionaries. For example, the following two commands are equivalent: .RS +.PP .CS dict get $dict foo bar spong dict get [dict get [dict get $dict foo] bar] spong .CE +.PP If no keys are provided, dict would return a list containing pairs of elements in a manner similar to \fBarray get\fR. That is, the first element of each pair would be the key and the second element would be the value for that key. - +.PP It is an error to attempt to retrieve a value for a key that is not present in the dictionary. .RE .TP \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR? +. This adds the given increment value (an integer that defaults to 1 if not specified) to the value that the given key maps to in the dictionary value contained in the given variable, writing the @@ -112,6 +124,7 @@ are treated as if they map to 0. It is an error to increment a value for an existing key if that value is not an integer. .TP \fBdict info \fIdictionaryValue\fR +. This returns information (intended for display to people) about the given dictionary though the format of this data is dependent on the implementation of the dictionary. For dictionaries that are @@ -119,12 +132,14 @@ implemented by hash tables, it is expected that this will return the string produced by \fBTcl_HashStats\fR, similar to \fBarray info\fR. .TP \fBdict keys \fIdictionaryValue \fR?\fIglobPattern\fR? +. Return a list of all keys in the given dictionary value. If a pattern is supplied, only those keys that match it (according to the rules of \fBstring match\fR) will be returned. The returned keys will be in the order that they were inserted into the dictionary. .TP \fBdict lappend \fIdictionaryVariable key \fR?\fIvalue ...\fR? +. This appends the given items to the list value that the given key maps to in the dictionary value contained in the given variable, writing the resulting dictionary value back to that variable. Non-existent @@ -133,6 +148,7 @@ there to be no items to append to the list. It is an error for the value that the key maps to to not be representable as a list. .TP \fBdict merge \fR?\fIdictionaryValue ...\fR? +. Return a dictionary that contains the contents of each of the \fIdictionaryValue\fR arguments. Where two (or more) dictionaries contain a mapping for the same key, the resulting dictionary maps that @@ -140,6 +156,7 @@ key to the value according to the last dictionary on the command line containing a mapping for that key. .TP \fBdict remove \fIdictionaryValue \fR?\fIkey ...\fR? +. Return a new dictionary that is a copy of an old one passed in as first argument except without mappings for each of the keys listed. It is legal for there to be no keys to remove, and it also legal for @@ -147,6 +164,7 @@ any of the keys to be removed to not be present in the input dictionary in the first place. .TP \fBdict replace \fIdictionaryValue \fR?\fIkey value ...\fR? +. Return a new dictionary that is a copy of an old one passed in as first argument except with some values different or some extra key/value pairs added. It is legal for this command to be called with @@ -154,6 +172,7 @@ no key/value pairs, but illegal for this command to be called with a key but no value. .TP \fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR +. This operation takes the name of a variable containing a dictionary value and places an updated dictionary value in that variable containing a mapping from the given key to the given value. When @@ -161,9 +180,11 @@ multiple keys are present, this operation creates or updates a chain of nested dictionaries. .TP \fBdict size \fIdictionaryValue\fR +. Return the number of key/value mappings in the given dictionary value. .TP \fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR? +. This operation (the companion to \fBdict set\fR) takes the name of a variable containing a dictionary value and places an updated dictionary value in that variable that does not contain a mapping for @@ -173,6 +194,7 @@ must be specified, but the last key on the key-path need not exist. All other components on the path must exist. .TP \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR +. Execute the Tcl script in \fIbody\fR with the value for each \fIkey\fR (as found by reading the dictionary value in \fIdictionaryVariable\fR) mapped to the variable \fIvarName\fR. There may be multiple @@ -189,6 +211,7 @@ does not use traces; changes to the \fIdictionaryVariable\fR's contents only happen when \fIbody\fR terminates. .TP \fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR? +. Return a list of all values in the given dictionary value. If a pattern is supplied, only those values that match it (according to the rules of \fBstring match\fR) will be returned. The returned values @@ -196,6 +219,7 @@ will be in the order of that the keys associated with those values were inserted into the dictionary. .TP \fBdict with \fIdictionaryVariable \fR?\fIkey ...\fR? \fIbody\fR +. Execute the Tcl script in \fIbody\fR with the value for each key in \fIdictionaryVariable\fR mapped (in a manner similarly to \fBdict update\fR) to a variable with the same name. Where one or more @@ -229,7 +253,9 @@ and .QW "apple carrot apple banana" are equivalent dictionaries (with different string representations). .SH EXAMPLES +.PP Constructing and using nested dictionaries: +.PP .CS # Data for one employee \fBdict set\fR employeeInfo 12345-A forenames "Joe" @@ -263,6 +289,7 @@ foreach id [\fBdict keys\fR $employeeInfo] { .CE .PP A localizable version of \fBstring toupper\fR: +.PP .CS # Set up the basic C locale set capital [\fBdict create\fR C [\fBdict create\fR]] @@ -285,3 +312,6 @@ set upperCase [string map $upperCaseMap $string] append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n) .SH KEYWORDS dictionary, create, update, lookup, iterate, filter +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/encoding.n b/doc/encoding.n index 1a6983d..c4c9637 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.16 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: encoding.n,v 1.17 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH encoding n "8.1" Tcl "Tcl Built-In Commands" @@ -83,9 +83,11 @@ contain a sequence of Latin-1 characters that correspond to the bytes of the original string. The \fBencoding\fR command can be used to convert this string to the expected Japanese Unicode characters. For example, +.PP .CS set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"] .CE +.PP would return the Unicode string .QW "\eu306F" , which is the Hiragana letter HA. diff --git a/doc/error.n b/doc/error.n index ffc3ebb..5c81878 100644 --- a/doc/error.n +++ b/doc/error.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: error.n,v 1.11 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: error.n,v 1.12 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH error n "" Tcl "Tcl Built-In Commands" @@ -39,14 +39,17 @@ with the \fBcatch\fR command: if a caught error cannot be handled successfully, \fIinfo\fR can be used to return a stack trace reflecting the original point of occurrence of the error: +.PP .CS \fBcatch {...} errMsg set savedInfo $::errorInfo \&... error $errMsg $savedInfo\fR .CE +.PP When working with Tcl 8.5 or later, the following code should be used instead: +.PP .CS \fBcatch {...} errMsg options \&... @@ -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: eval.n,v 1.11 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: eval.n,v 1.12 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH eval n "" Tcl "Tcl Built-In Commands" @@ -27,11 +27,13 @@ evaluation (or any error generated by it). Note that the \fBlist\fR command quotes sequences of words in such a way that they are not further expanded by the \fBeval\fR command. .SH EXAMPLES +.PP Often, it is useful to store a fragment of a script in a variable and execute it later on with extra values appended. This technique is used in a number of places throughout the Tcl core (e.g. in \fBfcopy\fR, \fBlsort\fR and \fBtrace\fR command callbacks). This example shows how to do this using core Tcl commands: +.PP .CS set script { puts "logging now" @@ -57,6 +59,7 @@ easier to make robust in practice. The following procedure acts in a way that is analogous to the \fBlappend\fR command, except it inserts the argument values at the start of the list in the variable: +.PP .CS proc lprepend {varName args} { upvar 1 $varName var @@ -66,6 +69,7 @@ proc lprepend {varName args} { set var [\fBeval\fR [list linsert $var 0] $args] } .CE +.PP However, the last line would now normally be written without \fBeval\fR, like this: .CS @@ -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: exec.n,v 1.24 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: exec.n,v 1.25 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH exec n 8.5 Tcl "Tcl Built-In Commands" @@ -366,9 +366,11 @@ console window is not available to them. . The \fBexec\fR command is fully functional and works as described. .SH "UNIX EXAMPLES" +.PP Here are some examples of the use of the \fBexec\fR command on Unix. .PP To execute a simple program and get its result: +.PP .CS \fBexec\fR uname -a .CE @@ -376,6 +378,7 @@ To execute a simple program and get its result: To execute a program that can return a non-zero result, you should wrap the call to \fBexec\fR in \fBcatch\fR and check the contents of the \fB\-errorcode\fR return option if you have an error: +.PP .CS set status 0 if {[catch {\fBexec\fR grep foo bar.txt} results options]} { @@ -391,10 +394,13 @@ if {[catch {\fBexec\fR grep foo bar.txt} results options]} { When translating a command from a Unix shell invocation, care should be taken over the fact that single quote characters have no special significance to Tcl. Thus: +.PP .CS awk '{sum += $1} END {print sum}' numbers.list .CE +.PP would be translated into something like: +.PP .CS \fBexec\fR awk {{sum += $1} END {print sum}} numbers.list .CE @@ -403,19 +409,23 @@ If you are converting invocations involving shell globbing, you should remember that Tcl does not handle globbing or expand things into multiple arguments by default. Instead you should write things like this: +.PP .CS \fBexec\fR ls -l {*}[glob *.tcl] .CE .SH "WINDOWS EXAMPLES" +.PP Here are some examples of the use of the \fBexec\fR command on Windows. .PP To start an instance of \fInotepad\fR editing a file without waiting for the user to finish editing the file: +.PP .CS \fBexec\fR notepad myfile.txt & .CE .PP To print a text file using \fInotepad\fR: +.PP .CS \fBexec\fR notepad /p myfile.txt .CE @@ -423,10 +433,13 @@ To print a text file using \fInotepad\fR: If a program calls other programs, such as is common with compilers, then you may need to resort to batch files to hide the console windows that sometimes pop up: +.PP .CS \fBexec\fR cmp.bat somefile.c -o somefile .CE +.PP With the file \fIcmp.bat\fR looking something like: +.PP .CS @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9 .CE @@ -444,6 +457,7 @@ applies especially when you want to run commands like \fIdir\fR from a Tcl script (if you just want to list filenames, use the \fBglob\fR command.) To do that, use this: +.PP .CS \fBexec\fR {*}[auto_execok dir] *.tcl .CE @@ -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: expr.n,v 1.35 2008/06/29 22:28:24 dkf Exp $ +'\" RCS: @(#) $Id: expr.n,v 1.36 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH expr n 8.5 Tcl "Tcl Built-In Commands" @@ -28,9 +28,11 @@ as the corresponding C operators. Expressions almost always yield numeric results (integer or floating-point values). For example, the expression +.PP .CS \fBexpr 8.2 + 6\fR .CE +.PP evaluates to 14.2. Tcl expressions differ from C expressions in the way that operands are specified. Also, Tcl expressions support @@ -205,18 +207,22 @@ divide operators, and produces a result that is the same as the output of the \fBpow\fR function (after any type conversions.) All of the binary operators group left-to-right within the same precedence level. For example, the command +.PP .CS \fBexpr\fR {4*2 < 7} .CE +.PP returns 0. .PP The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have .QW "lazy evaluation" , just as in C, which means that operands are not evaluated if they are not needed to determine the outcome. For example, in the command +.PP .CS \fBexpr {$v ? [a] : [b]}\fR .CE +.PP only one of .QW \fB[a]\fR or @@ -235,14 +241,19 @@ When the expression parser encounters a mathematical function such as \fBsin($x)\fR, it replaces it with a call to an ordinary Tcl function in the \fBtcl::mathfunc\fR namespace. The processing of an expression such as: +.PP .CS \fBexpr {sin($x+$y)}\fR .CE +.PP is the same in every way as the processing of: +.PP .CS \fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}\fR .CE +.PP which in turn is the same as the processing of: +.PP .CS \fBtcl::mathfunc::sin [expr {$x+$y}]\fR .CE @@ -280,23 +291,29 @@ and string operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is introduced, after which floating-point is used. For example, +.PP .CS \fBexpr\fR {5 / 4} .CE +.PP returns 1, while +.PP .CS \fBexpr\fR {5 / 4.0} \fBexpr\fR {5 / ( [string length "abcd"] + 0.0 )} .CE +.PP both return 1.25. Floating-point values are always returned with a .QW \fB.\fR or an .QW \fBe\fR so that they will not look like integer values. For example, +.PP .CS \fBexpr\fR {20.0/5.0} .CE +.PP returns \fB4.0\fR, not \fB4\fR. .SS "STRING OPERATIONS" .PP @@ -311,10 +328,12 @@ Canonical string representation for integer values is a decimal string format. Canonical string representation for floating-point values is that produced by the \fB%g\fR format specifier of Tcl's \fBformat\fR command. For example, the commands +.PP .CS \fBexpr {"0x03" > "2"}\fR \fBexpr {"0y" < "0x12"}\fR .CE +.PP both return 1. The first comparison is done using integer comparison, and the second is done using string comparison after the second operand is converted to the string \fB18\fR. @@ -332,11 +351,13 @@ This allows the Tcl bytecode compiler to generate the best code. As mentioned above, expressions are substituted twice: once by the Tcl parser and once by the \fBexpr\fR command. For example, the commands +.PP .CS \fBset a 3\fR \fBset b {$a + 2}\fR \fBexpr $b*4\fR .CE +.PP return 11, not a multiple of 4. This is because the Tcl parser will first substitute \fB$a + 2\fR for the variable \fBb\fR, @@ -362,6 +383,7 @@ operator, consider using the commands documented in the \fBmathfunc\fR(n) or Define a procedure that computes an .QW interesting mathematical function: +.PP .CS proc tcl::mathfunc::calc {x y} { \fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) } @@ -369,6 +391,7 @@ proc tcl::mathfunc::calc {x y} { .CE .PP Convert polar coordinates into cartesian coordinates: +.PP .CS # convert from ($radius,$angle) set x [\fBexpr\fR { $radius * cos($angle) }] @@ -376,6 +399,7 @@ set y [\fBexpr\fR { $radius * sin($angle) }] .CE .PP Convert cartesian coordinates into polar coordinates: +.PP .CS # convert from ($x,$y) set radius [\fBexpr\fR { hypot($y, $x) }] @@ -384,12 +408,14 @@ set angle [\fBexpr\fR { atan2($y, $x) }] .PP Print a message describing the relationship of two string values to each other: +.PP .CS puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]" .CE .PP Set a variable to whether an environment variable is both defined at all and also set to a true boolean value: +.PP .CS set isTrue [\fBexpr\fR { [info exists ::env(SOME_ENV_VAR)] && @@ -398,6 +424,7 @@ set isTrue [\fBexpr\fR { .CE .PP Generate a random integer in the range 0..99 inclusive: +.PP .CS set randNum [\fBexpr\fR { int(100 * rand()) }] .CE @@ -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: file.n,v 1.54 2008/09/24 19:31:28 dgp Exp $ +'\" RCS: @(#) $Id: file.n,v 1.55 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH file n 8.3 Tcl "Tcl Built-In Commands" @@ -138,20 +138,26 @@ only contains one path element, then returns If \fIname\fR refers to a root directory, then the root directory is returned. For example, .RS +.PP .CS \fBfile dirname c:/\fR .CE +.PP returns \fBc:/\fR. .PP Note that tilde substitution will only be performed if it is necessary to complete the command. For example, +.PP .CS \fBfile dirname ~/src/foo.c\fR .CE +.PP returns \fB~/src\fR, whereas +.PP .CS \fBfile dirname ~\fR .CE +.PP returns \fB/home\fR (or something similar). .RE .TP @@ -187,9 +193,11 @@ relative, then it will be joined to the previous file name argument. Otherwise, any earlier arguments will be discarded, and joining will proceed from the current argument. For example, .RS +.PP .CS \fBfile join a b /foo bar\fR .CE +.PP returns \fB/foo/bar\fR. .PP Note that any of the names can contain separators, and that the result @@ -372,10 +380,14 @@ All other elements will be relative. Path separators will be discarded unless they are needed ensure that an element is unambiguously relative. For example, under Unix .RS +.PP .CS file split /foo/~bar/baz .CE -returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands +.PP +returns +.QW \fB/\0\0foo\0\0./~bar\0\0baz\fR +to ensure that later commands that use the third component do not attempt to perform tilde substitution. .RE @@ -453,9 +465,11 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user, These commands always operate using the real user and group identifiers, not the effective ones. .SH EXAMPLES +.PP This procedure shows how to search for C files in a given directory that have a correspondingly-named object file in the current directory: +.PP .CS proc findMatchingCFiles {dir} { set files {} @@ -479,6 +493,7 @@ proc findMatchingCFiles {dir} { .PP Rename a file and leave a symbolic link pointing from the old location to the new place: +.PP .CS set oldName foobar.txt set newName foo/bar.txt @@ -495,6 +510,7 @@ On Windows, a file can be easily enough (equivalent to double-clicking on it in the Explorer interface) but the name passed to the operating system must be in native format: +.PP .CS exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt] .CE diff --git a/doc/fileevent.n b/doc/fileevent.n index ba35bdf..05d68f3 100644 --- a/doc/fileevent.n +++ b/doc/fileevent.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: fileevent.n,v 1.14 2008/06/24 14:42:51 patthoyts Exp $ +'\" RCS: @(#) $Id: fileevent.n,v 1.15 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH fileevent n 7.5 Tcl "Tcl Built-In Commands" @@ -107,12 +107,14 @@ In addition, the file event handler is deleted if it ever returns an error; this is done in order to prevent infinite loops due to buggy handlers. .SH EXAMPLE +.PP In this setup \fBGetData\fR will be called with the channel as an argument whenever $chan becomes readable. The \fBread\fR call will read whatever binary data is currently available without blocking. Here the channel has the fileevent removed when an end of file occurs to avoid being continually called (see above). Alternatively the channel may be closed on this condition. +.PP .CS proc GetData {chan} { set data [read $chan] @@ -125,8 +127,10 @@ proc GetData {chan} { fconfigure $chan -blocking 0 -encoding binary fileevent $chan readable [list GetData $chan] .CE +.PP The next example demonstrates use of \fBgets\fR to read line-oriented data. +.PP .CS proc GetData {chan} { if {[gets $chan line] >= 0} { @@ -140,15 +144,12 @@ proc GetData {chan} { fconfigure $chan -blocking 0 -buffering line -translation crlf fileevent $chan readable [list GetData $chan] .CE - .SH CREDITS .PP \fBfileevent\fR is based on the \fBaddinput\fR command created by Mark Diekhans. - .SH "SEE ALSO" fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3) - .SH KEYWORDS asynchronous I/O, blocking, channel, event handler, nonblocking, readable, script, writable. @@ -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: glob.n,v 1.23 2008/09/29 16:03:29 dgp Exp $ +'\" RCS: @(#) $Id: glob.n,v 1.24 2008/10/15 10:43:37 dkf Exp $ '\" .so man.macros .TH glob n 8.3 Tcl "Tcl Built-In Commands" @@ -98,11 +98,13 @@ The two forms may be mixed, so \fB\-types {d f r w}\fR will find all regular files OR directories that have both read AND write permissions. The following are equivalent: .RS +.PP .CS \fBglob \-type d *\fR \fBglob */\fR .CE .RE +.PP except that the first case doesn't return the trailing .QW / and is more platform independent. @@ -206,18 +208,22 @@ to use the Unix style forward slash as a path separator. Windows style paths can be converted to Unix style paths with the command \fBfile join $path\fR (or \fBfile normalize $path\fR in Tcl 8.4). .SH EXAMPLES +.PP Find all the Tcl files in the current directory: +.PP .CS \fBglob\fR *.tcl .CE .PP Find all the Tcl files in the user's home directory, irrespective of what the current directory is: +.PP .CS \fBglob\fR \-directory ~ *.tcl .CE .PP Find all subdirectories of the current directory: +.PP .CS \fBglob\fR \-type d * .CE @@ -228,12 +234,11 @@ a .QW b or the sequence .QW cde : +.PP .CS \fBglob\fR \-type f *{a,b,cde}* .CE - .SH "SEE ALSO" file(n) - .SH KEYWORDS exist, file, glob, pattern |