diff options
| author | dkf <donal.k.fellows@manchester.ac.uk> | 2008-06-29 22:28:20 (GMT) |
|---|---|---|
| committer | dkf <donal.k.fellows@manchester.ac.uk> | 2008-06-29 22:28:20 (GMT) |
| commit | 131a59f68c8b1673c1fcd9b035bb7791eea72bc9 (patch) | |
| tree | cdb9d2219449fc94b2623bab245f0b0cdcf45c52 | |
| parent | 7b7bac281c6cba5b97c0962a4032cc39dcc6308f (diff) | |
| download | tcl-131a59f68c8b1673c1fcd9b035bb7791eea72bc9.zip tcl-131a59f68c8b1673c1fcd9b035bb7791eea72bc9.tar.gz tcl-131a59f68c8b1673c1fcd9b035bb7791eea72bc9.tar.bz2 | |
Prepare Tcl's docs for life as 8.6 (remove out of date change bars, fix
typedefs, add a few missing bits)
80 files changed, 831 insertions, 836 deletions
@@ -1,3 +1,9 @@ +2008-06-29 Donal K. Fellows <dkf@users.sf.net> + + * doc/*.1, doc/*.3, doc/*.n: Many small updates, purging out of date + change bars and cleaning up the formatting of typedefs. Added a few + missing bits of documentation in the process. + 2008-06-29 Don Porter <dgp@users.sourceforge.net> * generic/tclPathObj.c: Plug memory leak in [Bug 1999176] fix. Thanks diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index cef07c8..161de0c 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.20 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: AddErrInfo.3,v 1.21 2008/06/29 22:28:21 dkf Exp $ '\" .so man.macros .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures" @@ -15,20 +15,16 @@ Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErr .SH SYNOPSIS .nf \fB#include <tcl.h>\fR -.VS 8.5 .sp Tcl_Obj * \fBTcl_GetReturnOptions\fR(\fIinterp, code\fR) .sp int \fBTcl_SetReturnOptions\fR(\fIinterp, options\fR) -.VE 8.5 .sp \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR) -.VS 8.5 .sp \fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR) -.VE 8.5 .sp \fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR) .sp @@ -59,11 +55,9 @@ this points to the first byte of an array of \fIlength\fR bytes containing a string to append to the \fB\-errorinfo\fR return option. This byte array may contain embedded null bytes unless \fIlength\fR is negative. -.VS 8.5 .AP Tcl_Obj *objPtr in A message to be appended to the \fB\-errorinfo\fR return option in the form of a Tcl_Obj value. -.VE 8.5 .AP int length in The number of bytes to copy from \fImessage\fR when appending to the \fB\-errorinfo\fR return option. @@ -86,7 +80,6 @@ Number of bytes in command; -1 means use all bytes up to first null byte .SH DESCRIPTION .PP -.VS 8.5 The \fBTcl_SetReturnOptions\fR and \fBTcl_GetReturnOptions\fR routines expose the same capabilities as the \fBreturn\fR and \fBcatch\fR commands, respectively, in the form of a C interface. @@ -163,7 +156,6 @@ notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return options should be set properly when the command procedure of a command returns \fBTCL_ERROR\fR. Tcl provides several simpler interfaces to more directly set these return options. -.VE 8.5 .PP The \fB\-errorinfo\fR option holds a stack trace of the operations that were in progress when an error occurred, @@ -209,12 +201,10 @@ The value of the \fB\-errorline\fR return option (retrieved via a call to \fBTcl_GetReturnOptions\fR) often makes up a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR. .PP -.VS 8.5 \fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the same functionality as \fBTcl_AddErrorInfo\fR. \fBTcl_AppendObjToErrorInfo\fR is called when the string value to be appended to the \fB\-errorinfo\fR option is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array. -.VE 8.5 .PP \fBTcl_AddObjErrorInfo\fR is nearly identical to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR diff --git a/doc/AssocData.3 b/doc/AssocData.3 index 6fb16ed..2b85137 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.7 2004/10/07 15:15:35 dkf Exp $ +'\" RCS: @(#) $Id: AssocData.3,v 1.8 2008/06/29 22:28:23 dkf Exp $ .so man.macros .TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures" .BS @@ -64,7 +64,7 @@ procedure to invoke if the interpreter is deleted before the association is deleted. \fIDeleteProc\fR should have arguments and result that match the type \fBTcl_InterpDeleteProc\fR: .CS -typedef void Tcl_InterpDeleteProc( +typedef void \fBTcl_InterpDeleteProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE diff --git a/doc/Async.3 b/doc/Async.3 index afcfcd3..346a26c 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.12 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: Async.3,v 1.13 2008/06/29 22:28:23 dkf Exp $ '\" .so man.macros .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures" @@ -84,7 +84,7 @@ the actions associated with the asynchronous event. \fIProc\fR should have arguments and result that match the type \fBTcl_AsyncProc\fR: .CS -typedef int Tcl_AsyncProc( +typedef int \fBTcl_AsyncProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIcode\fR); diff --git a/doc/CallDel.3 b/doc/CallDel.3 index e2abc8c..9c225e0 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.6 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: CallDel.3,v 1.7 2008/06/29 22:28:23 dkf Exp $ '\" .so man.macros .TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures" @@ -39,7 +39,7 @@ time of the call. \fIProc\fR should have arguments and result that match the type \fBTcl_InterpDeleteProc\fR: .CS -typedef void Tcl_InterpDeleteProc( +typedef void \fBTcl_InterpDeleteProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE diff --git a/doc/Class.3 b/doc/Class.3 index 8954ab7..b7e17db 100644 --- a/doc/Class.3 +++ b/doc/Class.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: Class.3,v 1.1 2008/05/31 11:42:06 dkf Exp $ +'\" RCS: @(#) $Id: Class.3,v 1.2 2008/06/29 22:28:23 dkf Exp $ '\" .so man.macros .TH Tcl_Class 3 0.1 TclOO "TclOO Library Functions" @@ -137,12 +137,12 @@ remove a piece of metadata that was not attached. The contents of the Tcl_ObjectMetadataType structure are as follows: .PP .CS - typedef const struct { - int \fIversion\fR; - const char *\fIname\fR; - Tcl_ObjectMetadataDeleteProc \fIdeleteProc\fR; - Tcl_CloneProc \fIcloneProc\fR; - } \fBTcl_ObjectMetadataType\fR; +typedef const struct { + int \fIversion\fR; + const char *\fIname\fR; + Tcl_ObjectMetadataDeleteProc \fIdeleteProc\fR; + Tcl_CloneProc \fIcloneProc\fR; +} \fBTcl_ObjectMetadataType\fR; .CE .PP The \fIversion\fR field allows for future expansion of the structure, and @@ -165,8 +165,8 @@ Functions matching this signature are used to delete metadata associated with a class or object. .PP .CS - typedef void (*\fBTcl_ObjectMetadataDeleteProc\fR) ( - ClientData \fImetadata\fR); +typedef void \fBTcl_ObjectMetadataDeleteProc\fR( + ClientData \fImetadata\fR); .CE .PP The \fImetadata\fR argument gives the address of the metadata to be @@ -177,10 +177,10 @@ Functions matching this signature are used to create copies of metadata associated with a class or object. .PP .CS - typedef int (*\fBTcl_CloneProc\fR) ( - Tcl_Interp *\fIinterp\fR, - ClientData \fIsrcMetadata\fR, - ClientData *\fIdstMetadataPtr\fR); +typedef int \fBTcl_CloneProc\fR( + Tcl_Interp *\fIinterp\fR, + ClientData \fIsrcMetadata\fR, + ClientData *\fIdstMetadataPtr\fR); .CE .PP The \fIinterp\fR argument gives a place to write an error message when the @@ -204,11 +204,11 @@ method implementations is to be used. The \fITcl_ObjectMapMethodNameProc\fR callback is defined as follows: .PP .CS - typedef int (*\fBTcl_ObjectMapMethodNameProc\fR)( - Tcl_Interp *\fIinterp\fR, - Tcl_Object \fIobject\fR, - Tcl_Class *\fIstartClsPtr\fR, - Tcl_Obj *\fImethodNameObj\fR); +typedef int \fBTcl_ObjectMapMethodNameProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Object \fIobject\fR, + Tcl_Class *\fIstartClsPtr\fR, + Tcl_Obj *\fImethodNameObj\fR); .CE .PP The \fIinterp\fR parameter (and the integer result) follow normal Tcl result diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 613ed90..a4a6c4c 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.40 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: CrtChannel.3,v 1.41 2008/06/29 22:28:23 dkf Exp $ .so man.macros .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -98,10 +98,8 @@ Tcl_DriverWideSeekProc * Tcl_DriverThreadActionProc * \fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR) .sp -.VS 8.5 Tcl_DriverTruncateProc * \fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR) -.VE 8.5 .sp Tcl_DriverSetOptionProc * \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR) @@ -159,9 +157,7 @@ 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. - .BE - .SH DESCRIPTION .PP Tcl uses a two-layered channel architecture. It provides a generic upper @@ -290,20 +286,16 @@ name is registered in the (thread)-global list of all channels (result (thread)global list of all channels (of the current thread). Application to a channel still registered in some interpreter is not allowed. -.VS 8.5 Also notifies the driver if the \fBTcl_ChannelType\fR version is \fBTCL_CHANNEL_VERSION_4\fR (or higher), and \fBTcl_DriverThreadActionProc\fR is defined for it. -.VE 8.5 .PP \fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the (thread)global list of all channels (of the current thread). Application to a channel registered in some interpreter is not allowed. -.VS 8.5 Also notifies the driver if the \fBTcl_ChannelType\fR version is \fBTCL_CHANNEL_VERSION_4\fR (or higher), and \fBTcl_DriverThreadActionProc\fR is defined for it. -.VE 8.5 .PP \fBTcl_ClearChannelHandlers\fR removes all channelhandlers and event scripts associated with the specified \fIchannel\fR, thus shutting @@ -336,10 +328,8 @@ typedef struct Tcl_ChannelType { Tcl_DriverHandlerProc *\fIhandlerProc\fR; Tcl_DriverWideSeekProc *\fIwideSeekProc\fR; Tcl_DriverThreadActionProc *\fIthreadActionProc\fR; -.VS 8.5 Tcl_DriverTruncateProc *\fItruncateProc\fR; -.VE 8.5 -} Tcl_ChannelType; +} \fBTcl_ChannelType\fR; .CE .PP It is not necessary to provide implementations for all channel @@ -360,9 +350,7 @@ structure, the following functions should be used to obtain the values: \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR, \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR, \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR, -.VS 8.5 \fBTcl_ChannelTruncateProc\fR, -.VE 8.5 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR, \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR, \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR. @@ -387,11 +375,9 @@ that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended. \fBTCL_CHANNEL_VERSION_3\fR must be set to specifiy the \fIwideSeekProc\fR member. \fBTCL_CHANNEL_VERSION_4\fR must be set to specifiy the \fIthreadActionProc\fR member (includes \fIwideSeekProc\fR). -.VS 8.5 \fBTCL_CHANNEL_VERSION_5\fR must be set to specifiy the \fItruncateProc\fR members (includes \fIwideSeekProc\fR and \fIthreadActionProc\fR). -.VE 8.5 If it is not set to any of these, then this \fBTcl_ChannelType\fR is assumed to have the original structure. See \fBOLD CHANNEL TYPES\fR for more details. While Tcl will recognize @@ -400,9 +386,7 @@ least \fBTCL_CHANNEL_VERSION_2\fR to function correctly. .PP This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns one of -.VS 8.5 \fBTCL_CHANNEL_VERSION_5\fR, -.VE 8.5 \fBTCL_CHANNEL_VERSION_4\fR, \fBTCL_CHANNEL_VERSION_3\fR, \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR. @@ -413,7 +397,7 @@ the generic layer to set blocking and nonblocking mode on the device. \fIBlockModeProc\fR should match the following prototype: .PP .CS -typedef int Tcl_DriverBlockModeProc( +typedef int \fBTcl_DriverBlockModeProc\fR( ClientData \fIinstanceData\fR, int \fImode\fR); .CE @@ -448,7 +432,7 @@ generic layer to clean up driver-related information when the channel is closed. \fICloseProc\fR must match the following prototype: .PP .CS -typedef int Tcl_DriverCloseProc( +typedef int \fBTcl_DriverCloseProc\fR( ClientData \fIinstanceData\fR, Tcl_Interp *\fIinterp\fR); .CE @@ -470,7 +454,7 @@ independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set following prototype: .PP .CS -typedef int Tcl_DriverClose2Proc( +typedef int \fBTcl_DriverClose2Proc\fR( ClientData \fIinstanceData\fR, Tcl_Interp *\fIinterp\fR, int \fIflags\fR); @@ -501,7 +485,7 @@ generic layer to read data from the file or device and store it in an internal buffer. \fIInputProc\fR must match the following prototype: .PP .CS -typedef int Tcl_DriverInputProc( +typedef int \fBTcl_DriverInputProc\fR( ClientData \fIinstanceData\fR, char *\fIbuf\fR, int \fIbufSize\fR, @@ -545,7 +529,7 @@ generic layer to transfer data from an internal buffer to the output device. \fIOutputProc\fR must match the following prototype: .PP .CS -typedef int Tcl_DriverOutputProc( +typedef int \fBTcl_DriverOutputProc\fR( ClientData \fIinstanceData\fR, const char *\fIbuf\fR, int \fItoWrite\fR, @@ -584,7 +568,7 @@ operations will be applied. \fISeekProc\fR must match the following prototype: .PP .CS -typedef int Tcl_DriverSeekProc( +typedef int \fBTcl_DriverSeekProc\fR( ClientData \fIinstanceData\fR, long \fIoffset\fR, int \fIseekMode\fR, @@ -614,7 +598,7 @@ in preference to the \fIseekProc\fR, but both must be defined if the following prototype: .PP .CS -typedef Tcl_WideInt Tcl_DriverWideSeekProc( +typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR( ClientData \fIinstanceData\fR, Tcl_WideInt \fIoffset\fR, int \fIseekMode\fR, @@ -636,7 +620,7 @@ the generic layer to set a channel type specific option on a channel. \fIsetOptionProc\fR must match the following prototype: .PP .CS -typedef int Tcl_DriverSetOptionProc( +typedef int \fBTcl_DriverSetOptionProc\fR( ClientData \fIinstanceData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIoptionName\fR, @@ -677,7 +661,7 @@ the generic layer to get the value of a channel type specific option on a channel. \fIgetOptionProc\fR must match the following prototype: .PP .CS -typedef int Tcl_DriverGetOptionProc( +typedef int \fBTcl_DriverGetOptionProc\fR( ClientData \fIinstanceData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIoptionName\fR, @@ -715,7 +699,7 @@ notice events of interest on this channel. \fIWatchProc\fR should match the following prototype: .PP .CS -typedef void Tcl_DriverWatchProc( +typedef void \fBTcl_DriverWatchProc\fR( ClientData \fIinstanceData\fR, int \fImask\fR); .CE @@ -746,7 +730,7 @@ the generic layer to retrieve a device-specific handle from the channel. \fIGetHandleProc\fR should match the following prototype: .PP .CS -typedef int Tcl_DriverGetHandleProc( +typedef int \fBTcl_DriverGetHandleProc\fR( ClientData \fIinstanceData\fR, int \fIdirection\fR, ClientData *\fIhandlePtr\fR); @@ -775,7 +759,7 @@ It should be set to NULL. \fIFlushProc\fR should match the following prototype: .PP .CS -typedef int Tcl_DriverFlushProc( +typedef int \fBTcl_DriverFlushProc\fR( ClientData \fIinstanceData\fR); .CE .PP @@ -790,7 +774,7 @@ that occur on the underlying (stacked) channel. \fIHandlerProc\fR should match the following prototype: .PP .CS -typedef int Tcl_DriverHandlerProc( +typedef int \fBTcl_DriverHandlerProc\fR( ClientData \fIinstanceData\fR, int \fIinterestMask\fR); .CE @@ -819,9 +803,9 @@ might be maintaining using the calling thread as the associate. See \fBTcl_CutChannel\fR and \fBTcl_SpliceChannel\fR for more detail. .PP .CS -typedef void Tcl_DriverThreadActionProc( +typedef void \fBTcl_DriverThreadActionProc\fR( ClientData \fIinstanceData\fR, - int \fIaction\fR); + int \fIaction\fR); .CE .PP \fIInstanceData\fR is the same as the value passed to @@ -836,7 +820,7 @@ called by the generic layer when a channel is truncated to some length. It can be NULL. .PP .CS -typedef int Tcl_DriverTruncateProc( +typedef int \fBTcl_DriverTruncateProc\fR( ClientData \fIinstanceData\fR, Tcl_WideInt \fIlength\fR); .CE @@ -891,18 +875,18 @@ the following fields: .PP .CS typedef struct Tcl_ChannelType { - char *\fItypeName\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; - Tcl_DriverCloseProc *\fIcloseProc\fR; - Tcl_DriverInputProc *\fIinputProc\fR; - Tcl_DriverOutputProc *\fIoutputProc\fR; - Tcl_DriverSeekProc *\fIseekProc\fR; - Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; - Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; - Tcl_DriverWatchProc *\fIwatchProc\fR; - Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; - Tcl_DriverClose2Proc *\fIclose2Proc\fR; -} Tcl_ChannelType; + char *\fItypeName\fR; + Tcl_DriverBlockModeProc *\fIblockModeProc\fR; + Tcl_DriverCloseProc *\fIcloseProc\fR; + Tcl_DriverInputProc *\fIinputProc\fR; + Tcl_DriverOutputProc *\fIoutputProc\fR; + Tcl_DriverSeekProc *\fIseekProc\fR; + Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; + Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; + Tcl_DriverWatchProc *\fIwatchProc\fR; + Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; + Tcl_DriverClose2Proc *\fIclose2Proc\fR; +} \fBTcl_ChannelType\fR; .CE .PP It is still possible to create channel with the above structure. The @@ -917,29 +901,27 @@ contained the following fields: .PP .CS typedef struct Tcl_ChannelType { - char *\fItypeName\fR; - Tcl_ChannelTypeVersion \fIversion\fR; - Tcl_DriverCloseProc *\fIcloseProc\fR; - Tcl_DriverInputProc *\fIinputProc\fR; - Tcl_DriverOutputProc *\fIoutputProc\fR; - Tcl_DriverSeekProc *\fIseekProc\fR; - Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; - Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; - Tcl_DriverWatchProc *\fIwatchProc\fR; - Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; - Tcl_DriverClose2Proc *\fIclose2Proc\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; - Tcl_DriverFlushProc *\fIflushProc\fR; - Tcl_DriverHandlerProc *\fIhandlerProc\fR; - Tcl_DriverTruncateProc *\fItruncateProc\fR; -} Tcl_ChannelType; + char *\fItypeName\fR; + Tcl_ChannelTypeVersion \fIversion\fR; + Tcl_DriverCloseProc *\fIcloseProc\fR; + Tcl_DriverInputProc *\fIinputProc\fR; + Tcl_DriverOutputProc *\fIoutputProc\fR; + Tcl_DriverSeekProc *\fIseekProc\fR; + Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; + Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; + Tcl_DriverWatchProc *\fIwatchProc\fR; + Tcl_DriverGetHandleProc *\fIgetHandleProc\fR; + Tcl_DriverClose2Proc *\fIclose2Proc\fR; + Tcl_DriverBlockModeProc *\fIblockModeProc\fR; + Tcl_DriverFlushProc *\fIflushProc\fR; + Tcl_DriverHandlerProc *\fIhandlerProc\fR; + Tcl_DriverTruncateProc *\fItruncateProc\fR; +} \fBTcl_ChannelType\fR; .CE .PP When the above structure is registered as a channel type, the \fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR. - .SH "SEE ALSO" Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3) - .SH KEYWORDS blocking, channel driver, channel registration, channel type, nonblocking diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3 index 790dcd3..5cb6b0c 100644 --- a/doc/CrtChnlHdlr.3 +++ b/doc/CrtChnlHdlr.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: CrtChnlHdlr.3,v 1.6 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: CrtChnlHdlr.3,v 1.7 2008/06/29 22:28:23 dkf Exp $ .so man.macros .TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures" .BS @@ -36,7 +36,6 @@ 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 @@ -48,7 +47,7 @@ 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( +typedef void \fBTcl_ChannelProc\fR( ClientData \fIclientData\fR, int \fImask\fR); .CE @@ -84,9 +83,7 @@ so that the channel is no longer readable when the second handler is invoked. For this reason it may be useful to use nonblocking I/O on channels for which there are event handlers. - .SH "SEE ALSO" Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). - .SH KEYWORDS blocking, callback, channel, events, handler, nonblocking. diff --git a/doc/CrtCloseHdlr.3 b/doc/CrtCloseHdlr.3 index 6d55d9d..4fe6c5c 100644 --- a/doc/CrtCloseHdlr.3 +++ b/doc/CrtCloseHdlr.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: CrtCloseHdlr.3,v 1.3 2004/10/07 14:44:31 dkf Exp $ +'\" RCS: @(#) $Id: CrtCloseHdlr.3,v 1.4 2008/06/29 22:28:23 dkf Exp $ .so man.macros .TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures" .BS @@ -30,7 +30,6 @@ The procedure to call as the callback. .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE - .SH DESCRIPTION .PP \fBTcl_CreateCloseHandler\fR arranges for \fIproc\fR to be called when @@ -39,7 +38,7 @@ Arbitrary one-word value to pass to \fIproc\fR. \fIProc\fR should match the following prototype: .PP .CS -typedef void Tcl_CloseProc( +typedef void \fBTcl_CloseProc\fR( ClientData \fIclientData\fR); .CE .PP @@ -51,9 +50,7 @@ The \fIproc\fR and \fIclientData\fR identify which close callback to remove; \fBTcl_DeleteCloseHandler\fR does nothing if its \fIproc\fR and \fIclientData\fR arguments do not match the \fIproc\fR and \fIclientData\fR for a close handler for \fIchannel\fR. - .SH "SEE ALSO" close(n), Tcl_Close(3), Tcl_UnregisterChannel(3) - .SH KEYWORDS callback, channel closing diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3 index 17938af..d9aab23 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.14 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: CrtCommand.3,v 1.15 2008/06/29 22:28:23 dkf Exp $ '\" .so man.macros .TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures" @@ -34,7 +34,6 @@ Procedure to call before \fIcmdName\fR is deleted from the interpreter; allows for command-specific cleanup. If NULL, then no procedure is called before the command is deleted. .BE - .SH DESCRIPTION .PP \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates @@ -78,7 +77,7 @@ and it returns NULL. \fIProc\fR should have arguments and result that match the type \fBTcl_CmdProc\fR: .CS -typedef int Tcl_CmdProc( +typedef int \fBTcl_CmdProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIargc\fR, @@ -124,22 +123,21 @@ anywhere within the \fIargv\fR values. Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want to return something from the \fIargv\fR array. .PP -\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted. -This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR, +\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted. This can +occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR, or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR. \fIDeleteProc\fR is invoked before the command is deleted, and gives the application an opportunity to release any structures associated with the command. \fIDeleteProc\fR should have arguments and result that match the type \fBTcl_CmdDeleteProc\fR: .CS -typedef void Tcl_CmdDeleteProc( +typedef void \fBTcl_CmdDeleteProc\fR( ClientData \fIclientData\fR); .CE The \fIclientData\fR argument will be the same as the \fIclientData\fR argument passed to \fBTcl_CreateCommand\fR. - .SH "SEE ALSO" -Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult - +Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, +Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult .SH KEYWORDS bind, command, create, delete, interpreter, namespace diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3 index e463c7c..4b352ba 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.8 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.9 2008/06/29 22:28:23 dkf Exp $ '\" .so man.macros .TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures" @@ -34,7 +34,6 @@ 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 @@ -52,7 +51,7 @@ as \fBvwait\fR. \fIProc\fR should have arguments and result that match the type \fBTcl_FileProc\fR: .CS -typedef void Tcl_FileProc( +typedef void \fBTcl_FileProc\fR( ClientData \fIclientData\fR, int \fImask\fR); .CE @@ -86,7 +85,6 @@ complete the application will not be able to service other events. Use blocking or nonblocking mode as required. .PP Note that these interfaces are only supported by the Unix -implementation of the Tcl notifier. - +implementation of the Tcl notifier. .SH KEYWORDS callback, file, handler diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3 index e238e50..3ad4a00 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.17 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.18 2008/06/29 22:28:23 dkf Exp $ '\" .so man.macros .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures" @@ -59,7 +59,6 @@ created if the function is not implemented directly in bytecode. Pattern to match against function names so as to filter them (by passing to \fITcl_StringMatch\fR), or NULL to not apply any filter. .BE - .SH DESCRIPTION .PP Tcl allows a number of mathematical functions to be used in @@ -88,7 +87,7 @@ Whenever the function is invoked in an expression Tcl will invoke \fIproc\fR. \fIProc\fR should have arguments and result that match the type \fBTcl_MathProc\fR: .CS -typedef int Tcl_MathProc( +typedef int \fBTcl_MathProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, Tcl_Value *\fIargs\fR, @@ -101,11 +100,11 @@ arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR. which describe the actual arguments to the function: .CS typedef struct Tcl_Value { - Tcl_ValueType \fItype\fR; - long \fIintValue\fR; - double \fIdoubleValue\fR; - Tcl_WideInt \fIwideValue\fR; -} Tcl_Value; + Tcl_ValueType \fItype\fR; + long \fIintValue\fR; + double \fIdoubleValue\fR; + Tcl_WideInt \fIwideValue\fR; +} \fBTcl_Value\fR; .CE .PP The \fItype\fR field indicates the type of the argument and is @@ -150,9 +149,7 @@ pointed to by \fIargTypesPointer\fR. \fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all the math functions defined in the interpreter whose name matches \fIpattern\fR. The returned object has a reference count of zero. - .SH "SEE ALSO" expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3) - .SH KEYWORDS expression, mathematical function diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index a32c410..2e30de9 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.17 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.18 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures" @@ -91,7 +91,7 @@ and it returns NULL. \fIproc\fR should have arguments and result that match the type \fBTcl_ObjCmdProc\fR: .CS -typedef int Tcl_ObjCmdProc( +typedef int \fBTcl_ObjCmdProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIobjc\fR, @@ -162,7 +162,7 @@ application an opportunity to release any structures associated with the command. \fIDeleteProc\fR should have arguments and result that match the type \fBTcl_CmdDeleteProc\fR: .CS -typedef void Tcl_CmdDeleteProc( +typedef void \fBTcl_CmdDeleteProc\fR( ClientData \fIclientData\fR); .CE The \fIclientData\fR argument will be the same as the \fIclientData\fR @@ -209,7 +209,7 @@ typedef struct Tcl_CmdInfo { Tcl_CmdDeleteProc *\fIdeleteProc\fR; ClientData \fIdeleteData\fR; Tcl_Namespace *\fInamespacePtr\fR; -} Tcl_CmdInfo; +} \fBTcl_CmdInfo\fR; .CE The \fIisNativeObjectProc\fR field has the value 1 if \fBTcl_CreateObjCommand\fR was called to register the command; @@ -294,6 +294,5 @@ 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 - .SH KEYWORDS bind, command, create, delete, namespace, object diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3 index 0559112..7e0368f 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.6 2007/12/13 15:22:30 dgp Exp $ +'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.7 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures" @@ -32,7 +32,6 @@ Arbitrary one-word value to pass to \fIproc\fR. 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 @@ -52,7 +51,8 @@ are other pending events to process before the call to \fIProc\fR should have arguments and return value that match the type \fBTcl_TimerProc\fR: .CS -typedef void Tcl_TimerProc(ClientData \fIclientData\fR); +typedef void \fBTcl_TimerProc\fR( + ClientData \fIclientData\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to @@ -70,6 +70,5 @@ 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 b1cadf6..1248619 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.14 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: CrtTrace.3,v 1.15 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" @@ -73,7 +73,7 @@ typedef int \fBTcl_CmdObjTraceProc\fR( const char *\fIcommand\fR, \fBTcl_Command\fR \fIcommandToken\fR, int \fIobjc\fR, - \fBTcl_Obj\fR *const \fIobjv\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. @@ -156,7 +156,7 @@ 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( +typedef void \fBTcl_CmdTraceProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIlevel\fR, diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3 index e69316e..b75de55 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.5 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.6 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures" @@ -26,7 +26,6 @@ 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 @@ -44,7 +43,8 @@ use \fBTcl_DoOneEvent\fR to dispatch events. \fIProc\fR should have arguments and result that match the type \fBTcl_IdleProc\fR: .CS -typedef void Tcl_IdleProc(ClientData \fIclientData\fR); +typedef void \fBTcl_IdleProc\fR( + 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 @@ -81,6 +81,5 @@ 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 51ef92f..a824b2f 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.29 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: Encoding.3,v 1.30 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures" @@ -21,10 +21,8 @@ Tcl_Encoding void \fBTcl_FreeEncoding\fR(\fIencoding\fR) .sp -.VS 8.5 int \fBTcl_GetEncodingFromObj\fR(\fIinterp, objPtr, encodingPtr\fR) -.VE 8.5 .sp char * \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR) @@ -52,10 +50,8 @@ const char * int \fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR) .sp -.VS 8.5 const char * \fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR) -.VE 8.5 .sp void \fBTcl_GetEncodingNames\fR(\fIinterp\fR) @@ -63,13 +59,11 @@ void Tcl_Encoding \fBTcl_CreateEncoding\fR(\fItypePtr\fR) .sp -.VS 8.5 Tcl_Obj * \fBTcl_GetEncodingSearchPath\fR() .sp int \fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR) -.VE 8.5 .sp const char * \fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR) @@ -87,13 +81,9 @@ Name of encoding to load. The encoding to query, free, or use for converting text. If \fIencoding\fR is NULL, the current system encoding is used. .AP Tcl_Obj *objPtr in -.VS 8.5 Name of encoding to get token for. -.VE 8.5 .AP Tcl_Encoding *encodingPtr out -.VS 8.5 Points to storage where encoding token is to be written. -.VE 8.5 .AP "const char" *src in For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the specified encoding that are to be converted to UTF-8. For the @@ -147,15 +137,11 @@ buffer as a result of the conversion. May be NULL. Filled with the number of characters that correspond to the number of bytes stored in the output buffer. May be NULL. .AP Tcl_DString *bufPtr out -.VS 8.5 Storage for the prescribed system encoding name. -.VE 8.5 .AP "const Tcl_EncodingType" *typePtr in Structure that defines a new type of encoding. .AP Tcl_Obj *searchPath in -.VS 8.5 List of filesystem directories in which to search for encoding data files. -.VE 8.5 .AP "const char" *path in A path to the location of the encoding file. .BE @@ -204,7 +190,6 @@ anywhere (i.e., it has been freed as many times as it has been gotten) \fBTcl_FreeEncoding\fR will release all storage the encoding was using and delete it from the database. .PP -.VS 8.5 \fBTcl_GetEncodingFromObj\fR treats the string representation of \fIobjPtr\fR as an encoding name, and finds an encoding with that name, just as \fBTcl_GetEncoding\fR does. When an encoding is found, @@ -216,7 +201,6 @@ writing to \fB*\fR\fIencodingPtr\fR takes place. Just as with \fBTcl_GetEncoding\fR, the caller should call \fBTcl_FreeEncoding\fR on the resulting encoding token when that token will no longer be used. -.VE 8.5 .PP \fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the specified \fIencoding\fR into UTF-8. The converted bytes are stored in @@ -331,14 +315,12 @@ procedure increments the reference count of the new system encoding, decrements the reference count of the old system encoding, and returns \fBTCL_OK\fR. .PP -.VS 8.5 \fBTcl_GetEncodingNameFromEnvironment\fR provides a means for the Tcl library to report the encoding name it believes to be the correct one to use as the system encoding, based on system calls and examination of the environment suitable for the platform. It accepts \fIbufPtr\fR, a pointer to an uninitialized or freed \fBTcl_DString\fR and writes the encoding name to it. The \fBTcl_DStringValue\fR is returned. -.VE 8.5 .PP \fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list consisting of the names of all the encodings that are currently defined @@ -366,13 +348,13 @@ convert between this encoding and UTF-8. It is defined as follows: .PP .CS typedef struct Tcl_EncodingType { - const char *\fIencodingName\fR; - Tcl_EncodingConvertProc *\fItoUtfProc\fR; - Tcl_EncodingConvertProc *\fIfromUtfProc\fR; - Tcl_EncodingFreeProc *\fIfreeProc\fR; - ClientData \fIclientData\fR; - int \fInullSize\fR; -} Tcl_EncodingType; + const char *\fIencodingName\fR; + Tcl_EncodingConvertProc *\fItoUtfProc\fR; + Tcl_EncodingConvertProc *\fIfromUtfProc\fR; + Tcl_EncodingFreeProc *\fIfreeProc\fR; + ClientData \fIclientData\fR; + int \fInullSize\fR; +} \fBTcl_EncodingType\fR; .CE .PP The \fIencodingName\fR provides a string name for the encoding, by @@ -400,7 +382,7 @@ The callback procedures \fItoUtfProc\fR and \fIfromUtfProc\fR should match the type \fBTcl_EncodingConvertProc\fR: .PP .CS -typedef int Tcl_EncodingConvertProc( +typedef int \fBTcl_EncodingConvertProc\fR( ClientData \fIclientData\fR, const char *\fIsrc\fR, int \fIsrcLen\fR, @@ -431,7 +413,7 @@ procedure will be a non-NULL location. The callback procedure \fIfreeProc\fR, if non-NULL, should match the type \fBTcl_EncodingFreeProc\fR: .CS -typedef void Tcl_EncodingFreeProc( +typedef void \fBTcl_EncodingFreeProc\fR( ClientData \fIclientData\fR); .CE .PP @@ -439,7 +421,6 @@ This \fIfreeProc\fR function is called when the encoding is deleted. The \fIclientData\fR parameter is the same as the \fIclientData\fR field specified to \fBTcl_CreateEncoding\fR when the encoding was created. .PP -.VS 8.5 \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR are called to access and set the list of filesystem directories searched for encoding data files. @@ -467,7 +448,6 @@ list. Since Tcl searches \fIsearchPath\fR for encoding data files in 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 algorithm, so many encodings are stored on disk as dynamically-loadable @@ -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.6 2003/09/29 21:47:38 dkf Exp $ +'\" RCS: @(#) $Id: Exit.3,v 1.7 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures" @@ -31,10 +31,8 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitTh .sp \fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR) .sp -.VS 8.5 Tcl_ExitProc * \fBTcl_SetExitProc\fR(\fIproc\fR) -.VE 8.5 .SH ARGUMENTS .AS Tcl_ExitProc clientData .AP int status in @@ -66,12 +64,10 @@ otherwise causes the application to terminate without calling \fBTcl_Exit\fR, the exit handlers will not be run. \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never returns control to its caller. -.VS 8.5 If an application exit handler has been installed (see \fBTcl_SetExitProc\fR), that handler is invoked with an argument consisting of the exit status (cast to ClientData); the application exit handler should not return control to Tcl. -.VE 8.5 .PP \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not exit from the current process. @@ -101,7 +97,8 @@ This provides a hook for cleanup operations such as flushing buffers and freeing global memory. \fIProc\fR should match the type \fBTcl_ExitProc\fR: .CS -typedef void Tcl_ExitProc(ClientData \fIclientData\fR); +typedef void \fBTcl_ExitProc\fR( + ClientData \fIclientData\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to @@ -118,7 +115,6 @@ indicated by \fIproc\fR and \fIclientData\fR so that no call to \fIproc\fR will be made. If no such handler exists then \fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing. .PP -.PP \fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers, in reverse order from the order in which they were registered. This matches the natural order in which extensions are loaded and unloaded; @@ -134,7 +130,6 @@ the process-wide exit handlers. This is because thread finalization shuts down the I/O channel system, so any attempt at I/O by the global exit handlers will vanish into the bitbucket. .PP -.VS 8.5 \fBTcl_SetExitProc\fR installs an application exit handler, returning the previously-installed application exit handler or NULL if no application handler was installed. If an application exit handler is @@ -143,7 +138,7 @@ finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an appropriate time. The argument passed to \fIproc\fR when it is invoked will be the exit status code (as passed to \fBTcl_Exit\fR) cast to a ClientData value. -.VE 8.5 - +.SH "SEE ALSO" +exit(n) .SH KEYWORDS callback, cleanup, dynamic loading, end application, exit, unloading, thread diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index d97266d..bf38dc2 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.62 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: FileSystem.3,v 1.63 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" @@ -27,7 +27,7 @@ ClientData void \fBTcl_FSMountsChanged\fR(\fIfsPtr\fR) .sp -Tcl_Filesystem* +Tcl_Filesystem * \fBTcl_FSGetFileSystemForPath\fR(\fIpathPtr\fR) .sp Tcl_PathType @@ -51,13 +51,11 @@ int int \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSListVolumes\fR(\fIvoid\fR) .sp -.VS 8.5 int \fBTcl_FSEvalFileEx\fR(\fIinterp, pathPtr, encodingName\fR) -.VE 8.5 .sp int \fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR) @@ -69,7 +67,7 @@ int int \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR) .sp int @@ -84,7 +82,7 @@ int int \fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR) .sp -const char** +const char ** \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR) .sp int @@ -96,28 +94,28 @@ int Tcl_Channel \fBTcl_FSOpenFileChannel\fR(\fIinterp, pathPtr, modeString, permissions\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSGetCwd\fR(\fIinterp\fR) .sp int \fBTcl_FSChdir\fR(\fIpathPtr\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSPathSeparator\fR(\fIpathPtr\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSJoinPath\fR(\fIlistObj, elements\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSSplitPath\fR(\fIpathPtr, lenPtr\fR) .sp int \fBTcl_FSEqualPaths\fR(\fIfirstPtr, secondPtr\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSGetNormalizedPath\fR(\fIinterp, pathPtr\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSJoinToPath\fR(\fIbasePtr, objc, objv\fR) .sp int @@ -132,16 +130,16 @@ Tcl_Obj * const char * \fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR) .sp const char * \fBTcl_FSGetNativePath\fR(\fIpathPtr\fR) .sp -Tcl_Obj* +Tcl_Obj * \fBTcl_FSFileSystemInfo\fR(\fIpathPtr\fR) .sp -Tcl_StatBuf* +Tcl_StatBuf * \fBTcl_AllocStatBuf\fR() .SH ARGUMENTS .AS Tcl_FSUnloadFileProc **unloadProcPtr out @@ -242,7 +240,6 @@ are \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR. When both flags are set and the underlying filesystem can do either, symbolic links are preferred. .BE - .SH DESCRIPTION .PP There are several reasons for calling the \fBTcl_FS\fR API functions @@ -368,7 +365,6 @@ 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 -.VS 8.5 \fBTcl_FSEvalFileEx\fR reads the file given by \fIpathPtr\fR using the encoding identified by \fIencodingName\fR and evaluates its contents as a Tcl script. It returns the same information as @@ -391,7 +387,6 @@ which will be safely substituted by the Tcl interpreter into \fBTcl_FSEvalFile\fR is a simpler version of \fBTcl_FSEvalFileEx\fR that always uses the system encoding when reading the file. -.VE 8.5 .PP \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and returns the addresses of two procedures within that file, if they are @@ -801,7 +796,7 @@ typedef struct Tcl_Filesystem { Tcl_FSLoadFileProc *\fIloadFileProc\fR; Tcl_FSGetCwdProc *\fIgetCwdProc\fR; Tcl_FSChdirProc *\fIchdirProc\fR; -} Tcl_Filesystem; +} \fBTcl_Filesystem\fR; .CE .PP Except for the first three fields in this structure which contain @@ -930,7 +925,7 @@ are invalidated when filesystem structures are added or removed from Tcl's internal list of known filesystems. .PP .CS -typedef int Tcl_FSPathInFilesystemProc( +typedef int \fBTcl_FSPathInFilesystemProc\fR( Tcl_Obj *\fIpathPtr\fR, ClientData *\fIclientDataPtr\fR); .CE @@ -942,7 +937,7 @@ simply not copy the internal representation, which may then need to be regenerated later. .PP .CS -typedef ClientData Tcl_FSDupInternalRepProc( +typedef ClientData \fBTcl_FSDupInternalRepProc\fR( ClientData \fIclientData\fR); .CE .SS FREEINTERNALREPPROC @@ -951,7 +946,7 @@ representations need freeing (i.e. if some memory is allocated when an internal representation is generated), but may otherwise be NULL. .PP .CS -typedef void Tcl_FSFreeInternalRepProc( +typedef void \fBTcl_FSFreeInternalRepProc\fR( ClientData \fIclientData\fR); .CE .SS INTERNALTONORMALIZEDPROC @@ -962,7 +957,7 @@ representation. The return value is a Tcl object whose string representation is the normalized path. .PP .CS -typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc( +typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR( ClientData \fIclientData\fR); .CE .SS CREATEINTERNALREPPROC @@ -974,7 +969,7 @@ the \fITcl_FSPathInFilesystemProc\fR for this filesystem always immediately creates an internal representation for paths it accepts. .PP .CS -typedef ClientData Tcl_FSCreateInternalRepProc( +typedef ClientData \fBTcl_FSCreateInternalRepProc\fR( Tcl_Obj *\fIpathPtr\fR); .CE .SS NORMALIZEPATHPROC @@ -1006,7 +1001,7 @@ the three valid cases, the implementation can assume that the path up to and including the file separator is known and normalized. .PP .CS -typedef int Tcl_FSNormalizePathProc( +typedef int \fBTcl_FSNormalizePathProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIpathPtr\fR, int \fInextCheckpoint\fR); @@ -1041,7 +1036,7 @@ increment the refCount of that object if it wishes to retain a reference to it. .PP .CS -typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc( +typedef Tcl_Obj *\fBTcl_FSFilesystemPathTypeProc\fR( Tcl_Obj *\fIpathPtr\fR); .CE .SS FILESYSTEMSEPARATORPROC @@ -1055,7 +1050,7 @@ uses, it is returned by the \fBfile separator\fR command. The return value should be an object with refCount of zero. .PP .CS -typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc( +typedef Tcl_Obj *\fBTcl_FSFilesystemSeparatorProc\fR( Tcl_Obj *\fIpathPtr\fR); .CE .SS STATPROC @@ -1066,7 +1061,7 @@ upon it (e.g. \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR, \fBglob\fR). .PP .CS -typedef int Tcl_FSStatProc( +typedef int \fBTcl_FSStatProc\fR( Tcl_Obj *\fIpathPtr\fR, Tcl_StatBuf *\fIstatPtr\fR); .CE @@ -1091,7 +1086,7 @@ any reasonable filesystem, since many Tcl level commands depend crucially upon it (e.g. \fBfile exists\fR, \fBfile readable\fR). .PP .CS -typedef int Tcl_FSAccessProc( +typedef int \fBTcl_FSAccessProc\fR( Tcl_Obj *\fIpathPtr\fR, int \fImode\fR); .CE @@ -1113,7 +1108,7 @@ which require open or accessing a file's contents will use it (e.g. \fBopen\fR, \fBencoding\fR, and many Tk commands). .PP .CS -typedef Tcl_Channel Tcl_FSOpenFileChannelProc( +typedef Tcl_Channel \fBTcl_FSOpenFileChannelProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIpathPtr\fR, int \fImode\fR, @@ -1146,8 +1141,8 @@ in the filesystem (and this may impact commands like \fBencoding names\fR which use glob functionality internally). .PP .CS -typedef int Tcl_FSMatchInDirectoryProc( - Tcl_Interp* \fIinterp\fR, +typedef int \fBTcl_FSMatchInDirectoryProc\fR( + Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIresultPtr\fR, Tcl_Obj *\fIpathPtr\fR, const char *\fIpattern\fR, @@ -1182,15 +1177,15 @@ The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR parameter contains the following fields: .CS typedef struct Tcl_GlobTypeData { - /* Corresponds to bcdpfls as in 'find -t' */ - int \fItype\fR; - /* Corresponds to file permissions */ - int \fIperm\fR; - /* Acceptable mac type */ - Tcl_Obj *\fImacType\fR; - /* Acceptable mac creator */ - Tcl_Obj *\fImacCreator\fR; -} Tcl_GlobTypeData; + /* Corresponds to bcdpfls as in 'find -t' */ + int \fItype\fR; + /* Corresponds to file permissions */ + int \fIperm\fR; + /* Acceptable mac type */ + Tcl_Obj *\fImacType\fR; + /* Acceptable mac creator */ + Tcl_Obj *\fImacCreator\fR; +} \fBTcl_GlobTypeData\fR; .CE .PP There are two specific cases which it is important to handle correctly, @@ -1212,7 +1207,7 @@ Function to process a \fBTcl_FSUtime\fR call. Required to allow setting open-r/open-w/fcopy implementation of \fBfile copy\fR. .PP .CS -typedef int Tcl_FSUtimeProc( +typedef int \fBTcl_FSUtimeProc\fR( Tcl_Obj *\fIpathPtr\fR, struct utimbuf *\fItval\fR); .CE @@ -1228,7 +1223,7 @@ Function to process a \fBTcl_FSLink\fR call. Should be implemented only if the filesystem supports links, and may otherwise be NULL. .PP .CS -typedef Tcl_Obj* Tcl_FSLinkProc( +typedef Tcl_Obj *\fBTcl_FSLinkProc\fR( Tcl_Obj *\fIlinkNamePtr\fR, Tcl_Obj *\fItoPtr\fR, int \fIlinkAction\fR); @@ -1253,7 +1248,7 @@ Should be implemented only if the filesystem adds volumes at the head of the filesystem, so that they can be returned by \fBfile volumes\fR. .PP .CS -typedef Tcl_Obj* Tcl_FSListVolumesProc(void); +typedef Tcl_Obj *\fBTcl_FSListVolumesProc\fR(void); .CE .PP The result should be a list of volumes added by this filesystem, or @@ -1281,9 +1276,9 @@ not implemented, there is no need to implement the \fBget\fR and \fBset\fR methods. .PP .CS -typedef const char** Tcl_FSFileAttrStringsProc( +typedef const char **\fBTcl_FSFileAttrStringsProc\fR( Tcl_Obj *\fIpathPtr\fR, - Tcl_Obj** \fIobjPtrRef\fR); + Tcl_Obj **\fIobjPtrRef\fR); .CE .PP The called function may either return an array of strings, or may @@ -1300,7 +1295,7 @@ Function to process a \fBTcl_FSFileAttrsGet\fR call, used by \fBfile attributes\fR. .PP .CS -typedef int Tcl_FSFileAttrsGetProc( +typedef int \fBTcl_FSFileAttrsGetProc\fR( Tcl_Interp *\fIinterp\fR, int \fIindex\fR, Tcl_Obj *\fIpathPtr\fR, @@ -1320,7 +1315,7 @@ attributes\fR. If the filesystem is read-only, there is no need to implement this. .PP .CS -typedef int Tcl_FSFileAttrsSetProc( +typedef int \fBTcl_FSFileAttrsSetProc\fR( Tcl_Interp *\fIinterp\fR, int \fIindex\fR, Tcl_Obj *\fIpathPtr\fR, @@ -1335,7 +1330,7 @@ Function to process a \fBTcl_FSCreateDirectory\fR call. Should be implemented unless the FS is read-only. .PP .CS -typedef int Tcl_FSCreateDirectoryProc( +typedef int \fBTcl_FSCreateDirectoryProc\fR( Tcl_Obj *\fIpathPtr\fR); .CE .PP @@ -1349,7 +1344,7 @@ Function to process a \fBTcl_FSRemoveDirectory\fR call. Should be implemented unless the FS is read-only. .PP .CS -typedef int Tcl_FSRemoveDirectoryProc( +typedef int \fBTcl_FSRemoveDirectoryProc\fR( Tcl_Obj *\fIpathPtr\fR, int \fIrecursive\fR, Tcl_Obj **\fIerrorPtr\fR); @@ -1371,7 +1366,7 @@ Function to process a \fBTcl_FSDeleteFile\fR call. Should be implemented unless the FS is read-only. .PP .CS -typedef int Tcl_FSDeleteFileProc( +typedef int \fBTcl_FSDeleteFileProc\fR( Tcl_Obj *\fIpathPtr\fR); .CE .PP @@ -1394,7 +1389,7 @@ it need only be implemented if a filesystem can differentiate between \fBstat\fR and \fBlstat\fR calls. .PP .CS -typedef int Tcl_FSLstatProc( +typedef int \fBTcl_FSLstatProc\fR( Tcl_Obj *\fIpathPtr\fR, Tcl_StatBuf *\fIstatPtr\fR); .CE @@ -1412,7 +1407,7 @@ Therefore it need only be implemented if the filesystem can perform that action more efficiently. .PP .CS -typedef int Tcl_FSCopyFileProc( +typedef int \fBTcl_FSCopyFileProc\fR( Tcl_Obj *\fIsrcPathPtr\fR, Tcl_Obj *\fIdestPathPtr\fR); .CE @@ -1437,7 +1432,7 @@ only be implemented if the filesystem can perform that action more efficiently. .PP .CS -typedef int Tcl_FSRenameFileProc( +typedef int \fBTcl_FSRenameFileProc\fR( Tcl_Obj *\fIsrcPathPtr\fR, Tcl_Obj *\fIdestPathPtr\fR); .CE @@ -1455,7 +1450,7 @@ mechanism. Therefore it need only be implemented if the filesystem can perform that action more efficiently. .PP .CS -typedef int Tcl_FSCopyDirectoryProc( +typedef int \fBTcl_FSCopyDirectoryProc\fR( Tcl_Obj *\fIsrcPathPtr\fR, Tcl_Obj *\fIdestPathPtr\fR, Tcl_Obj **\fIerrorPtr\fR); @@ -1482,7 +1477,7 @@ return \fBTCL_ERROR\fR to disable load functionality in this filesystem entirely. .PP .CS -typedef int Tcl_FSLoadFileProc( +typedef int \fBTcl_FSLoadFileProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIpathPtr\fR, Tcl_LoadHandle *\fIhandlePtr\fR, @@ -1510,7 +1505,7 @@ implemented, then this should also be implemented, if there is any cleanup action required. .PP .CS -typedef void Tcl_FSUnloadFileProc( +typedef void \fBTcl_FSUnloadFileProc\fR( Tcl_LoadHandle \fIloadHandle\fR); .CE .SS GETCWDPROC @@ -1520,7 +1515,7 @@ implement this. It will usually only be called once, if \fBgetcwd\fR is called before \fBchdir\fR. May be NULL. .PP .CS -typedef Tcl_Obj* Tcl_FSGetCwdProc( +typedef Tcl_Obj *\fBTcl_FSGetCwdProc\fR( Tcl_Interp *\fIinterp\fR); .CE .PP @@ -1543,7 +1538,7 @@ Real filesystems should carry out the correct action (i.e. call the correct system \fBchdir\fR API). .PP .CS -typedef int Tcl_FSChdirProc( +typedef int \fBTcl_FSChdirProc\fR( Tcl_Obj *\fIpathPtr\fR); .CE .PP diff --git a/doc/GetTime.3 b/doc/GetTime.3 index d932e47..c3f7134 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -21,27 +21,21 @@ Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time .sp \fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR) .SH ARGUMENTS -.AS "Tcl_Time *" timePtr out -.AP "Tcl_Time *" timePtr out +.AS Tcl_GetTimeProc *getProc in +.AP Tcl_Time *timePtr out Points to memory in which to store the date and time information. -.AS "Tcl_GetTimeProc *" getProc in -.AP "Tcl_GetTimeProc *" getProc in +.AP Tcl_GetTimeProc getProc in Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS. -.AS "Tcl_ScaleTimeProc *" scaleProc in -.AP "Tcl_ScaleTimeProc *" scaleProc in +.AP Tcl_ScaleTimeProc scaleProc in Pointer to handler function for the conversion of time delays in the virtual domain to real-time. -.AS "ClientData *" clientData in -.AP "ClientData *" clientData in +.AP ClientData clientData in Value passed through to the two handler functions. -.AS "Tcl_GetTimeProc **" getProcPtr inout -.AP "Tcl_GetTimeProc **" getProcPtr inout +.AP Tcl_GetTimeProc *getProcPtr out Pointer to place the currently registered get handler function into. -.AS "Tcl_ScaleTimeProc **" scaleProcPtr inout -.AP "Tcl_ScaleTimeProc **" scaleProcPtr inout +.AP Tcl_ScaleTimeProc *scaleProcPtr out Pointer to place the currently registered scale handler function into. -.AS "ClientData **" clientDataPtr inout -.AP "ClientData **" clientDataPtr inout +.AP ClientData *clientDataPtr out Pointer to place the currently registered pass-through value into. .BE .SH DESCRIPTION @@ -53,7 +47,7 @@ structure has the following definition: typedef struct Tcl_Time { long sec; long usec; -} Tcl_Time; +} \fBTcl_Time\fR; .CE .PP On return, the \fIsec\fR member of the structure is filled in with the @@ -70,20 +64,34 @@ computer system. On multiprocessor variants of Windows, this number may be limited to the 10- or 20-ms granularity of the system clock. (On single-processor Windows systems, the \fIusec\fR field is derived from a performance counter and is highly precise.) +.SS "VIRTUALIZED TIME" .PP -The \fBTcl_SetTime\fR function registers two related handler functions +The \fBTcl_SetTimeProc\fR function registers two related handler functions with the core. The first handler function is a replacement for \fBTcl_GetTime\fR, or rather the OS access made by \fBTcl_GetTime\fR. The other handler function is used by the Tcl notifier to convert wait/block times from the virtual domain into real time. .PP -The \fBTcl_QueryTime\fR function returns the currently registered +The \fBTcl_QueryTimeProc\fR function returns the currently registered handler functions. If no external handlers were set then this will return the standard handlers accessing and processing the native time 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: +.CS +typedef void \fBTcl_GetTimeProc\fR( + Tcl_Time *\fItimebuf\fR, + ClientData \fIclientData\fR); +typedef void \fBTcl_ScaleTimeProc\fR( + Tcl_Time *\fItimebuf\fR, + ClientData \fIclientData\fR); +.CE +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. +.PP Any handler pair specified has to return data which is consistent between them. In other words, setting one handler of the pair to something assuming a 10-times slowdown, and the other handler of the @@ -97,6 +105,6 @@ time one way or other. Note that the insertion of the hooks will not change the behaviour of the Tcl core with regard to this situation, i.e. the existing behaviour is retained. .SH "SEE ALSO" -clock +clock(n) .SH KEYWORDS date, time @@ -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.26 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: Hash.3,v 1.27 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" @@ -255,7 +255,7 @@ typedef struct Tcl_HashKeyType { Tcl_CompareHashKeysProc *\fIcompareKeysProc\fR; Tcl_AllocHashEntryProc *\fIallocEntryProc\fR; Tcl_FreeHashEntryProc *\fIfreeEntryProc\fR; -} Tcl_HashKeyType; +} \fBTcl_HashKeyType\fR; .CE .PP The \fIversion\fR member is the version of the table. If this structure is @@ -270,7 +270,6 @@ 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 then using the upper N bits as the index into the table. .IP \fBTCL_HASH_KEY_SYSTEM_HASH\fR 25 -.VS 8.5 This flag forces Tcl to use the memory allocation procedures provided by the operating system when allocating and freeing memory used to store the hash table data structures, and not any of Tcl's own customized memory allocation @@ -278,12 +277,11 @@ routines. This is important if the hash table is to be used in the implementation of a custom set of allocation routines, or something that a custom set of allocation routines might depend on, in order to avoid any circular dependency. -.VE 8.5 .PP The \fIhashKeyProc\fR member contains the address of a function called to calculate a hash value for the key. .CS -typedef unsigned int (Tcl_HashKeyProc) ( +typedef unsigned int \fBTcl_HashKeyProc\fR( Tcl_HashTable *\fItablePtr\fR, void *\fIkeyPtr\fR); .CE @@ -293,7 +291,7 @@ If this is NULL then \fIkeyPtr\fR is used and The \fIcompareKeysProc\fR member contains the address of a function called to compare two keys. .CS -typedef int (Tcl_CompareHashKeysProc) ( +typedef int \fBTcl_CompareHashKeysProc\fR( void *\fIkeyPtr\fR, Tcl_HashEntry *\fIhPtr\fR); .CE @@ -303,7 +301,7 @@ not match then the function returns 0, otherwise it returns 1. The \fIallocEntryProc\fR member contains the address of a function called to allocate space for an entry and initialize the key and clientData. .CS -typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) ( +typedef Tcl_HashEntry *\fBTcl_AllocHashEntryProc\fR( Tcl_HashTable *\fItablePtr\fR, void *\fIkeyPtr\fR); .CE @@ -319,7 +317,8 @@ object. The \fIfreeEntryProc\fR member contains the address of a function called to free space for an entry. .CS -typedef void (Tcl_FreeHashEntryProc) (Tcl_HashEntry *\fIhPtr\fR); +typedef void \fBTcl_FreeHashEntryProc\fR( + Tcl_HashEntry *\fIhPtr\fR); .CE 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 diff --git a/doc/IntObj.3 b/doc/IntObj.3 index 48caf5d..bad5dd0 100644 --- a/doc/IntObj.3 +++ b/doc/IntObj.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: IntObj.3,v 1.15 2008/06/27 19:55:46 dgp Exp $ +'\" RCS: @(#) $Id: IntObj.3,v 1.16 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures" @@ -40,7 +40,6 @@ int \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR) .sp .sp -.VS 8.5 \fB#include <tclTomMath.h>\fR .sp Tcl_Obj * @@ -56,7 +55,6 @@ int .sp int \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR) -.VE 8.5 .SH ARGUMENTS .AS Tcl_WideInt doubleValue in/out .AP int intValue in @@ -82,20 +80,14 @@ Points to place to store the long integer value retrieved from \fIobjPtr\fR. .AP Tcl_WideInt *widePtr out Points to place to store the wide integer value retrieved from \fIobjPtr\fR. .AP mp_int *bigValue in/out -.VS 8.5 Points to a multi-precision integer structure declared by the LibTomMath library. -.VE 8.5 .AP double doubleValue in -.VS 8.5 Double value from which the integer part is determined and used to initialize a multi-precision integer value. -.VE 8.5 .BE - .SH DESCRIPTION .PP -.VS 8.5 These procedures are used to create, modify, and read Tcl objects that hold integral values. .PP @@ -155,7 +147,6 @@ If anything later in the caller requires The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure that extracts the integer part of \fIdoubleValue\fR and stores that integer value in the \fBmp_int\fR value \fIbigValue\fR. -.VE 8.5 .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS diff --git a/doc/Interp.3 b/doc/Interp.3 index 362c80b..29c2c65 100644 --- a/doc/Interp.3 +++ b/doc/Interp.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: Interp.3,v 1.13 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: Interp.3,v 1.14 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" @@ -17,14 +17,14 @@ Tcl_Interp \- client-visible fields of interpreter structures \fB#include <tcl.h>\fR .sp typedef struct { - char *\fIresult\fR; - Tcl_FreeProc *\fIfreeProc\fR; - int \fIerrorLine\fR; -} Tcl_Interp; + char *\fIresult\fR; + Tcl_FreeProc *\fIfreeProc\fR; + int \fIerrorLine\fR; +} \fBTcl_Interp\fR; -typedef void Tcl_FreeProc(char *\fIblockPtr\fR); +typedef void \fBTcl_FreeProc\fR( + char *\fIblockPtr\fR); .BE - .SH DESCRIPTION .PP The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp @@ -34,11 +34,9 @@ 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 -.VS 8.5 \fBNote that access to all three fields, \fIresult\fB, \fIfreeProc\fB and \fIerrorLine\fB is deprecated.\fR Use \fBTcl_SetResult\fR, \fBTcl_GetResult\fR, and \fBTcl_GetReturnOptions\fR instead. -.VE 8.5 .PP The \fIresult\fR and \fIfreeProc\fR fields are used to return results or error messages from commands. diff --git a/doc/Limit.3 b/doc/Limit.3 index 002b422..425e41f 100644 --- a/doc/Limit.3 +++ b/doc/Limit.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: Limit.3,v 1.7 2004/11/12 09:01:25 das Exp $ +'\" RCS: @(#) $Id: Limit.3,v 1.8 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures" @@ -92,7 +92,6 @@ Arbitrary pointer-sized word used to pass some context to the Function to call whenever a handler is deleted. May be NULL if the \fIclientData\fR requires no deletion. .BE - .SH DESCRIPTION .PP Tcl's interpreter resource limit subsystem allows for close control @@ -164,7 +163,7 @@ the function that will actually be called; it should have the following prototype: .PP .CS -typedef void Tcl_LimitHandlerProc( +typedef void \fBTcl_LimitHandlerProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE @@ -181,7 +180,7 @@ function to call to delete the \fIclientData\fR value. It may be following prototype: .PP .CS -typedef void Tcl_LimitHandlerDeleteProc( +typedef void \fBTcl_LimitHandlerDeleteProc\fR( ClientData \fIclientData\fR); .CE .PP @@ -191,6 +190,5 @@ with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR, \fIhandlerProc\fR and \fIclientData\fR arguments. This function always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR). - .SH KEYWORDS interpreter, resource, limit, commands, time, callback diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 index 6f183f8..ad6d5f6 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.16 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: LinkVar.3,v 1.17 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" @@ -33,20 +33,14 @@ Name of global variable. Address of C variable that is to be linked to \fIvarName\fR. .AP int type in Type of C variable. Must be one of \fBTCL_LINK_INT\fR, -.VS 8.5 \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR, \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR, -\fBTCL_LINK_ULONG\fR, -.VE 8.5 -\fBTCL_LINK_WIDE_INT\fR, -.VS 8.5 +\fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR, \fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, -.VE 8.5 \fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or \fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make Tcl variable read-only. .BE - .SH DESCRIPTION .PP \fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable @@ -70,7 +64,6 @@ Any value written into the Tcl variable must have a proper integer form acceptable to \fBTcl_GetIntFromObj\fR; attempts to write non-integer values into \fIvarName\fR will be rejected with Tcl errors. -.VS 8.5 .TP \fBTCL_LINK_UINT\fR The C variable is of type \fBunsigned int\fR. @@ -124,7 +117,6 @@ integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the platform's defined range for the \fBunsigned long\fR type; attempts to write non-integer values (or values outside the range) into \fIvarName\fR will be rejected with Tcl errors. -.VE 8.5 .TP \fBTCL_LINK_DOUBLE\fR The C variable is of type \fBdouble\fR. @@ -132,7 +124,6 @@ Any value written into the Tcl variable must have a proper real form acceptable to \fBTcl_GetDoubleFromObj\fR; attempts to write non-real values into \fIvarName\fR will be rejected with Tcl errors. -.VS 8.5 .TP \fBTCL_LINK_FLOAT\fR The C variable is of type \fBfloat\fR. @@ -141,7 +132,6 @@ form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the range acceptable for a \fBfloat\fR; attempts to write non-real values (or values outside the range) into \fIvarName\fR will be rejected with Tcl errors. -.VE 8.5 .TP \fBTCL_LINK_WIDE_INT\fR The C variable is of type \fBTcl_WideInt\fR (which is an integer type @@ -150,7 +140,6 @@ Any value written into the Tcl variable must have a proper integer form acceptable to \fBTcl_GetWideIntFromObj\fR; attempts to write non-integer values into \fIvarName\fR will be rejected with Tcl errors. -.VS 8.5 .TP \fBTCL_LINK_WIDE_UINT\fR The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned @@ -162,7 +151,6 @@ cast to unsigned); .\" 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. @@ -206,6 +194,5 @@ Tk widget that wishes to display the value of the variable), the trace will not trigger when the C variable has changed. \fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl variable are invoked. - .SH KEYWORDS boolean, integer, link, read-only, real, string, traces, variable diff --git a/doc/Method.3 b/doc/Method.3 index 341dcac..a3a1af1 100644 --- a/doc/Method.3 +++ b/doc/Method.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: Method.3,v 1.1 2008/05/31 11:42:06 dkf Exp $ +'\" RCS: @(#) $Id: Method.3,v 1.2 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_Method 3 0.1 TclOO "TclOO Library Functions" @@ -162,13 +162,13 @@ The types of methods are described by a pointer to a Tcl_MethodType structure, which is defined as: .PP .CS - typedef const struct { - int \fIversion\fR; - const char *\fIname\fR; - Tcl_MethodCallProc \fIcallProc\fR; - Tcl_MethodDeleteProc \fIdeleteProc\fR; - Tcl_CloneProc \fIcloneProc\fR; - } \fBTcl_MethodType\fR; +typedef const struct { + int \fIversion\fR; + const char *\fIname\fR; + Tcl_MethodCallProc \fIcallProc\fR; + Tcl_MethodDeleteProc \fIdeleteProc\fR; + Tcl_CloneProc \fIcloneProc\fR; +} \fBTcl_MethodType\fR; .CE .PP The \fIversion\fR field allows for future expansion of the structure, and @@ -192,12 +192,12 @@ that the \fIclientData\fR can just be copied directly. Functions matching this signature are called when the method is invoked. .PP .CS - typedef int (*\fBTcl_MethodCallProc\fR) ( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - Tcl_ObjectContext \fIobjectContext\fR, - int \fIobjc\fR, - Tcl_Obj *const *\fIobjv\fR); +typedef int \fBTcl_MethodCallProc\fR( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tcl_ObjectContext \fIobjectContext\fR, + int \fIobjc\fR, + Tcl_Obj *const *\fIobjv\fR); .CE .PP The \fIclientData\fR argument to a Tcl_MethodCallProc is the value that was @@ -213,8 +213,8 @@ Functions matching this signature are used when a method is deleted, whether through a new method being created or because the object or class is deleted. .PP .CS - typedef void (*\fBTcl_MethodDeleteProc\fR) ( - ClientData \fIclientData\fR); +typedef void \fBTcl_MethodDeleteProc\fR( + ClientData \fIclientData\fR); .CE .PP The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as @@ -226,10 +226,10 @@ Functions matching this signature are used to copy a method when the object or class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR). .PP .CS - typedef int (*\fBTcl_CloneProc\fR) ( - Tcl_Interp *\fIinterp\fR, - ClientData \fIoldClientData\fR, - ClientData *\fInewClientDataPtr\fR); +typedef int \fBTcl_CloneProc\fR( + Tcl_Interp *\fIinterp\fR, + ClientData \fIoldClientData\fR, + ClientData *\fInewClientDataPtr\fR); .CE .PP The \fIinterp\fR argument gives a place to write an error message when the diff --git a/doc/Namespace.3 b/doc/Namespace.3 index a82248e..9f78b83 100644 --- a/doc/Namespace.3 +++ b/doc/Namespace.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: Namespace.3,v 1.9 2008/04/18 14:21:34 dkf Exp $ +'\" RCS: @(#) $Id: Namespace.3,v 1.10 2008/06/29 22:28:24 dkf Exp $ '\" '\" Note that some of these functions do not seem to belong, but they '\" were all introduced with the same TIP (#139) @@ -97,7 +97,6 @@ message should be left in the interpreter if the search fails.) A script fragment to be installed as the unknown command handler for the namespace, or NULL to reset the handler to its default. .BE - .SH DESCRIPTION .PP Namespaces are hierarchic naming contexts that can contain commands @@ -118,10 +117,12 @@ the global namespace.) \fBTcl_CreateNamespace\fR creates a new namespace. The \fIdeleteProc\fR will have the following type signature: .CS -typedef void (Tcl_NamespaceDeleteProc) (ClientData clientData); +typedef void \fBTcl_NamespaceDeleteProc\fR( + ClientData \fIclientData\fR); .CE .PP -\fBTcl_DeleteNamespace\fR deletes a namespace. +\fBTcl_DeleteNamespace\fR deletes a namespace, calling the +\fIdeleteProc\fR defined for the namespace (if any). .PP \fBTcl_AppendExportList\fR retrieves the export patterns for a namespace given namespace and appends them (as list items) to @@ -159,9 +160,7 @@ for the namespace, or NULL if none is set. \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to its default. - .SH "SEE ALSO" -Tcl_CreateCommand, Tcl_ListObjAppendElements, Tcl_SetVar - +Tcl_CreateCommand(3), Tcl_ListObjAppendElements(3), Tcl_SetVar(3) .SH KEYWORDS namespace, command diff --git a/doc/Notifier.3 b/doc/Notifier.3 index 5b7d964..b9d3495 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.21 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: Notifier.3,v 1.22 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Notifier 3 8.1 Tcl "Tcl Library Procedures" @@ -110,7 +110,6 @@ Structure of function pointers describing notifier procedures that are to replace the ones installed in the executable. See \fBREPLACING THE NOTIFIER\fR for details. .BE - .SH INTRODUCTION .PP The interfaces described here are used to customize the Tcl event @@ -217,7 +216,6 @@ return. .IP [7] Either return 0 to indicate that no events were ready, or go back to step [2] if blocking was requested by the caller. - .SH "CREATING A NEW EVENT SOURCE" .PP An event source consists of three procedures invoked by the notifier, @@ -232,7 +230,7 @@ Its arguments specify the setup procedure and check procedure for the event source. \fISetupProc\fR should match the following prototype: .CS -typedef void Tcl_EventSetupProc( +typedef void \fBTcl_EventSetupProc\fR( ClientData \fIclientData\fR, int \fIflags\fR); .CE @@ -272,9 +270,9 @@ a structure that describes a time interval in seconds and microseconds: .CS typedef struct Tcl_Time { - long \fIsec\fR; - long \fIusec\fR; -} Tcl_Time; + long \fIsec\fR; + long \fIusec\fR; +} \fBTcl_Time\fR; .CE The \fIusec\fR field should be less than 1000000. .PP @@ -306,7 +304,7 @@ procedure, indicated by the \fIcheckProc\fR argument to \fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the following prototype: .CS -typedef void Tcl_EventCheckProc( +typedef void \fBTcl_EventCheckProc\fR( ClientData \fIclientData\fR, int \fIflags\fR); .CE @@ -332,7 +330,7 @@ rest of the notifier. A \fBTcl_Event\fR has the following definition: typedef struct { Tcl_EventProc *\fIproc\fR; struct Tcl_Event *\fInextPtr\fR; -} Tcl_Event; +} \fBTcl_Event\fR; .CE The event source must fill in the \fIproc\fR field of the event before calling \fBTcl_QueueEvent\fR. @@ -362,7 +360,7 @@ 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: .CS -typedef int Tcl_EventProc( +typedef int \fBTcl_EventProc\fR( Tcl_Event *\fIevPtr\fR, int \fIflags\fR); .CE @@ -419,7 +417,7 @@ for each event in the queue, deleting those for with the procedure returns 1. Events for which the procedure returns 0 are left in the queue. \fIProc\fR should match the following prototype: .CS -typedef int Tcl_EventDeleteProc( +typedef int \fBTcl_EventDeleteProc\fR( Tcl_Event *\fIevPtr\fR, ClientData \fIclientData\fR); .CE @@ -432,7 +430,6 @@ point to the next event in the queue. \fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted. If no such source exists, \fBTcl_DeleteEventSource\fR has no effect. - .SH "CREATING A NEW NOTIFIER" .PP The notifier consists of all the procedures described in this manual @@ -528,7 +525,6 @@ in their respective manual pages. The easiest way to create a new notifier is to look at the code for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR or \fBwin/tclWinNotify.c\fR in the Tcl source distribution. - .SH "REPLACING THE NOTIFIER" .PP A notifier that has been written according to the conventions above @@ -551,7 +547,7 @@ typedef struct Tcl_NotifierProcs { Tcl_FinalizeNotifierProc *finalizeNotifierProc; Tcl_AlertNotifierProc *alertNotifierProc; Tcl_ServiceModeHookProc *serviceModeHookProc; -} Tcl_NotifierProcs; +} \fBTcl_NotifierProcs\fR; .CE Following the call to \fBTcl_SetNotifier\fR, the pointers given in the \fBTcl_NotifierProcs\fR structure replace whatever notifier had @@ -560,7 +556,6 @@ been installed in the process. It is extraordinarily unwise to replace a running notifier. Normally, \fBTcl_SetNotifier\fR should be called at process initialization time before the first call to \fBTcl_InitNotifier\fR. - .SH "EXTERNAL EVENT LOOPS" .PP The notifier interfaces are designed so that Tcl can be embedded into @@ -621,9 +616,8 @@ then calls to \fBTcl_ServiceAll\fR will behave normally. mode, which should be restored when the recursive loop exits. \fBTcl_GetServiceMode\fR returns the current value of the service mode. - .SH "SEE ALSO" -\fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR, -\fBTcl_DoOneEvent\fR, \fBThread(3)\fR +Tcl_CreateFileHandler(3), Tcl_DeleteFileHandler(3), Tcl_Sleep(3), +Tcl_DoOneEvent(3), Thread(3) .SH KEYWORDS event, notifier, event queue, event sources, file events, timer, idle, service mode, threads diff --git a/doc/Object.3 b/doc/Object.3 index b0f718b..6951f10 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.19 2008/06/27 21:46:19 dgp Exp $ +'\" RCS: @(#) $Id: Object.3,v 1.20 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures" @@ -35,7 +35,6 @@ int Points to an object; must have been the result of a previous call to \fBTcl_NewObj\fR. .BE - .SH INTRODUCTION .PP This man page presents an overview of Tcl objects and how they are used. @@ -112,25 +111,25 @@ Each Tcl object is represented by a \fBTcl_Obj\fR structure which is defined as follows. .CS typedef struct Tcl_Obj { - int \fIrefCount\fR; - char *\fIbytes\fR; - int \fIlength\fR; - Tcl_ObjType *\fItypePtr\fR; - union { - long \fIlongValue\fR; - double \fIdoubleValue\fR; - void *\fIotherValuePtr\fR; - Tcl_WideInt \fIwideValue\fR; - struct { - void *\fIptr1\fR; - void *\fIptr2\fR; - } \fItwoPtrValue\fR; - struct { - void *\fIptr\fR; - unsigned long \fIvalue\fR; - } \fIptrAndLongRep\fR; - } \fIinternalRep\fR; -} Tcl_Obj; + int \fIrefCount\fR; + char *\fIbytes\fR; + int \fIlength\fR; + Tcl_ObjType *\fItypePtr\fR; + union { + long \fIlongValue\fR; + double \fIdoubleValue\fR; + void *\fIotherValuePtr\fR; + Tcl_WideInt \fIwideValue\fR; + struct { + void *\fIptr1\fR; + void *\fIptr2\fR; + } \fItwoPtrValue\fR; + struct { + void *\fIptr\fR; + unsigned long \fIvalue\fR; + } \fIptrAndLongRep\fR; + } \fIinternalRep\fR; +} \fBTcl_Obj\fR; .CE The \fIbytes\fR and the \fIlength\fR members together hold an object's UTF-8 string representation, diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index 59dfeaf..e9d1137 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.36 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.37 2008/06/29 22:28:24 dkf Exp $ .so man.macros .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" .BS @@ -99,10 +99,8 @@ Tcl_WideInt Tcl_WideInt \fBTcl_Tell\fR(\fIchannel\fR) .sp -.VS 8.5 int \fBTcl_TruncateChannel\fR(\fIchannel, length\fR) -.VE 8.5 .sp int \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) @@ -212,7 +210,6 @@ values. Must have been initialized by the caller. .AP "const char" *newValue in New value for the option given by \fIoptionName\fR. .BE - .SH DESCRIPTION .PP The Tcl channel mechanism provides a device-independent and @@ -230,7 +227,6 @@ The procedures described in this manual entry comprise the C APIs of the generic layer of the channel architecture. For a description of the channel driver architecture and how to implement channel drivers for new types of channels, see the manual entry for \fBTcl_CreateChannel\fR. - .SH TCL_OPENFILECHANNEL .PP \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and @@ -252,7 +248,6 @@ register it, use \fBTcl_RegisterChannel\fR, described below. If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. - .SH TCL_OPENCOMMANDCHANNEL .PP \fBTcl_OpenCommandChannel\fR provides a C-level interface to the @@ -290,7 +285,6 @@ register it, use \fBTcl_RegisterChannel\fR, described below. If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. - .SH TCL_MAKEFILECHANNEL .PP \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing, @@ -300,7 +294,6 @@ register it, use \fBTcl_RegisterChannel\fR, described below. If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. - .SH TCL_GETCHANNEL .PP \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to @@ -318,7 +311,6 @@ according to the \fIpattern\fR. If \fIpattern\fR is NULL, then it will not do any filtering. The return value is \fBTCL_OK\fR if no errors occurred writing to the result, otherwise it is \fBTCL_ERROR\fR, and the error message is left in the interpreter's result. - .SH TCL_REGISTERCHANNEL .PP \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible @@ -343,7 +335,6 @@ call to \fBTcl_RegisterChannel\fR, they will get initialized by that call. See \fBTcl_StandardChannels\fR for a general treatise about standard channels and the behaviour of the Tcl library with regard to them. - .SH TCL_UNREGISTERCHANNEL .PP \fBTcl_UnregisterChannel\fR removes a channel from the set of channels @@ -358,7 +349,6 @@ that it no longer holds a reference to that channel. If this is the last reference to the channel, it will now be closed. \fBTcl_UnregisterChannel\fR is very similar to \fBTcl_DetachChannel\fR except that it will also close the channel if no further references to it exist. - .SH TCL_DETACHCHANNEL .PP \fBTcl_DetachChannel\fR removes a channel from the set of channels @@ -373,7 +363,6 @@ Code not associated with a Tcl interpreter can call that it no longer holds a reference to that channel. If this is the last reference to the channel, unlike \fBTcl_UnregisterChannel\fR, it will not be closed. - .SH TCL_ISSTANDARDCHANNEL .PP \fBTcl_IsStandardChannel\fR tests whether a channel is one of the @@ -382,7 +371,6 @@ three standard channels, stdin, stdout or stderr. If so, it returns .PP No attempt is made to check whether the given channel or the standard channels are initialized or otherwise valid. - .SH TCL_CLOSE .PP \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a @@ -412,7 +400,6 @@ been given as the \fBchan\fR argument in a call to \fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been matched by corresponding calls to \fBTcl_UnregisterChannel\fR. - .SH "TCL_READCHARS AND TCL_READ" .PP \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes @@ -473,7 +460,6 @@ stack the supplied channel is part of, \fBTcl_ReadRaw\fR does not. Thus this function is \fBonly\fR usable for transformational channel drivers, i.e. drivers used in the middle of a stack of channels, to move data from the channel below into the transformation. - .SH "TCL_GETSOBJ AND TCL_GETS" .PP \fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to @@ -500,7 +486,6 @@ of input unavailability. \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting characters are appended to the dynamic string given by \fIlineRead\fR rather than a Tcl object. - .SH "TCL_UNGETS" .PP \fBTcl_Ungets\fR is used to add data to the input queue of a channel, @@ -513,7 +498,6 @@ head of the queue. If \fIchannel\fR has a EOF set, no data will be added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or \-1 if an error occurs. - .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE" .PP \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at @@ -568,7 +552,6 @@ not. Thus this function is \fBonly\fR usable for transformational channel drivers, i.e. drivers used in the middle of a stack of channels, to move data from the transformation into the channel below it. - .SH TCL_FLUSH .PP \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR @@ -582,7 +565,6 @@ eventually, as fast as the channel is able to absorb it. The return value is normally \fBTCL_OK\fR. If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. - .SH TCL_SEEK .PP \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent @@ -593,20 +575,15 @@ buffered input is discarded, prior to the seek operation. If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. After an error, the access point may or may not have been moved. - .SH TCL_TELL .PP \fBTcl_Tell\fR returns the current access point for a channel. The returned value is \-1 if the channel does not support seeking. - .SH TCL_TRUNCATECHANNEL .PP -.VS 8.5 \fBTcl_TruncateChannel\fR truncates the file underlying \fIchannel\fR to a given \fIlength\fR of bytes. It returns \fBTCL_OK\fR if the operation succeeded, and \fBTCL_ERROR\fR otherwise. -.VE 8.5 - .SH TCL_GETCHANNELOPTION .PP \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of @@ -628,7 +605,6 @@ for the Tcl \fBsocket\fR command. The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX error code. - .SH TCL_SETCHANNELOPTION .PP \fBTcl_SetChannelOption\fR sets a new value \fInewValue\fR @@ -636,30 +612,26 @@ for an option \fIoptionName\fR on \fIchannel\fR. The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL, \fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result. - .SH TCL_EOF .PP \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered an end of file during the last input operation. - .SH TCL_INPUTBLOCKED .PP \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in nonblocking mode and the last input operation returned less data than requested because there was insufficient data available. The call always returns zero if the channel is in blocking mode. - .SH TCL_INPUTBUFFERED .PP \fBTcl_InputBuffered\fR returns the number of bytes of input currently buffered in the internal buffers for a channel. If the channel is not open for reading, this function always returns zero. - .SH TCL_OUTPUTBUFFERED +.PP \fBTcl_OutputBuffered\fR returns the number of bytes of output currently buffered in the internal buffers for a channel. If the channel is not open for writing, this function always returns zero. - .SH "PLATFORM ISSUES" .PP The handles returned from \fBTcl_GetChannelHandle\fR depend on the @@ -670,10 +642,8 @@ the channel was created with \fBTcl_OpenFileChannel\fR, \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other channel types may return a different type of handle on Windows platforms. - .SH "SEE ALSO" DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3) - .SH KEYWORDS access point, blocking, buffered I/O, channel, channel driver, end of file, flush, input, nonblocking, output, read, seek, write diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 index 70b80fa..6dd78f6 100644 --- a/doc/OpenTcp.3 +++ b/doc/OpenTcp.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: OpenTcp.3,v 1.11 2006/11/15 09:23:01 dkf Exp $ +'\" RCS: @(#) $Id: OpenTcp.3,v 1.12 2008/06/29 22:28:24 dkf Exp $ .so man.macros .TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures" .BS @@ -50,15 +50,13 @@ accepted via the socket. .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE - .SH DESCRIPTION .PP These functions are convenience procedures for creating channels that communicate over TCP sockets. The operations on a channel are described in the manual entry for \fBTcl_OpenFileChannel\fR. - -.SH TCL_OPENTCPCLIENT +.SS TCL_OPENTCPCLIENT .PP \fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR on a specific \fIhost\fR, and returns a channel that can be used to @@ -98,8 +96,7 @@ register it, use \fBTcl_RegisterChannel\fR. If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. - -.SH TCL_MAKETCPCLIENTCHANNEL +.SS TCL_MAKETCPCLIENTCHANNEL .PP \fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an existing, platform specific, handle for a client TCP socket. @@ -109,8 +106,7 @@ register it, use \fBTcl_RegisterChannel\fR. If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. - -.SH TCL_OPENTCPSERVER +.SS TCL_OPENTCPSERVER .PP \fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified \fIport\fR and uses the Tcl event mechanism to accept requests from clients @@ -121,7 +117,7 @@ Each time a client connects to this socket, Tcl creates a channel for the new connection and invokes \fIproc\fR with information about the channel. \fIProc\fR must match the following prototype: .CS -typedef void Tcl_TcpAcceptProc( +typedef void \fBTcl_TcpAcceptProc\fR( ClientData \fIclientData\fR, Tcl_Channel \fIchannel\fR, char *\fIhostName\fR, @@ -162,15 +158,12 @@ register it, use \fBTcl_RegisterChannel\fR. If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was previously closed, the act of creating the new channel also assigns it as a replacement for the standard channel. - .SH "PLATFORM ISSUES" .PP On Unix platforms, the socket handle is a Unix file descriptor as returned by the \fBsocket\fR system call. On the Windows platform, the socket handle is a \fBSOCKET\fR as defined in the WinSock API. - .SH "SEE ALSO" Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n) - .SH KEYWORDS -client, server, TCP +channel, client, server, socket, TCP diff --git a/doc/Panic.3 b/doc/Panic.3 index 0b2ec03..00187ff 100644 --- a/doc/Panic.3 +++ b/doc/Panic.3 @@ -2,7 +2,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Panic.3,v 1.8 2005/09/13 21:23:51 dgp Exp $ +'\" RCS: @(#) $Id: Panic.3,v 1.9 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_Panic 3 8.4 Tcl "Tcl Library Procedures" @@ -35,9 +35,7 @@ Must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. .AP Tcl_PanicProc *panicProc in Procedure to report fatal error message and abort. - .BE - .SH DESCRIPTION .PP When the Tcl library detects that its internal data structures are in an @@ -60,7 +58,7 @@ return. type \fBTcl_PanicProc\fR: .PP .CS -typedef void Tcl_PanicProc( +typedef void \fBTcl_PanicProc\fR( const char *\fBformat\fR, \fBarg\fR, \fBarg\fR,...); .CE @@ -89,10 +87,7 @@ will be displayed. .PP \fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of taking a variable number of arguments it takes an argument list. - .SH "SEE ALSO" abort(3), printf(3), exec(n), format(n) - .SH KEYWORDS abort, fatal, error - diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index 466f5c0..a75262e 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.27 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: ParseCmd.3,v 1.28 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures" @@ -82,7 +82,6 @@ if the parse was successful. Points to structure that was filled in by a previous call to \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseVarName\fR, etc. .BE - .SH DESCRIPTION .PP These procedures parse Tcl commands or portions of Tcl commands such as @@ -204,7 +203,6 @@ If an error or other exception occurs while evaluating the tokens (such as a reference to a non-existent variable) then the return value is NULL and an error message is left in \fIinterp\fR's result. The use of \fBTcl_EvalTokens\fR is deprecated. - .SH "TCL_PARSE STRUCTURE" .PP \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, @@ -212,22 +210,22 @@ of \fBTcl_EvalTokens\fR is deprecated. return parse information in two data structures, Tcl_Parse and Tcl_Token: .CS typedef struct Tcl_Parse { - const char *\fIcommentStart\fR; - int \fIcommentSize\fR; - const char *\fIcommandStart\fR; - int \fIcommandSize\fR; - int \fInumWords\fR; - Tcl_Token *\fItokenPtr\fR; - int \fInumTokens\fR; - ... -} Tcl_Parse; + const char *\fIcommentStart\fR; + int \fIcommentSize\fR; + const char *\fIcommandStart\fR; + int \fIcommandSize\fR; + int \fInumWords\fR; + Tcl_Token *\fItokenPtr\fR; + int \fInumTokens\fR; + ... +} \fBTcl_Parse\fR; typedef struct Tcl_Token { - int \fItype\fR; - const char *\fIstart\fR; - int \fIsize\fR; - int \fInumComponents\fR; -} Tcl_Token; + int \fItype\fR; + const char *\fIstart\fR; + int \fIsize\fR; + int \fInumComponents\fR; +} \fBTcl_Token\fR; .CE .PP The first five fields of a Tcl_Parse structure @@ -269,6 +267,7 @@ the \fInumComponents\fR field describes how many of these there are. The \fItype\fR field has one of the following values: .TP 20 \fBTCL_TOKEN_WORD\fR +. This token ordinarily describes one word of a command but it may also describe a quoted or braced string in an expression. The token describes a component of the script that is @@ -283,29 +282,32 @@ number of sub-tokens that make up the word, including sub-tokens of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens. .TP \fBTCL_TOKEN_SIMPLE_WORD\fR +. This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR sub-token. The \fInumComponents\fR field is always 1. .TP \fBTCL_TOKEN_EXPAND_WORD\fR -.VS 8.5 +. This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that the command parser notes this word began with the expansion prefix \fB{*}\fR, indicating that after substitution, the list value of this word should be expanded to form multiple arguments in command evaluation. This token type can only be created by Tcl_ParseCommand. -.VE 8.5 .TP \fBTCL_TOKEN_TEXT\fR +. The token describes a range of literal text that is part of a word. The \fInumComponents\fR field is always 0. .TP \fBTCL_TOKEN_BS\fR +. The token describes a backslash sequence such as \fB\en\fR or \fB\e0xa3\fR. The \fInumComponents\fR field is always 0. .TP \fBTCL_TOKEN_COMMAND\fR +. The token describes a command whose result must be substituted into the word. The token includes the square brackets that surround the command. The \fInumComponents\fR field is always 0 (the nested command @@ -313,6 +315,7 @@ is not parsed; call \fBTcl_ParseCommand\fR recursively if you want to see its tokens). .TP \fBTCL_TOKEN_VARIABLE\fR +. The token describes a variable substitution, including the \fB$\fR, variable name, and array index (if there is one) up through the close parenthesis that terminates the index. This token is followed @@ -328,6 +331,7 @@ array index. The \fInumComponents\fR field includes nested sub-tokens that are part of \fBTCL_TOKEN_VARIABLE\fR tokens in the array index. .TP \fBTCL_TOKEN_SUB_EXPR\fR +. The token describes one subexpression of an expression (or an entire expression). A subexpression may consist of a value @@ -354,6 +358,7 @@ counts the total number of sub-tokens that make up the subexpression; this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens. .TP \fBTCL_TOKEN_OPERATOR\fR +. The token describes one operator of an expression such as \fB&&\fR or \fBhypot\fR. A \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a @@ -385,7 +390,6 @@ is always 0. After \fBTcl_ParseCommand\fR returns, the first token pointed to by the \fItokenPtr\fR field of the Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or -.VS 8.5 \fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR. It is followed by the sub-tokens that must be concatenated to produce the value of that word. @@ -394,7 +398,6 @@ of \fBTCL_TOKEN_EXPAND_WORD\fR token for the second word, followed by sub-tokens for that word, and so on until all \fInumWords\fR have been accounted for. -.VE 8.5 .PP After \fBTcl_ParseExpr\fR returns, the first token pointed to by the \fItokenPtr\fR field of the @@ -461,6 +464,5 @@ There are additional fields in the Tcl_Parse structure after the \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be referenced by code outside of these procedures. - .SH KEYWORDS backslash substitution, braces, command, expression, parse, token, variable substitution diff --git a/doc/Preserve.3 b/doc/Preserve.3 index 5c860aa..e4ae2dc 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.6 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: Preserve.3,v 1.7 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures" @@ -29,7 +29,6 @@ to memory for structure. .AP Tcl_FreeProc *freeProc in Procedure to invoke to free \fIclientData\fR. .BE - .SH DESCRIPTION .PP These three procedures help implement a simple reference count mechanism @@ -81,7 +80,8 @@ All the work of freeing the object is carried out by \fIfreeProc\fR. \fIFreeProc\fR must have arguments and result that match the type \fBTcl_FreeProc\fR: .CS -typedef void Tcl_FreeProc(char *\fIblockPtr\fR); +typedef void \fBTcl_FreeProc\fR( + char *\fIblockPtr\fR); .CE The \fIblockPtr\fR argument to \fIfreeProc\fR will be the same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR. @@ -104,9 +104,7 @@ mechanism for long-term reference counts. The implementation does not depend in any way on the internal structure of the objects being freed; it keeps the reference counts in a separate structure. - .SH "SEE ALSO" Tcl_Interp, Tcl_Alloc - .SH KEYWORDS free, reference count, storage diff --git a/doc/PrintDbl.3 b/doc/PrintDbl.3 index 25ea85c..d0d2307 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.11 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: PrintDbl.3,v 1.12 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures" @@ -30,7 +30,6 @@ Floating-point value to be converted. Where to store the string representing \fIvalue\fR. Must have at least \fBTCL_DOUBLE_SPACE\fR characters of storage. .BE - .SH DESCRIPTION .PP \fBTcl_PrintDouble\fR generates a string that represents the value @@ -43,7 +42,6 @@ or an 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 precisely that many digits of significance. If the value is zero @@ -51,7 +49,5 @@ precisely that many digits of significance. If the value is zero represent the number in such a way that \fBTcl_NewDoubleObj\fR will generate the same number when presented with the given string. IEEE semantics of rounding to even apply to the conversion. -.VE - .SH KEYWORDS conversion, double-precision, floating-point, string diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 index 8e4cecf..83cc59c 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.8 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: RegConfig.3,v 1.9 2008/06/29 22:28:24 dkf Exp $ .so man.macros .TH Tcl_RegisterConfig 3 8.4 Tcl "Tcl Library Procedures" .BS @@ -37,7 +37,6 @@ Contains the name of the encoding used to store the configuration values as ASCII string. This means that this information is in UTF-8 too. Must not be NULL. .BE - .SH DESCRIPTION .PP The function described here has its base in TIP 59 and provides @@ -103,9 +102,9 @@ The \fBTcl_Config\fR structure contains the following fields: .PP .CS typedef struct Tcl_Config { - const char* key; - const char* value; -} Tcl_Config; + const char *\fIkey\fR; + const char *\fIvalue\fR; +} \fBTcl_Config\fR; .CE .\" No cross references yet. .\" .SH "SEE ALSO" diff --git a/doc/RegExp.3 b/doc/RegExp.3 index 4383d98..2c999ea 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.28 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: RegExp.3,v 1.29 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures" @@ -339,10 +339,10 @@ defined as follows: .PP .CS typedef struct Tcl_RegExpInfo { - int \fInsubs\fR; - Tcl_RegExpIndices *\fImatches\fR; - long \fIextendStart\fR; -} Tcl_RegExpInfo; + int \fInsubs\fR; + Tcl_RegExpIndices *\fImatches\fR; + long \fIextendStart\fR; +} \fBTcl_RegExpInfo\fR; .CE .PP The \fInsubs\fR field contains a count of the number of parenthesized @@ -357,9 +357,9 @@ follows: .PP .CS typedef struct Tcl_RegExpIndices { - long \fIstart\fR; - long \fIend\fR; -} Tcl_RegExpIndices; + long \fIstart\fR; + long \fIend\fR; +} \fBTcl_RegExpIndices\fR; .CE .PP The \fIstart\fR and \fIend\fR values are Unicode character indices diff --git a/doc/SaveResult.3 b/doc/SaveResult.3 index d893bce..f2ed536 100644 --- a/doc/SaveResult.3 +++ b/doc/SaveResult.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: SaveResult.3,v 1.9 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: SaveResult.3,v 1.10 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" @@ -40,10 +40,8 @@ Saved state token to be restored or discarded. .AP Tcl_SavedResult *savedPtr in Pointer to location where interpreter result should be saved or restored. .BE - .SH DESCRIPTION .PP -.VS 8.5 These routines allows a C procedure to take a snapshot of the current state of an interpreter so that it can be restored after a call to \fBTcl_Eval\fR or some other routine that modifies the interpreter @@ -99,7 +97,6 @@ must eventually be passed to either \fBTcl_RestoreInterpState\fR or \fBTcl_DiscardInterpState\fR to avoid a memory leak. Once the \fBTcl_InterpState\fR token is passed to one of them, the token is no longer valid and should not be used anymore. -.VE 8.5 .PP \fBTcl_SaveResult\fR moves the string and object results of \fIinterp\fR into the location specified by \fIstatePtr\fR. @@ -121,6 +118,5 @@ Once \fBTcl_SaveResult\fR is called to save the interpreter result, either \fBTcl_RestoreResult\fR or \fBTcl_DiscardResult\fR must be called to properly clean up the memory associated with the saved state. - .SH KEYWORDS result, state, interp diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 3e3e56a..0c7f1ec 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.18 2007/12/13 15:22:31 dgp Exp $ +'\" RCS: @(#) $Id: SetResult.3,v 1.19 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures" @@ -216,7 +216,8 @@ When Tcl no longer needs the storage for the string, it will call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and result that match the type \fBTcl_FreeProc\fR: .CS -typedef void Tcl_FreeProc(char *\fIblockPtr\fR); +typedef void \fBTcl_FreeProc\fR( + 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. diff --git a/doc/SplitList.3 b/doc/SplitList.3 index 046cbdf..04986d5 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.13 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: SplitList.3,v 1.14 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures" @@ -67,7 +67,6 @@ Information about \fIsrc\fR. Must be value returned by previous call to \fBTcl_ScanElement\fR, possibly OR-ed with \fBTCL_DONT_USE_BRACES\fR. .BE - .SH DESCRIPTION .PP These procedures may be used to disassemble and reassemble Tcl lists. @@ -166,7 +165,6 @@ used to generate a portion of an argument for a Tcl command. In this case, surrounding \fIsrc\fR with curly braces would cause the command not to be parsed correctly. .PP -.VS 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 @@ -178,12 +176,10 @@ is not necessary. When the caller can be sure that the element is not the first element of a list, it can disable quoting of the leading hash character by OR-ing the flag value returned by \fBTcl_ScanElement\fR with \fBTCL_DONT_QUOTE_HASH\fR. -.VE 8.5 .PP \fBTcl_ScanCountedElement\fR and \fBTcl_ConvertCountedElement\fR are the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except the length of string \fIsrc\fR is specified by the \fIlength\fR argument, and the string may contain embedded nulls. - .SH KEYWORDS backslash, convert, element, list, merge, split, strings diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 index 2e76fa5..ad50fa6 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.9 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: StaticPkg.3,v 1.10 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" @@ -34,7 +34,6 @@ 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 @@ -55,7 +54,8 @@ or not. \fIinitProc\fR and \fIsafeInitProc\fR must both match the following prototype: .CS -typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); +typedef int \fBTcl_PackageInitProc\fR( + 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 @@ -64,6 +64,5 @@ 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/StringObj.3 b/doc/StringObj.3 index 3db8b1e..99bfdfb 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.27 2008/05/07 10:25:22 patthoyts Exp $ +'\" RCS: @(#) $Id: StringObj.3,v 1.28 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" @@ -62,7 +62,6 @@ void .sp void \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) -.VS 8.5 .sp void \fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR) @@ -78,7 +77,6 @@ Tcl_Obj * .sp void \fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...\fR) -.VE 8.5 .sp void \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) @@ -135,7 +133,9 @@ An argument list which must have been initialised using Maximum number of bytes to be appended. .AP "const char" *ellipsis in Suffix to append when the limit leads to string truncation. -If NULL is passed then the suffix "..." is used. +If NULL is passed then the suffix +.QW "..." +is used. .AP "const char" *format in Format control string including % conversion specifiers. .AP int objc in @@ -146,7 +146,6 @@ The array of objects to format or concatenate. New length for the string value of \fIobjPtr\fR, not including the final null character. .BE - .SH DESCRIPTION .PP The procedures described in this manual entry allow Tcl objects to @@ -253,7 +252,6 @@ must be a NULL pointer to indicate the end of the list. except that instead of taking a variable number of arguments it takes an argument list. .PP -.VS 8.5 \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR except that it imposes a limit on how many bytes are appended. This can be handy when the string to be appended might be @@ -333,7 +331,6 @@ Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...)); .CE but with greater convenience and efficiency when the appending functionality is needed. -.VE 8.5 .PP The \fBTcl_SetObjLength\fR procedure changes the length of the string value of its \fIobjPtr\fR argument. If the \fInewLength\fR @@ -369,10 +366,8 @@ 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, format, sprintf - .SH KEYWORDS append, internal representation, object, object type, string object, string type, string representation, concat, concatenate, unicode @@ -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.18 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: Tcl.n,v 1.19 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl n "8.5" Tcl "Tcl Built-In Commands" @@ -50,7 +50,6 @@ as ordinary characters and included in the word. Command substitution, variable substitution, and backslash substitution are performed on the characters between the quotes as described below. The double-quotes are not retained as part of the word. -.VS 8.5 br .IP "[5] \fBArgument expansion.\fR" If a word starts with the string .QW {*} @@ -64,7 +63,6 @@ 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 .PQ { @@ -107,11 +105,13 @@ Variable substitution may take any of the following forms: .RS .TP 15 \fB$\fIname\fR +. \fIName\fR is the name of a scalar variable; the name is a sequence of one or more characters that are a letter, digit, underscore, or namespace separators (two or more colons). .TP 15 \fB$\fIname\fB(\fIindex\fB)\fR +. \fIName\fR gives the name of an array variable and \fIindex\fR gives the name of an element within that array. \fIName\fR must contain only letters, digits, underscores, and @@ -120,6 +120,7 @@ Command substitutions, variable substitutions, and backslash substitutions are performed on the characters of \fIindex\fR. .TP 15 \fB${\fIname\fB}\fR +. \fIName\fR is the name of a scalar variable. It may contain any characters whatsoever except for close braces. .LP diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index b055e08..edbe115 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.16 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: Tcl_Main.3,v 1.17 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures" @@ -32,7 +32,6 @@ The value for this argument is usually \fBTcl_AppInit\fR. .AP Tcl_MainLoopProc *mainLoopProc in Address of an application-specific event loop procedure. .BE - .SH DESCRIPTION .PP \fBTcl_Main\fR can serve as the main program for Tcl-based shell @@ -48,7 +47,7 @@ library and interactive shell operation. Other styles of embedding Tcl in an application are not supported by \fBTcl_Main\fR. Those must be achieved by calling lower level functions in the Tcl library directly. - +.PP The \fBTcl_Main\fR function has been offered by the Tcl library since release Tcl 7.4. In older releases of Tcl, the Tcl library itself defined a function \fBmain\fR, but that lacks flexibility @@ -100,9 +99,10 @@ created by \fBTcl_Main\fR, such as defining application-specific commands. The procedure must have an interface that matches the type \fBTcl_AppInitProc\fR: .CS -typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR); +typedef int \fBTcl_AppInitProc\fR( + Tcl_Interp *\fIinterp\fR); .CE - +.PP \fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more details on this procedure, see the documentation for \fBTcl_AppInit\fR. .PP @@ -132,7 +132,7 @@ will continue. The main loop procedure must have an interface that matches the type \fBTcl_MainLoopProc\fR: .CS -typedef void Tcl_MainLoopProc(void); +typedef void \fBTcl_MainLoopProc\fR(void); .CE .PP \fBTcl_Main\fR does not return. Normally a program based on @@ -144,10 +144,8 @@ procedure (if any) returns. In non-interactive mode, after \fBTcl_Main\fR evaluates the startup script, and the main loop procedure (if any) returns, \fBTcl_Main\fR will also evaluate the \fBexit\fR command. - .SH "SEE ALSO" tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3), exit(n) - .SH KEYWORDS application-specific initialization, command-line arguments, main program diff --git a/doc/Thread.3 b/doc/Thread.3 index 0abcfd2..73ba742 100644 --- a/doc/Thread.3 +++ b/doc/Thread.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: Thread.3,v 1.28 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: Thread.3,v 1.29 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Threads 3 "8.1" Tcl "Tcl Library Procedures" @@ -182,13 +182,12 @@ 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 +.PP 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), diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index ed85403..813f6a1 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.11 2007/12/13 15:22:32 dgp Exp $ +'\" CVS: @(#) $Id: TraceCmd.3,v 1.12 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" @@ -65,7 +65,7 @@ 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( +typedef void \fBTcl_CommandTraceProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIoldName\fR, diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index 022ef40..02e4c0d 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.19 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: TraceVar.3,v 1.20 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures" @@ -124,7 +124,7 @@ Whenever one of the specified operations occurs on the variable, It should have arguments and result that match the type \fBTcl_VarTraceProc\fR: .CS -typedef char *Tcl_VarTraceProc( +typedef char *\fBTcl_VarTraceProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, char *\fIname1\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: Utf.3,v 1.25 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: Utf.3,v 1.26 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH Utf 3 "8.1" Tcl "Tcl Library Procedures" @@ -15,7 +15,7 @@ Tcl_UniChar, Tcl_UniCharCaseMatch, Tcl_UniCharNcasecmp, Tcl_UniCharToUtf, Tcl_Ut .nf \fB#include <tcl.h>\fR .sp -typedef ... Tcl_UniChar; +typedef ... \fBTcl_UniChar\fR; .sp int \fBTcl_UniCharToUtf\fR(\fIch, buf\fR) diff --git a/doc/bgerror.n b/doc/bgerror.n index be6af02..5f09133 100644 --- a/doc/bgerror.n +++ b/doc/bgerror.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: bgerror.n,v 1.13 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: bgerror.n,v 1.14 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH bgerror n 7.5 Tcl "Tcl Built-In Commands" @@ -16,9 +16,8 @@ bgerror \- Command invoked to process background errors .SH SYNOPSIS \fBbgerror \fImessage\fR .BE - .SH DESCRIPTION -.VS 8.5 +.PP Release 8.5 of Tcl supports the \fBinterp bgerror\fR command, which allows applications to register in an interpreter the command that will handle background errors in that interpreter. In older @@ -30,7 +29,6 @@ describes the interface requirements of the \fBbgerror\fR command an application might define to retain compatibility with pre-8.5 releases of Tcl. Applications intending to support only Tcl releases 8.5 and later should simply make use of \fBinterp bgerror\fR. -.VE 8.5 .PP The \fBbgerror\fR command does not exist as built-in part of Tcl. Instead, individual applications or users can define a \fBbgerror\fR @@ -77,6 +75,7 @@ The reason for this is that the application programmer may also want to define a \fBbgerror\fR, or use other code that does and thus will have trouble integrating your code. .SH "EXAMPLE" +.PP This \fBbgerror\fR procedure appends errors to a file, with a timestamp. .CS proc bgerror {message} { @@ -86,9 +85,7 @@ proc bgerror {message} { close $fl } .CE - .SH "SEE ALSO" after(n), interp(n), tclvars(n) - .SH KEYWORDS background error, reporting diff --git a/doc/binary.n b/doc/binary.n index 16f7533..95373fb 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.38 2008/01/02 21:21:37 dkf Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.39 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -212,13 +212,11 @@ will return a string equivalent to \fB\ex00\ex03\exff\exfd\ex01\ex02\fR. .RE .IP \fBt\fR 5 -.VS 8.5 This form (mnemonically \fItiny\fR) is the same as \fBs\fR and \fBS\fR except that it stores the 16-bit integers in the output string in the native byte order of the machine where the Tcl script is running. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. -.VE 8.5 .IP \fBi\fR 5 This form is the same as \fBc\fR except that it stores one or more 32-bit integers in little-endian byte order in the output string. The @@ -244,14 +242,12 @@ will return a string equivalent to \fB\ex00\ex00\ex00\ex03\exff\exff\exff\exfd\ex00\ex01\ex00\ex00\fR .RE .IP \fBn\fR 5 -.VS 8.5 This form (mnemonically \fInumber\fR or \fInormal\fR) is the same as \fBi\fR and \fBI\fR except that it stores the 32-bit integers in the output string in the native byte order of the machine where the Tcl script is running. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. -.VE 8.5 .IP \fBw\fR 5 This form is the same as \fBc\fR except that it stores one or more 64-bit integers in little-endian byte order in the output string. The @@ -275,14 +271,12 @@ For example, will return the string \fBBigEndian\fR .RE .IP \fBm\fR 5 -.VS 8.5 This form (mnemonically the mirror of \fBw\fR) is the same as \fBw\fR and \fBW\fR except that it stores the 64-bit integers in the output string in the native byte order of the machine where the Tcl script is running. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. -.VE 8.5 .IP \fBf\fR 5 This form is the same as \fBc\fR except that it stores one or more one or more single-precision floating point numbers in the machine's native @@ -304,18 +298,14 @@ will return a string equivalent to \fB\excd\excc\excc\ex3f\ex9a\ex99\ex59\ex40\fR. .RE .IP \fBr\fR 5 -.VS 8.5 This form (mnemonically \fIreal\fR) is the same as \fBf\fR except that it stores the single-precision floating point numbers in little-endian order. This conversion only produces meaningful output when used on machines which use the IEEE floating point representation (very common, but not universal.) -.VE 8.5 .IP \fBR\fR 5 -.VS 8.5 This form is the same as \fBr\fR except that it stores the single-precision floating point numbers in big-endian order. -.VE 8.5 .IP \fBd\fR 5 This form is the same as \fBf\fR except that it stores one or more one or more double-precision floating point numbers in the machine's native @@ -329,18 +319,14 @@ will return a string equivalent to \fB\ex9a\ex99\ex99\ex99\ex99\ex99\exf9\ex3f\fR. .RE .IP \fBq\fR 5 -.VS 8.5 This form (mnemonically the mirror of \fBd\fR) is the same as \fBd\fR except that it stores the double-precision floating point numbers in little-endian order. This conversion only produces meaningful output when used on machines which use the IEEE floating point representation (very common, but not universal.) -.VE 8.5 .IP \fBQ\fR 5 -.VS 8.5 This form is the same as \fBq\fR except that it stores the double-precision floating point numbers in big-endian order. -.VE 8.5 .IP \fBx\fR 5 Stores \fIcount\fR null bytes in the output string. If \fIcount\fR is not specified, stores one null byte. If \fIcount\fR is \fB*\fR, @@ -597,13 +583,11 @@ will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR stored in \fIvar2\fR. .RE .IP \fBt\fR 5 -.VS 8.5 The data is interpreted as \fIcount\fR 16-bit signed integers represented in the native byte order of the machine running the Tcl script. It is otherwise identical to \fBs\fR and \fBS\fR. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. -.VE 8.5 .IP \fBi\fR 5 The data is interpreted as \fIcount\fR 32-bit signed integers represented in little-endian byte order. The integers are stored in @@ -637,13 +621,11 @@ will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB\-16\fR stored in \fIvar2\fR. .RE .IP \fBn\fR 5 -.VS 8.5 The data is interpreted as \fIcount\fR 32-bit signed integers represented in the native byte order of the machine running the Tcl script. It is otherwise identical to \fBi\fR and \fBI\fR. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. -.VE 8.5 .IP \fBw\fR 5 The data is interpreted as \fIcount\fR 64-bit signed integers represented in little-endian byte order. The integers are stored in @@ -673,13 +655,11 @@ will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB\-16\fR stored in \fIvar2\fR. .RE .IP \fBm\fR 5 -.VS 8.5 The data is interpreted as \fIcount\fR 64-bit signed integers represented in the native byte order of the machine running the Tcl script. It is otherwise identical to \fBw\fR and \fBW\fR. To determine what the native byte order of the machine is, refer to the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. -.VE 8.5 .IP \fBf\fR 5 The data is interpreted as \fIcount\fR single-precision floating point numbers in the machine's native representation. The floating point @@ -700,19 +680,15 @@ will return \fB1\fR with \fB1.6000000238418579\fR stored in \fIvar1\fR. .RE .IP \fBr\fR 5 -.VS 8.5 This form is the same as \fBf\fR except that the data is interpreted as \fIcount\fR single-precision floating point number in little-endian order. This conversion is not portable to the minority of systems not using IEEE floating point representations. -.VE 8.5 .IP \fBR\fR 5 -.VS 8.5 This form is the same as \fBf\fR except that the data is interpreted as \fIcount\fR single-precision floating point number in big-endian order. This conversion is not portable to the minority of systems not using IEEE floating point representations. -.VE 8.5 .IP \fBd\fR 5 This form is the same as \fBf\fR except that the data is interpreted as \fIcount\fR double-precision floating point numbers in the @@ -726,19 +702,15 @@ will return \fB1\fR with \fB1.6000000000000001\fR stored in \fIvar1\fR. .RE .IP \fBq\fR 5 -.VS 8.5 This form is the same as \fBd\fR except that the data is interpreted as \fIcount\fR double-precision floating point number in little-endian order. This conversion is not portable to the minority of systems not using IEEE floating point representations. -.VE 8.5 .IP \fBQ\fR 5 -.VS 8.5 This form is the same as \fBd\fR except that the data is interpreted as \fIcount\fR double-precision floating point number in big-endian order. This conversion is not portable to the minority of systems not using IEEE floating point representations. -.VE 8.5 .IP \fBx\fR 5 Moves the cursor forward \fIcount\fR bytes in \fIstring\fR. If \fIcount\fR is \fB*\fR or is larger than the number of bytes after the @@ -780,6 +752,7 @@ will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR stored in \fIvar2\fR. .RE .SH "PORTABILITY ISSUES" +.PP The \fBr\fR, \fBR\fR, \fBq\fR and \fBQ\fR conversions will only work reliably for transferring data between computers which are all using IEEE floating point representations. This is very common, but not @@ -787,6 +760,7 @@ universal. To transfer floating-point numbers portably between all architectures, use their textual representation (as produced by \fBformat\fR) instead. .SH EXAMPLES +.PP This is a procedure to write a Tcl string to a binary-encoded channel as UTF-8 data preceded by a length word: .CS diff --git a/doc/catch.n b/doc/catch.n index 8ab44af..b108565 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.18 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: catch.n,v 1.19 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH catch n "8.5" Tcl "Tcl Built-In Commands" @@ -17,12 +17,11 @@ catch \- Evaluate script and trap exceptional returns .SH SYNOPSIS \fBcatch\fI script \fR?\fIresultVarName\fR? ?\fIoptionsVarName\fR? .BE - .SH DESCRIPTION .PP The \fBcatch\fR command may be used to prevent errors from aborting command -interpretation. The \fBcatch\fR command calls the Tcl interpreter recursively to -execute \fIscript\fR, and always returns without raising an error, +interpretation. The \fBcatch\fR command calls the Tcl interpreter recursively +to execute \fIscript\fR, and always returns without raising an error, regardless of any errors that might occur while executing \fIscript\fR. .PP If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer @@ -39,12 +38,11 @@ and scripts that make use of the \fBreturn -code\fR command can also have return codes other than the five defined by Tcl. .PP If the \fIresultVarName\fR argument is given, then the variable it names is -set to the result of the script evaluation. When the return code from -the script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an error -message. When the return code from the script is 0 (\fBTCL_OK\fR), the value -stored in \fIresultVarName\fR is the value returned from \fIscript\fR. +set to the result of the script evaluation. When the return code from the +script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an +error message. When the return code from the script is 0 (\fBTCL_OK\fR), the +value stored in \fIresultVarName\fR is the value returned from \fIscript\fR. .PP -.VS 8.5 If the \fIoptionsVarName\fR argument is given, then the variable it names is set to a dictionary of return options returned by evaluation of \fIscript\fR. Tcl specifies two entries that are always @@ -77,8 +75,8 @@ Tcl packages may provide commands that set other entries in the dictionary of return options, and the \fBreturn\fR command may be used by scripts to set return options in addition to those defined above. -.VE 8.5 .SH EXAMPLES +.PP The \fBcatch\fR command may be used in an \fBif\fR to branch based on the success of a script. .CS @@ -90,9 +88,7 @@ if { [\fBcatch\fR {open $someFile w} fid] } { .PP There are more complex examples of \fBcatch\fR usage in the documentation for the \fBreturn\fR command. - .SH "SEE ALSO" break(n), continue(n), dict(n), error(n), return(n), tclvars(n) - .SH KEYWORDS catch, error diff --git a/doc/encoding.n b/doc/encoding.n index 554a977..1a6983d 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.15 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: encoding.n,v 1.16 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH encoding n "8.1" Tcl "Tcl Built-In Commands" @@ -14,7 +14,6 @@ encoding \- Manipulate encodings .SH SYNOPSIS \fBencoding \fIoption\fR ?\fIarg arg ...\fR? .BE - .SH INTRODUCTION .PP Strings in Tcl are encoded using 16-bit Unicode characters. Different @@ -27,6 +26,7 @@ Performs one of several encoding related operations, depending on \fIoption\fR. The legal \fIoption\fRs are: .TP \fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR +. Convert \fIdata\fR to Unicode from the specified \fIencoding\fR. The characters in \fIdata\fR are treated as binary data where the lower 8-bits of each character is taken as a single byte. The resulting @@ -35,6 +35,7 @@ sequence of bytes is treated as a string in the specified system encoding is used. .TP \fBencoding convertto\fR ?\fIencoding\fR? \fIstring\fR +. Convert \fIstring\fR from Unicode to the specified \fIencoding\fR. The result is a sequence of bytes that represents the converted string. Each byte is stored in the lower 8-bits of a Unicode @@ -42,7 +43,7 @@ character. If \fIencoding\fR is not specified, the current system encoding is used. .TP \fBencoding dirs\fR ?\fIdirectoryList\fR? -.VS 8.5 +. Tcl can load encoding data files from the file system that describe additional encodings for it to work with. This command sets the search path for \fB*.enc\fR encoding data files to the list of directories @@ -52,13 +53,14 @@ search path. It is an error for \fIdirectoryList\fR to not be a valid list. If, when a search for an encoding data file is happening, an element in \fIdirectoryList\fR does not refer to a readable, searchable directory, that element is ignored. -.VE 8.5 .TP \fBencoding names\fR +. Returns a list containing the names of all of the encodings that are currently available. .TP \fBencoding system\fR ?\fIencoding\fR? +. Set the system encoding to \fIencoding\fR. If \fIencoding\fR is omitted then the command returns the current system encoding. The system encoding is used whenever Tcl passes strings to system calls. @@ -87,9 +89,7 @@ set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"] would return the Unicode string .QW "\eu306F" , which is the Hiragana letter HA. - .SH "SEE ALSO" Tcl_GetEncoding(3) - .SH KEYWORDS encoding @@ -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.10 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: eval.n,v 1.11 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH eval n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ eval \- Evaluate a Tcl script .SH SYNOPSIS \fBeval \fIarg \fR?\fIarg ...\fR? .BE - .SH DESCRIPTION .PP \fBEval\fR takes one or more arguments, which together comprise a Tcl @@ -50,13 +49,11 @@ for {set i 0} {$i<10} {incr i} { } .CE .PP -.VS 8.5 Note that in the most common case (where the script fragment is actually just a list of words forming a command prefix), it is better to use \fB{*}$script\fR when doing this sort of invocation pattern. It is less general than the \fBeval\fR command, and hence easier to make robust in practice. -.VE 8.5 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: @@ -69,16 +66,12 @@ proc lprepend {varName args} { set var [\fBeval\fR [list linsert $var 0] $args] } .CE -.VS 8.5 However, the last line would now normally be written without \fBeval\fR, like this: .CS set var [linsert $var 0 {*}$args] .CE -.VE 8.5 - .SH "SEE ALSO" catch(n), concat(n), error(n), interp(n), list(n), namespace(n), subst(n), tclvars(n), uplevel(n) - .SH KEYWORDS concatenate, evaluate, script @@ -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.23 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: exec.n,v 1.24 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH exec n 8.5 Tcl "Tcl Built-In Commands" @@ -17,7 +17,6 @@ exec \- Invoke subprocesses .SH SYNOPSIS \fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR? .BE - .SH DESCRIPTION .PP This command treats its arguments as the specification @@ -32,16 +31,17 @@ of the pipeline specification. The following switches are currently supported: .TP 13 \fB\-ignorestderr\fR -.VS 8.5 +. Stops the \fBexec\fR command from treating the output of messages to the pipeline's standard error channel as an error case. -.VE 8.5 .TP 13 \fB\-keepnewline\fR +. Retains a trailing newline in the pipeline's output. Normally a trailing newline will be deleted. .TP 13 \fB\-\|\-\fR +. Marks the end of switches. The argument following this one will be treated as the first \fIarg\fR even if it starts with a \fB\-\fR. .PP @@ -57,64 +57,77 @@ or in the same argument with no intervening space (i.e. .QW \fB<\fIfileName\fR ). .TP 15 \fB|\fR +. Separates distinct commands in the pipeline. The standard output of the preceding command will be piped into the standard input of the next command. .TP 15 \fB|&\fR +. Separates distinct commands in the pipeline. Both standard output and standard error of the preceding command will be piped into the standard input of the next command. This form of redirection overrides forms such as 2> and >&. .TP 15 \fB<\0\fIfileName\fR +. The file named by \fIfileName\fR is opened and used as the standard input for the first command in the pipeline. .TP 15 \fB<@\0\fIfileId\fR +. \fIFileId\fR must be the identifier for an open file, such as the return value from a previous call to \fBopen\fR. It is used as the standard input for the first command in the pipeline. \fIFileId\fR must have been opened for reading. .TP 15 \fB<<\0\fIvalue\fR +. \fIValue\fR is passed to the first command as its standard input. .TP 15 \fB>\0\fIfileName\fR +. Standard output from the last command is redirected to the file named \fIfileName\fR, overwriting its previous contents. .TP 15 \fB2>\0\fIfileName\fR +. Standard error from all commands in the pipeline is redirected to the file named \fIfileName\fR, overwriting its previous contents. .TP 15 \fB>&\0\fIfileName\fR +. Both standard output from the last command and standard error from all commands are redirected to the file named \fIfileName\fR, overwriting its previous contents. .TP 15 \fB>>\0\fIfileName\fR +. Standard output from the last command is redirected to the file named \fIfileName\fR, appending to it rather than overwriting it. .TP 15 \fB2>>\0\fIfileName\fR +. Standard error from all commands in the pipeline is redirected to the file named \fIfileName\fR, appending to it rather than overwriting it. .TP 15 \fB>>&\0\fIfileName\fR +. Both standard output from the last command and standard error from all commands are redirected to the file named \fIfileName\fR, appending to it rather than overwriting it. .TP 15 \fB>@\0\fIfileId\fR +. \fIFileId\fR must be the identifier for an open file, such as the return value from a previous call to \fBopen\fR. Standard output from the last command is redirected to \fIfileId\fR's file, which must have been opened for writing. .TP 15 \fB2>@\0\fIfileId\fR +. \fIFileId\fR must be the identifier for an open file, such as the return value from a previous call to \fBopen\fR. Standard error from all commands in the pipeline is @@ -122,11 +135,13 @@ redirected to \fIfileId\fR's file. The file must have been opened for writing. .TP 15 \fB2>@1\0\fR +. Standard error from all commands in the pipeline is redirected to the command result. This operator is only valid at the end of the command pipeline. .TP 15 \fB>&@\0\fIfileId\fR +. \fIFileId\fR must be the identifier for an open file, such as the return value from a previous call to \fBopen\fR. Both standard output from the last command and standard error from @@ -135,12 +150,9 @@ The file must have been opened for writing. .PP If standard output has not been redirected then the \fBexec\fR command returns the standard output from the last command -in the pipeline, -.VS 8.5 -unless +in the pipeline, unless .QW 2>@1 was specified, in which case standard error is included as well. -.VE 8.5 If any of the commands in the pipeline exit abnormally or are killed or suspended, then \fBexec\fR will return an error and the error message will include the pipeline's output followed by @@ -149,9 +161,7 @@ error messages describing the abnormal terminations; the about the last abnormal termination encountered. If any of the commands writes to its standard error file and that standard error is not redirected -.VS 8.5 and \fB\-ignorestderr\fR is not specified, -.VE 8.5 then \fBexec\fR will return an error; the error message will include the pipeline's standard output, followed by messages about abnormal terminations (if any), followed by the standard error @@ -353,6 +363,7 @@ console window is not available to them. .RE .TP \fBUnix\fR\0\0\0\0\0\0\0 +. The \fBexec\fR command is fully functional and works as described. .SH "UNIX EXAMPLES" Here are some examples of the use of the \fBexec\fR command on Unix. @@ -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.34 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: expr.n,v 1.35 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH expr n 8.5 Tcl "Tcl Built-In Commands" @@ -43,7 +43,6 @@ and parentheses. White space may be used between the operands and operators and parentheses; it is ignored by the expression's instructions. Where possible, operands are interpreted as integer values. -.VS 8.5 Integer values may be specified in decimal (the normal case), in binary (if the first two characters of the operand are \fB0b\fR), in octal (if the first two characters of the operand are \fB0o\fR), or in hexadecimal @@ -60,7 +59,6 @@ the sign characters \fB+\fR or \fB\-\fR. For example, all of the following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. Also recognized as floating point values are the strings \fBInf\fR and \fBNaN\fR making use of any case for each character. -.VE 8.5 If no numeric interpretation is possible (note that all literal operands that are not numeric or boolean must be quoted with either braces or with double quotes), then an operand is left as a string @@ -91,7 +89,7 @@ the operand. As a mathematical function whose arguments have any of the above forms for operands, such as \fBsin($x)\fR. See \fBMATH FUNCTIONS\fR below for a discussion of how mathematical functions are handled. -.LP +.PP Where the above substitutions occur (e.g. inside quoted strings), they are performed by the expression's instructions. However, the command parser may already have performed one round of @@ -119,16 +117,17 @@ the \fBtcl::mathop\fR namespace; see the \fBmathop\fR(n) manual page for details) are listed below, grouped in decreasing order of precedence: .TP 20 \fB\-\0\0+\0\0~\0\0!\fR +. Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators may be applied to string operands, and bit-wise NOT may be applied only to integers. .TP 20 \fB**\fR -.VS 8.5 +. Exponentiation. Valid for any numeric operands. -.VE 8.5 .TP 20 \fB*\0\0/\0\0%\fR +. Multiply, divide, remainder. None of these operators may be applied to string operands, and remainder may be applied only to integers. @@ -136,66 +135,74 @@ The remainder will always have the same sign as the divisor and an absolute value smaller than the divisor. .TP 20 \fB+\0\0\-\fR +. Add and subtract. Valid for any numeric operands. .TP 20 \fB<<\0\0>>\fR +. Left and right shift. Valid for integer operands only. A right shift always propagates the sign bit. .TP 20 \fB<\0\0>\0\0<=\0\0>=\fR +. Boolean less, greater, less than or equal, and greater than or equal. Each operator produces 1 if the condition is true, 0 otherwise. These operators may be applied to strings as well as numeric operands, in which case string comparison is used. .TP 20 \fB==\0\0!=\fR +. Boolean equal and not equal. Each operator produces a zero/one result. Valid for all operand types. .TP 20 \fBeq\0\0ne\fR +. Boolean string equal and string not equal. Each operator produces a zero/one result. The operand types are interpreted only as strings. .TP 20 \fBin\0\0ni\fR -.VS 8.5 +. List containment and negated list containment. Each operator produces a zero/one result and treats its first argument as a string and its second argument as a Tcl list. The \fBin\fR operator indicates whether the first argument is a member of the second argument list; the \fBni\fR operator inverts the sense of the result. -.VE 8.5 .TP 20 \fB&\fR +. Bit-wise AND. Valid for integer operands only. .TP 20 \fB^\fR +. Bit-wise exclusive OR. Valid for integer operands only. .TP 20 \fB|\fR +. Bit-wise OR. Valid for integer operands only. .TP 20 \fB&&\fR +. Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. Valid for boolean and numeric (integers or floating-point) operands only. .TP 20 \fB||\fR +. Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. Valid for boolean and numeric (integers or floating-point) operands only. .TP 20 \fIx\fB?\fIy\fB:\fIz\fR +. If-then-else, as in C. If \fIx\fR evaluates to non-zero, then the result is the value of \fIy\fR. Otherwise the result is the value of \fIz\fR. The \fIx\fR operand must have a boolean or numeric value. -.LP +.PP See the C manual for more details on the results produced by each operator. -.VS 8.5 The exponentiation operator promotes types like the multiply and divide operators, and produces a result that is the same as the output of the \fBpow\fR function (after any type conversions.) -.VE 8.5 All of the binary operators group left-to-right within the same precedence level. For example, the command .CS @@ -224,7 +231,6 @@ and before invoking the \fBexpr\fR command. .SS "MATH FUNCTIONS" .PP -.VS 8.5 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 @@ -249,10 +255,8 @@ may as well (depending on the current \fBnamespace path\fR setting). .PP See the \fBmathfunc\fR(n) manual page for the math functions that are available by default. -.VE 8.5 .SS "TYPES, OVERFLOW, AND PRECISION" .PP -.VS 8.5 All internal computations involving integers are done calling on the LibTomMath multiple precision integer library as required so that all integer calculations are performed exactly. Note that in Tcl releases @@ -262,7 +266,6 @@ in those calculations where values overflowed the range of those types. Any code that relied on these implicit truncations will need to explicitly add \fBint()\fR or \fBwide()\fR function calls to expressions at the points where such truncation is required to take place. -.VE 8.5 .PP All internal computations involving floating-point are done with the C type \fIdouble\fR. @@ -351,12 +354,11 @@ The most expensive code is required for unbraced expressions that contain command substitutions. These expressions must be implemented by generating new code each time the expression is executed. -.VS 8.5 When the expression is unbraced to allow the substitution of a function or operator, consider using the commands documented in the \fBmathfunc\fR(n) or \fBmathop\fR(n) manual pages directly instead. -.VE 8.5 .SH EXAMPLES +.PP Define a procedure that computes an .QW interesting mathematical function: @@ -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: incr.n,v 1.6 2006/02/09 17:34:41 dgp Exp $ +'\" RCS: @(#) $Id: incr.n,v 1.7 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH incr n "" Tcl "Tcl Built-In Commands" @@ -16,7 +16,6 @@ incr \- Increment the value of a variable .SH SYNOPSIS \fBincr \fIvarName \fR?\fIincrement\fR? .BE - .SH DESCRIPTION .PP Increments the value stored in the variable whose name is \fIvarName\fR. @@ -27,12 +26,11 @@ integer) is added to the value of variable \fIvarName\fR; otherwise The new value is stored as a decimal string in variable \fIvarName\fR and also returned as result. .PP -.VS 8.5 Starting with the Tcl 8.5 release, the variable \fIvarName\fR passed to \fBincr\fR may be unset, and in that case, it will be set to the value \fIincrement\fR or to the default increment value of \fB1\fR. -.VE 8.5 .SH EXAMPLES +.PP Add one to the contents of the variable \fIx\fR: .CS \fBincr\fR x @@ -55,9 +53,7 @@ an error if it is not): .CS \fBincr\fR x 0 .CE - .SH "SEE ALSO" expr(n) - .SH KEYWORDS add, increment, variable, value @@ -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: info.n,v 1.26 2008/05/31 11:42:12 dkf Exp $ +'\" RCS: @(#) $Id: info.n,v 1.27 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH info n 8.4 Tcl "Tcl Built-In Commands" @@ -19,7 +19,6 @@ info \- Return information about the state of the Tcl interpreter .SH SYNOPSIS \fBinfo \fIoption \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP This command provides information about various internals of the Tcl @@ -27,27 +26,30 @@ interpreter. The legal \fIoption\fRs (which may be abbreviated) are: .TP \fBinfo args \fIprocname\fR +. Returns a list containing the names of the arguments to procedure \fIprocname\fR, in order. \fIProcname\fR must be the name of a Tcl command procedure. .TP \fBinfo body \fIprocname\fR +. Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be the name of a Tcl command procedure. .TP \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR -. +.VS 8.6 Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are described in \fBCLASS INTROSPECTION\fR below. +.VE 8.6 .TP \fBinfo cmdcount\fR +. Returns a count of the total number of commands that have been invoked in this interpreter. .TP \fBinfo commands \fR?\fIpattern\fR? +. If \fIpattern\fR is not specified, -.\" Do not move this .VS above the .TP -.VS 8.5 returns a list of names of all the Tcl commands visible (i.e. executable without using a qualified name) to the current namespace, including both the built-in commands written in C and @@ -66,9 +68,9 @@ of the specified namespace, and only the commands defined in the named namespace are returned. .\" Technically, most of this hasn't changed; that's mostly just the .\" way it always worked. Hardly anyone knew that though. -.VE 8.5 .TP \fBinfo complete \fIcommand\fR +. Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of having no unclosed quotes, braces, brackets or array element names. If the command does not appear to be complete then 0 is returned. @@ -78,6 +80,7 @@ command is not complete, the script can delay evaluating it until additional lines have been typed to complete the command. .TP \fBinfo default \fIprocname arg varname\fR +. \fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR must be the name of an argument to that procedure. If \fIarg\fR does not have a default value then the command returns \fB0\fR. @@ -85,11 +88,13 @@ Otherwise it returns \fB1\fR and places the default value of \fIarg\fR into variable \fIvarname\fR. .TP \fBinfo exists \fIvarName\fR +. Returns \fB1\fR if the variable named \fIvarName\fR exists in the current context (either as a global or local variable) and has been defined by being given a value, returns \fB0\fR otherwise. .TP \fBinfo frame\fR ?\fInumber\fR? +. This command provides access to all frames on the stack, even those hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this command returns a number giving the frame level of the command. This @@ -120,28 +125,34 @@ The result dictionary may contain the keys listed below, with the specified meanings for their values: .TP \fBtype\fR +. This entry is always present and describes the nature of the location for the command. The recognized values are \fBsource\fR, \fBproc\fR, \fBeval\fR, and \fBprecompiled\fR. .RS .TP \fBsource\fR\0\0\0\0\0\0\0\0 +. means that the command is found in a script loaded by the \fBsource\fR command. .TP \fBproc\fR\0\0\0\0\0\0\0\0 +. means that the command is found in dynamically created procedure body. .TP \fBeval\fR\0\0\0\0\0\0\0\0 +. means that the command is executed by \fBeval\fR or \fBuplevel\fR. .TP \fBprecompiled\fR\0\0\0\0\0\0\0\0 +. means that the command is found in a precompiled script (loadable by the package \fBtbcload\fR), and no further information will be available. .RE .TP \fBline\fR +. This entry provides the number of the line the command is at inside of the script it is a part of. This information is not present for type \fBprecompiled\fR. For type \fBsource\fR this information is counted @@ -149,10 +160,12 @@ relative to the beginning of the file, whereas for the last two types the line is counted relative to the start of the script. .TP \fBfile\fR +. This entry is present only for type \fBsource\fR. It provides the normalized path of the file the command is in. .TP \fBcmd\fR +. This entry provides the string representation of the command. This is usually the unsubstituted form, however for commands which are a pure list executed by eval it is the substituted form as they have no other @@ -160,15 +173,18 @@ string representation. Care is taken that the pure-List property of the latter is not spoiled. .TP \fBproc\fR +. This entry is present only if the command is found in the body of a regular Tcl procedure. It then provides the name of that procedure. .TP \fBlambda\fR +. This entry is present only if the command is found in the body of an anonymous Tcl procedure, i.e. a lambda. It then provides the entire definition of the lambda in question. .TP \fBlevel\fR +. This entry is present only if the queried frame has a corresponding frame returned by \fBinfo level\fR. It provides the index of this frame, relative to the current level (0 and negative numbers). @@ -199,6 +215,7 @@ counted relative to the start of each word (smallest scope) .RE .TP \fBinfo functions \fR?\fIpattern\fR? +. If \fIpattern\fR is not specified, returns a list of all the math functions currently defined. If \fIpattern\fR is specified, only those functions whose name matches @@ -206,6 +223,7 @@ If \fIpattern\fR is specified, only those functions whose name matches rules as for \fBstring match\fR. .TP \fBinfo globals \fR?\fIpattern\fR? +. If \fIpattern\fR is not specified, returns a list of all the names of currently-defined global variables. Global variables are variables in the global namespace. @@ -214,6 +232,7 @@ are returned. Matching is determined using the same rules as for \fBstring match\fR. .TP \fBinfo hostname\fR +. Returns the name of the computer on which this invocation is being executed. Note that this name is not guaranteed to be the fully qualified domain @@ -223,6 +242,7 @@ installed,) it is the name that is suitable for TCP/IP networking that is returned. .TP \fBinfo level\fR ?\fInumber\fR? +. If \fInumber\fR is not specified, this command returns a number giving the stack level of the invoking procedure, or 0 if the command is invoked at top-level. If \fInumber\fR is specified, @@ -236,6 +256,7 @@ See the \fBuplevel\fR command for more information on what stack levels mean. .TP \fBinfo library\fR +. Returns the name of the library directory in which standard Tcl scripts are stored. This is actually the value of the \fBtcl_library\fR @@ -243,6 +264,7 @@ variable and may be changed by setting \fBtcl_library\fR. See the \fBtclvars\fR manual entry for more information. .TP \fBinfo loaded \fR?\fIinterp\fR? +. Returns a list describing all of the packages that have been loaded into \fIinterp\fR with the \fBload\fR command. Each list element is a sub-list with two elements consisting of the @@ -255,6 +277,7 @@ To get a list of just the packages in the current interpreter, specify an empty string for the \fIinterp\fR argument. .TP \fBinfo locals \fR?\fIpattern\fR? +. If \fIpattern\fR is not specified, returns a list of all the names of currently-defined local variables, including arguments to the current procedure, if any. @@ -265,20 +288,24 @@ are returned. Matching is determined using the same rules as for \fBstring match\fR. .TP \fBinfo nameofexecutable\fR +. Returns the full path name of the binary file from which the application was invoked. If Tcl was unable to identify the file, then an empty string is returned. .TP \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR -. +.VS 8.6 Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are described in \fBOBJECT INTROSPECTION\fR below. +.VE 8.6 .TP \fBinfo patchlevel\fR +. Returns the value of the global variable \fBtcl_patchLevel\fR; see the \fBtclvars\fR manual entry for more information. .TP \fBinfo procs \fR?\fIpattern\fR? +. If \fIpattern\fR is not specified, returns a list of all the names of Tcl command procedures in the current namespace. If \fIpattern\fR is specified, @@ -293,6 +320,7 @@ within; the matching pattern is taken to be the part after the last namespace separator. .TP \fBinfo script\fR ?\fIfilename\fR? +. If a Tcl script file is currently being evaluated (i.e. there is a call to \fBTcl_EvalFile\fR active or there is an active invocation of the \fBsource\fR command), then this command returns the name @@ -303,16 +331,19 @@ useful in virtual file system applications. Otherwise the command returns an empty string. .TP \fBinfo sharedlibextension\fR +. Returns the extension used on this platform for the names of files containing shared libraries (for example, \fB.so\fR under Solaris). If shared libraries are not supported on this platform then an empty string is returned. .TP \fBinfo tclversion\fR +. Returns the value of the global variable \fBtcl_version\fR; see the \fBtclvars\fR manual entry for more information. .TP \fBinfo vars\fR ?\fIpattern\fR? +. If \fIpattern\fR is not specified, returns a list of all the names of currently-visible variables. This includes locals and currently-visible globals. @@ -333,173 +364,203 @@ Note that a currently-visible variable may not yet if it has not been set (e.g. a variable declared but not set by \fBvariable\fR). .SS "CLASS INTROSPECTION" +.VS 8.6 .PP The following \fIsubcommand\fR values are supported by \fBinfo class\fR: +.VE 8.6 .TP \fBinfo class constructor\fI class\fR -. +.VS 8.6 This subcommand returns a description of the definition of the constructor of class \fIclass\fR. The defintion is described as a two element list; the first element is the list of arguments to the constructor in a form suitable for passing to another call to \fBproc\fR or a method defintion, and the second element is the body of the constructor. If no constructor is present, this returns the empty list. +.VE 8.6 .TP \fBinfo class definition\fI class method\fR -. +.VS 8.6 This subcommand returns a description of the definition of the method named \fImethod\fR of class \fIclass\fR. The defintion is described as a two element list; the first element is the list of arguments to the method in a form suitable for passing to another call to \fBproc\fR or a method defintion, and the second element is the body of the method. +.VE 8.6 .TP \fBinfo class destructor\fI class\fR -. +.VS 8.6 This subcommand returns the body of the destructor of class \fIclass\fR. If no destructor is present, this returns the empty string. +.VE 8.6 .TP \fBinfo class filters\fI class\fR -. +.VS 8.6 This subcommand returns the list of filter methods set on the class. +.VE 8.6 .TP \fBinfo class forward\fI class method\fR -. +.VS 8.6 This subcommand returns the argument list for the method forwarding called \fImethod\fR that is set on the class called \fIclass\fR. +.VE 8.6 .TP \fBinfo class instances\fI class\fR ?\fIpattern\fR? -. +.VS 8.6 This subcommand returns a list of instances of class \fIclass\fR. If the optional \fIpattern\fR argument is present, it constrains the list of returned instances to those that match it according to the rules of \fBstring match\fR. +.VE 8.6 .TP \fBinfo class methods\fI class\fR ?\fIoptions...\fR? -. +.VS 8.6 This subcommand returns a list of all public (i.e. exported) methods of the class called \fIclass\fR. Any of the following \fIoption\fRs may be specified, controlling exactly which method names are returned: .RS +.VE 8.6 .TP \fB\-all\fR -. +.VS 8.6 If the \fB\-all\fR flag is given, the list of methods will include those methods defined not just by the class, but also by the class's superclasses and mixins. +.VE 8.6 .TP \fB\-private\fR -. +.VS 8.6 If the \fB\-private\fR flag is given, the list of methods will also include the private (i.e. non-exported) methods of the class (and superclasses and mixins, if \fB\-all\fR is also given). .RE +.VE 8.6 .TP \fBinfo class mixins\fI class\fR -. +.VS 8.6 This subcommand returns a list of all classes that have been mixed into the class named \fIclass\fR. +.VE 8.6 .TP \fBinfo class subclasses\fI class\fR ?\fIpattern\fR? -. +.VS 8.6 This subcommand returns a list of direct subclasses of class \fIclass\fR. If the optional \fIpattern\fR argument is present, it constrains the list of returned classes to those that match it according to the rules of \fBstring match\fR. +.VE 8.6 .TP \fBinfo class superclasses\fI class\fR -. +.VS 8.6 This subcommand returns a list of direct superclasses of class \fIclass\fR in inheritance precedence order. .SS "OBJECT INTROSPECTION" .PP The following \fIsubcommand\fR values are supported by \fBinfo object\fR: +.VE 8.6 .TP \fBinfo object class\fI object\fR ?\fIclassName\fR? -. +.VS 8.6 If \fIclassName\fR is unspecified, this subcommand returns class of the \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a boolean value indicating whether the \fIobject\fR is of that class. +.VE 8.6 .TP \fBinfo object definition\fI object method\fR -. +.VS 8.6 This subcommand returns a description of the definition of the method named \fImethod\fR of object \fIobject\fR. The defintion is described as a two element list; the first element is the list of arguments to the method in a form suitable for passing to another call to \fBproc\fR or a method defintion, and the second element is the body of the method. +.VE 8.6 .TP \fBinfo object filters\fI object\fR -. +.VS 8.6 This subcommand returns the list of filter methods set on the object. +.VE 8.6 .TP \fBinfo object forward\fI object method\fR -. +.VS 8.6 This subcommand returns the argument list for the method forwarding called \fImethod\fR that is set on the object called \fIobject\fR. +.VE 8.6 .TP \fBinfo object isa\fI category object\fR ?\fIarg\fR? -. +.VS 8.6 This subcommand tests whether an object belongs to a particular category, returning a boolean value that indicates whether the \fIobject\fR argument meets the criteria for the category. The supported categories are: +.VE 8.6 .RS .TP \fBinfo object isa class\fI object\fR -. +.VS 8.6 This returns whether \fIobject\fR is a class (i.e. an instance of \fBoo::class\fR or one of its subclasses). +.VE 8.6 .TP \fBinfo object isa metaclass\fI object\fR -. +.VS 8.6 This returns whether \fIobject\fR is a class that can manufacture classes (i.e. is \fBoo::class\fR or a subclass of it). +.VE 8.6 .TP \fBinfo object isa mixin\fI object class\fR -. +.VS 8.6 This returns whether \fIclass\fR is directly mixed into \fIobject\fR. +.VE 8.6 .TP \fBinfo object isa object\fI object\fR -. +.VS 8.6 This returns whether \fIobject\fR really is an object. +.VE 8.6 .TP \fBinfo object isa typeof\fI object class\fR -. +.VS 8.6 This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether direct or indirect). .RE +.VE 8.6 .TP \fBinfo object methods\fI object\fR ?\fIoption...\fR? -. +.VS 8.6 This subcommand returns a list of all public (i.e. exported) methods of the object called \fIobject\fR. Any of the following \fIoption\fRs may be specified, controlling exactly which method names are returned: .RS +.VE 8.6 .TP \fB\-all\fR -. +.VS 8.6 If the \fB\-all\fR flag is given, the list of methods will include those methods defined not just by the object, but also by the object's class and mixins, plus the superclasses of those classes. +.VE 8.6 .TP \fB\-private\fR -. +.VS 8.6 If the \fB\-private\fR flag is given, the list of methods will also include the private (i.e. non-exported) methods of the object (and classes, if \fB\-all\fR is also given). .RE +.VE 8.6 .TP \fBinfo object mixins\fI object\fR -. +.VS 8.6 This subcommand returns a list of all classes that have been mixed into the object named \fIobject\fR. +.VE 8.6 .TP \fBinfo object vars\fI object\fR ?\fIpattern\fR? -. +.VS 8.6 This subcommand returns a list of all variables in the private namespace of the object named \fIobject\fR. If the optional \fIpattern\fR argument is given, it is a filter (in the syntax of a \fBstring match\fR glob pattern) that constrains the list of variables returned. +.VE 8.6 .SH EXAMPLES +.PP This command prints out a procedure suitable for saving in a Tcl script: .PP @@ -520,6 +581,7 @@ proc printProc {procName} { } .CE .SS "EXAMPLES WITH OBJECTS" +.VS 8.6 .PP Every object necessarily knows what its class is; this information is trivially extractable through introspection: @@ -552,10 +614,16 @@ proc getDef {obj method} { return [\fBinfo class definition\fR $cls $method] } .CE +.VE 8.6 .SH "SEE ALSO" +.VS 8.6 global(n), oo::class(n), oo::object(n), proc(n), self(n) +.VE 8.6 .SH KEYWORDS -command, information, interpreter, introspection, level, namespace, object, +command, information, interpreter, introspection, level, namespace, +.VS 8.6 +object, +.VE 8.6 procedure, variable .\" Local Variables: .\" mode: nroff diff --git a/doc/lindex.n b/doc/lindex.n index d13924b..ac17d25 100644 --- a/doc/lindex.n +++ b/doc/lindex.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: lindex.n,v 1.17 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: lindex.n,v 1.18 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH lindex n 8.4 Tcl "Tcl Built-In Commands" @@ -46,11 +46,9 @@ substitution and command substitution do not occur. If \fIindex\fR is negative or greater than or equal to the number of elements in \fIvalue\fR, then an empty string is returned. -.VS 8.5 The interpretation of each simple \fIindex\fR value is the same as for the command \fBstring index\fR, supporting simple index arithmetic and indices relative to the end of the list. -.VE 8.5 .PP If additional \fIindex\fR arguments are supplied, then each argument is used in turn to select an element from the previous indexing operation, @@ -67,6 +65,7 @@ is synonymous with lindex [lindex [lindex $a 1] 2] 3 .CE .SH EXAMPLES +.PP .CS \fBlindex\fR {a b c} \fI\(-> a b c\fR @@ -92,9 +91,6 @@ lindex [lindex [lindex $a 1] 2] 3 .SH "SEE ALSO" list(n), lappend(n), linsert(n), llength(n), lsearch(n), lset(n), lsort(n), lrange(n), lreplace(n), -.VS 8.5 string(n) -.VE - .SH KEYWORDS element, index, list diff --git a/doc/linsert.n b/doc/linsert.n index 5930a90..79ec3ff 100644 --- a/doc/linsert.n +++ b/doc/linsert.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: linsert.n,v 1.14 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: linsert.n,v 1.15 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH linsert n 8.2 Tcl "Tcl Built-In Commands" @@ -17,7 +17,6 @@ linsert \- Insert elements into a list .SH SYNOPSIS \fBlinsert \fIlist index element \fR?\fIelement element ...\fR? .BE - .SH DESCRIPTION .PP This command produces a new list from \fIlist\fR by inserting all of the @@ -25,12 +24,11 @@ This command produces a new list from \fIlist\fR by inserting all of the \fIlist\fR. Each \fIelement\fR argument will become a separate element of the new list. If \fIindex\fR is less than or equal to zero, then the new elements are inserted at the beginning of the list. -.VS 8.5 The interpretation of the \fIindex\fR value is the same as for the command \fBstring index\fR, supporting simple index arithmetic and indices relative to the end of the list. -.VE .SH EXAMPLE +.PP Putting some values into a list, first indexing from the start and then indexing from the end, and then chaining them together: .CS @@ -40,13 +38,9 @@ set newList [\fBlinsert\fR $midList end-1 lazy] # The old lists still exist though... set newerList [\fBlinsert\fR [\fBlinsert\fR $oldList end-1 quick] 1 lazy] .CE - .SH "SEE ALSO" list(n), lappend(n), lindex(n), llength(n), lsearch(n), lset(n), lsort(n), lrange(n), lreplace(n), -.VS 8.5 string(n) -.VE - .SH KEYWORDS element, insert, list @@ -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: list.n,v 1.11 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: list.n,v 1.12 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH list n "" Tcl "Tcl Built-In Commands" @@ -17,7 +17,6 @@ list \- Create a list .SH SYNOPSIS \fBlist \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP This command returns a list comprised of all the \fIarg\fRs, @@ -30,6 +29,7 @@ its arguments. \fBList\fR produces slightly different results than \fBconcat\fR: \fBconcat\fR removes one level of grouping before forming the list, while \fBlist\fR works directly from the original arguments. .SH EXAMPLE +.PP The command .CS \fBlist\fR a b "c d e " " f {g h}" @@ -42,13 +42,9 @@ while \fBconcat\fR with the same arguments will return .CS \fBa b c d e f {g h}\fR .CE - .SH "SEE ALSO" lappend(n), lindex(n), linsert(n), llength(n), lrange(n), -.VS 8.5 lrepeat(n), -.VE 8.5 lreplace(n), lsearch(n), lset(n), lsort(n) - .SH KEYWORDS element, list @@ -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.22 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: load.n,v 1.23 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH load n 7.5 Tcl "Tcl Built-In Commands" @@ -19,7 +19,6 @@ load \- Load machine code and initialize new commands .br \fBload \fIfileName packageName interp\fR .BE - .SH DESCRIPTION .PP This command loads binary code from a file into the @@ -59,7 +58,8 @@ on Safe\-Tcl, see the \fBsafe\fR manual entry. .PP The initialization procedure must match the following prototype: .CS -typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); +typedef int \fBTcl_PackageInitProc\fR( + 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 @@ -73,12 +73,10 @@ in an application. If a given \fIfileName\fR is loaded into multiple interpreters, then the first \fBload\fR will load the code and call the initialization procedure; subsequent \fBload\fRs will call the initialization procedure without loading the code again. -.VS 8.5 For Tcl versions lower than 8.5, it is not possible to unload or reload a package. From version 8.5 however, the \fBunload\fR command allows the unloading of libraries loaded with \fBload\fR, for libraries that are aware of the Tcl's unloading mechanism. -.VE 8.5 .PP The \fBload\fR command also supports packages that are statically linked with the application, if those packages have been registered @@ -131,6 +129,7 @@ be loaded into the process's address space multiple times. The behavior of this varies from system to system (some systems may detect the redundant loads, others may not). .SH EXAMPLE +.PP The following is a minimal extension: .PP .CS @@ -169,9 +168,7 @@ switch $tcl_platform(platform) { # Now execute the command defined by the extension foo .CE - .SH "SEE ALSO" info sharedlibextension, Tcl_StaticPackage(3), safe(n) - .SH KEYWORDS binary code, loading, safe interpreter, shared library diff --git a/doc/lrange.n b/doc/lrange.n index 290e37f..830d7fa 100644 --- a/doc/lrange.n +++ b/doc/lrange.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: lrange.n,v 1.17 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: lrange.n,v 1.18 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH lrange n 7.4 Tcl "Tcl Built-In Commands" @@ -17,18 +17,15 @@ lrange \- Return one or more adjacent elements from a list .SH SYNOPSIS \fBlrange \fIlist first last\fR .BE - .SH DESCRIPTION .PP \fIList\fR must be a valid Tcl list. This command will return a new list consisting of elements \fIfirst\fR through \fIlast\fR, inclusive. -.VS 8.5 The index values \fIfirst\fR and \fIlast\fR are interpreted the same as index values for the command \fBstring index\fR, supporting simple index arithmetic and indices relative to the end of the list. -.VE If \fIfirst\fR is less than zero, it is treated as if it were zero. If \fIlast\fR is greater than or equal to the number of elements in the list, then it is treated as if it were \fBend\fR. @@ -70,13 +67,9 @@ elements to % \fBlrange\fR $var 1 1 {elements to} .CE - .SH "SEE ALSO" list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lset(n), lreplace(n), lsort(n), -.VS 8.5 string(n) -.VE - .SH KEYWORDS element, list, range, sublist diff --git a/doc/lreplace.n b/doc/lreplace.n index deda8d9..605e46f 100644 --- a/doc/lreplace.n +++ b/doc/lreplace.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: lreplace.n,v 1.19 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: lreplace.n,v 1.20 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH lreplace n 7.4 Tcl "Tcl Built-In Commands" @@ -21,7 +21,6 @@ lreplace \- Replace elements in a list with new elements .PP \fBlreplace\fR returns a new list formed by replacing one or more elements of \fIlist\fR with the \fIelement\fR arguments. -.VS 8.5 \fIfirst\fR and \fIlast\fR are index values specifying the first and last elements of the range to replace. The index values \fIfirst\fR and \fIlast\fR are interpreted @@ -31,7 +30,6 @@ end of the list. 0 refers to the first element of the list, and \fBend\fR refers to the last element of the list. If \fIlist\fR is empty, then \fIfirst\fR and \fIlast\fR are ignored. -.VE .PP If \fIfirst\fR is less than zero, it is considered to refer to before the first element of the list. For non-empty lists, the element indicated @@ -49,6 +47,7 @@ the list. If no \fIelement\fR arguments are specified, then the elements between \fIfirst\fR and \fIlast\fR are simply deleted. If \fIlist\fR is empty, any \fIelement\fR arguments are added to the end of the list. .SH EXAMPLES +.PP Replacing an element of a list with another: .CS % \fBlreplace\fR {a b c d e} 1 1 foo @@ -80,8 +79,6 @@ proc lremove {listVariable value} { .SH "SEE ALSO" list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lset(n), lrange(n), lsort(n), -.VS 8.5 string(n) -.VE .SH KEYWORDS element, list, replace diff --git a/doc/lsearch.n b/doc/lsearch.n index 3457237..b5f950d 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.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: lsearch.n,v 1.34 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: lsearch.n,v 1.35 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH lsearch n 8.5 Tcl "Tcl Built-In Commands" @@ -18,7 +18,6 @@ lsearch \- See if a list contains a particular element .SH SYNOPSIS \fBlsearch \fR?\fIoptions\fR? \fIlist pattern\fR .BE - .SH DESCRIPTION .PP This command searches the elements of \fIlist\fR to see if one @@ -29,24 +28,29 @@ If not, the command returns \fB\-1\fR. The \fIoption\fR arguments indicates how the elements of the list are to be matched against \fIpattern\fR and must have one of the values below: .SS "MATCHING STYLE OPTIONS" +.PP If all matching style options are omitted, the default matching style is \fB\-glob\fR. If more than one matching style is specified, the last matching style given takes precedence. .TP \fB\-exact\fR +. \fIPattern\fR is a literal string that is compared for exact equality against each list element. .TP \fB\-glob\fR +. \fIPattern\fR is a glob-style pattern which is matched against each list element using the same rules as the \fBstring match\fR command. .TP \fB\-regexp\fR +. \fIPattern\fR is treated as a regular expression and matched against each list element using the rules described in the \fBre_syntax\fR reference page. .TP \fB\-sorted\fR +. The list elements are in sorted order. If this option is specified, \fBlsearch\fR will use a more efficient searching algorithm to search \fIlist\fR. If no other options are specified, \fIlist\fR is assumed @@ -55,6 +59,7 @@ option is mutually exclusive with \fB\-glob\fR and \fB\-regexp\fR, and is treated exactly like \fB\-exact\fR when either \fB\-all\fR or \fB\-not\fR are specified. .SS "GENERAL MODIFIER OPTIONS" +.PP These options may be given with all matching styles. .TP \fB\-all\fR @@ -65,32 +70,36 @@ indices will be in numeric order. If values are returned, the order of the values will be the order of those values within the input \fIlist\fR. .TP \fB\-inline\fR +. The matching value is returned instead of its index (or an empty string if no value matches.) If \fB\-all\fR is also specified, then the result of the command is the list of all values that matched. .TP \fB\-not\fR +. This negates the sense of the match, returning the index of the first non-matching value in the list. .TP \fB\-start\fR\0\fIindex\fR +. The list is searched starting at position \fIindex\fR. -.VS 8.5 The interpretation of the \fIindex\fR value is the same as for the command \fBstring index\fR, supporting simple index arithmetic and indices relative to the end of the list. -.VE 8.5 .SS "CONTENTS DESCRIPTION OPTIONS" +.PP These options describe how to interpret the items in the list being searched. They are only meaningful when used with the \fB\-exact\fR and \fB\-sorted\fR options. If more than one is specified, the last one takes precedence. The default is \fB\-ascii\fR. .TP \fB\-ascii\fR +. The list elements are to be examined as Unicode strings (the name is for backward-compatibility reasons.) .TP \fB\-dictionary\fR +. The list elements are to be compared using dictionary-style comparisons (see \fBlsort\fR for a fuller description). Note that this only makes a meaningful difference from the \fB\-ascii\fR option when @@ -98,48 +107,54 @@ the \fB\-sorted\fR option is given, because values are only dictionary-equal when exactly equal. .TP \fB\-integer\fR +. The list elements are to be compared as integers. -.VS 8.5 .TP \fB\-nocase\fR +. Causes comparisons to be handled in a case-insensitive manner. Has no effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or \fB\-real\fR options. -.VE 8.5 .TP \fB\-real\fR +. The list elements are to be compared as floating-point values. .SS "SORTED LIST OPTIONS" +.PP These options (only meaningful with the \fB\-sorted\fR option) specify how the list is sorted. If more than one is given, the last one takes precedence. The default option is \fB\-increasing\fR. .TP \fB\-decreasing\fR +. The list elements are sorted in decreasing order. This option is only meaningful when used with \fB\-sorted\fR. .TP \fB\-increasing\fR +. The list elements are sorted in increasing order. This option is only meaningful when used with \fB\-sorted\fR. .SS "NESTED LIST OPTIONS" -.VS 8.5 +.PP These options are used to search lists of lists. They may be used with any other options. .TP \fB\-index\fR\0\fIindexList\fR +. This option is designed for use when searching within nested lists. The \fIindexList\fR argument gives a path of indices (much as might be used with the \fBlindex\fR or \fBlset\fR commands) within each element to allow the location of the term being matched against. .TP \fB\-subindices\fR +. If this option is given, the index result from this command (or every index result when \fB\-all\fR is also specified) will be a complete path (suitable for use with \fBlindex\fR or \fBlset\fR) within the overall list to the term found. This option has no effect unless the \fI\-index\fR is also specified, and is just a convenience short-cut. -.VE 8.5 .SH EXAMPLES +.PP Basic searching: .CS \fBlsearch\fR {a b c d e} c @@ -182,9 +197,7 @@ It is also possible to search inside elements: .SH "SEE ALSO" foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), lset(n), lsort(n), lrange(n), lreplace(n), -.VS 8.5 string(n) -.VE .SH KEYWORDS list, match, pattern, regular expression, search, string '\" Local Variables: @@ -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: lset.n,v 1.15 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: lset.n,v 1.16 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH lset n 8.4 Tcl "Tcl Built-In Commands" @@ -52,11 +52,9 @@ command. If \fIindex\fR is negative or greater than or equal to the number of elements in \fI$varName\fR, then an error occurs. .PP -.VS 8.5 The interpretation of each simple \fIindex\fR value is the same as for the command \fBstring index\fR, supporting simple index arithmetic and indices relative to the end of the list. -.VE 8.5 .PP If additional \fIindex\fR arguments are supplied, then each argument is used in turn to address an element within a sublist designated @@ -77,6 +75,7 @@ argument must be strictly less than the length of the corresponding list. In other words, the \fBlset\fR command cannot change the size of a list. If an index is outside the permitted range, an error is reported. .SH EXAMPLES +.PP In each of these examples, the initial value of \fIx\fR is: .CS set x [list [list a b c] [list d e f] [list g h i]] @@ -121,10 +120,6 @@ The indicated return value also becomes the new value of \fIx\fR. .SH "SEE ALSO" list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lsort(n), lrange(n), lreplace(n), -.VS 8.5 string(n) -.VE - - .SH KEYWORDS element, index, list, replace, set diff --git a/doc/lsort.n b/doc/lsort.n index e2f4c15..ec80885 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.29 2008/03/26 09:59:22 dkf Exp $ +'\" RCS: @(#) $Id: lsort.n,v 1.30 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH lsort n 8.5 Tcl "Tcl Built-In Commands" @@ -18,7 +18,6 @@ lsort \- Sort the elements of a list .SH SYNOPSIS \fBlsort \fR?\fIoptions\fR? \fIlist\fR .BE - .SH DESCRIPTION .PP This command sorts the elements of \fIlist\fR, returning a new @@ -32,10 +31,12 @@ specified before \fIlist\fR to control the sorting process (unique abbreviations are accepted): .TP 20 \fB\-ascii\fR +. Use string comparison with Unicode code-point collation order (the name is for backward-compatibility reasons.) This is the default. .TP 20 \fB\-dictionary\fR +. Use dictionary-style comparison. This is the same as \fB\-ascii\fR except (a) case is ignored except as a tie-breaker and (b) if two strings contain embedded numbers, the numbers compare as integers, @@ -44,12 +45,15 @@ sorts between \fBbigbang\fR and \fBbigboy\fR, and \fBx10y\fR sorts between \fBx9y\fR and \fBx11y\fR. .TP 20 \fB\-integer\fR +. Convert list elements to integers and use integer comparison. .TP 20 \fB\-real\fR +. Convert list elements to floating-point values and use floating comparison. .TP 20 \fB\-command\0\fIcommand\fR +. Use \fIcommand\fR as a comparison command. To compare two elements, evaluate a Tcl script consisting of \fIcommand\fR with the two elements appended as additional @@ -59,29 +63,29 @@ be considered less than, equal to, or greater than the second, respectively. .TP 20 \fB\-increasing\fR +. Sort the list in increasing order .PQ smallest "items first" . This is the default. .TP 20 \fB\-decreasing\fR +. Sort the list in decreasing order .PQ largest "items first" . .TP 20 \fB\-indices\fR -.VS "8.5 (TIP#217)" +. Return a list of indices into \fIlist\fR in sorted order instead of the values themselves. -.VE "8.5 (TIP#217)" .TP 20 \fB\-index\0\fIindexList\fR +. If this option is specified, each of the elements of \fIlist\fR must itself be a proper Tcl sublist. Instead of sorting based on whole sublists, \fBlsort\fR will extract the \fIindexList\fR'th element from each sublist -.VS 8.5 (as if the overall element and the \fIindexList\fR were passed to \fBlindex\fR) and sort based on the given element. -.VE 8.5 For example, .RS .CS @@ -97,7 +101,6 @@ 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, -.VS 8.5 and .CS lsort -index {0 1} { @@ -108,19 +111,18 @@ lsort -index {0 1} { .CE returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR (because \fBe\fR sorts before \fBi\fR which sorts before \fBo\fR.) -.VE 8.5 This option is much more efficient than using \fB\-command\fR to achieve the same effect. .RE -.VS 8.5 .TP 20 \fB\-nocase\fR +. Causes comparisons to be handled in a case-insensitive manner. Has no effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or \fB\-real\fR options. -.VE 8.5 .TP 20 \fB\-unique\fR +. If this option is specified, then only the last set of duplicate elements found in the list will be retained. Note that duplicates are determined relative to the comparison used in the sort. Thus if @@ -200,10 +202,8 @@ More complex sorting using a comparison function: {{3 apple} {0x2 carrot} {1 dingo} {2 banana}} {1 dingo} {2 banana} {0x2 carrot} {3 apple} .CE - .SH "SEE ALSO" list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lset(n), lrange(n), lreplace(n) - .SH KEYWORDS element, list, order, sort diff --git a/doc/mathfunc.n b/doc/mathfunc.n index a84c095..dd89a4c 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.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: mathfunc.n,v 1.21 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: mathfunc.n,v 1.22 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions" @@ -37,10 +37,8 @@ package require \fBTcl 8.5\fR .br \fB::tcl::mathfunc::double\fR \fIarg\fR .br -.VS 8.5 \fB::tcl::mathfunc::entier\fR \fIarg\fR .br -.VE 8.5 \fB::tcl::mathfunc::exp\fR \fIarg\fR .br \fB::tcl::mathfunc::floor\fR \fIarg\fR @@ -117,28 +115,34 @@ for new implementations. .SS "DETAILED DEFINITIONS" .TP \fBabs \fIarg\fR +. Returns the absolute value of \fIarg\fR. \fIArg\fR may be either integer or floating-point, and the result is returned in the same form. .TP \fBacos \fIarg\fR +. Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR] radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. .TP \fBasin \fIarg\fR +. Returns the arc sine of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. .TP \fBatan \fIarg\fR +. Returns the arc tangent of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] radians. .TP \fBatan2 \fIy x\fR +. Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI\-pi\fR,\fIpi\fR] radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater than \fI0\fR, this is equivalent to .QW "\fBatan \fR[\fBexpr\fR {\fIy\fB/\fIx\fR}]" . .TP \fBbool \fIarg\fR +. Accepts any numeric value, or any string acceptable to \fBstring is boolean\fR, and returns the corresponding boolean value \fB0\fR or \fB1\fR. Non-zero numbers are true. @@ -146,18 +150,22 @@ Other numbers are false. Non-numeric strings produce boolean value in agreement with \fBstring is true\fR and \fBstring is false\fR. .TP \fBceil \fIarg\fR +. Returns the smallest integral floating-point value (i.e. with a zero fractional part) not less than \fIarg\fR. The argument may be any numeric value. .TP \fBcos \fIarg\fR +. Returns the cosine of \fIarg\fR, measured in radians. .TP \fBcosh \fIarg\fR +. Returns the hyperbolic cosine of \fIarg\fR. If the result would cause an overflow, an error is returned. .TP \fBdouble \fIarg\fR +. The argument may be any numeric value, If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts \fIarg\fR to floating-point and returns the converted value. May return @@ -165,31 +173,35 @@ If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts the floating-point range. .TP \fBentier \fIarg\fR -.VS 8.5 +. The argument may be any numeric value. The integer part of \fIarg\fR is determined and returned. The integer range returned by this function is unlimited, unlike \fBint\fR and \fBwide\fR which truncate their range to fit in particular storage widths. -.VE 8.5 .TP \fBexp \fIarg\fR +. Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR. If the result would cause an overflow, an error is returned. .TP \fBfloor \fIarg\fR +. Returns the largest integral floating-point value (i.e. with a zero fractional part) not greater than \fIarg\fR. The argument may be any numeric value. .TP \fBfmod \fIx y\fR +. Returns the floating-point remainder of the division of \fIx\fR by \fIy\fR. If \fIy\fR is 0, an error is returned. .TP \fBhypot \fIx y\fR +. Computes the length of the hypotenuse of a right-angled triangle .QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]". .TP \fBint \fIarg\fR +. The argument may be any numeric value. The integer part of \fIarg\fR is determined, and then the low order bits of that integer value up to the machine word size are returned as an integer value. For reference, @@ -197,32 +209,39 @@ the number of bytes in the machine word are stored in \fBtcl_platform(wordSize)\fR. .TP \fBisqrt \fIarg\fR +. Computes the integer part of the square root of \fIarg\fR. \fIArg\fR must be a positive value, either an integer or a floating point number. Unlike \fBsqrt\fR, which is limited to the precision of a floating point number, \fIisqrt\fR will return a result of arbitrary precision. .TP \fBlog \fIarg\fR +. Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a positive value. .TP \fBlog10 \fIarg\fR +. Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a positive value. .TP \fBmax \fIarg\fB \fI...\fR +. Accepts one or more numeric arguments. Returns the one argument with the greatest value. .TP \fBmin \fIarg\fB \fI...\fR +. Accepts one or more numeric arguments. Returns the one argument with the least value. .TP \fBpow \fIx y\fR +. Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR is negative, \fIy\fR must be an integer value. .TP \fBrand\fR +. Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR). The generator algorithm is a simple linear congruential generator that is not cryptographically secure. Each result from \fBrand\fR completely @@ -232,34 +251,42 @@ one-time passwords. The seed of the generator is initialized from the internal clock of the machine or may be set with the \fBsrand\fR function. .TP \fBround \fIarg\fR +. If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts \fIarg\fR to integer by rounding and returns the converted value. .TP \fBsin \fIarg\fR +. Returns the sine of \fIarg\fR, measured in radians. .TP \fBsinh \fIarg\fR +. Returns the hyperbolic sine of \fIarg\fR. If the result would cause an overflow, an error is returned. .TP \fBsqrt \fIarg\fR +. The argument may be any non-negative numeric value. Returns a floating-point value that is the square root of \fIarg\fR. May return \fBInf\fR when the argument is a numeric value that exceeds the square of the maximum value of the floating-point range. .TP \fBsrand \fIarg\fR +. The \fIarg\fR, which must be an integer, is used to reset the seed for the random number generator of \fBrand\fR. Returns the first random number (see \fBrand\fR) from that seed. Each interpreter has its own seed. .TP \fBtan \fIarg\fR +. Returns the tangent of \fIarg\fR, measured in radians. .TP \fBtanh \fIarg\fR +. Returns the hyperbolic tangent of \fIarg\fR. .TP \fBwide \fIarg\fR +. The argument may be any numeric value. The integer part of \fIarg\fR is determined, and then the low order 64 bits of that integer value are returned as an integer value. diff --git a/doc/msgcat.n b/doc/msgcat.n index ce8ef6e..4ed83eb 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -51,6 +51,7 @@ wishes to be enabled for multi-lingual applications. .SH COMMANDS .TP \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? +. Returns a translation of \fIsrc-string\fR according to the user's current locale. If additional arguments past \fIsrc-string\fR are given, the \fBformat\fR command is used to substitute the @@ -73,12 +74,14 @@ later simply by defining new message catalog entries. .RE .TP \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? +. Given several source strings, \fB::msgcat::mcmax\fR returns the length of the longest translated string. This is useful when designing localized GUIs, which may require that all buttons, for example, be a fixed width (which will be the width of the widest button). .TP -\fB::msgcat::mclocale \fR?\fInewLocale\fR? +\fB::msgcat::mclocale \fR?\fInewLocale\fR? +. This function sets the locale to \fInewLocale\fR. If \fInewLocale\fR is omitted, the current locale is returned, otherwise the current locale is set to \fInewLocale\fR. msgcat stores and compares the locale in a @@ -88,6 +91,7 @@ the user's environment. See \fBLOCALE SPECIFICATION\fR below for a description of the locale string format. .TP \fB::msgcat::mcpreferences\fR +. Returns an ordered list of the locales preferred by the user, based on the user's language specification. The list is ordered from most specific to least @@ -95,11 +99,10 @@ preference. The list is derived from the current locale set in msgcat by \fB::msgcat::mclocale\fR, and cannot be set independently. For example, if the current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR -.VS 1.4 returns \fB{en_US_funky en_US en {}}\fR. -.VE 1.4 .TP \fB::msgcat::mcload \fIdirname\fR +. Searches the specified directory for files that match the language specifications returned by \fB::msgcat::mcpreferences\fR (note that these are all lowercase), extended by the file extension @@ -113,12 +116,14 @@ evaluation. The number of message files which matched the specification and were loaded is returned. .TP \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? +. Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the specified \fIlocale\fR and the current namespace. If \fItranslate-string\fR is not specified, \fIsrc-string\fR is used for both. The function returns \fItranslate-string\fR. .TP \fB::msgcat::mcmset \fIlocale src-trans-list\fR +. Sets the translation for multiple source strings in \fIsrc-trans-list\fR in the specified \fIlocale\fR and the current namespace. @@ -129,6 +134,7 @@ faster than multiple invocations of \fB::msgcat::mcset\fR. The function returns the number of translations set. .TP \fB::msgcat::mcunknown \fIlocale src-string\fR +. This routine is called by \fB::msgcat::mc\fR in the case when a translation for \fIsrc-string\fR is not defined in the current locale. The default action is to return @@ -178,7 +184,6 @@ When a locale is specified by the user, a .QW "best match" search is performed during string translation. For example, if a user specifies -.VS 1.4 en_GB_Funky, the locales .QW en_GB_Funky , .QW en_GB , @@ -186,7 +191,6 @@ en_GB_Funky, the locales and .MT (the empty string) -.VE 1.4 are searched in order until a matching translation string is found. If no translation string is available, then \fB::msgcat::mcunknown\fR is called. @@ -260,7 +264,6 @@ For example: es.msg \(em spanish en_gb.msg \(em United Kingdom English .CE -.VS 1.4 \fIException:\fR The message file for the root locale .MT is called @@ -269,7 +272,6 @@ This exception is made so as not to cause peculiar behavior, such as marking the message file as .QW hidden on Unix file systems. -.VE 1.4 .IP [3] The file contains a series of calls to \fBmcset\fR and \fBmcmset\fR, setting the necessary translation strings diff --git a/doc/namespace.n b/doc/namespace.n index e4d3d6d..4a31500 100644 --- a/doc/namespace.n +++ b/doc/namespace.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: namespace.n,v 1.30 2008/03/06 22:08:26 dkf Exp $ +'\" RCS: @(#) $Id: namespace.n,v 1.31 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH namespace n 8.5 Tcl "Tcl Built-In Commands" @@ -28,6 +28,7 @@ The legal values of \fIsubcommand\fR are listed below. Note that you can abbreviate the \fIsubcommand\fRs. .TP \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR? +. Returns a list of all child namespaces that belong to the namespace \fInamespace\fR. If \fInamespace\fR is not specified, @@ -43,6 +44,7 @@ otherwise the namespace \fInamespace\fR is prepended onto the pattern. .TP \fBnamespace code \fIscript\fR +. Captures the current namespace context for later execution of the script \fIscript\fR. It returns a new script in which \fIscript\fR has been wrapped @@ -70,6 +72,7 @@ See the section \fBSCOPED SCRIPTS\fR for some examples of how this is used to create callback scripts. .TP \fBnamespace current\fR +. Returns the fully-qualified name for the current namespace. The actual name of the global namespace is .MT @@ -78,6 +81,7 @@ but this command returns \fB::\fR for the global namespace as a convenience to programmers. .TP \fBnamespace delete \fR?\fInamespace namespace ...\fR? +. Each namespace \fInamespace\fR is deleted and all variables, procedures, and child namespaces contained in the namespace are deleted. @@ -89,13 +93,13 @@ If a namespace does not exist, this command returns an error. If no namespace names are given, this command does nothing. .TP \fBnamespace ensemble\fR \fIsubcommand\fR ?\fIarg ...\fR? -.VS 8.5 +. Creates and manipulates a command that is formed out of an ensemble of subcommands. See the section \fBENSEMBLES\fR below for further details. -.VE 8.5 .TP \fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR? +. Activates a namespace called \fInamespace\fR and evaluates some code in that context. If the namespace does not already exist, it is created. @@ -111,10 +115,12 @@ they are automatically created. .RE .TP \fBnamespace exists\fR \fInamespace\fR +. Returns \fB1\fR if \fInamespace\fR is a valid namespace in the current context, returns \fB0\fR otherwise. .TP \fBnamespace export \fR?\-\fBclear\fR? ?\fIpattern pattern ...\fR? +. Specifies which commands are exported from a namespace. The exported commands are those that can be later imported into another namespace using a \fBnamespace import\fR command. @@ -135,6 +141,7 @@ If no \fIpattern\fRs are given and the \fB\-clear\fR flag is not given, this command returns the namespace's current export list. .TP \fBnamespace forget \fR?\fIpattern pattern ...\fR? +. Removes previously imported commands from a namespace. Each \fIpattern\fR is a simple or qualified name such as \fBx\fR, \fBfoo::x\fR or \fBa::b::p*\fR. @@ -159,7 +166,7 @@ If so, this command deletes the corresponding imported commands. In effect, this un-does the action of a \fBnamespace import\fR command. .TP \fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR? -.VS 8.5 +. Imports commands into a namespace, or queries the set of imported commands in a namespace. When no arguments are present, \fBnamespace import\fR returns the list of commands in @@ -168,7 +175,6 @@ namespaces. The commands in the returned list are in the format of simple names, with no namespace qualifiers at all. This format is suitable for composition with \fBnamespace forget\fR (see \fBEXAMPLES\fR below). -.VE 8.5 When \fIpattern\fR arguments are present, each \fIpattern\fR is a qualified name like \fBfoo::x\fR or \fBa::p*\fR. @@ -195,6 +201,7 @@ If another command is defined and exported in this namespace later on, it will not be imported. .TP \fBnamespace inscope\fR \fInamespace\fR \fIscript\fR ?\fIarg ...\fR? +. Executes a script in the context of the specified \fInamespace\fR. This command is not expected to be used directly by programmers; calls to it are generated implicitly when applications @@ -218,6 +225,7 @@ as is the case with \fBnamespace eval\fR. .RE .TP \fBnamespace origin \fIcommand\fR +. Returns the fully-qualified name of the original command to which the imported command \fIcommand\fR refers. When a command is imported into a namespace, @@ -232,23 +240,23 @@ If \fIcommand\fR does not refer to an imported command, the command's own fully-qualified name is returned. .TP \fBnamespace parent\fR ?\fInamespace\fR? +. Returns the fully-qualified name of the parent namespace for namespace \fInamespace\fR. If \fInamespace\fR is not specified, the fully-qualified name of the current namespace's parent is returned. .TP \fBnamespace path\fR ?\fInamespaceList\fR? -.\" Should really have the .TP inside the .VS, but that triggers a groff bug -.VS 8.5 +. Returns the command resolution path of the current namespace. If \fInamespaceList\fR is specified as a list of named namespaces, the current namespace's command resolution path is set to those namespaces and returns the empty list. The default command resolution path is always empty. See the section \fBNAME RESOLUTION\fR below for an explanation of the rules regarding name resolution. -.VE 8.5 .TP \fBnamespace qualifiers\fR \fIstring\fR +. Returns any leading namespace qualifiers for \fIstring\fR. Qualifiers are namespace names separated by double colons (\fB::\fR). For the \fIstring\fR \fB::foo::bar::x\fR, @@ -260,6 +268,7 @@ namespace names are, in fact, the names of currently defined namespaces. .TP \fBnamespace tail\fR \fIstring\fR +. Returns the simple name at the end of a qualified string. Qualifiers are namespace names separated by double colons (\fB::\fR). For the \fIstring\fR \fB::foo::bar::x\fR, @@ -270,6 +279,7 @@ It does not check whether the namespace names are, in fact, the names of currently defined namespaces. .TP \fBnamespace upvar\fR \fInamespace\fR \fIotherVar myVar \fR?\fIotherVar myVar \fR... +. This command arranges for one or more local variables in the current procedure to refer to variables in \fInamespace\fR. The namespace name is resolved as described in section \fBNAME RESOLUTION\fR. @@ -280,6 +290,7 @@ used for qualified namespace or variable names. \fBnamespace upvar\fR returns an empty string. .TP \fBnamespace unknown\fR ?\fIscript\fR? +. Sets or returns the unknown command handler for the current namespace. The handler is invoked when a command called from within the namespace cannot be found (in either the current namespace or the global namespace). @@ -291,6 +302,7 @@ default handler for all namespaces is \fB::unknown\fR. If no argument is given, it returns the handler for the current namespace. .TP \fBnamespace which\fR ?\-\fBcommand\fR? ?\-\fBvariable\fR? \fIname\fR +. Looks up \fIname\fR as either a command or variable and returns its fully-qualified name. For example, if \fIname\fR does not exist in the current namespace @@ -445,14 +457,12 @@ Tcl follows basic rules for looking it up: Variable names are always resolved by looking first in the current namespace, and then in the global namespace. -.VS 8.5 Command names are also always resolved by looking in the current namespace first. If not found there, they are searched for in every namespace on the current namespace's command path (which is empty by default). If not found there, command names are looked up in the global namespace (or, failing that, are processed by the \fBunknown\fR command.) -.VE 8.5 Namespace names, on the other hand, are always resolved by looking in only the current namespace. .PP @@ -656,7 +666,6 @@ the value of a::b has changed to c .CE .SH ENSEMBLES .PP -.VS 8.5 The \fBnamespace ensemble\fR is used to create and manipulate ensemble commands, which are commands formed by grouping subcommands together. The commands typically come from the current namespace when the @@ -670,6 +679,7 @@ namespace is maintained however the ensemble is renamed. Three subcommands of the \fBnamespace ensemble\fR command are defined: .TP \fBnamespace ensemble create\fR ?\fIoption value ...\fR? +. Creates a new ensemble command linked to the current namespace, returning the fully qualified name of the command created. The arguments to \fBnamespace ensemble create\fR allow the configuration @@ -680,12 +690,14 @@ namespace. See the section \fBENSEMBLE OPTIONS\fR below for a full list of options supported and their effects. .TP \fBnamespace ensemble configure \fIcommand\fR ?\fIoption\fR? ?\fIvalue ...\fR? +. Retrieves the value of an option associated with the ensemble command named \fIcommand\fR, or updates some options associated with that ensemble command. See the section \fBENSEMBLE OPTIONS\fR below for a full list of options supported and their effects. .TP \fBnamespace ensemble exists\fR \fIcommand\fR +. Returns a boolean value that describes whether the command \fIcommand\fR exists and is an ensemble command. This command only ever returns an error if the number of arguments to the command is @@ -708,6 +720,7 @@ create\fR and \fBnamespace ensemble configure\fR commands, control how an ensemble command behaves: .TP \fB\-map\fR +. When non-empty, this option supplies a dictionary that provides a mapping from subcommand names to a list of prefix words to substitute in place of the ensemble command and subcommand words (in a manner @@ -719,12 +732,14 @@ name. Note that when this option is non-empty and the will be exactly those words that have mappings in the dictionary. .TP \fB\-prefixes\fR +. This option (which is enabled by default) controls whether the ensemble command recognizes unambiguous prefixes of its subcommands. When turned off, the ensemble command requires exact matching of subcommand names. .TP \fB\-subcommands\fR +. When non-empty, this option lists exactly what subcommands are in the ensemble. The mapping for each of those commands will be either whatever is defined in the \fB\-map\fR option, or to the command with the same @@ -735,6 +750,7 @@ of the linked namespace at the time of the invocation of the ensemble command. .TP \fB\-unknown\fR +. When non-empty, this option provides a partial command (to which all the words that are arguments to the ensemble command, including the fully-qualified name of the ensemble, are appended) to handle the case @@ -748,6 +764,7 @@ The following extra option is allowed by \fBnamespace ensemble create\fR: .TP \fB\-command\fR +. This write-only option allows the name of the ensemble created by \fBnamespace ensemble create\fR to be anything in any existing namespace. The default value for this option is the fully-qualified @@ -758,6 +775,7 @@ The following extra option is allowed by \fBnamespace ensemble configure\fR: .TP \fB\-namespace\fR +. This read-only option allows the retrieval of the fully-qualified name of the namespace which the ensemble was created within. .SS "UNKNOWN HANDLER BEHAVIOUR" @@ -809,7 +827,6 @@ error message from \fBTcl_GetIndexFromObj\fR). This is the error that will be thrown when the subcommand is still not recognized during reparsing. It is also an error for an \fB\-unknown\fR handler to delete its namespace. -.VE 8.5 .SH EXAMPLES Create a namespace containing a variable and an exported command: .CS @@ -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: open.n,v 1.34 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: open.n,v 1.35 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH open n 8.3 Tcl "Tcl Built-In Commands" @@ -36,73 +36,84 @@ The \fIaccess\fR argument, if present, indicates the way in which the file In the first form \fIaccess\fR may have any of the following values: .TP 15 \fBr\fR +. Open the file for reading only; the file must already exist. This is the default value if \fIaccess\fR is not specified. .TP 15 \fBr+\fR +. Open the file for both reading and writing; the file must already exist. .TP 15 \fBw\fR +. Open the file for writing only. Truncate it if it exists. If it does not exist, create a new file. .TP 15 \fBw+\fR +. Open the file for reading and writing. Truncate it if it exists. If it does not exist, create a new file. .TP 15 \fBa\fR +. Open the file for writing only. If the file does not exist, create a new empty file. Set the file pointer to the end of the file prior to each write. .TP 15 \fBa+\fR +. Open the file for reading and writing. If the file does not exist, create a new empty file. Set the initial access position to the end of the file. -.VS 8.5 .PP All of the legal \fIaccess\fR values above may have the character \fBb\fR added as the second or third character in the value to indicate that the opened channel should be configured with the \fB\-translation binary\fR option, making the channel suitable for reading or writing of binary data. -.VE 8.5 .PP In the second form, \fIaccess\fR consists of a list of any of the following flags, all of which have the standard POSIX meanings. One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR. .TP 15 \fBRDONLY\fR +. Open the file for reading only. .TP 15 \fBWRONLY\fR +. Open the file for writing only. .TP 15 \fBRDWR\fR +. Open the file for both reading and writing. .TP 15 \fBAPPEND\fR +. Set the file pointer to the end of the file prior to each write. -.VS 8.5 .TP 15 \fBBINARY\fR +. Configure the opened channel with the \fB\-translation binary\fR option. -.VE 8.5 .TP 15 \fBCREAT\fR +. Create the file if it does not already exist (without this flag it is an error for the file not to exist). .TP 15 \fBEXCL\fR +. If \fBCREAT\fR is also specified, an error is returned if the file already exists. .TP 15 \fBNOCTTY\fR +. If the file is a terminal device, this flag prevents the file from becoming the controlling terminal of the process. .TP 15 \fBNONBLOCK\fR +. Prevents the process from blocking while opening the file, and possibly in subsequent I/O operations. The exact behavior of this flag is system- and device-dependent; its use is discouraged @@ -112,6 +123,7 @@ For details refer to your system documentation on the \fBopen\fR system call's \fBO_NONBLOCK\fR flag. .TP 15 \fBTRUNC\fR +. If the file exists it is truncated to zero length. .PP If a new file is created as part of opening it, \fIpermissions\fR @@ -158,6 +170,7 @@ The \fBfconfigure\fR command can be used to query and set additional configuration options specific to serial ports (where supported): .TP \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR +. This option is a set of 4 comma-separated values: the baud rate, parity, number of data bits, and number of stop bits for this serial port. The \fIbaud\fR rate is a simple integer that specifies the connection speed. @@ -174,6 +187,7 @@ data bits and should be an integer from 5 to 8, while \fIstop\fR is the number of stop bits and should be the integer 1 or 2. .TP \fB\-handshake\fR \fItype\fR +. (Windows and Unix). This option is used to setup automatic handshake control. Note that not all handshake types maybe supported by your operating system. The \fItype\fR parameter is case-independent. @@ -191,11 +205,13 @@ The \fB\-handshake\fR option cannot be queried. .RE .TP \fB\-queue\fR +. (Windows and Unix). The \fB\-queue\fR option can only be queried. It returns a list of two integers representing the current number of bytes in the input and output queue respectively. .TP \fB\-timeout\fR \fImsec\fR +. (Windows and Unix). This option is used to set the timeout for blocking read operations. It specifies the maximum interval between the reception of two bytes in milliseconds. @@ -205,6 +221,7 @@ nonblocking reads. This option cannot be queried. .TP \fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR +. (Windows and Unix). This option is used to setup the handshake output lines (see below) permanently or to send a BREAK over the serial line. The \fIsignal\fR names are case-independent. @@ -217,6 +234,7 @@ The result is unpredictable. The \fB\-ttycontrol\fR option cannot be queried. .TP \fB\-ttystatus\fR +. (Windows and Unix). The \fB\-ttystatus\fR option can only be queried. It returns the current modem status and handshake input signals (see below). @@ -225,12 +243,14 @@ e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR. The \fIsignal\fR names are returned upper case. .TP \fB\-xchar\fR \fI{xonChar xoffChar}\fR +. (Windows and Unix). This option is used to query or change the software handshake characters. Normally the operating system default should be DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters. .TP \fB\-pollinterval\fR \fImsec\fR +. (Windows only). This option is used to set the maximum time between polling for fileevents. This affects the time interval between checking for events throughout the Tcl @@ -241,6 +261,7 @@ you want to poll the serial port more or less often than 10 msec \fB\-sysbuffer\fR \fIinSize\fR .TP \fB\-sysbuffer\fR \fI{inSize outSize}\fR +. (Windows only). This option is used to change the size of Windows system buffers for a serial channel. Especially at higher communication rates the default input buffer size of 4096 bytes can overrun @@ -248,6 +269,7 @@ for latent systems. The first form specifies the input buffer size, in the second form both input and output buffers are defined. .TP \fB\-lasterror\fR +. (Windows only). This option is query only. In case of a serial communication error, \fBread\fR or \fBputs\fR returns a general Tcl file I/O error. @@ -305,35 +327,42 @@ general file I/O error. Then \fBfconfigure -lasterror\fR may help to locate the problem. The following error codes may be returned. .TP 10 \fBRXOVER\fR +. Windows input buffer overrun. The data comes faster than your scripts reads it or your system is overloaded. Use \fBfconfigure -sysbuffer\fR to avoid a temporary bottleneck and/or make your script faster. .TP 10 \fBTXFULL\fR +. Windows output buffer overrun. Complement to RXOVER. This error should practically not happen, because Tcl cares about the output buffer status. .TP 10 \fBOVERRUN\fR +. UART buffer overrun (hardware) with data lost. The data comes faster than the system driver receives it. Check your advanced serial port settings to enable the FIFO (16550) buffer and/or setup a lower(1) interrupt threshold value. .TP 10 \fBRXPARITY\fR +. A parity error has been detected by your UART. Wrong parity settings with \fBfconfigure -mode\fR or a noisy data line (RXD) may cause this error. .TP 10 \fBFRAME\fR +. A stop-bit error has been detected by your UART. Wrong mode settings with \fBfconfigure -mode\fR or a noisy data line (RXD) may cause this error. .TP 10 \fBBREAK\fR +. A BREAK condition has been detected by your UART (see above). .SH "PORTABILITY ISSUES" .TP \fBWindows \fR(all versions) +. Valid values for \fIfileName\fR to open a serial port are of the form \fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4. This notation only works for serial ports from 1 to 9, if the system @@ -344,6 +373,7 @@ where X is any number that corresponds to a serial port; please note that this method is considerably slower on Windows 95 and Windows 98. .TP \fBWindows NT\fR +. When running Tcl interactively, there may be some strange interactions between the real console, if one is present, and a command pipeline that uses standard input or output. If a command pipeline is opened for reading, some @@ -359,6 +389,7 @@ standard input or output, but is redirected from or to a file, then the above problems do not occur. .TP \fBWindows 95\fR +. A command pipeline that executes a 16-bit DOS application cannot be opened for both reading and writing, since 16-bit DOS applications that receive standard input from a pipe and send standard output to a pipe run @@ -390,6 +421,7 @@ applications are run synchronously, as described above. .RE .TP \fBUnix\fR\0\0\0\0\0\0\0 +. Valid values for \fIfileName\fR to open a serial port are generally of the form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name of any pseudo-file that maps to a serial port may be used. @@ -412,6 +444,7 @@ See the \fBPORTABILITY ISSUES\fR section of the \fBexec\fR command for additional information not specific to command pipelines about executing applications on the various platforms .SH "EXAMPLE" +.PP Open a command pipeline and catch any errors: .CS set fl [\fBopen\fR "| ls this_file_does_not_exist"] diff --git a/doc/regexp.n b/doc/regexp.n index ad3a46f..1e31131 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.28 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: regexp.n,v 1.29 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH regexp n 8.3 Tcl "Tcl Built-In Commands" @@ -12,11 +12,9 @@ '\" Note: do not modify the .SH NAME line immediately below! .SH NAME regexp \- Match a regular expression against a string - .SH SYNOPSIS \fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR? .BE - .SH DESCRIPTION .PP Determines whether the regular expression \fIexp\fR matches part or @@ -24,7 +22,7 @@ all of \fIstring\fR and returns 1 if it does, 0 if it does not, unless \fB\-inline\fR is specified (see below). (Regular expression matching is described in the \fBre_syntax\fR reference page.) -.LP +.PP If additional arguments are specified after \fIstring\fR then they are treated as the names of variables in which to return information about which part(s) of \fIstring\fR matched \fIexp\fR. @@ -40,6 +38,7 @@ they are treated as switches. The following switches are currently supported: .TP 15 \fB\-about\fR +. Instead of attempting to match the regular expression, returns a list containing information about the regular expression. The first element of the list is a subexpression count. The second element is a @@ -47,11 +46,13 @@ list of property names that describe various attributes of the regular expression. This switch is primarily intended for debugging purposes. .TP 15 \fB\-expanded\fR +. Enables use of the expanded regular expression syntax where whitespace and comments are ignored. This is the same as specifying the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 15 \fB\-indices\fR +. Changes what is stored in the \fIsubMatchVar\fRs. Instead of storing the matching characters from \fIstring\fR, each variable @@ -60,6 +61,7 @@ in \fIstring\fR of the first and last characters in the matching range of characters. .TP 15 \fB\-line\fR +. Enables newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning. With this flag, @@ -77,6 +79,7 @@ specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 15 \fB\-linestop\fR +. Changes the behavior of .QW [^ bracket expressions and @@ -86,6 +89,7 @@ stop at newlines. This is the same as specifying the \fB(?p)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 15 \fB\-lineanchor\fR +. Changes the behavior of .QW ^ and @@ -98,16 +102,19 @@ specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 15 \fB\-nocase\fR +. Causes upper-case characters in \fIstring\fR to be treated as lower case during the matching process. .TP 15 \fB\-all\fR +. Causes the regular expression to be matched as many times as possible in the string, returning the total number of matches found. If this is specified with match variables, they will contain information for the last match only. .TP 15 \fB\-inline\fR +. Causes the command to return, as a list, the data that would otherwise be placed in match variables. When using \fB\-inline\fR, match variables may not be specified. If used with \fB\-all\fR, the @@ -123,12 +130,11 @@ regular expression. Examples are: .CE .TP 15 \fB\-start\fR \fIindex\fR +. Specifies a character index offset into the string to start matching the regular expression at. -.VS 8.5 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, .QW ^ will not match the beginning of the line, and \eA will still @@ -138,6 +144,7 @@ absolute beginning of the input string. \fIindex\fR will be constrained to the bounds of the input string. .TP 15 \fB\-\|\-\fR +. Marks the end of switches. The argument following this one will be treated as \fIexp\fR even if it starts with a \fB\-\fR. .PP @@ -149,6 +156,7 @@ portion of the expression that was not matched), then the corresponding .QW "\fB\-1 \-1\fR" if \fB\-indices\fR has been specified or to an empty string otherwise. .SH EXAMPLES +.PP 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: @@ -175,13 +183,8 @@ characters) in a string: .CS \fBregexp\fR \-all \-inline {\eS+} $string .CE - .SH "SEE ALSO" re_syntax(n), regsub(n), -.VS 8.5 string(n) -.VE - - .SH KEYWORDS match, regular expression, string diff --git a/doc/regsub.n b/doc/regsub.n index ca16aa8..cc5994f 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.22 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: regsub.n,v 1.23 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH regsub n 8.3 Tcl "Tcl Built-In Commands" @@ -58,6 +58,7 @@ they are treated as switches. The following switches are currently supported: .TP 10 \fB\-all\fR +. All ranges in \fIstring\fR that match \fIexp\fR are found and substitution is performed for each of these ranges. Without this switch only the first @@ -70,11 +71,13 @@ sequences are handled for each substitution using the information from the corresponding match. .TP 15 \fB\-expanded\fR +. Enables use of the expanded regular expression syntax where whitespace and comments are ignored. This is the same as specifying the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 15 \fB\-line\fR +. Enables newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning. With this flag, .QW [^ @@ -91,6 +94,7 @@ specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 15 \fB\-linestop\fR +. Changes the behavior of .QW [^ bracket expressions and @@ -100,6 +104,7 @@ stop at newlines. This is the same as specifying the \fB(?p)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 15 \fB\-lineanchor\fR +. Changes the behavior of .QW ^ and @@ -112,17 +117,17 @@ specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR manual page). .TP 10 \fB\-nocase\fR +. Upper-case characters in \fIstring\fR will be converted to lower-case before matching against \fIexp\fR; however, substitutions specified by \fIsubSpec\fR use the original unconverted form of \fIstring\fR. .TP 10 \fB\-start\fR \fIindex\fR +. Specifies a character index offset into the string to start matching the regular expression at. -.VS 8.5 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, .QW ^ will not match the beginning of the line, and \eA will still @@ -130,6 +135,7 @@ match the start of the string at \fIindex\fR. \fIindex\fR will be constrained to the bounds of the input string. .TP 10 \fB\-\|\-\fR +. Marks the end of switches. The argument following this one will be treated as \fIexp\fR even if it starts with a \fB\-\fR. .PP @@ -139,6 +145,7 @@ string after replacement is returned. See the manual entry for \fBregexp\fR for details on the interpretation of regular expressions. .SH EXAMPLES +.PP Replace (in the string in variable \fIstring\fR) every instance of \fBfoo\fR which is a word by itself with \fBbar\fR: .CS @@ -166,8 +173,6 @@ set quoted [subst [\fBregsub\fR -all $RE $string $substitution]] .CE .SH "SEE ALSO" regexp(n), re_syntax(n), subst(n), -.VS 8.5 string(n) -.VE .SH KEYWORDS match, pattern, regular expression, substitute diff --git a/doc/return.n b/doc/return.n index 9df81a4..7432491 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.19 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: return.n,v 1.20 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH return n 8.5 Tcl "Tcl Built-In Commands" @@ -48,31 +48,37 @@ exceptional return from the procedure. \fICode\fR may have any of the following values: .TP 13 \fBok (or 0)\fR +. Normal return: same as if the option is omitted. The return code of the procedure is 0 (\fBTCL_OK\fR). .TP 13 \fBerror (1)\fR +. Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR). The procedure command behaves in its calling context as if it were the command \fBerror \fIresult\fR. See below for additional options. .TP 13 \fBreturn (2)\fR +. The return code of the procedure is 2 (\fBTCL_RETURN\fR). The procedure command behaves in its calling context as if it were the command \fBreturn\fR (with no arguments). .TP 13 \fBbreak (3)\fR +. The return code of the procedure is 3 (\fBTCL_BREAK\fR). The procedure command behaves in its calling context as if it were the command \fBbreak\fR. .TP 13 \fBcontinue (4)\fR +. The return code of the procedure is 4 (\fBTCL_CONTINUE\fR). The procedure command behaves in its calling context as if it were the command \fBcontinue\fR. .TP 13 \fIvalue\fR +. \fIValue\fR must be an integer; it will be returned as the return code for the current procedure. .LP @@ -89,7 +95,6 @@ an invocation of the \fBreturn \-code \fIcode\fR command will cause the return code of \fBsource\fR to be \fIcode\fR. .SH "RETURN OPTIONS" .PP -.VS 8.5 In addition to a result and a return code, evaluation of a command in Tcl also produces a dictionary of return options. In general usage, all \fIoption value\fR pairs given as arguments to \fBreturn\fR @@ -98,13 +103,13 @@ are acceptable except as noted below. The \fBcatch\fR command may be used to capture all of this information \(em the return code, the result, and the return options dictionary \(em that arise from evaluation of a script. -.VE 8.5 .PP As documented above, the \fB\-code\fR entry in the return options dictionary receives special treatment by Tcl. There are other return options also recognized and treated specially by Tcl. They are: .TP \fB\-errorcode \fIlist\fR +. The \fB\-errorcode\fR option receives special treatment only when the value of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then the \fIlist\fR value is meant to be additional information about the error, @@ -116,6 +121,7 @@ to the default value of \fBNONE\fR. The \fB\-errorcode\fR return option will also be stored in the global variable \fBerrorCode\fR. .TP \fB\-errorinfo \fIinfo\fR +. The \fB\-errorinfo\fR option receives special treatment only when the value of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then \fIinfo\fR is the initial stack trace, meant to provide to a human reader additional information @@ -133,7 +139,7 @@ by the \fBcatch\fR command (or from the copy of that information stored in the global variable \fBerrorInfo\fR). .TP \fB\-level \fIlevel\fR -.VS 8.5 +. The \fB\-level\fR and \fB\-code\fR options work together to set the return code to be returned by one of the commands currently being evaluated. The \fIlevel\fR value must be a non-negative integer representing a number @@ -143,14 +149,12 @@ be \fIcode\fR. If no \fB\-level\fR option is provided, the default value of \fIlevel\fR is 1, so that \fBreturn\fR sets the return code that the current procedure returns to its caller, 1 level up the call stack. The mechanism by which these options work is described in more detail below. -.VE 8.5 .TP \fB\-options \fIoptions\fR -.VS 8.5 +. The value \fIoptions\fR must be a valid dictionary. The entries of that dictionary are treated as additional \fIoption value\fR pairs for the \fBreturn\fR command. -.VE 8.5 .SH "RETURN CODE HANDLING MECHANISMS" .PP Return codes are used in Tcl to control program flow. A Tcl script @@ -176,7 +180,6 @@ of \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR, the loop command can react in such a way as to give the \fBbreak\fR and \fBcontinue\fR commands their documented interpretation in loops. .PP -.VS 8.5 Procedure invocation also involves evaluation of a script, the body of the procedure. Procedure invocation provides special treatment when evaluation of the procedure body returns the return code @@ -204,8 +207,8 @@ of the \fB\-code\fR option (or \fBTCL_OK\fR by default). Any other value for the \fB\-level\fR option (including the default value of 1) will cause the return code of the \fBreturn\fR command itself to be \fBTCL_RETURN\fR, triggering a return from the enclosing procedure. -.VE 8.5 .SH EXAMPLES +.PP First, a simple example of using \fBreturn\fR to return from a procedure, interrupting the procedure body. .CS @@ -256,7 +259,6 @@ proc myBreak {} { } .CE .PP -.VS 8.5 With the \fB\-level 0\fR option, \fBreturn\fR itself can serve as a replacement for \fBbreak\fR. .CS @@ -291,7 +293,6 @@ proc myReturn {args} { \fBreturn\fR -options $options $result } .CE -.VE 8.5 .SH "SEE ALSO" break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n) .SH KEYWORDS @@ -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.24 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: scan.n,v 1.25 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH scan n 8.4 Tcl "Tcl Built-In Commands" @@ -69,7 +69,6 @@ list must correspond to exactly one conversion specifier or an error is generated, or in the inline case, any position can be specified at most once and the empty positions will be filled in with empty strings. .PP -.VS 8.5 The size modifier field is used only when scanning a substring into one of Tcl's integer values. The size modifier field dictates the integer range acceptable to be stored in a variable, or, for the inline @@ -84,26 +83,29 @@ modifier. Either one indicates the integer range to be stored is limited to the same range produced by the \fBwide()\fR function of the \fBexpr\fR command. The \fBll\fR size modifier indicates that the integer range to be stored is unlimited. -.VE 8.5 .PP The following conversion characters are supported: .TP 10 \fBd\fR +. The input substring must be a decimal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. .TP 10 \fBo\fR +. The input substring must be an octal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. .TP 10 \fBx\fR +. The input substring must be a hexadecimal integer. It is read in and the integer value is stored in the variable, truncated as required by the size modifier value. .TP 10 \fBu\fR +. The input substring must be a decimal integer. The integer value is truncated as required by the size modifier value, and the corresponding unsigned value for that truncated @@ -112,23 +114,27 @@ The conversion makes no sense without reference to a truncation range, so the size modifier \fBll\fR is not permitted in combination with conversion character \fBu\fR. .TP 10 -\fBi\fR +\fBi\fR +. The input substring must be an integer. The base (i.e. decimal, binary, octal, or hexadecimal) is determined in the same fashion as described in \fBexpr\fR. The integer value is stored in the variable, truncated as required by the size modifier value. .TP 10 \fBc\fR +. A single character is read in and its Unicode value is stored in the variable as an integer value. Initial white space is not skipped in this case, so the input substring may be a white-space character. .TP 10 \fBs\fR +. The input substring consists of all the characters up to the next white-space character; the characters are copied to the variable. .TP 10 \fBe\fR or \fBf\fR or \fBg\fR +. The input substring must be a floating-point number consisting of an optional sign, a string of decimal digits possibly containing a decimal point, and an optional exponent consisting @@ -137,6 +143,7 @@ decimal digits. It is read in and stored in the variable as a floating-point value. .TP 10 \fB[\fIchars\fB]\fR +. The input substring consists of one or more characters in \fIchars\fR. The matching string is stored in the variable. If the first character between the brackets is a \fB]\fR then @@ -149,6 +156,7 @@ If the first or last character between the brackets is a \fB\-\fR, then it is treated as part of \fIchars\fR rather than indicating a range. .TP 10 \fB[^\fIchars\fB]\fR +. The input substring consists of one or more characters not in \fIchars\fR. The matching string is stored in the variable. If the character immediately following the \fB^\fR is a \fB]\fR then it is @@ -162,9 +170,10 @@ If the first or last character between the brackets is a \fB\-\fR, then it is treated as part of \fIchars\fR rather than indicating a range value. .TP 10 \fBn\fR +. No input is consumed from the input string. Instead, the total number of characters scanned from the input string so far is stored in the variable. -.LP +.PP The number of characters read from the input for a conversion is the largest number that makes sense for that particular conversion (e.g. as many decimal digits as possible for \fB%d\fR, as @@ -194,6 +203,7 @@ modifier has no \fBsscanf\fR counterpart. If the end of the input string is reached before any conversions have been performed and no variables are given, an empty string is returned. .SH EXAMPLES +.PP Convert a UNICODE character to its numeric value: .CS set char "x" @@ -249,7 +259,6 @@ if { puts "X=$x, Y=$y" .CE .PP -.VS 8.5 An interactive session demonstrating the truncation of integer values determined by size modifiers: .CS @@ -262,7 +271,6 @@ values determined by size modifiers: % scan 20000000000000000000 %lld 20000000000000000000 .CE -.VE 8.5 .SH "SEE ALSO" format(n), sscanf(3) .SH KEYWORDS diff --git a/doc/source.n b/doc/source.n index a0f5466..6428d80 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.18 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: source.n,v 1.19 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH source n "" Tcl "Tcl Built-In Commands" @@ -17,9 +17,7 @@ source \- Evaluate a file or resource as a Tcl script .SH SYNOPSIS \fBsource \fIfileName\fR .sp -.VS 8.5 \fBsource\fR \fB\-encoding \fIencodingName fileName\fR -.VE 8.5 .BE .SH DESCRIPTION .PP @@ -47,18 +45,18 @@ or which will be safely substituted by the Tcl interpreter into .QW ^Z . .PP -.VS 8.5 The \fB\-encoding\fR option is used to specify the encoding of the data stored in \fIfileName\fR. When the \fB\-encoding\fR option is omitted, the system encoding is assumed. -.VE 8.5 .SH EXAMPLE +.PP Run the script in the file \fBfoo.tcl\fR and then the script in the file \fBbar.tcl\fR: .CS \fBsource\fR foo.tcl \fBsource\fR bar.tcl .CE +.PP Alternatively: .CS foreach scriptFile {foo.tcl bar.tcl} { diff --git a/doc/string.n b/doc/string.n index 1d342a0..d0cb8d8 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.43 2007/12/13 15:22:33 dgp Exp $ +.\" RCS: @(#) $Id: string.n,v 1.44 2008/06/29 22:28:24 dkf Exp $ .\" .so man.macros .TH string n 8.1 Tcl "Tcl Built-In Commands" @@ -16,13 +16,13 @@ string \- Manipulate strings .SH SYNOPSIS \fBstring \fIoption arg \fR?\fIarg ...?\fR .BE - .SH DESCRIPTION .PP Performs one of several string operations, depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: .TP \fBstring bytelength \fIstring\fR +. Returns a decimal string giving the number of bytes used to represent \fIstring\fR in memory. Because UTF\-8 uses one to three bytes to represent Unicode characters, the byte length will not be the same as @@ -33,6 +33,7 @@ Tcl ByteArray object). Refer to the \fBTcl_NumUtfChars\fR manual entry for more details on the UTF\-8 representation. .TP \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR +. Perform a character-by-character comparison of strings \fIstring1\fR and \fIstring2\fR. Returns \-1, 0, or 1, depending on whether \fIstring1\fR is lexicographically less than, equal to, or greater @@ -42,6 +43,7 @@ first \fIlength\fR characters are used in the comparison. If specified, then the strings are compared in a case-insensitive manner. .TP \fBstring equal\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR +. Perform a character-by-character comparison of strings \fIstring1\fR and \fIstring2\fR. Returns 1 if \fIstring1\fR and \fIstring2\fR are identical, or 0 when not. If \fB\-length\fR is specified, then only @@ -50,6 +52,7 @@ the first \fIlength\fR characters are used in the comparison. If specified, then the strings are compared in a case-insensitive manner. .TP \fBstring first \fIneedleString haystackString\fR ?\fIstartIndex\fR? +. Search \fIhaystackString\fR for a sequence of characters that exactly match the characters in \fIneedleString\fR. If found, return the index of the first character in the first such match within \fIhaystackString\fR. If not @@ -69,10 +72,10 @@ will return \fB\-1\fR. .RE .TP \fBstring index \fIstring charIndex\fR +. Returns the \fIcharIndex\fR'th character of the \fIstring\fR argument. A \fIcharIndex\fR of 0 corresponds to the first character of the string. \fIcharIndex\fR may be specified as follows: -.VS 8.5 .RS .IP \fIinteger\fR 10 For any index value that passes \fBstring is integer -strict\fR, @@ -121,9 +124,9 @@ leading whitespace. If \fIcharIndex\fR is less than 0 or greater than or equal to the length of the string then this command returns an empty string. .RE -.VE .TP \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR +. Returns 1 if \fIstring\fR is a valid member of the specified character class, otherwise returns 0. If \fB\-strict\fR is specified, then an empty string returns 0, otherwise an empty string will return 1 on @@ -179,12 +182,10 @@ Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is true. .IP \fBupper\fR 12 Any upper case alphabet character in the Unicode character set. -.VS 8.5 .IP \fBwideinteger\fR 12 Any of the valid forms for a wide integer in Tcl, with optional surrounding whitespace. In case of under/overflow in the value, 0 is returned and the \fIvarname\fR will contain \-1. -.VE 8.5 .IP \fBwordchar\fR 12 Any Unicode word character. That is any alphanumeric character, and any Unicode connector punctuation characters (e.g. underscore). @@ -197,6 +198,7 @@ function will return 0, then the \fIvarname\fR will always be set to .RE .TP \fBstring last \fIneedleString haystackString\fR ?\fIlastIndex\fR? +. Search \fIhaystackString\fR for a sequence of characters that exactly match the characters in \fIneedleString\fR. If found, return the index of the first character in the last such match within \fIhaystackString\fR. If there @@ -216,6 +218,7 @@ will return \fB1\fR. .RE .TP \fBstring length \fIstring\fR +. Returns a decimal string giving the number of characters in \fIstring\fR. Note that this is not necessarily the same as the number of bytes used to store the string. If the object is a @@ -223,6 +226,7 @@ ByteArray object (such as those returned from reading a binary encoded channel), then this will return the actual byte length of the object. .TP \fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR +. Replaces substrings in \fIstring\fR based on the key-value pairs in \fImapping\fR. \fImapping\fR is a list of \fIkey value key value ...\fR as in the form returned by \fBarray get\fR. Each instance of a @@ -249,6 +253,7 @@ it will return the string \fB02c322c222c\fR. .RE .TP \fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR +. See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 if it does not. If \fB\-nocase\fR is specified, then the pattern attempts to match against the string in a case insensitive manner. For the two @@ -282,6 +287,7 @@ the special interpretation of the characters \fB*?[]\e\fR in .RE .TP \fBstring range \fIstring first last\fR +. Returns a range of consecutive characters from \fIstring\fR, starting with the character whose index is \fIfirst\fR and ending with the character whose index is \fIlast\fR. An index of 0 refers to the first @@ -293,9 +299,11 @@ equal to the length of the string then it is treated as if it were string is returned. .TP \fBstring repeat \fIstring count\fR +. Returns \fIstring\fR repeated \fIcount\fR number of times. .TP \fBstring replace \fIstring first last\fR ?\fInewstring\fR? +. Removes a range of consecutive characters from \fIstring\fR, starting with the character whose index is \fIfirst\fR and ending with the character whose index is \fIlast\fR. An index of 0 refers to the @@ -307,14 +315,14 @@ and if \fIlast\fR is greater than or equal to the length of the string then it is treated as if it were \fBend\fR. If \fIfirst\fR is greater than \fIlast\fR or the length of the initial string, or \fIlast\fR is less than 0, then the initial string is returned untouched. -.VS 8.5 .TP \fBstring reverse \fIstring\fR +. Returns a string that is the same length as \fIstring\fR but with its characters in the reverse order. -.VE 8.5 .TP \fBstring tolower \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? +. Returns a value equal to \fIstring\fR except that all upper (or title) case letters have been converted to lower case. If \fIfirst\fR is specified, it refers to the first char index in the string to start @@ -323,6 +331,7 @@ the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified as for the \fBindex\fR method. .TP \fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? +. Returns a value equal to \fIstring\fR except that the first character in \fIstring\fR is converted to its Unicode title case variant (or upper case if there is no title case variant) and the rest of the @@ -333,6 +342,7 @@ stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified as for the \fBindex\fR method. .TP \fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR? +. Returns a value equal to \fIstring\fR except that all lower (or title) case letters have been converted to upper case. If \fIfirst\fR is specified, it refers to the first char index in the string to start @@ -341,24 +351,28 @@ the string to stop at (inclusive). \fIfirst\fR and \fIlast\fR may be specified as for the \fBindex\fR method. .TP \fBstring trim \fIstring\fR ?\fIchars\fR? +. Returns a value equal to \fIstring\fR except that any leading or trailing characters present in the string given by \fIchars\fR are removed. If \fIchars\fR is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). .TP \fBstring trimleft \fIstring\fR ?\fIchars\fR? +. Returns a value equal to \fIstring\fR except that any leading characters present in the string given by \fIchars\fR are removed. If \fIchars\fR is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). .TP \fBstring trimright \fIstring\fR ?\fIchars\fR? +. Returns a value equal to \fIstring\fR except that any trailing characters present in the string given by \fIchars\fR are removed. If \fIchars\fR is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). .TP \fBstring wordend \fIstring charIndex\fR +. Returns the index of the character just after the last one in the word containing character \fIcharIndex\fR of \fIstring\fR. \fIcharIndex\fR may be specified as for the \fBindex\fR method. A word is @@ -367,6 +381,7 @@ or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these. .TP \fBstring wordstart \fIstring charIndex\fR +. Returns the index of the first character in the word containing character \fIcharIndex\fR of \fIstring\fR. \fIcharIndex\fR may be specified as for the \fBindex\fR method. A word is considered to be any @@ -374,6 +389,7 @@ contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these. .SH EXAMPLE +.PP Test if the string in the variable \fIstring\fR is a proper non-empty prefix of the string \fBfoobar\fR. .CS @@ -384,14 +400,11 @@ if {$length == 0} { set isPrefix [\fBstring equal\fR -length $length $string "foobar"] } .CE - .SH "SEE ALSO" expr(n), list(n) - .SH KEYWORDS case conversion, compare, index, match, pattern, string, word, equal, ctype, character, reverse - .\" Local Variables: .\" mode: nroff .\" End: diff --git a/doc/switch.n b/doc/switch.n index 13edde8..21ecfc2 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.18 2008/03/21 19:22:31 dkf Exp $ +'\" RCS: @(#) $Id: switch.n,v 1.19 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH switch n 8.5 Tcl "Tcl Built-In Commands" @@ -33,32 +33,33 @@ command returns an empty string. .PP If the initial arguments to \fBswitch\fR start with \fB\-\fR then they are treated as options -.VS 8.5 unless there are exactly two arguments to \fBswitch\fR (in which case the first must the \fIstring\fR and the second must be the \fIpattern\fR/\fIbody\fR list). -.VE 8.5 The following options are currently supported: .TP 10 \fB\-exact\fR +. Use exact matching when comparing \fIstring\fR to a pattern. This is the default. .TP 10 \fB\-glob\fR +. When matching \fIstring\fR to the patterns, use glob-style matching (i.e. the same as implemented by the \fBstring match\fR command). .TP 10 \fB\-regexp\fR +. When matching \fIstring\fR to the patterns, use regular expression matching (as described in the \fBre_syntax\fR reference page). -'\" Options defined by TIP#75 -.VS 8.5 .TP 10 \fB\-nocase\fR +. Causes comparisons to be handled in a case-insensitive manner. .TP 10 \fB\-matchvar\fR \fIvarName\fR +. This option (only legal when \fB\-regexp\fR is also specified) specifies the name of a variable into which the list of matches found by the regular expression engine will be written. The first @@ -71,6 +72,7 @@ empty list written to it. This option may be specified at the same time as the \fB\-indexvar\fR option. .TP 10 \fB\-indexvar\fR \fIvarName\fR +. This option (only legal when \fB\-regexp\fR is also specified) specifies the name of a variable into which the list of indices referring to matching substrings @@ -85,15 +87,13 @@ capturing parenthesis in the regular expression that matched, and so on. When a \fBdefault\fR branch is taken, the variable will have the empty list written to it. This option may be specified at the same time as the \fB\-matchvar\fR option. -.VE 8.5 .TP 10 \fB\-\|\-\fR +. Marks the end of options. The argument following this one will be treated as \fIstring\fR even if it starts with a \fB\-\fR. -.VS 8.5 This is not required when the matching patterns and bodies are grouped together in a single argument. -.VE 8.5 .PP Two syntaxes are provided for the \fIpattern\fR and \fIbody\fR arguments. The first uses a separate argument for each of the patterns and commands; @@ -161,7 +161,6 @@ last) is taken. This example has a result of \fI3\fR: } .CE .PP -.VS 8.5 When matching against regular expressions, information about what exactly matched is easily obtained using the \fB\-matchvar\fR option: .CS @@ -175,7 +174,6 @@ exactly matched is easily obtained using the \fB\-matchvar\fR option: } } .CE -.VE 8.5 .SH "SEE ALSO" for(n), if(n), regexp(n) .SH KEYWORDS diff --git a/doc/tclsh.1 b/doc/tclsh.1 index dde112d..71932e1 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.14 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: tclsh.1,v 1.15 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH tclsh 1 "" Tcl "Tcl Applications" @@ -16,7 +16,6 @@ tclsh \- Simple shell containing Tcl interpreter .SH SYNOPSIS \fBtclsh\fR ?-encoding \fIname\fR? ?\fIfileName arg arg ...\fR? .BE - .SH DESCRIPTION .PP \fBTclsh\fR is a shell-like application that reads Tcl commands @@ -30,15 +29,11 @@ If there exists a file \fB.tclshrc\fR (or \fBtclshrc.tcl\fR on the Windows platforms) in the home directory of the user, interactive \fBtclsh\fR evaluates the file as a Tcl script just before reading the first command from standard input. - .SH "SCRIPT FILES" .PP -.VS 8.5 If \fBtclsh\fR is invoked with arguments then the first few arguments specify the name of a script file, and, optionally, the encoding of -the text data stored in that script file. -.VE 8.5 -Any additional arguments +the text data stored in that script file. Any additional arguments are made available to the script as variables (see below). Instead of reading commands from standard input \fBtclsh\fR will read Tcl commands from the named file; \fBtclsh\fR will exit @@ -79,6 +74,7 @@ following three lines: # the next line restarts using tclsh \e exec tclsh "$0" "$@"\fR .CE +.PP This approach has three advantages over the approach in the previous 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 @@ -103,28 +99,30 @@ its version number as part of the name. This has the advantage of allowing multiple versions of Tcl to exist on the same system at once, but also the disadvantage of making it harder to write scripts that start up uniformly across different versions of Tcl. - .SH "VARIABLES" .PP \fBTclsh\fR sets the following Tcl variables: .TP 15 \fBargc\fR +. Contains a count of the number of \fIarg\fR arguments (0 if none), not including the name of the script file. .TP 15 \fBargv\fR +. Contains a Tcl list whose elements are the \fIarg\fR arguments, in order, or an empty string if there are no \fIarg\fR arguments. .TP 15 \fBargv0\fR +. Contains \fIfileName\fR if it was specified. Otherwise, contains the name by which \fBtclsh\fR was invoked. .TP 15 \fBtcl_interactive\fR +. Contains 1 if \fBtclsh\fR is running interactively (no \fIfileName\fR was specified and standard input is a terminal-like device), 0 otherwise. - .SH PROMPTS .PP When \fBtclsh\fR is invoked interactively it normally prompts for each @@ -139,13 +137,10 @@ The variable \fBtcl_prompt2\fR is used in a similar way when 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" .PP See \fBTcl_StandardChannels\fR for more explanations. - .SH "SEE ALSO" encoding(n), fconfigure(n), tclvars(n) - .SH KEYWORDS argument, interpreter, prompt, script file, shell diff --git a/doc/tclvars.n b/doc/tclvars.n index cd5cc15..5d51f89 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.35 2007/12/13 15:22:33 dgp Exp $ +'\" RCS: @(#) $Id: tclvars.n,v 1.36 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH tclvars n 8.0 Tcl "Tcl Built-In Commands" @@ -21,6 +21,7 @@ by the Tcl library. Except where noted below, these variables should normally be treated as read-only by application-specific code and by users. .TP \fBenv\fR +. This variable is maintained by Tcl as an array whose elements are the environment variables for the process. Reading an element will return the value of the corresponding @@ -52,6 +53,7 @@ will not work on Windows and is discouraged for cross-platform usage. .RE .TP \fBerrorCode\fR +. This variable holds the value of the \fB\-errorcode\fR return option set by the most recent error that occurred in this interpreter. This list value represents additional information about the error @@ -81,6 +83,7 @@ and system libraries. .RE .TP \fBCHILDKILLED\fI pid sigName msg\fR +. This format is used when a child process has been killed because of a signal. The \fIpid\fR element will be the process's identifier (in decimal). The \fIsigName\fR element will be the symbolic name of the signal that caused @@ -92,12 +95,14 @@ describing the signal, such as for \fBSIGPIPE\fR. .TP \fBCHILDSTATUS\fI pid code\fR +. This format is used when a child process has exited with a non-zero exit status. The \fIpid\fR element will be the process's identifier (in decimal) and the \fIcode\fR element will be the exit code returned by the process (also in decimal). .TP \fBCHILDSUSP\fI pid sigName msg\fR +. This format is used when a child process has been suspended because of a signal. The \fIpid\fR element will be the process's identifier, in decimal. @@ -110,6 +115,7 @@ describing the signal, such as for \fBSIGTTIN\fR. .TP \fBNONE\fR +. This format is used for errors where no additional information is available for an error besides the message returned with the error. In these cases the \fB\-errorcode\fR return option @@ -117,6 +123,7 @@ will consist of a list containing a single element whose contents are \fBNONE\fR. .TP \fBPOSIX \fIerrName msg\fR +. If the first element is \fBPOSIX\fR, then the error occurred during a POSIX kernel call. The \fIerrName\fR element will contain the symbolic name @@ -135,13 +142,14 @@ If none of these methods for setting the error code has been used, the Tcl interpreter will reset the variable to \fBNONE\fR after the next error. .RE -.\" .TP -.\" \fBTCL\fR ... -.\" . -.\" Indicates some sort of problem generated in relation to Tcl itself, -.\" e.g. a failure to look up a channel or variable. +.TP +\fBTCL\fR ... +. +Indicates some sort of problem generated in relation to Tcl itself, e.g. a +failure to look up a channel or variable. .TP \fBerrorInfo\fR +. This variable holds the value of the \fB\-errorinfo\fR return option set by the most recent error that occurred in this interpreter. This string value will contain one or more lines @@ -151,6 +159,7 @@ Its contents take the form of a stack trace showing the various nested Tcl commands that had been invoked at the time of the error. .TP \fBtcl_library\fR +. This variable holds the name of a directory containing the system library of Tcl scripts, such as those used for auto-loading. The value of this variable is returned by the \fBinfo library\fR command. @@ -181,6 +190,7 @@ The value of this variable is returned by the \fBinfo patchlevel\fR command. .TP \fBtcl_pkgPath\fR +. This variable holds a list of directories indicating where packages are normally installed. It is not used on Windows. It typically contains either one or two entries; if it contains two entries, the first is @@ -198,6 +208,7 @@ directories for packages you should add the names of those directories to \fBauto_path\fR, not \fBtcl_pkgPath\fR. .TP \fBtcl_platform\fR +. This is an associative array whose elements contain information about the platform on which the application is running, such as the name of the operating system, its current release number, and the machine's @@ -209,10 +220,12 @@ predefined elements are: .RS .TP \fBbyteOrder\fR +. The native byte order of this machine: either \fBlittleEndian\fR or \fBbigEndian\fR. .TP \fBdebug\fR +. If this variable exists, then the interpreter was compiled with and linked to a debug-enabled C run-time. This variable will only exist on Windows, so extension writers can specify which package to load depending on the @@ -220,11 +233,13 @@ C run-time library that is in use. This is not an indication that this core contains symbols. .TP \fBmachine\fR +. The instruction set executed by this machine, such as \fBintel\fR, \fBPPC\fR, \fB68k\fR, or \fBsun4m\fR. On UNIX machines, this is the value returned by \fBuname -m\fR. .TP -\fBos\fR +\fBos\fR +. The name of the operating system running on this machine, such as \fBWindows 95\fR, \fBWindows NT\fR, or \fBSunOS\fR. On UNIX machines, this is the value returned by \fBuname -s\fR. @@ -233,38 +248,44 @@ On Windows 95 and Windows 98, the value returned will be \fBWindows distinguish between the two, check the \fBosVersion\fR. .TP \fBosVersion\fR +. The version number for the operating system running on this machine. On UNIX machines, this is the value returned by \fBuname -r\fR. On Windows 95, the version will be 4.0; on Windows 98, the version will be 4.10. .TP \fBplatform\fR +. Either \fBwindows\fR, or \fBunix\fR. This identifies the general operating environment of the machine. .TP +\fBpointerSize\fR +. +This gives the size of the native-machine pointer in bytes (strictly, it +is same as the result of evaluating \fIsizeof(void*)\fR in C.) +.TP \fBthreaded\fR +. If this variable exists, then the interpreter was compiled with threads enabled. .TP \fBuser\fR +. This identifies the current user based on the login information available on the platform. This comes from the USER or LOGNAME environment variable on Unix, and the value from GetUserName on Windows. .TP \fBwordSize\fR +. This gives the size of the native-machine word in bytes (strictly, it is same as the result of evaluating \fIsizeof(long)\fR in C.) -.TP -\fBpointerSize\fR -This gives the size of the native-machine pointer in bytes (strictly, it -is same as the result of evaluating \fIsizeof(void*)\fR in C.) .RE .TP \fBtcl_precision\fR +. This variable controls the number of digits to generate when converting floating-point values to strings. It defaults -.VS 8.5 to 0. \fIApplications should not change this value;\fR it is provided for compatibility with legacy code. .PP @@ -278,7 +299,6 @@ will convert as \fI1.4\fR rather than \fI1.3999999999999999\fR even though the latter is nearer to the exact value of the binary number. .RE -.VE 8.5 .PP .RS 17 digits is @@ -299,6 +319,7 @@ variable. .RE .TP \fBtcl_rcFileName\fR +. This variable is used during initialization to indicate the name of a user-specific startup file. If it is set by application-specific initialization, then the Tcl startup code will check for the existence @@ -307,6 +328,7 @@ the variable is set to \fB~/.wishrc\fR for Unix and \fB~/wishrc.tcl\fR for Windows. .TP \fBtcl_traceCompile\fR +. The value of this variable can be set to control how much tracing information is displayed during bytecode compilation. @@ -324,6 +346,7 @@ This variable and functionality only exist if .RE .TP \fBtcl_traceExec\fR +. The value of this variable can be set to control how much tracing information is displayed during bytecode execution. @@ -349,6 +372,7 @@ This variable and functionality only exist if .RE .TP \fBtcl_wordchars\fR +. The value of this variable is a regular expression that can be set to control what are considered .QW word @@ -359,6 +383,7 @@ 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 .QW non-word @@ -369,6 +394,7 @@ character. Otherwise it defaults to \fB\eW\fR, which is anything but a Unicode word character (number, letter, or underscore). .TP \fBtcl_version\fR +. When an interpreter is created Tcl initializes this variable to hold the version number for this version of Tcl in the form \fIx.y\fR. Changes to \fIx\fR represent major changes with probable @@ -382,17 +408,21 @@ and \fBwish\fR executables; the Tcl library does not define them itself but many Tcl environments do. .TP 6 \fBargc\fR +. The number of arguments to \fBtclsh\fR or \fBwish\fR. .TP 6 \fBargv\fR +. Tcl list of arguments to \fBtclsh\fR or \fBwish\fR. .TP 6 \fBargv0\fR +. The script that \fBtclsh\fR or \fBwish\fR started executing (if it was specified) or otherwise the name by which \fBtclsh\fR or \fBwish\fR was invoked. .TP 6 \fBtcl_interactive\fR +. Contains 1 if \fBtclsh\fR or \fBwish\fR is running interactively (no script was specified and standard input is a terminal-like device), 0 otherwise. @@ -401,6 +431,7 @@ The \fBwish\fR executable additionally specifies the following global variable: .TP 6 \fBgeometry\fR +. If set, contains the user-supplied geometry specification to use for the main Tk window. .SH "SEE ALSO" diff --git a/doc/unload.n b/doc/unload.n index b587bd6..b02c124 100644 --- a/doc/unload.n +++ b/doc/unload.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: unload.n,v 1.11 2008/03/26 14:51:42 dkf Exp $ +'\" RCS: @(#) $Id: unload.n,v 1.12 2008/06/29 22:28:24 dkf Exp $ '\" .so man.macros .TH unload n 8.5 Tcl "Tcl Built-In Commands" @@ -91,7 +91,9 @@ detached from the process. .PP The unload procedure must match the following prototype: .CS -typedef int Tcl_PackageUnloadProc(Tcl_Interp *\fIinterp\fR, int \fIflags\fR); +typedef int \fBTcl_PackageUnloadProc\fR( + Tcl_Interp *\fIinterp\fR, + int \fIflags\fR); .CE .PP The \fIinterp\fR argument identifies the interpreter from which the @@ -144,6 +146,7 @@ library is still loaded), it may be dangerous to use \fBunload\fR on such a library (as the library will be completely detached from the application while some interpreters will continue to use it). .SH EXAMPLE +.PP If an unloadable module in the file \fBfoobar.dll\fR had been loaded using the \fBload\fR command like this (on Windows): .CS |