From 9b525f538d2ae806e4667dbac5f8fe8edbb6c7f7 Mon Sep 17 00:00:00 2001 From: dgp Date: Mon, 29 Oct 2007 17:17:53 +0000 Subject: line endings --- doc/Backslash.3 | 98 +++++----- doc/CallDel.3 | 126 ++++++------- doc/CrtChnlHdlr.3 | 184 +++++++++--------- doc/CrtFileHdlr.3 | 184 +++++++++--------- doc/CrtTimerHdlr.3 | 150 +++++++-------- doc/CrtTrace.3 | 374 ++++++++++++++++++------------------ doc/DetachPids.3 | 154 +++++++-------- doc/DoOneEvent.3 | 216 ++++++++++----------- doc/DoWhenIdle.3 | 172 ++++++++--------- doc/GetCwd.3 | 108 +++++------ doc/GetOpnFl.3 | 118 ++++++------ doc/Init.3 | 72 +++---- doc/Interp.3 | 250 ++++++++++++------------ doc/RecEvalObj.3 | 110 +++++------ doc/RecordEval.3 | 114 +++++------ doc/Sleep.3 | 72 +++---- doc/StaticPkg.3 | 138 +++++++------- doc/StringObj.3 | 544 ++++++++++++++++++++++++++--------------------------- doc/Thread.3 | 394 +++++++++++++++++++------------------- doc/TraceCmd.3 | 326 ++++++++++++++++---------------- doc/file.n | 145 ++++++-------- doc/global.n | 118 ++++++------ doc/pid.n | 100 +++++----- doc/proc.n | 194 +++++++++---------- doc/puts.n | 196 +++++++++---------- doc/unset.n | 126 ++++++------- 26 files changed, 2377 insertions(+), 2406 deletions(-) diff --git a/doc/Backslash.3 b/doc/Backslash.3 index f8b6c69..f84bbfb 100644 --- a/doc/Backslash.3 +++ b/doc/Backslash.3 @@ -1,49 +1,49 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Backslash.3,v 1.8 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Backslash \- parse a backslash sequence -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -char -\fBTcl_Backslash\fR(\fIsrc, countPtr\fR) -.SH ARGUMENTS -.AS char *countPtr out -.AP char *src in -Pointer to a string starting with a backslash. -.AP int *countPtr out -If \fIcountPtr\fR is not NULL, \fI*countPtr\fR gets filled -in with number of characters in the backslash sequence, including -the backslash character. -.BE - -.SH DESCRIPTION -.PP -The use of \fBTcl_Backslash\fR is deprecated in favor of -\fBTcl_UtfBackslash\fR. -.PP -This is a utility procedure provided for backwards compatibility with -non-internationalized Tcl extensions. It parses a backslash sequence and -returns the low byte of the Unicode character corresponding to the sequence. -\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of -characters in the backslash sequence. -.PP -See the Tcl manual entry for information on the valid backslash sequences. -All of the sequences described in the Tcl manual entry are supported by -\fBTcl_Backslash\fR. -.SH "SEE ALSO" -Tcl(n), Tcl_UtfBackslash(3) - -.SH KEYWORDS -backslash, parse +'\" +'\" Copyright (c) 1989-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: Backslash.3,v 1.9 2007/10/29 17:17:53 dgp Exp $ +'\" +.so man.macros +.TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_Backslash \- parse a backslash sequence +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +char +\fBTcl_Backslash\fR(\fIsrc, countPtr\fR) +.SH ARGUMENTS +.AS char *countPtr out +.AP char *src in +Pointer to a string starting with a backslash. +.AP int *countPtr out +If \fIcountPtr\fR is not NULL, \fI*countPtr\fR gets filled +in with number of characters in the backslash sequence, including +the backslash character. +.BE + +.SH DESCRIPTION +.PP +The use of \fBTcl_Backslash\fR is deprecated in favor of +\fBTcl_UtfBackslash\fR. +.PP +This is a utility procedure provided for backwards compatibility with +non-internationalized Tcl extensions. It parses a backslash sequence and +returns the low byte of the Unicode character corresponding to the sequence. +\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of +characters in the backslash sequence. +.PP +See the Tcl manual entry for information on the valid backslash sequences. +All of the sequences described in the Tcl manual entry are supported by +\fBTcl_Backslash\fR. +.SH "SEE ALSO" +Tcl(n), Tcl_UtfBackslash(3) + +.SH KEYWORDS +backslash, parse diff --git a/doc/CallDel.3 b/doc/CallDel.3 index a4baa0c..a1b3cc4 100644 --- a/doc/CallDel.3 +++ b/doc/CallDel.3 @@ -1,63 +1,63 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: CallDel.3,v 1.4 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interpreter is deleted -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTcl_CallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) -.sp -\fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) -.SH ARGUMENTS -.AS Tcl_InterpDeleteProc clientData -.AP Tcl_Interp *interp in -Interpreter with which to associated callback. -.AP Tcl_InterpDeleteProc *proc in -Procedure to call when \fIinterp\fR is deleted. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by -\fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future -time. \fIProc\fR will be invoked just before the interpreter -is deleted, but the interpreter will still be valid at the -time of the call. -\fIProc\fR should have arguments and result that match the -type \fBTcl_InterpDeleteProc\fR: -.CS -typedef void Tcl_InterpDeleteProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR); -.CE -The \fIclientData\fR and \fIinterp\fR parameters are -copies of the \fIclientData\fR and \fIinterp\fR arguments given -to \fBTcl_CallWhenDeleted\fR. -Typically, \fIclientData\fR points to an application-specific -data structure that \fIproc\fR uses to perform cleanup when an -interpreter is about to go away. -\fIProc\fR does not return a value. -.PP -\fBTcl_DontCallWhenDeleted\fR cancels a previous call to -\fBTcl_CallWhenDeleted\fR with the same arguments, so that -\fIproc\fR will not be called after all when \fIinterp\fR is -deleted. -If there is no deletion callback that matches \fIinterp\fR, -\fIproc\fR, and \fIclientData\fR then the call to -\fBTcl_DontCallWhenDeleted\fR has no effect. - -.SH KEYWORDS -callback, delete, interpreter +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: CallDel.3,v 1.5 2007/10/29 17:17:53 dgp Exp $ +'\" +.so man.macros +.TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interpreter is deleted +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +\fBTcl_CallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) +.sp +\fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) +.SH ARGUMENTS +.AS Tcl_InterpDeleteProc clientData +.AP Tcl_Interp *interp in +Interpreter with which to associated callback. +.AP Tcl_InterpDeleteProc *proc in +Procedure to call when \fIinterp\fR is deleted. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by +\fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future +time. \fIProc\fR will be invoked just before the interpreter +is deleted, but the interpreter will still be valid at the +time of the call. +\fIProc\fR should have arguments and result that match the +type \fBTcl_InterpDeleteProc\fR: +.CS +typedef void Tcl_InterpDeleteProc( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR); +.CE +The \fIclientData\fR and \fIinterp\fR parameters are +copies of the \fIclientData\fR and \fIinterp\fR arguments given +to \fBTcl_CallWhenDeleted\fR. +Typically, \fIclientData\fR points to an application-specific +data structure that \fIproc\fR uses to perform cleanup when an +interpreter is about to go away. +\fIProc\fR does not return a value. +.PP +\fBTcl_DontCallWhenDeleted\fR cancels a previous call to +\fBTcl_CallWhenDeleted\fR with the same arguments, so that +\fIproc\fR will not be called after all when \fIinterp\fR is +deleted. +If there is no deletion callback that matches \fIinterp\fR, +\fIproc\fR, and \fIclientData\fR then the call to +\fBTcl_DontCallWhenDeleted\fR has no effect. + +.SH KEYWORDS +callback, delete, interpreter diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3 index 8a9409b..ee22bb9 100644 --- a/doc/CrtChnlHdlr.3 +++ b/doc/CrtChnlHdlr.3 @@ -1,92 +1,92 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: CrtChnlHdlr.3,v 1.4 2007/10/28 14:17:38 dkf Exp $ -.so man.macros -.TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable -.SH SYNOPSIS -.nf -.nf -\fB#include \fR -.sp -void -\fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR) -.sp -void -\fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR) -.sp -.SH ARGUMENTS -.AS Tcl_ChannelProc clientData -.AP Tcl_Channel channel in -Tcl channel such as returned by \fBTcl_CreateChannel\fR. -.AP int mask in -Conditions under which \fIproc\fR should be called: OR-ed combination of -\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify -a zero value to temporarily disable an existing handler. -.AP Tcl_FileProc *proc in -Procedure to invoke whenever the channel indicated by \fIchannel\fR meets -the conditions specified by \fImask\fR. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the -future whenever input or output becomes possible on the channel identified -by \fIchannel\fR, or whenever an exceptional condition exists for -\fIchannel\fR. The conditions of interest under which \fIproc\fR will be -invoked are specified by the \fImask\fR argument. -See the manual entry for \fBfileevent\fR for a precise description of -what it means for a channel to be readable or writable. -\fIProc\fR must conform to the following prototype: -.CS -typedef void Tcl_ChannelProc( - ClientData \fIclientData\fR, - int \fImask\fR); -.CE -.PP -The \fIclientData\fR argument is the same as the value passed to -\fBTcl_CreateChannelHandler\fR when the handler was created. Typically, -\fIclientData\fR points to a data structure containing application-specific -information about the channel. \fIMask\fR is an integer mask indicating -which of the requested conditions actually exists for the channel; it will -contain a subset of the bits from the \fImask\fR argument to -\fBTcl_CreateChannelHandler\fR when the handler was created. -.PP -Each channel handler is identified by a unique combination of \fIchannel\fR, -\fIproc\fR and \fIclientData\fR. -There may be many handlers for a given channel as long as they do not -have the same \fIchannel\fR, \fIproc\fR, and \fIclientData\fR. -If \fBTcl_CreateChannelHandler\fR is invoked when there is already a handler -for \fIchannel\fR, \fIproc\fR, and \fIclientData\fR, then no new -handler is created; instead, the \fImask\fR is changed for the -existing handler. -.PP -\fBTcl_DeleteChannelHandler\fR deletes a channel handler identified by -\fIchannel\fR, \fIproc\fR and \fIclientData\fR; if no such handler exists, -the call has no effect. -.PP -Channel handlers are invoked via the Tcl event mechanism, so they -are only useful in applications that are event-driven. -Note also that the conditions specified in the \fImask\fR argument -to \fIproc\fR may no longer exist when \fIproc\fR is invoked: for -example, if there are two handlers for \fBTCL_READABLE\fR on the same -channel, the first handler could consume all of the available input -so that the channel is no longer readable when the second handler -is invoked. -For this reason it may be useful to use nonblocking I/O on channels -for which there are event handlers. - -.SH "SEE ALSO" -Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). - -.SH KEYWORDS -blocking, callback, channel, events, handler, nonblocking. +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: CrtChnlHdlr.3,v 1.5 2007/10/29 17:17:53 dgp Exp $ +.so man.macros +.TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable +.SH SYNOPSIS +.nf +.nf +\fB#include \fR +.sp +void +\fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR) +.sp +void +\fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR) +.sp +.SH ARGUMENTS +.AS Tcl_ChannelProc clientData +.AP Tcl_Channel channel in +Tcl channel such as returned by \fBTcl_CreateChannel\fR. +.AP int mask in +Conditions under which \fIproc\fR should be called: OR-ed combination of +\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify +a zero value to temporarily disable an existing handler. +.AP Tcl_FileProc *proc in +Procedure to invoke whenever the channel indicated by \fIchannel\fR meets +the conditions specified by \fImask\fR. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the +future whenever input or output becomes possible on the channel identified +by \fIchannel\fR, or whenever an exceptional condition exists for +\fIchannel\fR. The conditions of interest under which \fIproc\fR will be +invoked are specified by the \fImask\fR argument. +See the manual entry for \fBfileevent\fR for a precise description of +what it means for a channel to be readable or writable. +\fIProc\fR must conform to the following prototype: +.CS +typedef void Tcl_ChannelProc( + ClientData \fIclientData\fR, + int \fImask\fR); +.CE +.PP +The \fIclientData\fR argument is the same as the value passed to +\fBTcl_CreateChannelHandler\fR when the handler was created. Typically, +\fIclientData\fR points to a data structure containing application-specific +information about the channel. \fIMask\fR is an integer mask indicating +which of the requested conditions actually exists for the channel; it will +contain a subset of the bits from the \fImask\fR argument to +\fBTcl_CreateChannelHandler\fR when the handler was created. +.PP +Each channel handler is identified by a unique combination of \fIchannel\fR, +\fIproc\fR and \fIclientData\fR. +There may be many handlers for a given channel as long as they do not +have the same \fIchannel\fR, \fIproc\fR, and \fIclientData\fR. +If \fBTcl_CreateChannelHandler\fR is invoked when there is already a handler +for \fIchannel\fR, \fIproc\fR, and \fIclientData\fR, then no new +handler is created; instead, the \fImask\fR is changed for the +existing handler. +.PP +\fBTcl_DeleteChannelHandler\fR deletes a channel handler identified by +\fIchannel\fR, \fIproc\fR and \fIclientData\fR; if no such handler exists, +the call has no effect. +.PP +Channel handlers are invoked via the Tcl event mechanism, so they +are only useful in applications that are event-driven. +Note also that the conditions specified in the \fImask\fR argument +to \fIproc\fR may no longer exist when \fIproc\fR is invoked: for +example, if there are two handlers for \fBTCL_READABLE\fR on the same +channel, the first handler could consume all of the available input +so that the channel is no longer readable when the second handler +is invoked. +For this reason it may be useful to use nonblocking I/O on channels +for which there are event handlers. + +.SH "SEE ALSO" +Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). + +.SH KEYWORDS +blocking, callback, channel, events, handler, nonblocking. diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3 index 27bd621..087a4f7 100644 --- a/doc/CrtFileHdlr.3 +++ b/doc/CrtFileHdlr.3 @@ -1,92 +1,92 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.6 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only) -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR) -.sp -\fBTcl_DeleteFileHandler\fR(\fIfd\fR) -.SH ARGUMENTS -.AS Tcl_FileProc clientData -.AP int fd in -Unix file descriptor for an open file or device. -.AP int mask in -Conditions under which \fIproc\fR should be called: -OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR, -and \fBTCL_EXCEPTION\fR. May be set to 0 to temporarily disable -a handler. -.AP Tcl_FileProc *proc in -Procedure to invoke whenever the file or device indicated -by \fIfile\fR meets the conditions specified by \fImask\fR. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be -invoked in the future whenever I/O becomes possible on a file -or an exceptional condition exists for the file. The file -is indicated by \fIfd\fR, and the conditions of interest -are indicated by \fImask\fR. For example, if \fImask\fR -is \fBTCL_READABLE\fR, \fIproc\fR will be called when -the file is readable. -The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so -\fBTcl_CreateFileHandler\fR is only useful in programs that dispatch -events through \fBTcl_DoOneEvent\fR or through Tcl commands such -as \fBvwait\fR. -.PP -\fIProc\fR should have arguments and result that match the -type \fBTcl_FileProc\fR: -.CS -typedef void Tcl_FileProc( - ClientData \fIclientData\fR, - int \fImask\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy -of the \fIclientData\fR -argument given to \fBTcl_CreateFileHandler\fR when the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information about -the file. \fIMask\fR is an integer mask indicating which -of the requested conditions actually exists for the file; it -will contain a subset of the bits in the \fImask\fR argument -to \fBTcl_CreateFileHandler\fR. -.PP -.PP -There may exist only one handler for a given file at a given time. -If \fBTcl_CreateFileHandler\fR is called when a handler already -exists for \fIfd\fR, then the new callback replaces the information -that was previously recorded. -.PP -\fBTcl_DeleteFileHandler\fR may be called to delete the -file handler for \fIfd\fR; if no handler exists for the -file given by \fIfd\fR then the procedure has no effect. -.PP -The purpose of file handlers is to enable an application to respond to -events while waiting for files to become ready for I/O. For this to work -correctly, the application may need to use non-blocking I/O operations on -the files for which handlers are declared. Otherwise the application may -block if it reads or writes too much data; while waiting for the I/O to -complete the application will not be able to service other events. Use -\fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into -blocking or nonblocking mode as required. -.PP -Note that these interfaces are only supported by the Unix -implementation of the Tcl notifier. - -.SH KEYWORDS -callback, file, handler +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.7 2007/10/29 17:17:53 dgp Exp $ +'\" +.so man.macros +.TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only) +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR) +.sp +\fBTcl_DeleteFileHandler\fR(\fIfd\fR) +.SH ARGUMENTS +.AS Tcl_FileProc clientData +.AP int fd in +Unix file descriptor for an open file or device. +.AP int mask in +Conditions under which \fIproc\fR should be called: +OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR, +and \fBTCL_EXCEPTION\fR. May be set to 0 to temporarily disable +a handler. +.AP Tcl_FileProc *proc in +Procedure to invoke whenever the file or device indicated +by \fIfile\fR meets the conditions specified by \fImask\fR. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be +invoked in the future whenever I/O becomes possible on a file +or an exceptional condition exists for the file. The file +is indicated by \fIfd\fR, and the conditions of interest +are indicated by \fImask\fR. For example, if \fImask\fR +is \fBTCL_READABLE\fR, \fIproc\fR will be called when +the file is readable. +The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so +\fBTcl_CreateFileHandler\fR is only useful in programs that dispatch +events through \fBTcl_DoOneEvent\fR or through Tcl commands such +as \fBvwait\fR. +.PP +\fIProc\fR should have arguments and result that match the +type \fBTcl_FileProc\fR: +.CS +typedef void Tcl_FileProc( + ClientData \fIclientData\fR, + int \fImask\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy +of the \fIclientData\fR +argument given to \fBTcl_CreateFileHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information about +the file. \fIMask\fR is an integer mask indicating which +of the requested conditions actually exists for the file; it +will contain a subset of the bits in the \fImask\fR argument +to \fBTcl_CreateFileHandler\fR. +.PP +.PP +There may exist only one handler for a given file at a given time. +If \fBTcl_CreateFileHandler\fR is called when a handler already +exists for \fIfd\fR, then the new callback replaces the information +that was previously recorded. +.PP +\fBTcl_DeleteFileHandler\fR may be called to delete the +file handler for \fIfd\fR; if no handler exists for the +file given by \fIfd\fR then the procedure has no effect. +.PP +The purpose of file handlers is to enable an application to respond to +events while waiting for files to become ready for I/O. For this to work +correctly, the application may need to use non-blocking I/O operations on +the files for which handlers are declared. Otherwise the application may +block if it reads or writes too much data; while waiting for the I/O to +complete the application will not be able to service other events. Use +\fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into +blocking or nonblocking mode as required. +.PP +Note that these interfaces are only supported by the Unix +implementation of the Tcl notifier. + +.SH KEYWORDS +callback, file, handler diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3 index 8509e26..3d3fed6 100644 --- a/doc/CrtTimerHdlr.3 +++ b/doc/CrtTimerHdlr.3 @@ -1,75 +1,75 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.4 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a given time -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tcl_TimerToken -\fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR) -.sp -\fBTcl_DeleteTimerHandler\fR(\fItoken\fR) -.SH ARGUMENTS -.AS Tcl_TimerToken milliseconds -.AP int milliseconds in -How many milliseconds to wait before invoking \fIproc\fR. -.AP Tcl_TimerProc *proc in -Procedure to invoke after \fImilliseconds\fR have elapsed. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.AP Tcl_TimerToken token in -Token for previously created timer handler (the return value -from some previous call to \fBTcl_CreateTimerHandler\fR). -.BE - -.SH DESCRIPTION -.PP -\fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be -invoked at a time \fImilliseconds\fR milliseconds in the -future. -The callback to \fIproc\fR will be made by \fBTcl_DoOneEvent\fR, -so \fBTcl_CreateTimerHandler\fR is only useful in programs that -dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands -such as \fBvwait\fR. -The call to \fIproc\fR may not be made at the exact time given by -\fImilliseconds\fR: it will be made at the next opportunity -after that time. For example, if \fBTcl_DoOneEvent\fR is not -called until long after the time has elapsed, or if there -are other pending events to process before the call to -\fIproc\fR, then the call to \fIproc\fR will be delayed. -.PP -\fIProc\fR should have arguments and return value that match -the type \fBTcl_TimerProc\fR: -.CS -typedef void Tcl_TimerProc(ClientData \fIclientData\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a -copy of the \fIclientData\fR argument given to -\fBTcl_CreateTimerHandler\fR when the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information about -what to do in \fIproc\fR. -.PP -\fBTcl_DeleteTimerHandler\fR may be called to delete a -previously created timer handler. It deletes the handler -indicated by \fItoken\fR so that no call to \fIproc\fR -will be made; if that handler no longer exists -(e.g. because the time period has already elapsed and \fIproc\fR -has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing. -The tokens returned by \fBTcl_CreateTimerHandler\fR never have -a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR -then the procedure does nothing. - -.SH KEYWORDS -callback, clock, handler, timer +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.5 2007/10/29 17:17:53 dgp Exp $ +'\" +.so man.macros +.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a given time +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +Tcl_TimerToken +\fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR) +.sp +\fBTcl_DeleteTimerHandler\fR(\fItoken\fR) +.SH ARGUMENTS +.AS Tcl_TimerToken milliseconds +.AP int milliseconds in +How many milliseconds to wait before invoking \fIproc\fR. +.AP Tcl_TimerProc *proc in +Procedure to invoke after \fImilliseconds\fR have elapsed. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.AP Tcl_TimerToken token in +Token for previously created timer handler (the return value +from some previous call to \fBTcl_CreateTimerHandler\fR). +.BE + +.SH DESCRIPTION +.PP +\fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be +invoked at a time \fImilliseconds\fR milliseconds in the +future. +The callback to \fIproc\fR will be made by \fBTcl_DoOneEvent\fR, +so \fBTcl_CreateTimerHandler\fR is only useful in programs that +dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands +such as \fBvwait\fR. +The call to \fIproc\fR may not be made at the exact time given by +\fImilliseconds\fR: it will be made at the next opportunity +after that time. For example, if \fBTcl_DoOneEvent\fR is not +called until long after the time has elapsed, or if there +are other pending events to process before the call to +\fIproc\fR, then the call to \fIproc\fR will be delayed. +.PP +\fIProc\fR should have arguments and return value that match +the type \fBTcl_TimerProc\fR: +.CS +typedef void Tcl_TimerProc(ClientData \fIclientData\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a +copy of the \fIclientData\fR argument given to +\fBTcl_CreateTimerHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information about +what to do in \fIproc\fR. +.PP +\fBTcl_DeleteTimerHandler\fR may be called to delete a +previously created timer handler. It deletes the handler +indicated by \fItoken\fR so that no call to \fIproc\fR +will be made; if that handler no longer exists +(e.g. because the time period has already elapsed and \fIproc\fR +has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing. +The tokens returned by \fBTcl_CreateTimerHandler\fR never have +a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR +then the procedure does nothing. + +.SH KEYWORDS +callback, clock, handler, timer diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index 80d2b47..5035fd6 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -1,187 +1,187 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 2002 by Kevin B. Kenny. All rights reserved. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: CrtTrace.3,v 1.11 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tcl_Trace -\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR) -.sp -Tcl_Trace -\fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR) -.sp -\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) -.SH ARGUMENTS -.AS Tcl_CmdObjTraceDeleteProc *deleteProc -.AP Tcl_Interp *interp in -Interpreter containing command to be traced or untraced. -.AP int level in -Only commands at or below this nesting level will be traced unless -0 is specified. 1 means -top-level commands only, 2 means top-level commands or those that are -invoked as immediate consequences of executing top-level commands -(procedure bodies, bracketed commands, etc.) and so on. -A value of 0 means that commands at any level are traced. -.AP int flags in -Flags governing the trace execution. See below for details. -.AP Tcl_CmdObjTraceProc *objProc in -Procedure to call for each command that is executed. See below for -details of the calling sequence. -.AP Tcl_CmdTraceProc *proc in -Procedure to call for each command that is executed. See below for -details on the calling sequence. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR. -.AP Tcl_CmdObjTraceDeleteProc *deleteProc in -Procedure to call when the trace is deleted. See below for details of -the calling sequence. A NULL pointer is permissible and results in no -callback when the trace is deleted. -.AP Tcl_Trace trace in -Token for trace to be removed (return value from previous call -to \fBTcl_CreateTrace\fR). -.BE -.SH DESCRIPTION -.PP -\fBTcl_CreateObjTrace\fR arranges for command tracing. After it is -called, \fIobjProc\fR will be invoked before the Tcl interpreter calls -any command procedure when evaluating commands in \fIinterp\fR. -The return value from \fBTcl_CreateObjTrace\fR is a token for the trace, -which may be passed to \fBTcl_DeleteTrace\fR to remove the trace. -There may be many traces in effect simultaneously for the same -interpreter. -.PP -\fIobjProc\fR should have arguments and result that match the type, -\fBTcl_CmdObjTraceProc\fR: -.CS -typedef int \fBTcl_CmdObjTraceProc\fR( - \fBClientData\fR \fIclientData\fR, - \fBTcl_Interp\fR* \fIinterp\fR, - int \fIlevel\fR, - const char *\fIcommand\fR, - \fBTcl_Command\fR \fIcommandToken\fR, - int \fIobjc\fR, - \fBTcl_Obj\fR *const \fIobjv\fR[] ); -.CE -The \fIclientData\fR and \fIinterp\fR parameters are copies of the -corresponding arguments given to \fBTcl_CreateTrace\fR. -\fIClientData\fR typically points to an application-specific data -structure that describes what to do when \fIobjProc\fR is invoked. The -\fIlevel\fR parameter gives the nesting level of the command (1 for -top-level commands passed to \fBTcl_Eval\fR by the application, 2 for -the next-level commands passed to \fBTcl_Eval\fR as part of parsing or -interpreting level-1 commands, and so on). The \fIcommand\fR parameter -points to a string containing the text of the command, before any -argument substitution. The \fIcommandToken\fR parameter is a Tcl -command token that identifies the command to be invoked. The token -may be passed to \fBTcl_GetCommandName\fR, -\fBTcl_GetCommandTokenInfo\fR, or \fBTcl_SetCommandTokenInfo\fR to -manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR -parameters designate the final parameter count and parameter vector -that will be passed to the command, and have had all substitutions -performed. -.PP -The \fIobjProc\fR callback is expected to return a standard Tcl status -return code. If this code is \fBTCL_OK\fR (the normal case), then -the Tcl interpreter will invoke the command. Any other return code -is treated as if the command returned that status, and the command is -\fInot\fR invoked. -.PP -The \fIobjProc\fR callback must not modify \fIobjv\fR in any way. It -is, however, permissible to change the command by calling -\fBTcl_SetCommandTokenInfo\fR prior to returning. Any such change -takes effect immediately, and the command is invoked with the new -information. -.PP -Tracing will only occur for commands at nesting level less than -or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR -parameter to \fIobjProc\fR will always be less than or equal to the -\fIlevel\fR parameter to \fBTcl_CreateTrace\fR). -.PP -Tracing has a significant effect on runtime performance because it -causes the bytecode compiler to refrain from generating in-line code -for Tcl commands such as \fBif\fR and \fBwhile\fR in order that they -may be traced. If traces for the built-in commands are not required, -the \fIflags\fR parameter may be set to the constant value -\fBTCL_ALLOW_INLINE_COMPILATION\fR. In this case, traces on built-in -commands may or may not result in trace callbacks, depending on the -state of the interpreter, but run-time performance will be improved -significantly. (This functionality is desirable, for example, when -using \fBTcl_CreateObjTrace\fR to implement an execution time -profiler.) -.PP -Calls to \fIobjProc\fR will be made by the Tcl parser immediately before -it calls the command procedure for the command (\fIcmdProc\fR). This -occurs after argument parsing and substitution, so tracing for -substituted commands occurs before tracing of the commands -containing the substitutions. If there is a syntax error in a -command, or if there is no command procedure associated with a -command name, then no tracing will occur for that command. If a -string passed to Tcl_Eval contains multiple commands (bracketed, or -on different lines) then multiple calls to \fIobjProc\fR will occur, -one for each command. -.PP -\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be -made to the procedure associated with the trace. After \fBTcl_DeleteTrace\fR -returns, the caller should never again use the \fItrace\fR token. -.PP -When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the -\fIdeleteProc\fR that was passed as a parameter to -\fBTcl_CreateObjTrace\fR. The \fIdeleteProc\fR must match the type, -\fBTcl_CmdObjTraceDeleteProc\fR: -.CS -typedef void \fBTcl_CmdObjTraceDeleteProc\fR( - \fBClientData\fR \fIclientData\fR); -.CE -The \fIclientData\fR parameter will be the same as the -\fIclientData\fR parameter that was originally passed to -\fBTcl_CreateObjTrace\fR. -.PP -\fBTcl_CreateTrace\fR is an alternative interface for command tracing, -\fInot recommended for new applications\fR. It is provided for backward -compatibility with code that was developed for older versions of the -Tcl interpreter. It is similar to \fBTcl_CreateObjTrace\fR, except -that its \fIproc\fR parameter should have arguments and result that -match the type \fBTcl_CmdTraceProc\fR: -.CS -typedef void Tcl_CmdTraceProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIlevel\fR, - char *\fIcommand\fR, - Tcl_CmdProc *\fIcmdProc\fR, - ClientData \fIcmdClientData\fR, - int \fIargc\fR, - const char *\fIargv\fR[]); -.CE -The parameters to the \fIproc\fR callback are similar to those of the -\fIobjProc\fR callback above. The \fIcommandToken\fR is -replaced with \fIcmdProc\fR, a pointer to the (string-based) command -procedure that will be invoked; and \fIcmdClientData\fR, the client -data that will be passed to the procedure. The \fIobjc\fR parameter -is replaced with an \fIargv\fR parameter, that gives the arguments to -the command as character strings. -\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings. -.PP -If a trace created with \fBTcl_CreateTrace\fR is in effect, inline -compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always -disabled. There is no notification when a trace created with -\fBTcl_CreateTrace\fR is deleted. -There is no way to be notified when the trace created by -\fBTcl_CreateTrace\fR is deleted. There is no way for the \fIproc\fR -associated with a call to \fBTcl_CreateTrace\fR to abort execution of -\fIcommand\fR. -.SH KEYWORDS -command, create, delete, interpreter, trace +'\" +'\" Copyright (c) 1989-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 2002 by Kevin B. Kenny. All rights reserved. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: CrtTrace.3,v 1.12 2007/10/29 17:17:53 dgp Exp $ +'\" +.so man.macros +.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +Tcl_Trace +\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR) +.sp +Tcl_Trace +\fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR) +.sp +\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) +.SH ARGUMENTS +.AS Tcl_CmdObjTraceDeleteProc *deleteProc +.AP Tcl_Interp *interp in +Interpreter containing command to be traced or untraced. +.AP int level in +Only commands at or below this nesting level will be traced unless +0 is specified. 1 means +top-level commands only, 2 means top-level commands or those that are +invoked as immediate consequences of executing top-level commands +(procedure bodies, bracketed commands, etc.) and so on. +A value of 0 means that commands at any level are traced. +.AP int flags in +Flags governing the trace execution. See below for details. +.AP Tcl_CmdObjTraceProc *objProc in +Procedure to call for each command that is executed. See below for +details of the calling sequence. +.AP Tcl_CmdTraceProc *proc in +Procedure to call for each command that is executed. See below for +details on the calling sequence. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR. +.AP Tcl_CmdObjTraceDeleteProc *deleteProc in +Procedure to call when the trace is deleted. See below for details of +the calling sequence. A NULL pointer is permissible and results in no +callback when the trace is deleted. +.AP Tcl_Trace trace in +Token for trace to be removed (return value from previous call +to \fBTcl_CreateTrace\fR). +.BE +.SH DESCRIPTION +.PP +\fBTcl_CreateObjTrace\fR arranges for command tracing. After it is +called, \fIobjProc\fR will be invoked before the Tcl interpreter calls +any command procedure when evaluating commands in \fIinterp\fR. +The return value from \fBTcl_CreateObjTrace\fR is a token for the trace, +which may be passed to \fBTcl_DeleteTrace\fR to remove the trace. +There may be many traces in effect simultaneously for the same +interpreter. +.PP +\fIobjProc\fR should have arguments and result that match the type, +\fBTcl_CmdObjTraceProc\fR: +.CS +typedef int \fBTcl_CmdObjTraceProc\fR( + \fBClientData\fR \fIclientData\fR, + \fBTcl_Interp\fR* \fIinterp\fR, + int \fIlevel\fR, + const char *\fIcommand\fR, + \fBTcl_Command\fR \fIcommandToken\fR, + int \fIobjc\fR, + \fBTcl_Obj\fR *const \fIobjv\fR[] ); +.CE +The \fIclientData\fR and \fIinterp\fR parameters are copies of the +corresponding arguments given to \fBTcl_CreateTrace\fR. +\fIClientData\fR typically points to an application-specific data +structure that describes what to do when \fIobjProc\fR is invoked. The +\fIlevel\fR parameter gives the nesting level of the command (1 for +top-level commands passed to \fBTcl_Eval\fR by the application, 2 for +the next-level commands passed to \fBTcl_Eval\fR as part of parsing or +interpreting level-1 commands, and so on). The \fIcommand\fR parameter +points to a string containing the text of the command, before any +argument substitution. The \fIcommandToken\fR parameter is a Tcl +command token that identifies the command to be invoked. The token +may be passed to \fBTcl_GetCommandName\fR, +\fBTcl_GetCommandTokenInfo\fR, or \fBTcl_SetCommandTokenInfo\fR to +manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR +parameters designate the final parameter count and parameter vector +that will be passed to the command, and have had all substitutions +performed. +.PP +The \fIobjProc\fR callback is expected to return a standard Tcl status +return code. If this code is \fBTCL_OK\fR (the normal case), then +the Tcl interpreter will invoke the command. Any other return code +is treated as if the command returned that status, and the command is +\fInot\fR invoked. +.PP +The \fIobjProc\fR callback must not modify \fIobjv\fR in any way. It +is, however, permissible to change the command by calling +\fBTcl_SetCommandTokenInfo\fR prior to returning. Any such change +takes effect immediately, and the command is invoked with the new +information. +.PP +Tracing will only occur for commands at nesting level less than +or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR +parameter to \fIobjProc\fR will always be less than or equal to the +\fIlevel\fR parameter to \fBTcl_CreateTrace\fR). +.PP +Tracing has a significant effect on runtime performance because it +causes the bytecode compiler to refrain from generating in-line code +for Tcl commands such as \fBif\fR and \fBwhile\fR in order that they +may be traced. If traces for the built-in commands are not required, +the \fIflags\fR parameter may be set to the constant value +\fBTCL_ALLOW_INLINE_COMPILATION\fR. In this case, traces on built-in +commands may or may not result in trace callbacks, depending on the +state of the interpreter, but run-time performance will be improved +significantly. (This functionality is desirable, for example, when +using \fBTcl_CreateObjTrace\fR to implement an execution time +profiler.) +.PP +Calls to \fIobjProc\fR will be made by the Tcl parser immediately before +it calls the command procedure for the command (\fIcmdProc\fR). This +occurs after argument parsing and substitution, so tracing for +substituted commands occurs before tracing of the commands +containing the substitutions. If there is a syntax error in a +command, or if there is no command procedure associated with a +command name, then no tracing will occur for that command. If a +string passed to Tcl_Eval contains multiple commands (bracketed, or +on different lines) then multiple calls to \fIobjProc\fR will occur, +one for each command. +.PP +\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be +made to the procedure associated with the trace. After \fBTcl_DeleteTrace\fR +returns, the caller should never again use the \fItrace\fR token. +.PP +When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the +\fIdeleteProc\fR that was passed as a parameter to +\fBTcl_CreateObjTrace\fR. The \fIdeleteProc\fR must match the type, +\fBTcl_CmdObjTraceDeleteProc\fR: +.CS +typedef void \fBTcl_CmdObjTraceDeleteProc\fR( + \fBClientData\fR \fIclientData\fR); +.CE +The \fIclientData\fR parameter will be the same as the +\fIclientData\fR parameter that was originally passed to +\fBTcl_CreateObjTrace\fR. +.PP +\fBTcl_CreateTrace\fR is an alternative interface for command tracing, +\fInot recommended for new applications\fR. It is provided for backward +compatibility with code that was developed for older versions of the +Tcl interpreter. It is similar to \fBTcl_CreateObjTrace\fR, except +that its \fIproc\fR parameter should have arguments and result that +match the type \fBTcl_CmdTraceProc\fR: +.CS +typedef void Tcl_CmdTraceProc( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + int \fIlevel\fR, + char *\fIcommand\fR, + Tcl_CmdProc *\fIcmdProc\fR, + ClientData \fIcmdClientData\fR, + int \fIargc\fR, + const char *\fIargv\fR[]); +.CE +The parameters to the \fIproc\fR callback are similar to those of the +\fIobjProc\fR callback above. The \fIcommandToken\fR is +replaced with \fIcmdProc\fR, a pointer to the (string-based) command +procedure that will be invoked; and \fIcmdClientData\fR, the client +data that will be passed to the procedure. The \fIobjc\fR parameter +is replaced with an \fIargv\fR parameter, that gives the arguments to +the command as character strings. +\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings. +.PP +If a trace created with \fBTcl_CreateTrace\fR is in effect, inline +compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always +disabled. There is no notification when a trace created with +\fBTcl_CreateTrace\fR is deleted. +There is no way to be notified when the trace created by +\fBTcl_CreateTrace\fR is deleted. There is no way for the \fIproc\fR +associated with a call to \fBTcl_CreateTrace\fR to abort execution of +\fIcommand\fR. +.SH KEYWORDS +command, create, delete, interpreter, trace diff --git a/doc/DetachPids.3 b/doc/DetachPids.3 index 3ab4fe1..0549fbc 100644 --- a/doc/DetachPids.3 +++ b/doc/DetachPids.3 @@ -1,77 +1,77 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: DetachPids.3,v 1.5 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR) -.sp -\fBTcl_ReapDetachedProcs\fR() -.sp -Tcl_Pid -\fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR) -.SH ARGUMENTS -.AS Tcl_Pid *statusPtr out -.AP int numPids in -Number of process ids contained in the array pointed to by \fIpidPtr\fR. -.AP int *pidPtr in -Address of array containing \fInumPids\fR process ids. -.AP Tcl_Pid pid in -The id of the process (pipe) to wait for. -.AP int *statusPtr out -The result of waiting on a process (pipe). Either 0 or ECHILD. -.AP int options in -The options controlling the wait. WNOHANG specifies not to wait when -checking the process. -.BE -.SH DESCRIPTION -.PP -\fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a -mechanism for managing subprocesses that are running in background. -These procedures are needed because the parent of a process must -eventually invoke the \fBwaitpid\fR kernel call (or one of a few other -similar kernel calls) to wait for the child to exit. Until the -parent waits for the child, the child's state cannot be completely -reclaimed by the system. If a parent continually creates children -and doesn't wait on them, the system's process table will eventually -overflow, even if all the children have exited. -.PP -\fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility -for one or more processes whose process ids are contained in the -\fIpidPtr\fR array passed as argument. The caller presumably -has started these processes running in background and does not -want to have to deal with them again. -.PP -\fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call -on each of the background processes so that its state can be cleaned -up if it has exited. If the process has not exited yet, -\fBTcl_ReapDetachedProcs\fR does not wait for it to exit; it will check again -the next time it is invoked. -Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the -\fBexec\fR command is executed, so in most cases it is not necessary -for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR. -However, if you call \fBTcl_DetachPids\fR in situations where the -\fBexec\fR command may never get executed, you may wish to call -\fBTcl_ReapDetachedProcs\fR from time to time so that background -processes can be cleaned up. -.PP -\fBTcl_WaitPid\fR is a thin wrapper around the facilities provided by -the operating system to wait on the end of a spawned process and to -check a whether spawned process is still running. It is used by -\fBTcl_ReapDetachedProcs\fR and the channel system to portably access -the operating system. - -.SH KEYWORDS -background, child, detach, process, wait +'\" +'\" Copyright (c) 1989-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: DetachPids.3,v 1.6 2007/10/29 17:17:53 dgp Exp $ +'\" +.so man.macros +.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR) +.sp +\fBTcl_ReapDetachedProcs\fR() +.sp +Tcl_Pid +\fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR) +.SH ARGUMENTS +.AS Tcl_Pid *statusPtr out +.AP int numPids in +Number of process ids contained in the array pointed to by \fIpidPtr\fR. +.AP int *pidPtr in +Address of array containing \fInumPids\fR process ids. +.AP Tcl_Pid pid in +The id of the process (pipe) to wait for. +.AP int *statusPtr out +The result of waiting on a process (pipe). Either 0 or ECHILD. +.AP int options in +The options controlling the wait. WNOHANG specifies not to wait when +checking the process. +.BE +.SH DESCRIPTION +.PP +\fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a +mechanism for managing subprocesses that are running in background. +These procedures are needed because the parent of a process must +eventually invoke the \fBwaitpid\fR kernel call (or one of a few other +similar kernel calls) to wait for the child to exit. Until the +parent waits for the child, the child's state cannot be completely +reclaimed by the system. If a parent continually creates children +and doesn't wait on them, the system's process table will eventually +overflow, even if all the children have exited. +.PP +\fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility +for one or more processes whose process ids are contained in the +\fIpidPtr\fR array passed as argument. The caller presumably +has started these processes running in background and does not +want to have to deal with them again. +.PP +\fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call +on each of the background processes so that its state can be cleaned +up if it has exited. If the process has not exited yet, +\fBTcl_ReapDetachedProcs\fR does not wait for it to exit; it will check again +the next time it is invoked. +Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the +\fBexec\fR command is executed, so in most cases it is not necessary +for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR. +However, if you call \fBTcl_DetachPids\fR in situations where the +\fBexec\fR command may never get executed, you may wish to call +\fBTcl_ReapDetachedProcs\fR from time to time so that background +processes can be cleaned up. +.PP +\fBTcl_WaitPid\fR is a thin wrapper around the facilities provided by +the operating system to wait on the end of a spawned process and to +check a whether spawned process is still running. It is used by +\fBTcl_ReapDetachedProcs\fR and the channel system to portably access +the operating system. + +.SH KEYWORDS +background, child, detach, process, wait diff --git a/doc/DoOneEvent.3 b/doc/DoOneEvent.3 index a027c80..3296d3b 100644 --- a/doc/DoOneEvent.3 +++ b/doc/DoOneEvent.3 @@ -1,108 +1,108 @@ -'\" -'\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: DoOneEvent.3,v 1.4 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_DoOneEvent \- wait for events and invoke event handlers -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTcl_DoOneEvent\fR(\fIflags\fR) -.SH ARGUMENTS -.AS int flags -.AP int flags in -This parameter is normally zero. It may be an OR-ed combination -of any of the following flag bits: -\fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR, -\fBTCL_TIMER_EVENTS\fR, \fBTCL_IDLE_EVENTS\fR, \fBTCL_ALL_EVENTS\fR, -or \fBTCL_DONT_WAIT\fR. -.BE - -.SH DESCRIPTION -.PP -This procedure is the entry point to Tcl's event loop; it is responsible for -waiting for events and dispatching event handlers created with -procedures such as \fBTk_CreateEventHandler\fR, \fBTcl_CreateFileHandler\fR, -\fBTcl_CreateTimerHandler\fR, and \fBTcl_DoWhenIdle\fR. -\fBTcl_DoOneEvent\fR checks to see if -events are already present on the Tcl event queue; if so, -it calls the handler(s) for the first (oldest) event, removes it from -the queue, and returns. -If there are no events ready to be handled, then \fBTcl_DoOneEvent\fR -checks for new events from all possible sources. -If any are found, it puts all of them on Tcl's event queue, calls -handlers for the first event on the queue, and returns. -If no events are found, \fBTcl_DoOneEvent\fR checks for \fBTcl_DoWhenIdle\fR -callbacks; if any are found, it invokes all of them and returns. -Finally, if no events or idle callbacks have been found, then -\fBTcl_DoOneEvent\fR sleeps until an event occurs; then it adds any -new events to the Tcl event queue, calls handlers for the first event, -and returns. -The normal return value is 1 to signify that some event -was processed (see below for other alternatives). -.PP -If the \fIflags\fR argument to \fBTcl_DoOneEvent\fR is non-zero, -it restricts the kinds of events that will be processed by -\fBTcl_DoOneEvent\fR. -\fIFlags\fR may be an OR-ed combination of any of the following bits: -.TP 27 -\fBTCL_WINDOW_EVENTS\fR \- -Process window system events. -.TP 27 -\fBTCL_FILE_EVENTS\fR \- -Process file events. -.TP 27 -\fBTCL_TIMER_EVENTS\fR \- -Process timer events. -.TP 27 -\fBTCL_IDLE_EVENTS\fR \- -Process idle callbacks. -.TP 27 -\fBTCL_ALL_EVENTS\fR \- -Process all kinds of events: equivalent to OR-ing together all of the -above flags or specifying none of them. -.TP 27 -\fBTCL_DONT_WAIT\fR \- -Do not sleep: process only events that are ready at the time of the -call. -.LP -If any of the flags \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR, -\fBTCL_TIMER_EVENTS\fR, or \fBTCL_IDLE_EVENTS\fR is set, then the only -events that will be considered are those for which flags are set. -Setting none of these flags is equivalent to the value -\fBTCL_ALL_EVENTS\fR, which causes all event types to be processed. -If an application has defined additional event sources with -\fBTcl_CreateEventSource\fR, then additional \fIflag\fR values -may also be valid, depending on those event sources. -.PP -The \fBTCL_DONT_WAIT\fR flag causes \fBTcl_DoOneEvent\fR not to put -the process to sleep: it will check for events but if none are found -then it returns immediately with a return value of 0 to indicate -that no work was done. -\fBTcl_DoOneEvent\fR will also return 0 without doing anything if -the only alternative is to block forever (this can happen, for example, -if \fIflags\fR is \fBTCL_IDLE_EVENTS\fR and there are no -\fBTcl_DoWhenIdle\fR callbacks pending, or if no event handlers or -timer handlers exist). -.PP -\fBTcl_DoOneEvent\fR may be invoked recursively. For example, -it is possible to invoke \fBTcl_DoOneEvent\fR recursively -from a handler called by \fBTcl_DoOneEvent\fR. This sort -of operation is useful in some modal situations, such -as when a -notification dialog has been popped up and an application wishes to -wait for the user to click a button in the dialog before -doing anything else. - -.SH KEYWORDS -callback, event, handler, idle, timer +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: DoOneEvent.3,v 1.5 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_DoOneEvent \- wait for events and invoke event handlers +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_DoOneEvent\fR(\fIflags\fR) +.SH ARGUMENTS +.AS int flags +.AP int flags in +This parameter is normally zero. It may be an OR-ed combination +of any of the following flag bits: +\fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR, +\fBTCL_TIMER_EVENTS\fR, \fBTCL_IDLE_EVENTS\fR, \fBTCL_ALL_EVENTS\fR, +or \fBTCL_DONT_WAIT\fR. +.BE + +.SH DESCRIPTION +.PP +This procedure is the entry point to Tcl's event loop; it is responsible for +waiting for events and dispatching event handlers created with +procedures such as \fBTk_CreateEventHandler\fR, \fBTcl_CreateFileHandler\fR, +\fBTcl_CreateTimerHandler\fR, and \fBTcl_DoWhenIdle\fR. +\fBTcl_DoOneEvent\fR checks to see if +events are already present on the Tcl event queue; if so, +it calls the handler(s) for the first (oldest) event, removes it from +the queue, and returns. +If there are no events ready to be handled, then \fBTcl_DoOneEvent\fR +checks for new events from all possible sources. +If any are found, it puts all of them on Tcl's event queue, calls +handlers for the first event on the queue, and returns. +If no events are found, \fBTcl_DoOneEvent\fR checks for \fBTcl_DoWhenIdle\fR +callbacks; if any are found, it invokes all of them and returns. +Finally, if no events or idle callbacks have been found, then +\fBTcl_DoOneEvent\fR sleeps until an event occurs; then it adds any +new events to the Tcl event queue, calls handlers for the first event, +and returns. +The normal return value is 1 to signify that some event +was processed (see below for other alternatives). +.PP +If the \fIflags\fR argument to \fBTcl_DoOneEvent\fR is non-zero, +it restricts the kinds of events that will be processed by +\fBTcl_DoOneEvent\fR. +\fIFlags\fR may be an OR-ed combination of any of the following bits: +.TP 27 +\fBTCL_WINDOW_EVENTS\fR \- +Process window system events. +.TP 27 +\fBTCL_FILE_EVENTS\fR \- +Process file events. +.TP 27 +\fBTCL_TIMER_EVENTS\fR \- +Process timer events. +.TP 27 +\fBTCL_IDLE_EVENTS\fR \- +Process idle callbacks. +.TP 27 +\fBTCL_ALL_EVENTS\fR \- +Process all kinds of events: equivalent to OR-ing together all of the +above flags or specifying none of them. +.TP 27 +\fBTCL_DONT_WAIT\fR \- +Do not sleep: process only events that are ready at the time of the +call. +.LP +If any of the flags \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR, +\fBTCL_TIMER_EVENTS\fR, or \fBTCL_IDLE_EVENTS\fR is set, then the only +events that will be considered are those for which flags are set. +Setting none of these flags is equivalent to the value +\fBTCL_ALL_EVENTS\fR, which causes all event types to be processed. +If an application has defined additional event sources with +\fBTcl_CreateEventSource\fR, then additional \fIflag\fR values +may also be valid, depending on those event sources. +.PP +The \fBTCL_DONT_WAIT\fR flag causes \fBTcl_DoOneEvent\fR not to put +the process to sleep: it will check for events but if none are found +then it returns immediately with a return value of 0 to indicate +that no work was done. +\fBTcl_DoOneEvent\fR will also return 0 without doing anything if +the only alternative is to block forever (this can happen, for example, +if \fIflags\fR is \fBTCL_IDLE_EVENTS\fR and there are no +\fBTcl_DoWhenIdle\fR callbacks pending, or if no event handlers or +timer handlers exist). +.PP +\fBTcl_DoOneEvent\fR may be invoked recursively. For example, +it is possible to invoke \fBTcl_DoOneEvent\fR recursively +from a handler called by \fBTcl_DoOneEvent\fR. This sort +of operation is useful in some modal situations, such +as when a +notification dialog has been popped up and an application wishes to +wait for the user to click a button in the dialog before +doing anything else. + +.SH KEYWORDS +callback, event, handler, idle, timer diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3 index 239878e..f2a962d 100644 --- a/doc/DoWhenIdle.3 +++ b/doc/DoWhenIdle.3 @@ -1,86 +1,86 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.3 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR) -.sp -\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR) -.SH ARGUMENTS -.AS Tcl_IdleProc clientData -.AP Tcl_IdleProc *proc in -Procedure to invoke. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked -when the application becomes idle. The application is -considered to be idle when \fBTcl_DoOneEvent\fR has been -called, could not find any events to handle, and is about -to go to sleep waiting for an event to occur. At this -point all pending \fBTcl_DoWhenIdle\fR handlers are -invoked. For each call to \fBTcl_DoWhenIdle\fR there will -be a single call to \fIproc\fR; after \fIproc\fR is -invoked the handler is automatically removed. -\fBTcl_DoWhenIdle\fR is only usable in programs that -use \fBTcl_DoOneEvent\fR to dispatch events. -.PP -\fIProc\fR should have arguments and result that match the -type \fBTcl_IdleProc\fR: -.CS -typedef void Tcl_IdleProc(ClientData \fIclientData\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR -argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR -points to a data structure containing application-specific information about -what \fIproc\fR should do. -.PP -\fBTcl_CancelIdleCall\fR -may be used to cancel one or more previous -calls to \fBTcl_DoWhenIdle\fR: if there is a \fBTcl_DoWhenIdle\fR -handler registered for \fIproc\fR and \fIclientData\fR, then it -is removed without invoking it. If there is more than one -handler on the idle list that refers to \fIproc\fR and \fIclientData\fR, -all of the handlers are removed. If no existing handlers match -\fIproc\fR and \fIclientData\fR then nothing happens. -.PP -\fBTcl_DoWhenIdle\fR is most useful in situations where -(a) a piece of work will have to be done but (b) it is -possible that something will happen in the near future -that will change what has to be done or require something -different to be done. \fBTcl_DoWhenIdle\fR allows the -actual work to be deferred until all pending events have -been processed. At this point the exact work to be done -will presumably be known and it can be done exactly once. -.PP -For example, \fBTcl_DoWhenIdle\fR might be used by an editor -to defer display updates until all pending commands have -been processed. Without this feature, redundant redisplays -might occur in some situations, such as the processing of -a command file. -.SH BUGS -.PP -At present it is not safe for an idle callback to reschedule itself -continuously. This will interact badly with certain features of Tk -that attempt to wait for all idle callbacks to complete. If you would -like for an idle callback to reschedule itself continuously, it is -better to use a timer handler with a zero timeout period. - -.SH KEYWORDS -callback, defer, idle callback +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.4 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR) +.sp +\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR) +.SH ARGUMENTS +.AS Tcl_IdleProc clientData +.AP Tcl_IdleProc *proc in +Procedure to invoke. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked +when the application becomes idle. The application is +considered to be idle when \fBTcl_DoOneEvent\fR has been +called, could not find any events to handle, and is about +to go to sleep waiting for an event to occur. At this +point all pending \fBTcl_DoWhenIdle\fR handlers are +invoked. For each call to \fBTcl_DoWhenIdle\fR there will +be a single call to \fIproc\fR; after \fIproc\fR is +invoked the handler is automatically removed. +\fBTcl_DoWhenIdle\fR is only usable in programs that +use \fBTcl_DoOneEvent\fR to dispatch events. +.PP +\fIProc\fR should have arguments and result that match the +type \fBTcl_IdleProc\fR: +.CS +typedef void Tcl_IdleProc(ClientData \fIclientData\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR +argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR +points to a data structure containing application-specific information about +what \fIproc\fR should do. +.PP +\fBTcl_CancelIdleCall\fR +may be used to cancel one or more previous +calls to \fBTcl_DoWhenIdle\fR: if there is a \fBTcl_DoWhenIdle\fR +handler registered for \fIproc\fR and \fIclientData\fR, then it +is removed without invoking it. If there is more than one +handler on the idle list that refers to \fIproc\fR and \fIclientData\fR, +all of the handlers are removed. If no existing handlers match +\fIproc\fR and \fIclientData\fR then nothing happens. +.PP +\fBTcl_DoWhenIdle\fR is most useful in situations where +(a) a piece of work will have to be done but (b) it is +possible that something will happen in the near future +that will change what has to be done or require something +different to be done. \fBTcl_DoWhenIdle\fR allows the +actual work to be deferred until all pending events have +been processed. At this point the exact work to be done +will presumably be known and it can be done exactly once. +.PP +For example, \fBTcl_DoWhenIdle\fR might be used by an editor +to defer display updates until all pending commands have +been processed. Without this feature, redundant redisplays +might occur in some situations, such as the processing of +a command file. +.SH BUGS +.PP +At present it is not safe for an idle callback to reschedule itself +continuously. This will interact badly with certain features of Tk +that attempt to wait for all idle callbacks to complete. If you would +like for an idle callback to reschedule itself continuously, it is +better to use a timer handler with a zero timeout period. + +.SH KEYWORDS +callback, defer, idle callback diff --git a/doc/GetCwd.3 b/doc/GetCwd.3 index 48eddf7..59f4195 100755 --- a/doc/GetCwd.3 +++ b/doc/GetCwd.3 @@ -1,54 +1,54 @@ -'\" -'\" Copyright (c) 1998-1999 Scriptics Corporation -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: GetCwd.3,v 1.7 2007/10/28 14:17:38 dkf Exp $ -'\" -.so man.macros -.TH Tcl_GetCwd 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetCwd, Tcl_Chdir \- manipulate the current working directory -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -char * -\fBTcl_GetCwd\fR(\fIinterp\fR, \fIbufferPtr\fR) -.sp -int -\fBTcl_Chdir\fR(\fIpath\fR) -.SH ARGUMENTS -.AS Tcl_DString *bufferPtr in/out -.AP Tcl_Interp *interp in -Interpreter in which to report an error, if any. -.AP Tcl_DString *bufferPtr in/out -This dynamic string is used to store the current working directory. -At the time of the call it should be uninitialized or free. The -caller must eventually call \fBTcl_DStringFree\fR to free up -anything stored here. -.AP char *path in -File path in UTF\-8 format. -.BE - -.SH DESCRIPTION -.PP -These procedures may be used to manipulate the current working -directory for the application. They provide C\-level access to -the same functionality as the Tcl \fBpwd\fR command. -.PP -\fBTcl_GetCwd\fR returns a pointer to a string specifying the current -directory, or NULL if the current directory could not be determined. -If NULL is returned, an error message is left in the \fIinterp\fR's result. -Storage for the result string is allocated in bufferPtr; the caller -must call \fBTcl_DStringFree()\fR when the result is no longer needed. -The format of the path is UTF\-8. -.PP -\fBTcl_Chdir\fR changes the applications current working directory to -the value specified in \fIpath\fR. The format of the passed in string -must be UTF\-8. The function returns -1 on error or 0 on success. - -.SH KEYWORDS -pwd +'\" +'\" Copyright (c) 1998-1999 Scriptics Corporation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: GetCwd.3,v 1.8 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_GetCwd 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_GetCwd, Tcl_Chdir \- manipulate the current working directory +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +char * +\fBTcl_GetCwd\fR(\fIinterp\fR, \fIbufferPtr\fR) +.sp +int +\fBTcl_Chdir\fR(\fIpath\fR) +.SH ARGUMENTS +.AS Tcl_DString *bufferPtr in/out +.AP Tcl_Interp *interp in +Interpreter in which to report an error, if any. +.AP Tcl_DString *bufferPtr in/out +This dynamic string is used to store the current working directory. +At the time of the call it should be uninitialized or free. The +caller must eventually call \fBTcl_DStringFree\fR to free up +anything stored here. +.AP char *path in +File path in UTF\-8 format. +.BE + +.SH DESCRIPTION +.PP +These procedures may be used to manipulate the current working +directory for the application. They provide C\-level access to +the same functionality as the Tcl \fBpwd\fR command. +.PP +\fBTcl_GetCwd\fR returns a pointer to a string specifying the current +directory, or NULL if the current directory could not be determined. +If NULL is returned, an error message is left in the \fIinterp\fR's result. +Storage for the result string is allocated in bufferPtr; the caller +must call \fBTcl_DStringFree()\fR when the result is no longer needed. +The format of the path is UTF\-8. +.PP +\fBTcl_Chdir\fR changes the applications current working directory to +the value specified in \fIpath\fR. The format of the passed in string +must be UTF\-8. The function returns -1 on error or 0 on success. + +.SH KEYWORDS +pwd diff --git a/doc/GetOpnFl.3 b/doc/GetOpnFl.3 index 06023e1..976f6f1 100644 --- a/doc/GetOpnFl.3 +++ b/doc/GetOpnFl.3 @@ -1,59 +1,59 @@ -'\" -'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: GetOpnFl.3,v 1.12 2007/10/28 14:17:39 dkf Exp $ -.so man.macros -.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpreter (Unix only) -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTcl_GetOpenFile\fR(\fIinterp, chanID, write, checkUsage, filePtr\fR) -.sp -.SH ARGUMENTS -.AS Tcl_Interp checkUsage out -.AP Tcl_Interp *interp in -Tcl interpreter from which file handle is to be obtained. -.AP "const char" *chanID in -String identifying channel, such as \fBstdin\fR or \fBfile4\fR. -.AP int write in -Non-zero means the file will be used for writing, zero means it will -be used for reading. -.AP int checkUsage in -If non-zero, then an error will be generated if the file was not opened -for the access indicated by \fIwrite\fR. -.AP ClientData *filePtr out -Points to word in which to store pointer to FILE structure for -the file given by \fIchanID\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_GetOpenFile\fR takes as argument a file identifier of the form -returned by the \fBopen\fR command and -returns at \fI*filePtr\fR a pointer to the FILE structure for -the file. -The \fIwrite\fR argument indicates whether the FILE pointer will -be used for reading or writing. -In some cases, such as a channel that connects to a pipeline of -subprocesses, different FILE pointers will be returned for reading -and writing. -\fBTcl_GetOpenFile\fR normally returns \fBTCL_OK\fR. -If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIchanID\fR did not -make any sense or \fIcheckUsage\fR was set and the file was not opened -for the access specified by \fIwrite\fR) then \fBTCL_ERROR\fR is returned -and the interpreter's result will contain an error message. -In the current implementation \fIcheckUsage\fR is ignored and consistency -checks are always performed. -.PP -Note that this interface is only supported on the Unix platform. - -.SH KEYWORDS -channel, file handle, permissions, pipeline, read, write +'\" +'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: GetOpnFl.3,v 1.13 2007/10/29 17:17:54 dgp Exp $ +.so man.macros +.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpreter (Unix only) +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_GetOpenFile\fR(\fIinterp, chanID, write, checkUsage, filePtr\fR) +.sp +.SH ARGUMENTS +.AS Tcl_Interp checkUsage out +.AP Tcl_Interp *interp in +Tcl interpreter from which file handle is to be obtained. +.AP "const char" *chanID in +String identifying channel, such as \fBstdin\fR or \fBfile4\fR. +.AP int write in +Non-zero means the file will be used for writing, zero means it will +be used for reading. +.AP int checkUsage in +If non-zero, then an error will be generated if the file was not opened +for the access indicated by \fIwrite\fR. +.AP ClientData *filePtr out +Points to word in which to store pointer to FILE structure for +the file given by \fIchanID\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_GetOpenFile\fR takes as argument a file identifier of the form +returned by the \fBopen\fR command and +returns at \fI*filePtr\fR a pointer to the FILE structure for +the file. +The \fIwrite\fR argument indicates whether the FILE pointer will +be used for reading or writing. +In some cases, such as a channel that connects to a pipeline of +subprocesses, different FILE pointers will be returned for reading +and writing. +\fBTcl_GetOpenFile\fR normally returns \fBTCL_OK\fR. +If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIchanID\fR did not +make any sense or \fIcheckUsage\fR was set and the file was not opened +for the access specified by \fIwrite\fR) then \fBTCL_ERROR\fR is returned +and the interpreter's result will contain an error message. +In the current implementation \fIcheckUsage\fR is ignored and consistency +checks are always performed. +.PP +Note that this interface is only supported on the Unix platform. + +.SH KEYWORDS +channel, file handle, permissions, pipeline, read, write diff --git a/doc/Init.3 b/doc/Init.3 index 5f6395c..59640e8 100644 --- a/doc/Init.3 +++ b/doc/Init.3 @@ -1,36 +1,36 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id: Init.3,v 1.4 2007/10/28 14:17:39 dkf Exp $ -'\" -.so man.macros -.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Init \- find and source initialization script -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTcl_Init\fR(\fIinterp\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Interpreter to initialize. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fRs the -\fBinit.tcl\fR script, which should exist somewhere on the Tcl library -path. -.PP -\fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures. - -.SH "SEE ALSO" -Tcl_AppInit, Tcl_Main - -.SH KEYWORDS -application, initialization, interpreter +'\" +'\" Copyright (c) 1998-2000 by Scriptics Corporation. +'\" All rights reserved. +'\" +'\" RCS: @(#) $Id: Init.3,v 1.5 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_Init \- find and source initialization script +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_Init\fR(\fIinterp\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp +.AP Tcl_Interp *interp in +Interpreter to initialize. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fRs the +\fBinit.tcl\fR script, which should exist somewhere on the Tcl library +path. +.PP +\fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures. + +.SH "SEE ALSO" +Tcl_AppInit, Tcl_Main + +.SH KEYWORDS +application, initialization, interpreter diff --git a/doc/Interp.3 b/doc/Interp.3 index 9ee66f9..2b7d48a 100644 --- a/doc/Interp.3 +++ b/doc/Interp.3 @@ -1,125 +1,125 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Interp.3,v 1.10 2007/10/28 14:17:39 dkf Exp $ -'\" -.so man.macros -.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Interp \- client-visible fields of interpreter structures -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -typedef struct { - char *\fIresult\fR; - Tcl_FreeProc *\fIfreeProc\fR; - int \fIerrorLine\fR; -} Tcl_Interp; - -typedef void Tcl_FreeProc(char *\fIblockPtr\fR); -.BE - -.SH DESCRIPTION -.PP -The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp -structure. This pointer is then passed into other Tcl procedures -to process commands in the interpreter and perform other operations -on the interpreter. Interpreter structures contain many fields -that are used by Tcl, but only three that may be accessed by -clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR. -.PP -\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR -\fBdeprecated.\fR Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead. -.PP -The \fIresult\fR and \fIfreeProc\fR fields are used to return -results or error messages from commands. -This information is returned by command procedures back to \fBTcl_Eval\fR, -and by \fBTcl_Eval\fR back to its callers. -The \fIresult\fR field points to the string that represents the -result or error message, and the \fIfreeProc\fR field tells how -to dispose of the storage for the string when it is not needed anymore. -The easiest way for command procedures to manipulate these -fields is to call procedures like \fBTcl_SetResult\fR -or \fBTcl_AppendResult\fR; they -will hide all the details of managing the fields. -The description below is for those procedures that manipulate the -fields directly. -.PP -Whenever a command procedure returns, it must ensure -that the \fIresult\fR field of its interpreter points to the string -being returned by the command. -The \fIresult\fR field must always point to a valid string. -If a command wishes to return no result then \fIinterp->result\fR -should point to an empty string. -Normally, results are assumed to be statically allocated, -which means that the contents will not change before the next time -\fBTcl_Eval\fR is called or some other command procedure is invoked. -In this case, the \fIfreeProc\fR field must be zero. -Alternatively, a command procedure may dynamically -allocate its return value (e.g. using \fBTcl_Alloc\fR) -and store a pointer to it in \fIinterp->result\fR. -In this case, the command procedure must also set \fIinterp->freeProc\fR -to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR -if the storage was allocated directly by Tcl or by a call to -\fBTcl_Alloc\fR. -If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR -to free the space pointed to by \fIinterp->result\fR before it -invokes the next command. -If a client procedure overwrites \fIinterp->result\fR when -\fIinterp->freeProc\fR is non-zero, then it is responsible for calling -\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR -macro should be used for this purpose). -.PP -\fIFreeProc\fR should have arguments and result that match the -\fBTcl_FreeProc\fR declaration above: it receives a single -argument which is a pointer to the result value to free. -In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever -used for \fIfreeProc\fR. -However, an application may store a different procedure address -in \fIfreeProc\fR in order to use an alternate memory allocator -or in order to do other cleanup when the result memory is freed. -.PP -As part of processing each command, \fBTcl_Eval\fR initializes -\fIinterp->result\fR -and \fIinterp->freeProc\fR just before calling the command procedure for -the command. The \fIfreeProc\fR field will be initialized to zero, -and \fIinterp->result\fR will point to an empty string. Commands that -do not return any value can simply leave the fields alone. -Furthermore, the empty string pointed to by \fIresult\fR is actually -part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200). -If a command wishes to return a short string, it can simply copy -it to the area pointed to by \fIinterp->result\fR. Or, it can use -the sprintf procedure to generate a short result string at the location -pointed to by \fIinterp->result\fR. -.PP -It is a general convention in Tcl-based applications that the result -of an interpreter is normally in the initialized state described -in the previous paragraph. -Procedures that manipulate an interpreter's result (e.g. by -returning an error) will generally assume that the result -has been initialized when the procedure is called. -If such a procedure is to be called after the result has been -changed, then \fBTcl_ResetResult\fR should be called first to -reset the result to its initialized state. The direct use of -\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR). -.PP -The \fIerrorLine\fR -field is valid only after \fBTcl_Eval\fR returns -a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR -field identifies the line number of the command being executed when -the error occurred. The line numbers are relative to the command -being executed: 1 means the first line of the command passed to -\fBTcl_Eval\fR, 2 means the second line, and so on. -The \fIerrorLine\fR field is typically used in conjunction with -\fBTcl_AddErrorInfo\fR to report information about where an error -occurred. -\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR. - -.SH KEYWORDS -free, initialized, interpreter, malloc, result +'\" +'\" Copyright (c) 1989-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: Interp.3,v 1.11 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_Interp \- client-visible fields of interpreter structures +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +typedef struct { + char *\fIresult\fR; + Tcl_FreeProc *\fIfreeProc\fR; + int \fIerrorLine\fR; +} Tcl_Interp; + +typedef void Tcl_FreeProc(char *\fIblockPtr\fR); +.BE + +.SH DESCRIPTION +.PP +The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp +structure. This pointer is then passed into other Tcl procedures +to process commands in the interpreter and perform other operations +on the interpreter. Interpreter structures contain many fields +that are used by Tcl, but only three that may be accessed by +clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR. +.PP +\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR +\fBdeprecated.\fR Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead. +.PP +The \fIresult\fR and \fIfreeProc\fR fields are used to return +results or error messages from commands. +This information is returned by command procedures back to \fBTcl_Eval\fR, +and by \fBTcl_Eval\fR back to its callers. +The \fIresult\fR field points to the string that represents the +result or error message, and the \fIfreeProc\fR field tells how +to dispose of the storage for the string when it is not needed anymore. +The easiest way for command procedures to manipulate these +fields is to call procedures like \fBTcl_SetResult\fR +or \fBTcl_AppendResult\fR; they +will hide all the details of managing the fields. +The description below is for those procedures that manipulate the +fields directly. +.PP +Whenever a command procedure returns, it must ensure +that the \fIresult\fR field of its interpreter points to the string +being returned by the command. +The \fIresult\fR field must always point to a valid string. +If a command wishes to return no result then \fIinterp->result\fR +should point to an empty string. +Normally, results are assumed to be statically allocated, +which means that the contents will not change before the next time +\fBTcl_Eval\fR is called or some other command procedure is invoked. +In this case, the \fIfreeProc\fR field must be zero. +Alternatively, a command procedure may dynamically +allocate its return value (e.g. using \fBTcl_Alloc\fR) +and store a pointer to it in \fIinterp->result\fR. +In this case, the command procedure must also set \fIinterp->freeProc\fR +to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR +if the storage was allocated directly by Tcl or by a call to +\fBTcl_Alloc\fR. +If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR +to free the space pointed to by \fIinterp->result\fR before it +invokes the next command. +If a client procedure overwrites \fIinterp->result\fR when +\fIinterp->freeProc\fR is non-zero, then it is responsible for calling +\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR +macro should be used for this purpose). +.PP +\fIFreeProc\fR should have arguments and result that match the +\fBTcl_FreeProc\fR declaration above: it receives a single +argument which is a pointer to the result value to free. +In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever +used for \fIfreeProc\fR. +However, an application may store a different procedure address +in \fIfreeProc\fR in order to use an alternate memory allocator +or in order to do other cleanup when the result memory is freed. +.PP +As part of processing each command, \fBTcl_Eval\fR initializes +\fIinterp->result\fR +and \fIinterp->freeProc\fR just before calling the command procedure for +the command. The \fIfreeProc\fR field will be initialized to zero, +and \fIinterp->result\fR will point to an empty string. Commands that +do not return any value can simply leave the fields alone. +Furthermore, the empty string pointed to by \fIresult\fR is actually +part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200). +If a command wishes to return a short string, it can simply copy +it to the area pointed to by \fIinterp->result\fR. Or, it can use +the sprintf procedure to generate a short result string at the location +pointed to by \fIinterp->result\fR. +.PP +It is a general convention in Tcl-based applications that the result +of an interpreter is normally in the initialized state described +in the previous paragraph. +Procedures that manipulate an interpreter's result (e.g. by +returning an error) will generally assume that the result +has been initialized when the procedure is called. +If such a procedure is to be called after the result has been +changed, then \fBTcl_ResetResult\fR should be called first to +reset the result to its initialized state. The direct use of +\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR). +.PP +The \fIerrorLine\fR +field is valid only after \fBTcl_Eval\fR returns +a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR +field identifies the line number of the command being executed when +the error occurred. The line numbers are relative to the command +being executed: 1 means the first line of the command passed to +\fBTcl_Eval\fR, 2 means the second line, and so on. +The \fIerrorLine\fR field is typically used in conjunction with +\fBTcl_AddErrorInfo\fR to report information about where an error +occurred. +\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR. + +.SH KEYWORDS +free, initialized, interpreter, malloc, result diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3 index 05bd6da..a1af593 100644 --- a/doc/RecEvalObj.3 +++ b/doc/RecEvalObj.3 @@ -1,55 +1,55 @@ -'\" -'\" Copyright (c) 1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: RecEvalObj.3,v 1.6 2007/10/28 14:17:39 dkf Exp $ -'\" -.so man.macros -.TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_RecordAndEvalObj \- save command on history list before evaluating -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTcl_RecordAndEvalObj\fR(\fIinterp, cmdPtr, flags\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Tcl interpreter in which to evaluate command. -.AP Tcl_Obj *cmdPtr in -Points to a Tcl object containing a command (or sequence of commands) -to execute. -.AP int flags in -An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the -command but do not evaluate it. \fBTCL_EVAL_GLOBAL\fR means evaluate -the command at global level instead of the current stack level. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event -on the history list and then execute it using \fBTcl_EvalObjEx\fR -(or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set -in \fIflags\fR). -It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR, -as well as a result object containing additional information -(a result value or error message) -that can be retrieved using \fBTcl_GetObjResult\fR. -If you do not want the command recorded on the history list then -you should invoke \fBTcl_EvalObjEx\fR instead of \fBTcl_RecordAndEvalObj\fR. -Normally \fBTcl_RecordAndEvalObj\fR is only called with top-level -commands typed by the user, since the purpose of history is to -allow the user to re-issue recently invoked commands. -If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then -the command is recorded without being evaluated. - -.SH "SEE ALSO" -Tcl_EvalObjEx, Tcl_GetObjResult - -.SH KEYWORDS -command, event, execute, history, interpreter, object, record +'\" +'\" Copyright (c) 1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: RecEvalObj.3,v 1.7 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_RecordAndEvalObj \- save command on history list before evaluating +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_RecordAndEvalObj\fR(\fIinterp, cmdPtr, flags\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp +.AP Tcl_Interp *interp in +Tcl interpreter in which to evaluate command. +.AP Tcl_Obj *cmdPtr in +Points to a Tcl object containing a command (or sequence of commands) +to execute. +.AP int flags in +An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the +command but do not evaluate it. \fBTCL_EVAL_GLOBAL\fR means evaluate +the command at global level instead of the current stack level. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event +on the history list and then execute it using \fBTcl_EvalObjEx\fR +(or \fBTcl_GlobalEvalObj\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set +in \fIflags\fR). +It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR, +as well as a result object containing additional information +(a result value or error message) +that can be retrieved using \fBTcl_GetObjResult\fR. +If you do not want the command recorded on the history list then +you should invoke \fBTcl_EvalObjEx\fR instead of \fBTcl_RecordAndEvalObj\fR. +Normally \fBTcl_RecordAndEvalObj\fR is only called with top-level +commands typed by the user, since the purpose of history is to +allow the user to re-issue recently invoked commands. +If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then +the command is recorded without being evaluated. + +.SH "SEE ALSO" +Tcl_EvalObjEx, Tcl_GetObjResult + +.SH KEYWORDS +command, event, execute, history, interpreter, object, record diff --git a/doc/RecordEval.3 b/doc/RecordEval.3 index afea09d..1eae01e 100644 --- a/doc/RecordEval.3 +++ b/doc/RecordEval.3 @@ -1,57 +1,57 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: RecordEval.3,v 1.8 2007/10/28 14:17:39 dkf Exp $ -'\" -.so man.macros -.TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_RecordAndEval \- save command on history list before evaluating -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTcl_RecordAndEval\fR(\fIinterp, cmd, flags\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Tcl interpreter in which to evaluate command. -.AP "const char" *cmd in -Command (or sequence of commands) to execute. -.AP int flags in -An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the -command but do not evaluate it. \fBTCL_EVAL_GLOBAL\fR means evaluate -the command at global level instead of the current stack level. -.BE - -.SH DESCRIPTION -.PP -\fBTcl_RecordAndEval\fR is invoked to record a command as an event -on the history list and then execute it using \fBTcl_Eval\fR -(or \fBTcl_GlobalEval\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set in \fIflags\fR). -It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_Eval\fR -and it leaves information in the interpreter's result. -If you do not want the command recorded on the history list then -you should invoke \fBTcl_Eval\fR instead of \fBTcl_RecordAndEval\fR. -Normally \fBTcl_RecordAndEval\fR is only called with top-level -commands typed by the user, since the purpose of history is to -allow the user to re-issue recently-invoked commands. -If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then -the command is recorded without being evaluated. -.PP -Note that \fBTcl_RecordAndEval\fR has been largely replaced by the -object-based procedure \fBTcl_RecordAndEvalObj\fR. -That object-based procedure records and optionally executes -a command held in a Tcl object instead of a string. - -.SH "SEE ALSO" -Tcl_RecordAndEvalObj - -.SH KEYWORDS -command, event, execute, history, interpreter, record +'\" +'\" Copyright (c) 1989-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: RecordEval.3,v 1.9 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_RecordAndEval \- save command on history list before evaluating +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +int +\fBTcl_RecordAndEval\fR(\fIinterp, cmd, flags\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp +.AP Tcl_Interp *interp in +Tcl interpreter in which to evaluate command. +.AP "const char" *cmd in +Command (or sequence of commands) to execute. +.AP int flags in +An OR'ed combination of flag bits. \fBTCL_NO_EVAL\fR means record the +command but do not evaluate it. \fBTCL_EVAL_GLOBAL\fR means evaluate +the command at global level instead of the current stack level. +.BE + +.SH DESCRIPTION +.PP +\fBTcl_RecordAndEval\fR is invoked to record a command as an event +on the history list and then execute it using \fBTcl_Eval\fR +(or \fBTcl_GlobalEval\fR if the \fBTCL_EVAL_GLOBAL\fR bit is set in \fIflags\fR). +It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_Eval\fR +and it leaves information in the interpreter's result. +If you do not want the command recorded on the history list then +you should invoke \fBTcl_Eval\fR instead of \fBTcl_RecordAndEval\fR. +Normally \fBTcl_RecordAndEval\fR is only called with top-level +commands typed by the user, since the purpose of history is to +allow the user to re-issue recently-invoked commands. +If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then +the command is recorded without being evaluated. +.PP +Note that \fBTcl_RecordAndEval\fR has been largely replaced by the +object-based procedure \fBTcl_RecordAndEvalObj\fR. +That object-based procedure records and optionally executes +a command held in a Tcl object instead of a string. + +.SH "SEE ALSO" +Tcl_RecordAndEvalObj + +.SH KEYWORDS +command, event, execute, history, interpreter, record diff --git a/doc/Sleep.3 b/doc/Sleep.3 index ab650be..579d5a2 100644 --- a/doc/Sleep.3 +++ b/doc/Sleep.3 @@ -1,36 +1,36 @@ -'\" -'\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Sleep.3,v 1.4 2007/10/28 14:17:39 dkf Exp $ -'\" -.so man.macros -.TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_Sleep \- delay execution for a given number of milliseconds -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTcl_Sleep\fR(\fIms\fR) -.SH ARGUMENTS -.AS int ms -.AP int ms in -Number of milliseconds to sleep. -.BE -.SH DESCRIPTION -.PP -This procedure delays the calling process by the number of -milliseconds given by the \fIms\fR parameter and returns -after that time has elapsed. It is typically used for things -like flashing a button, where the delay is short and the -application need not do anything while it waits. For longer -delays where the application needs to respond to other events -during the delay, the procedure \fBTcl_CreateTimerHandler\fR -should be used instead of \fBTcl_Sleep\fR. -.SH KEYWORDS -sleep, time, wait +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: Sleep.3,v 1.5 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_Sleep \- delay execution for a given number of milliseconds +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +\fBTcl_Sleep\fR(\fIms\fR) +.SH ARGUMENTS +.AS int ms +.AP int ms in +Number of milliseconds to sleep. +.BE +.SH DESCRIPTION +.PP +This procedure delays the calling process by the number of +milliseconds given by the \fIms\fR parameter and returns +after that time has elapsed. It is typically used for things +like flashing a button, where the delay is short and the +application need not do anything while it waits. For longer +delays where the application needs to respond to other events +during the delay, the procedure \fBTcl_CreateTimerHandler\fR +should be used instead of \fBTcl_Sleep\fR. +.SH KEYWORDS +sleep, time, wait diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 index 49d9f52..e160949 100644 --- a/doc/StaticPkg.3 +++ b/doc/StaticPkg.3 @@ -1,69 +1,69 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: StaticPkg.3,v 1.7 2007/10/28 14:17:39 dkf Exp $ -'\" -.so man.macros -.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_StaticPackage \- make a statically linked package available via the 'load' command -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTcl_StaticPackage\fR(\fIinterp, pkgName, initProc, safeInitProc\fR) -.SH ARGUMENTS -.AS Tcl_PackageInitProc *safeInitProc -.AP Tcl_Interp *interp in -If not NULL, points to an interpreter into which the package has -already been loaded (i.e., the caller has already invoked the -appropriate initialization procedure). NULL means the package -has not yet been incorporated into any interpreter. -.AP "const char" *pkgName in -Name of the package; should be properly capitalized (first letter -upper-case, all others lower-case). -.AP Tcl_PackageInitProc *initProc in -Procedure to invoke to incorporate this package into a trusted -interpreter. -.AP Tcl_PackageInitProc *safeInitProc in -Procedure to call to incorporate this package into a safe interpreter -(one that will execute untrusted scripts). NULL means the package -cannot be used in safe interpreters. -.BE - -.SH DESCRIPTION -.PP -This procedure may be invoked to announce that a package has been -linked statically with a Tcl application and, optionally, that it -has already been loaded into an interpreter. -Once \fBTcl_StaticPackage\fR has been invoked for a package, it -may be loaded into interpreters using the \fBload\fR command. -\fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR -procedure for the application, not by packages for themselves -(\fBTcl_StaticPackage\fR should only be invoked for statically -loaded packages, and code in the package itself should not need -to know whether the package is dynamically or statically loaded). -.PP -When the \fBload\fR command is used later to load the package into -an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will -be invoked, depending on whether the target interpreter is safe -or not. -\fIinitProc\fR and \fIsafeInitProc\fR must both match the -following prototype: -.CS -typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); -.CE -The \fIinterp\fR argument identifies the interpreter in which the package -is to be loaded. The initialization procedure must return \fBTCL_OK\fR or -\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in -the event of an error it should set the interpreter's result to point to an -error message. The result or error from the initialization procedure will -be returned as the result of the \fBload\fR command that caused the -initialization procedure to be invoked. - -.SH KEYWORDS -initialization procedure, package, static linking +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: StaticPkg.3,v 1.8 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_StaticPackage \- make a statically linked package available via the 'load' command +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +\fBTcl_StaticPackage\fR(\fIinterp, pkgName, initProc, safeInitProc\fR) +.SH ARGUMENTS +.AS Tcl_PackageInitProc *safeInitProc +.AP Tcl_Interp *interp in +If not NULL, points to an interpreter into which the package has +already been loaded (i.e., the caller has already invoked the +appropriate initialization procedure). NULL means the package +has not yet been incorporated into any interpreter. +.AP "const char" *pkgName in +Name of the package; should be properly capitalized (first letter +upper-case, all others lower-case). +.AP Tcl_PackageInitProc *initProc in +Procedure to invoke to incorporate this package into a trusted +interpreter. +.AP Tcl_PackageInitProc *safeInitProc in +Procedure to call to incorporate this package into a safe interpreter +(one that will execute untrusted scripts). NULL means the package +cannot be used in safe interpreters. +.BE + +.SH DESCRIPTION +.PP +This procedure may be invoked to announce that a package has been +linked statically with a Tcl application and, optionally, that it +has already been loaded into an interpreter. +Once \fBTcl_StaticPackage\fR has been invoked for a package, it +may be loaded into interpreters using the \fBload\fR command. +\fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR +procedure for the application, not by packages for themselves +(\fBTcl_StaticPackage\fR should only be invoked for statically +loaded packages, and code in the package itself should not need +to know whether the package is dynamically or statically loaded). +.PP +When the \fBload\fR command is used later to load the package into +an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will +be invoked, depending on whether the target interpreter is safe +or not. +\fIinitProc\fR and \fIsafeInitProc\fR must both match the +following prototype: +.CS +typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR); +.CE +The \fIinterp\fR argument identifies the interpreter in which the package +is to be loaded. The initialization procedure must return \fBTCL_OK\fR or +\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in +the event of an error it should set the interpreter's result to point to an +error message. The result or error from the initialization procedure will +be returned as the result of the \fBload\fR command that caused the +initialization procedure to be invoked. + +.SH KEYWORDS +initialization procedure, package, static linking diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 78b801e..8b80b2a 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -1,272 +1,272 @@ -'\" -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: StringObj.3,v 1.21 2007/10/28 14:17:39 dkf Exp $ -'\" -.so man.macros -.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tcl_Obj * -\fBTcl_NewStringObj\fR(\fIbytes, length\fR) -.sp -Tcl_Obj * -\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR) -.sp -void -\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR) -.sp -void -\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR) -.sp -char * -\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR) -.sp -char * -\fBTcl_GetString\fR(\fIobjPtr\fR) -.sp -Tcl_UniChar * -\fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR) -.sp -Tcl_UniChar * -\fBTcl_GetUnicode\fR(\fIobjPtr\fR) -.sp -Tcl_UniChar -\fBTcl_GetUniChar\fR(\fIobjPtr, index\fR) -.sp -int -\fBTcl_GetCharLength\fR(\fIobjPtr\fR) -.sp -Tcl_Obj * -\fBTcl_GetRange\fR(\fIobjPtr, first, last\fR) -.sp -void -\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR) -.sp -void -\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR) -.sp -void -\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR) -.sp -void -\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR) -.sp -void -\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) -.sp -void -\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) -.sp -int -\fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR) -.sp -Tcl_Obj * -\fBTcl_ConcatObj\fR(\fIobjc, objv\fR) -.SH ARGUMENTS -.AS "const Tcl_UniChar" *appendObjPtr in/out -.AP "const char" *bytes in -Points to the first byte of an array of UTF-8-encoded bytes -used to set or append to a string object. -This byte array may contain embedded null characters -unless \fInumChars\fR is negative. (Applications needing null bytes -should represent them as the two-byte sequence \fI\e700\e600\fR, use -\fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if -the string is a collection of uninterpreted bytes.) -.AP int length in -The number of bytes to copy from \fIbytes\fR when -initializing, setting, or appending to a string object. -If negative, all bytes up to the first null are used. -.AP "const Tcl_UniChar" *unicode in -Points to the first byte of an array of Unicode characters -used to set or append to a string object. -This byte array may contain embedded null characters -unless \fInumChars\fR is negative. -.AP int numChars in -The number of Unicode characters to copy from \fIunicode\fR when -initializing, setting, or appending to a string object. -If negative, all characters up to the first null character are used. -.AP int index in -The index of the Unicode character to return. -.AP int first in -The index of the first Unicode character in the Unicode range to be -returned as a new object. -.AP int last in -The index of the last Unicode character in the Unicode range to be -returned as a new object. -.AP Tcl_Obj *objPtr in/out -Points to an object to manipulate. -.AP Tcl_Obj *appendObjPtr in -The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. -.AP int *lengthPtr out -If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store -the length of an object's string representation. -.AP "const char" *string in -Null-terminated string value to append to \fIobjPtr\fR. -.AP va_list argList in -An argument list which must have been initialised using -\fBva_start\fR, and cleared using \fBva_end\fR. -.AP int newLength in -New length for the string value of \fIobjPtr\fR, not including the -final null character. -.AP int objc in -The number of elements to concatenate. -.AP Tcl_Obj *objv[] in -The array of objects to concatenate. -.BE - -.SH DESCRIPTION -.PP -The procedures described in this manual entry allow Tcl objects to -be manipulated as string values. They use the internal representation -of the object to store additional information to make the string -manipulations more efficient. In particular, they make a series of -append operations efficient by allocating extra storage space for the -string so that it does not have to be copied for each append. -Also, indexing and length computations are optimized because the -Unicode string representation is calculated and cached as needed. -When using the \fBTcl_Append*\fR family of functions where the -interpreter's result is the object being appended to, it is important -to call Tcl_ResetResult first to ensure you are not unintentionally -appending to existing data in the result object. -.PP -\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object -or modify an existing object to hold a copy of the string given by -\fIbytes\fR and \fIlength\fR. \fBTcl_NewUnicodeObj\fR and -\fBTcl_SetUnicodeObj\fR create a new object or modify an existing -object to hold a copy of the Unicode string given by \fIunicode\fR and -\fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR -return a pointer to a newly created object with reference count zero. -All four procedures set the object to hold a copy of the specified -string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any -old string representation as well as any old internal representation -of the object. -.PP -\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's -string representation. This is given by the returned byte pointer and -(for \fBTcl_GetStringFromObj\fR) length, which is stored in -\fIlengthPtr\fR if it is non-NULL. If the object's UTF string -representation is invalid (its byte pointer is NULL), the string -representation is regenerated from the object's internal -representation. The storage referenced by the returned byte pointer -is owned by the object manager. It is passed back as a writable -pointer so that extension author creating their own \fBTcl_ObjType\fR -will be able to modify the string representation within the -\fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that -limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR -or \fBTcl_GetString\fR should be treated as read-only. It is -recommended that this pointer be assigned to a (const char *) variable. -Even in the limited situations where writing to this pointer is -acceptable, one should take care to respect the copy-on-write -semantics required by \fBTcl_Obj\fR's, with appropriate calls -to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any -in-place modification of the string representation. -The procedure \fBTcl_GetString\fR is used in the common case -where the caller does not need the length of the string -representation. -.PP -\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's -value as a Unicode string. This is given by the returned pointer and -(for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in -\fIlengthPtr\fR if it is non-NULL. The storage referenced by the returned -byte pointer is owned by the object manager and should not be modified by -the caller. The procedure \fBTcl_GetUnicode\fR is used in the common case -where the caller does not need the length of the unicode string -representation. -.PP -\fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the -object's Unicode representation. -.PP -\fBTcl_GetRange\fR returns a newly created object comprised of the -characters between \fIfirst\fR and \fIlast\fR (inclusive) in the -object's Unicode representation. If the object's Unicode -representation is invalid, the Unicode representation is regenerated -from the object's string representation. -.PP -\fBTcl_GetCharLength\fR returns the number of characters (as opposed -to bytes) in the string object. -.PP -\fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and -\fIlength\fR to the string representation of the object specified by -\fIobjPtr\fR. If the object has an invalid string representation, -then an attempt is made to convert \fIbytes\fR is to the Unicode -format. If the conversion is successful, then the converted form of -\fIbytes\fR is appended to the object's Unicode representation. -Otherwise, the object's Unicode representation is invalidated and -converted to the UTF format, and \fIbytes\fR is appended to the -object's new string representation. -.PP -\fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by -\fIunicode\fR and \fInumChars\fR to the object specified by -\fIobjPtr\fR. If the object has an invalid Unicode representation, -then \fIunicode\fR is converted to the UTF format and appended to the -object's string representation. Appends are optimized to handle -repeated appends relatively efficiently (it overallocates the string -or Unicode space to avoid repeated reallocations and copies of -object's string value). -.PP -\fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it -appends the string or Unicode value (whichever exists and is best -suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to -\fIobjPtr\fR. -.PP -\fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR -except that it can be passed more than one value to append and -each value must be a null-terminated string (i.e. none of the -values may contain internal null characters). Any number of -\fIstring\fR arguments may be provided, but the last argument -must be a NULL pointer to indicate the end of the list. -.PP -\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR -except that instead of taking a variable number of arguments it takes an -argument list. -.PP -The \fBTcl_SetObjLength\fR procedure changes the length of the -string value of its \fIobjPtr\fR argument. If the \fInewLength\fR -argument is greater than the space allocated for the object's -string, then the string space is reallocated and the old value -is copied to the new space; the bytes between the old length of -the string and the new length may have arbitrary values. -If the \fInewLength\fR argument is less than the current length -of the object's string, with \fIobjPtr->length\fR is reduced without -reallocating the string space; the original allocated size for the -string is recorded in the object, so that the string length can be -enlarged in a subsequent call to \fBTcl_SetObjLength\fR without -reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves -a null character at \fIobjPtr->bytes[newLength]\fR. -.PP -\fBTcl_AttemptSetObjLength\fR is identical in function to -\fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the -request cannot be allocated, it does not cause the Tcl interpreter to -\fBpanic\fR. Thus, if \fInewLength\fR is greater than the space -allocated for the object's string, and there is not enough memory -available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take -no action and return 0 to indicate failure. If there is enough memory -to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like -\fBTcl_SetObjLength\fR and returns 1 to indicate success. -.PP -The \fBTcl_ConcatObj\fR function returns a new string object whose -value is the space-separated concatenation of the string -representations of all of the objects in the \fIobjv\fR -array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space -as it copies the string representations of the \fIobjv\fR array to the -result. If an element of the \fIobjv\fR array consists of nothing but -white space, then that object is ignored entirely. This white-space -removal was added to make the output of the \fBconcat\fR command -cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a -newly-created object whose ref count is zero. - -.SH "SEE ALSO" -Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount - -.SH KEYWORDS -append, internal representation, object, object type, string object, -string type, string representation, concat, concatenate, unicode +'\" +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: StringObj.3,v 1.22 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +Tcl_Obj * +\fBTcl_NewStringObj\fR(\fIbytes, length\fR) +.sp +Tcl_Obj * +\fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR) +.sp +void +\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR) +.sp +void +\fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR) +.sp +char * +\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR) +.sp +char * +\fBTcl_GetString\fR(\fIobjPtr\fR) +.sp +Tcl_UniChar * +\fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR) +.sp +Tcl_UniChar * +\fBTcl_GetUnicode\fR(\fIobjPtr\fR) +.sp +Tcl_UniChar +\fBTcl_GetUniChar\fR(\fIobjPtr, index\fR) +.sp +int +\fBTcl_GetCharLength\fR(\fIobjPtr\fR) +.sp +Tcl_Obj * +\fBTcl_GetRange\fR(\fIobjPtr, first, last\fR) +.sp +void +\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR) +.sp +void +\fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR) +.sp +void +\fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR) +.sp +void +\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR) +.sp +void +\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) +.sp +void +\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) +.sp +int +\fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR) +.sp +Tcl_Obj * +\fBTcl_ConcatObj\fR(\fIobjc, objv\fR) +.SH ARGUMENTS +.AS "const Tcl_UniChar" *appendObjPtr in/out +.AP "const char" *bytes in +Points to the first byte of an array of UTF-8-encoded bytes +used to set or append to a string object. +This byte array may contain embedded null characters +unless \fInumChars\fR is negative. (Applications needing null bytes +should represent them as the two-byte sequence \fI\e700\e600\fR, use +\fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if +the string is a collection of uninterpreted bytes.) +.AP int length in +The number of bytes to copy from \fIbytes\fR when +initializing, setting, or appending to a string object. +If negative, all bytes up to the first null are used. +.AP "const Tcl_UniChar" *unicode in +Points to the first byte of an array of Unicode characters +used to set or append to a string object. +This byte array may contain embedded null characters +unless \fInumChars\fR is negative. +.AP int numChars in +The number of Unicode characters to copy from \fIunicode\fR when +initializing, setting, or appending to a string object. +If negative, all characters up to the first null character are used. +.AP int index in +The index of the Unicode character to return. +.AP int first in +The index of the first Unicode character in the Unicode range to be +returned as a new object. +.AP int last in +The index of the last Unicode character in the Unicode range to be +returned as a new object. +.AP Tcl_Obj *objPtr in/out +Points to an object to manipulate. +.AP Tcl_Obj *appendObjPtr in +The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. +.AP int *lengthPtr out +If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store +the length of an object's string representation. +.AP "const char" *string in +Null-terminated string value to append to \fIobjPtr\fR. +.AP va_list argList in +An argument list which must have been initialised using +\fBva_start\fR, and cleared using \fBva_end\fR. +.AP int newLength in +New length for the string value of \fIobjPtr\fR, not including the +final null character. +.AP int objc in +The number of elements to concatenate. +.AP Tcl_Obj *objv[] in +The array of objects to concatenate. +.BE + +.SH DESCRIPTION +.PP +The procedures described in this manual entry allow Tcl objects to +be manipulated as string values. They use the internal representation +of the object to store additional information to make the string +manipulations more efficient. In particular, they make a series of +append operations efficient by allocating extra storage space for the +string so that it does not have to be copied for each append. +Also, indexing and length computations are optimized because the +Unicode string representation is calculated and cached as needed. +When using the \fBTcl_Append*\fR family of functions where the +interpreter's result is the object being appended to, it is important +to call Tcl_ResetResult first to ensure you are not unintentionally +appending to existing data in the result object. +.PP +\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object +or modify an existing object to hold a copy of the string given by +\fIbytes\fR and \fIlength\fR. \fBTcl_NewUnicodeObj\fR and +\fBTcl_SetUnicodeObj\fR create a new object or modify an existing +object to hold a copy of the Unicode string given by \fIunicode\fR and +\fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR +return a pointer to a newly created object with reference count zero. +All four procedures set the object to hold a copy of the specified +string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any +old string representation as well as any old internal representation +of the object. +.PP +\fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's +string representation. This is given by the returned byte pointer and +(for \fBTcl_GetStringFromObj\fR) length, which is stored in +\fIlengthPtr\fR if it is non-NULL. If the object's UTF string +representation is invalid (its byte pointer is NULL), the string +representation is regenerated from the object's internal +representation. The storage referenced by the returned byte pointer +is owned by the object manager. It is passed back as a writable +pointer so that extension author creating their own \fBTcl_ObjType\fR +will be able to modify the string representation within the +\fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that +limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR +or \fBTcl_GetString\fR should be treated as read-only. It is +recommended that this pointer be assigned to a (const char *) variable. +Even in the limited situations where writing to this pointer is +acceptable, one should take care to respect the copy-on-write +semantics required by \fBTcl_Obj\fR's, with appropriate calls +to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any +in-place modification of the string representation. +The procedure \fBTcl_GetString\fR is used in the common case +where the caller does not need the length of the string +representation. +.PP +\fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's +value as a Unicode string. This is given by the returned pointer and +(for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in +\fIlengthPtr\fR if it is non-NULL. The storage referenced by the returned +byte pointer is owned by the object manager and should not be modified by +the caller. The procedure \fBTcl_GetUnicode\fR is used in the common case +where the caller does not need the length of the unicode string +representation. +.PP +\fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the +object's Unicode representation. +.PP +\fBTcl_GetRange\fR returns a newly created object comprised of the +characters between \fIfirst\fR and \fIlast\fR (inclusive) in the +object's Unicode representation. If the object's Unicode +representation is invalid, the Unicode representation is regenerated +from the object's string representation. +.PP +\fBTcl_GetCharLength\fR returns the number of characters (as opposed +to bytes) in the string object. +.PP +\fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and +\fIlength\fR to the string representation of the object specified by +\fIobjPtr\fR. If the object has an invalid string representation, +then an attempt is made to convert \fIbytes\fR is to the Unicode +format. If the conversion is successful, then the converted form of +\fIbytes\fR is appended to the object's Unicode representation. +Otherwise, the object's Unicode representation is invalidated and +converted to the UTF format, and \fIbytes\fR is appended to the +object's new string representation. +.PP +\fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by +\fIunicode\fR and \fInumChars\fR to the object specified by +\fIobjPtr\fR. If the object has an invalid Unicode representation, +then \fIunicode\fR is converted to the UTF format and appended to the +object's string representation. Appends are optimized to handle +repeated appends relatively efficiently (it overallocates the string +or Unicode space to avoid repeated reallocations and copies of +object's string value). +.PP +\fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it +appends the string or Unicode value (whichever exists and is best +suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to +\fIobjPtr\fR. +.PP +\fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR +except that it can be passed more than one value to append and +each value must be a null-terminated string (i.e. none of the +values may contain internal null characters). Any number of +\fIstring\fR arguments may be provided, but the last argument +must be a NULL pointer to indicate the end of the list. +.PP +\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR +except that instead of taking a variable number of arguments it takes an +argument list. +.PP +The \fBTcl_SetObjLength\fR procedure changes the length of the +string value of its \fIobjPtr\fR argument. If the \fInewLength\fR +argument is greater than the space allocated for the object's +string, then the string space is reallocated and the old value +is copied to the new space; the bytes between the old length of +the string and the new length may have arbitrary values. +If the \fInewLength\fR argument is less than the current length +of the object's string, with \fIobjPtr->length\fR is reduced without +reallocating the string space; the original allocated size for the +string is recorded in the object, so that the string length can be +enlarged in a subsequent call to \fBTcl_SetObjLength\fR without +reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves +a null character at \fIobjPtr->bytes[newLength]\fR. +.PP +\fBTcl_AttemptSetObjLength\fR is identical in function to +\fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the +request cannot be allocated, it does not cause the Tcl interpreter to +\fBpanic\fR. Thus, if \fInewLength\fR is greater than the space +allocated for the object's string, and there is not enough memory +available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take +no action and return 0 to indicate failure. If there is enough memory +to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like +\fBTcl_SetObjLength\fR and returns 1 to indicate success. +.PP +The \fBTcl_ConcatObj\fR function returns a new string object whose +value is the space-separated concatenation of the string +representations of all of the objects in the \fIobjv\fR +array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space +as it copies the string representations of the \fIobjv\fR array to the +result. If an element of the \fIobjv\fR array consists of nothing but +white space, then that object is ignored entirely. This white-space +removal was added to make the output of the \fBconcat\fR command +cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a +newly-created object whose ref count is zero. + +.SH "SEE ALSO" +Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount + +.SH KEYWORDS +append, internal representation, object, object type, string object, +string type, string representation, concat, concatenate, unicode diff --git a/doc/Thread.3 b/doc/Thread.3 index 28aa635..766d7ad 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -1,197 +1,197 @@ -'\" -'\" Copyright (c) 1999 Scriptics Corporation -'\" Copyright (c) 1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Thread.3,v 1.26 2007/10/29 11:28:50 dkf Exp $ -'\" -.so man.macros -.TH Threads 3 "8.1" Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -void -\fBTcl_ConditionNotify\fR(\fIcondPtr\fR) -.sp -void -\fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR) -.sp -void -\fBTcl_ConditionFinalize\fR(\fIcondPtr\fR) -.sp -Void * -\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR) -.sp -void -\fBTcl_MutexLock\fR(\fImutexPtr\fR) -.sp -void -\fBTcl_MutexUnlock\fR(\fImutexPtr\fR) -.sp -void -\fBTcl_MutexFinalize\fR(\fImutexPtr\fR) -.sp -int -\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR) -.sp -int -\fBTcl_JoinThread\fR(\fIid, result\fR) -.SH ARGUMENTS -.AS Tcl_CreateThreadProc threadProc out -.AP Tcl_Condition *condPtr in -A condition variable, which must be associated with a mutex lock. -.AP Tcl_Mutex *mutexPtr in -A mutex lock. -.AP Tcl_Time *timePtr in -A time limit on the condition wait. NULL to wait forever. -Note that a polling value of 0 seconds does not make much sense. -.AP Tcl_ThreadDataKey *keyPtr in -This identifies a block of thread local storage. The key should be -static and process-wide, yet each thread will end up associating -a different block of storage with this key. -.AP int *size in -The size of the thread local storage block. This amount of data -is allocated and initialized to zero the first time each thread -calls \fBTcl_GetThreadData\fR. -.AP Tcl_ThreadId *idPtr out -The referred storage will contain the id of the newly created thread as -returned by the operating system. -.AP Tcl_ThreadId id in -Id of the thread waited upon. -.AP Tcl_ThreadCreateProc threadProc in -This procedure will act as the \fBmain()\fR of the newly created -thread. The specified \fIclientData\fR will be its sole argument. -.AP ClientData clientData in -Arbitrary information. Passed as sole argument to the \fIthreadProc\fR. -.AP int stackSize in -The size of the stack given to the new thread. -.AP int flags in -Bitmask containing flags allowing the caller to modify behaviour of -the new thread. -.AP int *result out -The referred storage is used to place the exit code of the thread -waited upon into it. -.BE -.SH INTRODUCTION -Beginning with the 8.1 release, the Tcl core is thread safe, which -allows you to incorporate Tcl into multithreaded applications without -customizing the Tcl core. To enable Tcl multithreading support, -you must include the \fB\-\|\-enable-threads\fR option to \fBconfigure\fR -when you configure and compile your Tcl core. -.PP -An important constraint of the Tcl threads implementation is that -\fIonly the thread that created a Tcl interpreter can use that -interpreter\fR. In other words, multiple threads can not access -the same Tcl interpreter. (However, a single thread can safely create -and use multiple interpreters.) -.SH DESCRIPTION -Tcl provides \fBTcl_CreateThread\fR for creating threads. The -caller can determine the size of the stack given to the new thread and -modify the behaviour through the supplied \fIflags\fR. The value -\fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that -the default size as specified by the operating system is to be used -for the new thread. As for the flags, currently only the values -\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The -first of them invokes the default behaviour with no -specialties. Using the second value marks the new thread as -\fIjoinable\fR. This means that another thread can wait for the such -marked thread to exit and join it. -.PP -Restrictions: On some UNIX systems the pthread-library does not -contain the functionality to specify the stack size of a thread. The -specified value for the stack size is ignored on these systems. -Windows currently does not support joinable threads. This -flag value is therefore ignored on this platform. -.PP -Tcl provides the \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR functions -for terminating threads and invoking optional per-thread exit -handlers. See the \fBTcl_Exit\fR page for more information on these -procedures. -.PP -The \fBTcl_JoinThread\fR function is provided to allow threads to wait -upon the exit of another thread, which must have been marked as -joinable through usage of the \fBTCL_THREAD_JOINABLE\fR-flag during -its creation via \fBTcl_CreateThread\fR. -.PP -Trying to wait for the exit of a non-joinable thread or a thread which -is already waited upon will result in an error. Waiting for a joinable -thread which already exited is possible, the system will retain the -necessary information until after the call to \fBTcl_JoinThread\fR. -This means that not calling \fBTcl_JoinThread\fR for a joinable thread -will cause a memory leak. -.PP -The \fBTcl_GetThreadData\fR call returns a pointer to a block of -thread-private data. Its argument is a key that is shared by all threads -and a size for the block of storage. The storage is automatically -allocated and initialized to all zeros the first time each thread asks for it. -The storage is automatically deallocated by \fBTcl_FinalizeThread\fR. -.SS "SYNCHRONIZATION AND COMMUNICATION" -Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR -for handling event queuing in multithreaded applications. See -the \fBNotifier\fR manual page for more information on these procedures. -.PP -A mutex is a lock that is used to serialize all threads through a piece -of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR. -If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will -block until \fBTcl_MutexUnlock\fR is called. -A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR. -The result of locking a mutex twice from the same thread is undefined. -On some platforms it will result in a deadlock. -The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR -procedures are defined as empty macros if not compiling with threads enabled. -For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used. -This macro assures correct mutex handling even when the core is compiled -without threads enabled. -.PP -A condition variable is used as a signaling mechanism: -a thread can lock a mutex and then wait on a condition variable -with \fBTcl_ConditionWait\fR. This atomically releases the mutex lock -and blocks the waiting thread until another thread calls -\fBTcl_ConditionNotify\fR. The caller of \fBTcl_ConditionNotify\fR should -have the associated mutex held by previously calling \fBTcl_MutexLock\fR, -but this is not enforced. Notifying the -condition variable unblocks all threads waiting on the condition variable, -but they do not proceed until the mutex is released with \fBTcl_MutexUnlock\fR. -The implementation of \fBTcl_ConditionWait\fR automatically locks -the mutex before returning. -.PP -The caller of \fBTcl_ConditionWait\fR should be prepared for spurious -notifications by calling \fBTcl_ConditionWait\fR within a while loop -that tests some invariant. -.PP -A condition variable can be destroyed after its use by calling -\fBTcl_ConditionFinalize\fR. -.PP -The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and -\fBTcl_ConditionFinalize\fR procedures are defined as empty macros if -not compiling with threads enabled. -.SS INITIALIZATION -.PP -All of these synchronization objects are self-initializing. -They are implemented as opaque pointers that should be NULL -upon first use. -The mutexes and condition variables are -either cleaned up by process exit handlers (if living that long) or -explicitly by calls to \fBTcl_MutexFinalize\fR or -\fBTcl_ConditionFinalize\fR. -Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR. -.SH "SCRIPT-LEVEL ACCESS TO THREADS" -.VS 8.5 -Tcl provides no built-in commands for scripts to use to create, -manage, or join threads, nor any script-level access to mutex or -condition variables. It provides such facilities only via C -interfaces, and leaves it up to packages to expose these matters to -the script level. One such package is the \fBThread\fR package. -.VE 8.5 -.SH "SEE ALSO" -Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3), -Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3), -Tcl_DeleteThreadExitHandler(3), Thread -.SH KEYWORDS -thread, mutex, condition variable, thread local storage +'\" +'\" Copyright (c) 1999 Scriptics Corporation +'\" Copyright (c) 1998 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: Thread.3,v 1.27 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Threads 3 "8.1" Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +void +\fBTcl_ConditionNotify\fR(\fIcondPtr\fR) +.sp +void +\fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR) +.sp +void +\fBTcl_ConditionFinalize\fR(\fIcondPtr\fR) +.sp +Void * +\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR) +.sp +void +\fBTcl_MutexLock\fR(\fImutexPtr\fR) +.sp +void +\fBTcl_MutexUnlock\fR(\fImutexPtr\fR) +.sp +void +\fBTcl_MutexFinalize\fR(\fImutexPtr\fR) +.sp +int +\fBTcl_CreateThread\fR(\fIidPtr, threadProc, clientData, stackSize, flags\fR) +.sp +int +\fBTcl_JoinThread\fR(\fIid, result\fR) +.SH ARGUMENTS +.AS Tcl_CreateThreadProc threadProc out +.AP Tcl_Condition *condPtr in +A condition variable, which must be associated with a mutex lock. +.AP Tcl_Mutex *mutexPtr in +A mutex lock. +.AP Tcl_Time *timePtr in +A time limit on the condition wait. NULL to wait forever. +Note that a polling value of 0 seconds does not make much sense. +.AP Tcl_ThreadDataKey *keyPtr in +This identifies a block of thread local storage. The key should be +static and process-wide, yet each thread will end up associating +a different block of storage with this key. +.AP int *size in +The size of the thread local storage block. This amount of data +is allocated and initialized to zero the first time each thread +calls \fBTcl_GetThreadData\fR. +.AP Tcl_ThreadId *idPtr out +The referred storage will contain the id of the newly created thread as +returned by the operating system. +.AP Tcl_ThreadId id in +Id of the thread waited upon. +.AP Tcl_ThreadCreateProc threadProc in +This procedure will act as the \fBmain()\fR of the newly created +thread. The specified \fIclientData\fR will be its sole argument. +.AP ClientData clientData in +Arbitrary information. Passed as sole argument to the \fIthreadProc\fR. +.AP int stackSize in +The size of the stack given to the new thread. +.AP int flags in +Bitmask containing flags allowing the caller to modify behaviour of +the new thread. +.AP int *result out +The referred storage is used to place the exit code of the thread +waited upon into it. +.BE +.SH INTRODUCTION +Beginning with the 8.1 release, the Tcl core is thread safe, which +allows you to incorporate Tcl into multithreaded applications without +customizing the Tcl core. To enable Tcl multithreading support, +you must include the \fB\-\|\-enable-threads\fR option to \fBconfigure\fR +when you configure and compile your Tcl core. +.PP +An important constraint of the Tcl threads implementation is that +\fIonly the thread that created a Tcl interpreter can use that +interpreter\fR. In other words, multiple threads can not access +the same Tcl interpreter. (However, a single thread can safely create +and use multiple interpreters.) +.SH DESCRIPTION +Tcl provides \fBTcl_CreateThread\fR for creating threads. The +caller can determine the size of the stack given to the new thread and +modify the behaviour through the supplied \fIflags\fR. The value +\fBTCL_THREAD_STACK_DEFAULT\fR for the \fIstackSize\fR indicates that +the default size as specified by the operating system is to be used +for the new thread. As for the flags, currently only the values +\fBTCL_THREAD_NOFLAGS\fR and \fBTCL_THREAD_JOINABLE\fR are defined. The +first of them invokes the default behaviour with no +specialties. Using the second value marks the new thread as +\fIjoinable\fR. This means that another thread can wait for the such +marked thread to exit and join it. +.PP +Restrictions: On some UNIX systems the pthread-library does not +contain the functionality to specify the stack size of a thread. The +specified value for the stack size is ignored on these systems. +Windows currently does not support joinable threads. This +flag value is therefore ignored on this platform. +.PP +Tcl provides the \fBTcl_ExitThread\fR and \fBTcl_FinalizeThread\fR functions +for terminating threads and invoking optional per-thread exit +handlers. See the \fBTcl_Exit\fR page for more information on these +procedures. +.PP +The \fBTcl_JoinThread\fR function is provided to allow threads to wait +upon the exit of another thread, which must have been marked as +joinable through usage of the \fBTCL_THREAD_JOINABLE\fR-flag during +its creation via \fBTcl_CreateThread\fR. +.PP +Trying to wait for the exit of a non-joinable thread or a thread which +is already waited upon will result in an error. Waiting for a joinable +thread which already exited is possible, the system will retain the +necessary information until after the call to \fBTcl_JoinThread\fR. +This means that not calling \fBTcl_JoinThread\fR for a joinable thread +will cause a memory leak. +.PP +The \fBTcl_GetThreadData\fR call returns a pointer to a block of +thread-private data. Its argument is a key that is shared by all threads +and a size for the block of storage. The storage is automatically +allocated and initialized to all zeros the first time each thread asks for it. +The storage is automatically deallocated by \fBTcl_FinalizeThread\fR. +.SS "SYNCHRONIZATION AND COMMUNICATION" +Tcl provides \fBTcl_ThreadQueueEvent\fR and \fBTcl_ThreadAlert\fR +for handling event queuing in multithreaded applications. See +the \fBNotifier\fR manual page for more information on these procedures. +.PP +A mutex is a lock that is used to serialize all threads through a piece +of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR. +If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will +block until \fBTcl_MutexUnlock\fR is called. +A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR. +The result of locking a mutex twice from the same thread is undefined. +On some platforms it will result in a deadlock. +The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR +procedures are defined as empty macros if not compiling with threads enabled. +For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used. +This macro assures correct mutex handling even when the core is compiled +without threads enabled. +.PP +A condition variable is used as a signaling mechanism: +a thread can lock a mutex and then wait on a condition variable +with \fBTcl_ConditionWait\fR. This atomically releases the mutex lock +and blocks the waiting thread until another thread calls +\fBTcl_ConditionNotify\fR. The caller of \fBTcl_ConditionNotify\fR should +have the associated mutex held by previously calling \fBTcl_MutexLock\fR, +but this is not enforced. Notifying the +condition variable unblocks all threads waiting on the condition variable, +but they do not proceed until the mutex is released with \fBTcl_MutexUnlock\fR. +The implementation of \fBTcl_ConditionWait\fR automatically locks +the mutex before returning. +.PP +The caller of \fBTcl_ConditionWait\fR should be prepared for spurious +notifications by calling \fBTcl_ConditionWait\fR within a while loop +that tests some invariant. +.PP +A condition variable can be destroyed after its use by calling +\fBTcl_ConditionFinalize\fR. +.PP +The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and +\fBTcl_ConditionFinalize\fR procedures are defined as empty macros if +not compiling with threads enabled. +.SS INITIALIZATION +.PP +All of these synchronization objects are self-initializing. +They are implemented as opaque pointers that should be NULL +upon first use. +The mutexes and condition variables are +either cleaned up by process exit handlers (if living that long) or +explicitly by calls to \fBTcl_MutexFinalize\fR or +\fBTcl_ConditionFinalize\fR. +Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR. +.SH "SCRIPT-LEVEL ACCESS TO THREADS" +.VS 8.5 +Tcl provides no built-in commands for scripts to use to create, +manage, or join threads, nor any script-level access to mutex or +condition variables. It provides such facilities only via C +interfaces, and leaves it up to packages to expose these matters to +the script level. One such package is the \fBThread\fR package. +.VE 8.5 +.SH "SEE ALSO" +Tcl_GetCurrentThread(3), Tcl_ThreadQueueEvent(3), Tcl_ThreadAlert(3), +Tcl_ExitThread(3), Tcl_FinalizeThread(3), Tcl_CreateThreadExitHandler(3), +Tcl_DeleteThreadExitHandler(3), Thread +.SH KEYWORDS +thread, mutex, condition variable, thread local storage diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index 1278269..c86dd5b 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.3 @@ -1,163 +1,163 @@ -'\" -'\" Copyright (c) 2002 Donal K. Fellows -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" CVS: @(#) $Id: TraceCmd.3,v 1.9 2007/10/28 14:17:40 dkf Exp $ -'\" -.so man.macros -.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -ClientData -\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR -.sp -int -\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR -.sp -void -\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR -.SH ARGUMENTS -.AS Tcl_CommandTraceProc prevClientData -.AP Tcl_Interp *interp in -Interpreter containing the command. -.AP "const char" *cmdName in -Name of command. -.AP int flags in -OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and -\fBTCL_TRACE_DELETE\fR. -.AP Tcl_CommandTraceProc *proc in -Procedure to call when specified operations occur to \fIcmdName\fR. -.AP ClientData clientData in -Arbitrary argument to pass to \fIproc\fR. -.AP ClientData prevClientData in -If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR, -so this call will return information about next trace. If NULL, this -call will return information about first trace. -.BE -.SH DESCRIPTION -.PP -\fBTcl_TraceCommand\fR allows a C procedure to monitor operations -performed on a Tcl command, so that the C procedure is invoked -whenever the command is renamed or deleted. If the trace is created -successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error -occurred (e.g. \fIcmdName\fR specifies a non-existent command) then -\fBTCL_ERROR\fR is returned and an error message is left in the -interpreter's result. -.PP -The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the -trace procedure is to be invoked. It consists of an OR'ed combination -of any of the following values: -.TP -\fBTCL_TRACE_RENAME\fR -Invoke \fIproc\fR whenever the command is renamed. -.TP -\fBTCL_TRACE_DELETE\fR -Invoke \fIproc\fR when the command is deleted. -.PP -Whenever one of the specified operations occurs to the command, -\fIproc\fR will be invoked. It should have arguments and result that -match the type \fBTcl_CommandTraceProc\fR: -.CS -typedef void Tcl_CommandTraceProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - const char *\fIoldName\fR, - const char *\fInewName\fR, - int \fIflags\fR); -.CE -The \fIclientData\fR and \fIinterp\fR parameters will have the same -values as those passed to \fBTcl_TraceCommand\fR when the trace was -created. \fIClientData\fR typically points to an application-specific -data structure that describes what to do when \fIproc\fR is invoked. -\fIOldName\fR gives the name of the command being renamed, and -\fInewName\fR gives the name that the command is being renamed to (or -an empty string or NULL when the command is being deleted.) -\fIFlags\fR is an OR'ed combination of bits potentially providing -several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and -\fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which -operation is being performed on the command. The bit -\fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about -to be destroyed; this information may be useful to \fIproc\fR so that -it can clean up its own internal data structures (see the section -\fBTCL_TRACE_DESTROYED\fR below for more details). Lastly, the bit -\fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being -destroyed. When this bit is set, \fIproc\fR must be especially -careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR -below). -.PP -\fBTcl_UntraceCommand\fR may be used to remove a trace. If the -command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has -a trace set with \fIflags\fR, \fIproc\fR, and \fIclientData\fR, then -the corresponding trace is removed. If no such trace exists, then the -call to \fBTcl_UntraceCommand\fR has no effect. The same bits are -valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR. -.PP -\fBTcl_CommandTraceInfo\fR may be used to retrieve information about -traces set on a given command. -The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR -associated with a particular trace. -The trace must be on the command specified by the \fIinterp\fR, -\fIcmdName\fR, and \fIflags\fR arguments (note that currently the -flags are ignored; \fIflags\fR should be set to 0 for future -compatibility) and its trace procedure must the same as the \fIproc\fR -argument. -If the \fIprevClientData\fR argument is NULL then the return -value corresponds to the first (most recently created) matching -trace, or NULL if there are no matching traces. -If the \fIprevClientData\fR argument is not NULL, then it should -be the return value from a previous call to \fBTcl_CommandTraceInfo\fR. -In this case, the new return value will correspond to the next -matching trace after the one whose \fIclientData\fR matches -\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR -or if there are no more matching traces after it. -This mechanism makes it possible to step through all of the -traces for a given command that have the same \fIproc\fR. -.SH "CALLING COMMANDS DURING TRACES" -.PP -During rename traces, the command being renamed is visible with both -names simultaneously, and the command still exists during delete -traces (if \fBTCL_INTERP_DESTROYED\fR is not set). However, there is no -mechanism for signaling that an error occurred in a trace procedure, -so great care should be taken that errors do not get silently lost. -.SH "MULTIPLE TRACES" -.PP -It is possible for multiple traces to exist on the same command. -When this happens, all of the trace procedures will be invoked on each -access, in order from most-recently-created to least-recently-created. -Attempts to delete the command during a delete trace will fail -silently, since the command is already scheduled for deletion anyway. -If the command being renamed is renamed by one of its rename traces, -that renaming takes precedence over the one that triggered the trace -and the collection of traces will not be reexecuted; if several traces -rename the command, the last renaming takes precedence. -.SH "TCL_TRACE_DESTROYED FLAG" -.PP -In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit -is set in \fIflags\fR. -.\" Perhaps need some more comments here? - DKF -.SH "TCL_INTERP_DESTROYED" -.PP -When an interpreter is destroyed, unset traces are called for -all of its commands. -The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR -argument passed to the trace procedures. -Trace procedures must be extremely careful in what they do if -the \fBTCL_INTERP_DESTROYED\fR bit is set. -It is not safe for the procedures to invoke any Tcl procedures -on the interpreter, since its state is partially deleted. -All that trace procedures should do under these circumstances is -to clean up and free their own internal data structures. -.SH BUGS -.PP -Tcl does not do any error checking to prevent trace procedures -from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR -set. -.SH KEYWORDS -clientData, trace, command +'\" +'\" Copyright (c) 2002 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" CVS: @(#) $Id: TraceCmd.3,v 1.10 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +ClientData +\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR +.sp +int +\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR +.sp +void +\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR +.SH ARGUMENTS +.AS Tcl_CommandTraceProc prevClientData +.AP Tcl_Interp *interp in +Interpreter containing the command. +.AP "const char" *cmdName in +Name of command. +.AP int flags in +OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and +\fBTCL_TRACE_DELETE\fR. +.AP Tcl_CommandTraceProc *proc in +Procedure to call when specified operations occur to \fIcmdName\fR. +.AP ClientData clientData in +Arbitrary argument to pass to \fIproc\fR. +.AP ClientData prevClientData in +If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR, +so this call will return information about next trace. If NULL, this +call will return information about first trace. +.BE +.SH DESCRIPTION +.PP +\fBTcl_TraceCommand\fR allows a C procedure to monitor operations +performed on a Tcl command, so that the C procedure is invoked +whenever the command is renamed or deleted. If the trace is created +successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error +occurred (e.g. \fIcmdName\fR specifies a non-existent command) then +\fBTCL_ERROR\fR is returned and an error message is left in the +interpreter's result. +.PP +The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the +trace procedure is to be invoked. It consists of an OR'ed combination +of any of the following values: +.TP +\fBTCL_TRACE_RENAME\fR +Invoke \fIproc\fR whenever the command is renamed. +.TP +\fBTCL_TRACE_DELETE\fR +Invoke \fIproc\fR when the command is deleted. +.PP +Whenever one of the specified operations occurs to the command, +\fIproc\fR will be invoked. It should have arguments and result that +match the type \fBTcl_CommandTraceProc\fR: +.CS +typedef void Tcl_CommandTraceProc( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + const char *\fIoldName\fR, + const char *\fInewName\fR, + int \fIflags\fR); +.CE +The \fIclientData\fR and \fIinterp\fR parameters will have the same +values as those passed to \fBTcl_TraceCommand\fR when the trace was +created. \fIClientData\fR typically points to an application-specific +data structure that describes what to do when \fIproc\fR is invoked. +\fIOldName\fR gives the name of the command being renamed, and +\fInewName\fR gives the name that the command is being renamed to (or +an empty string or NULL when the command is being deleted.) +\fIFlags\fR is an OR'ed combination of bits potentially providing +several pieces of information. One of the bits \fBTCL_TRACE_RENAME\fR and +\fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which +operation is being performed on the command. The bit +\fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about +to be destroyed; this information may be useful to \fIproc\fR so that +it can clean up its own internal data structures (see the section +\fBTCL_TRACE_DESTROYED\fR below for more details). Lastly, the bit +\fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being +destroyed. When this bit is set, \fIproc\fR must be especially +careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR +below). +.PP +\fBTcl_UntraceCommand\fR may be used to remove a trace. If the +command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has +a trace set with \fIflags\fR, \fIproc\fR, and \fIclientData\fR, then +the corresponding trace is removed. If no such trace exists, then the +call to \fBTcl_UntraceCommand\fR has no effect. The same bits are +valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR. +.PP +\fBTcl_CommandTraceInfo\fR may be used to retrieve information about +traces set on a given command. +The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR +associated with a particular trace. +The trace must be on the command specified by the \fIinterp\fR, +\fIcmdName\fR, and \fIflags\fR arguments (note that currently the +flags are ignored; \fIflags\fR should be set to 0 for future +compatibility) and its trace procedure must the same as the \fIproc\fR +argument. +If the \fIprevClientData\fR argument is NULL then the return +value corresponds to the first (most recently created) matching +trace, or NULL if there are no matching traces. +If the \fIprevClientData\fR argument is not NULL, then it should +be the return value from a previous call to \fBTcl_CommandTraceInfo\fR. +In this case, the new return value will correspond to the next +matching trace after the one whose \fIclientData\fR matches +\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR +or if there are no more matching traces after it. +This mechanism makes it possible to step through all of the +traces for a given command that have the same \fIproc\fR. +.SH "CALLING COMMANDS DURING TRACES" +.PP +During rename traces, the command being renamed is visible with both +names simultaneously, and the command still exists during delete +traces (if \fBTCL_INTERP_DESTROYED\fR is not set). However, there is no +mechanism for signaling that an error occurred in a trace procedure, +so great care should be taken that errors do not get silently lost. +.SH "MULTIPLE TRACES" +.PP +It is possible for multiple traces to exist on the same command. +When this happens, all of the trace procedures will be invoked on each +access, in order from most-recently-created to least-recently-created. +Attempts to delete the command during a delete trace will fail +silently, since the command is already scheduled for deletion anyway. +If the command being renamed is renamed by one of its rename traces, +that renaming takes precedence over the one that triggered the trace +and the collection of traces will not be reexecuted; if several traces +rename the command, the last renaming takes precedence. +.SH "TCL_TRACE_DESTROYED FLAG" +.PP +In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit +is set in \fIflags\fR. +.\" Perhaps need some more comments here? - DKF +.SH "TCL_INTERP_DESTROYED" +.PP +When an interpreter is destroyed, unset traces are called for +all of its commands. +The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR +argument passed to the trace procedures. +Trace procedures must be extremely careful in what they do if +the \fBTCL_INTERP_DESTROYED\fR bit is set. +It is not safe for the procedures to invoke any Tcl procedures +on the interpreter, since its state is partially deleted. +All that trace procedures should do under these circumstances is +to clean up and free their own internal data structures. +.SH BUGS +.PP +Tcl does not do any error checking to prevent trace procedures +from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR +set. +.SH KEYWORDS +clientData, trace, command diff --git a/doc/file.n b/doc/file.n index 6c1abea..24ed432 100644 --- a/doc/file.n +++ b/doc/file.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: file.n,v 1.49 2007/10/29 11:28:50 dkf Exp $ +'\" RCS: @(#) $Id: file.n,v 1.50 2007/10/29 17:17:54 dgp Exp $ '\" .so man.macros .TH file n 8.3 Tcl "Tcl Built-In Commands" @@ -32,7 +32,7 @@ Returns a decimal string giving the time at which file \fIname\fR was last accessed. If \fItime\fR is specified, it is an access time to set for the file. The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file -does not exist or its access time cannot be queried or set then an error is +doesn't exist or its access time cannot be queried or set then an error is generated. On Windows, FAT file systems do not support access time. .TP \fBfile attributes \fIname\fR @@ -47,11 +47,11 @@ flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows: .PP -On Unix, \fB\-group\fR gets or sets the group name for the file. A group id -can be given to the command, but it returns a group name. \fB\-owner\fR gets +On Unix, \fB-group\fR gets or sets the group name for the file. A group id +can be given to the command, but it returns a group name. \fB-owner\fR gets or sets the user name of the owner of the file. The command returns the owner name, but the numerical id can be passed when setting the -owner. \fB\-permissions\fR sets or retrieves the octal code that chmod(1) +owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1) uses. This command does also has limited support for setting using the symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]], where multiple symbolic attributes can be separated by commas (example: @@ -59,24 +59,24 @@ where multiple symbolic attributes can be separated by commas (example: permissions for group and other). A simplified \fBls\fR style string, of the form rwxrwxrwx (must be 9 characters), is also supported (example: \fBrwxr\-xr\-t\fR is equivalent to 01755). -On versions of Unix supporting file flags, \fB\-readonly\fR gives the +On versions of Unix supporting file flags, \fB-readonly\fR gives the value or sets or clears the readonly attribute of the file, i.e. the user immutable flag \fBuchg\fR to chflags(1). .PP -On Windows, \fB\-archive\fR gives the value or sets or clears the -archive attribute of the file. \fB\-hidden\fR gives the value or sets -or clears the hidden attribute of the file. \fB\-readonly\fR gives the -value or sets or clears the readonly attribute of the file. -\fB\-system\fR gives or sets or clears the value of the system -attribute of the file. \fB\-longname\fR will expand each path element -to its long version. \fB\-shortname\fR gives a string where every -path element is replaced with its short (8.3) version of the name. The -\fB\-longname\fR and \fB\-shortname\fR attributes cannot be set. +On Windows, \fB-archive\fR gives the value or sets or clears the +archive attribute of the file. \fB-hidden\fR gives the value or sets +or clears the hidden attribute of the file. \fB-longname\fR will +expand each path element to its long version. This attribute cannot be +set. \fB-readonly\fR gives the value or sets or clears the readonly +attribute of the file. \fB-shortname\fR gives a string where every +path element is replaced with its short (8.3) version of the +name. This attribute cannot be set. \fB-system\fR gives or sets or +clears the value of the system attribute of the file. .PP -On Mac OS X and Darwin, \fB\-creator\fR gives or sets the -Finder creator type of the file. \fB\-hidden\fR gives or sets or clears -the hidden attribute of the file. \fB\-readonly\fR gives or sets or -clears the readonly attribute of the file. \fB\-rsrclength\fR gives +On Mac OS X and Darwin, \fB-creator\fR gives or sets the +Finder creator type of the file. \fB-hidden\fR gives or sets or clears +the hidden attribute of the file. \fB-readonly\fR gives or sets or +clears the readonly attribute of the file. \fB-rsrclength\fR gives the length of the resource fork of the file, this attribute can only be set to the value 0, which results in the resource fork being stripped off the file. @@ -84,7 +84,7 @@ off the file. .TP \fBfile channels ?\fIpattern\fR? . -If \fIpattern\fR is not specified, returns a list of names of all +If \fIpattern\fR isn't specified, returns a list of names of all registered open channels in this interpreter. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. @@ -122,9 +122,7 @@ Trying to delete a non-existent file is not considered an error. Trying to delete a read-only file will cause the file to be deleted, even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR option is specified on a directory, Tcl will attempt both to change -permissions and move the current directory -.QW pwd -out of the given path +permissions and move the current directory 'pwd' out of the given path if that is necessary to allow the deletion to proceed. Arguments are processed in the order specified, halting at the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the @@ -134,9 +132,7 @@ a \fB\-\fR. \fBfile dirname \fIname\fR Returns a name comprised of all of the path components in \fIname\fR excluding the last element. If \fIname\fR is a relative file name and -only contains one path element, then returns -.QW \fB.\fR . -If \fIname\fR +only contains one path element, then returns ``\fB.\fR''. If \fIname\fR refers to a root directory, then the root directory is returned. For example, .RS @@ -199,42 +195,36 @@ is always canonical for the current platform: \fB/\fR for Unix and Windows. .RE .TP -\fBfile link ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR? +\fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR? . If only one argument is given, that argument is assumed to be \fIlinkName\fR, and this command returns the value of the link given by \fIlinkName\fR (i.e. the name of the file it points to). If -\fIlinkName\fR is not a link or its value cannot be read (as, for example, +\fIlinkName\fR isn't a link or its value cannot be read (as, for example, seems to be the case with hard links, which look just like ordinary files), then an error is returned. -.RS -.PP +. If 2 arguments are given, then these are assumed to be \fIlinkName\fR and \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR -does not exist, an error will be returned. Otherwise, Tcl creates a new +doesn't exist, an error will be returned. Otherwise, Tcl creates a new link called \fIlinkName\fR which points to the existing filesystem object at \fItarget\fR (which is also the returned value), where the type of the link is platform-specific (on Unix a symbolic link will be the default). This is useful for the case where the user wishes to -create a link in a cross-platform way, and does not care what type of +create a link in a cross-platform way, and doesn't care what type of link is created. -.PP +. If the user wishes to make a link of a specific type only, (and signal an error if for some reason that is not possible), then the optional -\fI\-linktype\fR argument should be given. Accepted values for -\fI\-linktype\fR are -.QW \-symbolic -and -.QW \-hard . -.PP +\fI-linktype\fR argument should be given. Accepted values for +\fI-linktype\fR are "-symbolic" and "-hard". +. On Unix, symbolic links can be made to relative paths, and those paths must be relative to the actual \fIlinkName\fR's location (not to the cwd), but on all other platforms where relative links are not supported, target paths will always be converted to absolute, normalized form before the link is created (and therefore relative paths are interpreted -as relative to the cwd). Furthermore, -.QW ~user -paths are always expanded +as relative to the cwd). Furthermore, "~user" paths are always expanded to absolute form. When creating links on filesystems that either do not support any links, or do not support the specific type requested, an error message will be returned. In particular Windows 95, 98 and ME do @@ -242,7 +232,6 @@ not support any links at present, but most Unix platforms support both symbolic and hard links (the latter for files only) and Windows NT/2000/XP (on NTFS drives) support symbolic directory links and hard file links. -.RE .TP \fBfile lstat \fIname varName\fR . @@ -250,7 +239,7 @@ Same as \fBstat\fR option (see below) except uses the \fIlstat\fR kernel call instead of \fIstat\fR. This means that if \fIname\fR refers to a symbolic link the information returned in \fIvarName\fR is for the link rather than the file it refers to. On systems that -do not support symbolic links this option behaves exactly the same +don't support symbolic links this option behaves exactly the same as the \fBstat\fR option. .TP \fBfile mkdir \fIdir\fR ?\fIdir\fR ...? @@ -268,7 +257,7 @@ Returns a decimal string giving the time at which file \fIname\fR was last modified. If \fItime\fR is specified, it is a modification time to set for the file (equivalent to Unix \fBtouch\fR). The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January -1, 1970). If the file does not exist or its modified time cannot be queried +1, 1970). If the file doesn't exist or its modified time cannot be queried or set then an error is generated. .TP \fBfile nativename \fIname\fR @@ -283,20 +272,16 @@ under Windows. Returns a unique normalized path representation for the file-system object (file, directory, link, etc), whose string value can be used as a unique identifier for it. A normalized path is an absolute path which has -all -.QW ../ , -.QW ./ -removed. Also it is one which is in the -.QW standard +all '../', './' removed. Also it is one which is in the ``standard'' format for the native platform. On Unix, this means the segments leading up to the path must be free of symbolic links/aliases (but the very last path component may be a symbolic link), and on Windows it also means we want the long form with that form's case-dependence (which gives us a unique, case-dependent path). The one exception concerning the last link in the path is necessary, because Tcl or the user may wish to -operate on the actual symbolic link itself (for example \fBfile delete\fR, -\fBfile rename\fR, \fBfile copy\fR are defined to operate on symbolic -links, not on the things that they point to). +operate on the actual symbolic link itself (for example 'file delete', 'file +rename', 'file copy' are defined to operate on symbolic links, not on the +things that they point to). .RE .TP \fBfile owned \fIname\fR @@ -322,8 +307,8 @@ Returns \fB1\fR if file \fIname\fR is readable by the current user, \fBfile readlink \fIname\fR . Returns the value of the symbolic link given by \fIname\fR (i.e. the name -of the file it points to). If \fIname\fR is not a symbolic link or its -value cannot be read, then an error is returned. On systems that do not +of the file it points to). If \fIname\fR isn't a symbolic link or its +value cannot be read, then an error is returned. On systems that don't support symbolic links this option is undefined. .TP \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR @@ -349,10 +334,8 @@ switches; the argument following the \fB\-\|\-\fR will be treated as a \fBfile rootname \fIname\fR . Returns all of the characters in \fIname\fR up to but not including the -last -.QW . -character in the last component of name. If the last -component of \fIname\fR does not contain a dot, then returns \fIname\fR. +last ``.'' character in the last component of name. If the last +component of \fIname\fR doesn't contain a dot, then returns \fIname\fR. .TP \fBfile separator\fR ?\fIname\fR? . @@ -365,7 +348,7 @@ is generated. \fBfile size \fIname\fR . Returns a decimal string giving the size of file \fIname\fR in bytes. If -the file does not exist or its size cannot be queried then an error is +the file doesn't exist or its size cannot be queried then an error is generated. .TP \fBfile split \fIname\fR @@ -405,20 +388,12 @@ the filesystem to use for the file, and the second, if given, an arbitrary string representing the filesystem-specific nature or type of the location within that filesystem. If a filesystem only supports one type of file, the second element may not be supplied. For example the -native files have a first element -.QW native , -and a second element which +native files have a first element 'native', and a second element which when given is a platform-specific type name for the file's system -(e.g. -.QW NTFS , -.QW FAT , -on Windows). A generic virtual file system might return -the list -.QW "vfs ftp" -to represent a file on a remote ftp site mounted as a -virtual filesystem through an extension called -.QW vfs . -If the file does not belong to any filesystem, an error is generated. +(e.g. 'NTFS', 'FAT', on Windows). A generic virtual file system might return +the list 'vfs ftp' to represent a file on a remote ftp site mounted as a +virtual filesystem through an extension called 'vfs'. If the file does +not belong to any filesystem, an error is generated. .TP \fBfile tail \fIname\fR . @@ -435,16 +410,13 @@ Returns a string giving the type of file \fIname\fR, which will be one of \fBfifo\fR, \fBlink\fR, or \fBsocket\fR. .TP \fBfile volumes\fR -. +. Returns the absolute paths to the volumes mounted on the system, as a proper Tcl list. Without any virtual filesystems mounted as root -volumes, on UNIX, the command will always return -.QW / , -since all filesystems are locally mounted. +volumes, on UNIX, the command will always return "/", since all +filesystems are locally mounted. On Windows, it will return a list of the available local drives -(e.g. -.QW "a:/ c:/" ). -If any virtual filesystem has mounted additional +(e.g. {a:/ c:/}). If any virtual filesystem has mounted additional volumes, they will be in the returned list. .TP \fBfile writable \fIname\fR @@ -455,11 +427,8 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user, .TP \fBUnix\fR\0\0\0\0\0\0\0 . -The subcommands that test whether a particular mode of access is permitted -always operate using the real user and group identifiers, not the effective -ones. As such, robust code should just \fBopen\fR a file for reading instead -of testing to see whether it is readable with \fBfile readable\fR. This also -avoids potential race conditions. +These commands always operate using the real user and group identifiers, +not the effective ones. .SH EXAMPLES This procedure shows how to search for C files in a given directory that have a correspondingly-named object file in the current @@ -497,8 +466,10 @@ if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} { \fBfile rename\fR $oldName $newName \fBfile link\fR -symbolic $oldName $newName .CE + .SH "SEE ALSO" -chan(n), close(n), eof(n), fblocked(n), filename(n), flush(n), gets(n), -open(n), seek(n), tell(n) +filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n), +fblocked(n), flush(n) + .SH KEYWORDS attributes, copy files, delete files, directory, file, move files, name, rename files, stat diff --git a/doc/global.n b/doc/global.n index 2294dee..198bc88 100644 --- a/doc/global.n +++ b/doc/global.n @@ -1,59 +1,59 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: global.n,v 1.10 2007/10/28 14:17:40 dkf Exp $ -'\" -.so man.macros -.TH global n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -global \- Access global variables -.SH SYNOPSIS -\fBglobal \fIvarname \fR?\fIvarname ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command has no effect unless executed in the context of a proc body. -If the \fBglobal\fR command is executed in the context of a proc body, it -creates local variables linked to the corresponding global variables (and -therefore these variables are listed by info locals). -.PP -If \fIvarname\fR contains namespace qualifiers, the local variable's name is -the unqualified name of the global variable, as determined by the -\fBnamespace tail\fR command. -.PP -\fIvarname\fR is always treated as the name of a variable, not an -array element. An error is returned if the name looks like an array element, -such as \fBa(b)\fR. -.SH EXAMPLES -This procedure sets the namespace variable \fI::a::x\fR -.CS -proc reset {} { - \fBglobal\fR a::x - set x 0 -} -.CE -.PP -This procedure accumulates the strings passed to it in a global -buffer, separated by newlines. It is useful for situations when you -want to build a message piece-by-piece (as if with \fBputs\fR) but -send that full message in a single piece (e.g. over a connection -opened with \fBsocket\fR or as part of a counted HTTP response). -.CS -proc accum {string} { - \fBglobal\fR accumulator - append accumulator $string \en -} -.CE - -.SH "SEE ALSO" -namespace(n), upvar(n), variable(n) - -.SH KEYWORDS -global, namespace, procedure, variable +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: global.n,v 1.11 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH global n "" Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +global \- Access global variables +.SH SYNOPSIS +\fBglobal \fIvarname \fR?\fIvarname ...\fR? +.BE + +.SH DESCRIPTION +.PP +This command has no effect unless executed in the context of a proc body. +If the \fBglobal\fR command is executed in the context of a proc body, it +creates local variables linked to the corresponding global variables (and +therefore these variables are listed by info locals). +.PP +If \fIvarname\fR contains namespace qualifiers, the local variable's name is +the unqualified name of the global variable, as determined by the +\fBnamespace tail\fR command. +.PP +\fIvarname\fR is always treated as the name of a variable, not an +array element. An error is returned if the name looks like an array element, +such as \fBa(b)\fR. +.SH EXAMPLES +This procedure sets the namespace variable \fI::a::x\fR +.CS +proc reset {} { + \fBglobal\fR a::x + set x 0 +} +.CE +.PP +This procedure accumulates the strings passed to it in a global +buffer, separated by newlines. It is useful for situations when you +want to build a message piece-by-piece (as if with \fBputs\fR) but +send that full message in a single piece (e.g. over a connection +opened with \fBsocket\fR or as part of a counted HTTP response). +.CS +proc accum {string} { + \fBglobal\fR accumulator + append accumulator $string \en +} +.CE + +.SH "SEE ALSO" +namespace(n), upvar(n), variable(n) + +.SH KEYWORDS +global, namespace, procedure, variable diff --git a/doc/pid.n b/doc/pid.n index 04999f0..409a3a0 100644 --- a/doc/pid.n +++ b/doc/pid.n @@ -1,50 +1,50 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: pid.n,v 1.7 2007/10/29 01:42:19 dkf Exp $ -'\" -.so man.macros -.TH pid n 7.0 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pid \- Retrieve process identifiers -.SH SYNOPSIS -\fBpid \fR?\fIfileId\fR? -.BE - -.SH DESCRIPTION -.PP -If the \fIfileId\fR argument is given then it should normally -refer to a process pipeline created with the \fBopen\fR command. -In this case the \fBpid\fR command will return a list whose elements -are the process identifiers of all the processes in the pipeline, -in order. -The list will be empty if \fIfileId\fR refers to an open file -that is not a process pipeline. -If no \fIfileId\fR argument is given then \fBpid\fR returns the process -identifier of the current process. -All process identifiers are returned as decimal strings. -.SH EXAMPLE -Print process information about the processes in a pipeline using the -SysV \fBps\fR program before reading the output of that pipeline: -.PP -.CS -set pipeline [open "| zcat somefile.gz | grep foobar | sort -u"] -# Print process information -exec ps -fp [\fBpid\fR $pipeline] >@stdout -# Print a separator and then the output of the pipeline -puts [string repeat - 70] -puts [read $pipeline] -close $pipeline -.CE - -.SH "SEE ALSO" -exec(n), open(n) - -.SH KEYWORDS -file, pipeline, process identifier +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: pid.n,v 1.8 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH pid n 7.0 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +pid \- Retrieve process identifiers +.SH SYNOPSIS +\fBpid \fR?\fIfileId\fR? +.BE + +.SH DESCRIPTION +.PP +If the \fIfileId\fR argument is given then it should normally +refer to a process pipeline created with the \fBopen\fR command. +In this case the \fBpid\fR command will return a list whose elements +are the process identifiers of all the processes in the pipeline, +in order. +The list will be empty if \fIfileId\fR refers to an open file +that is not a process pipeline. +If no \fIfileId\fR argument is given then \fBpid\fR returns the process +identifier of the current process. +All process identifiers are returned as decimal strings. +.SH EXAMPLE +Print process information about the processes in a pipeline using the +SysV \fBps\fR program before reading the output of that pipeline: +.PP +.CS +set pipeline [open "| zcat somefile.gz | grep foobar | sort -u"] +# Print process information +exec ps -fp [\fBpid\fR $pipeline] >@stdout +# Print a separator and then the output of the pipeline +puts [string repeat - 70] +puts [read $pipeline] +close $pipeline +.CE + +.SH "SEE ALSO" +exec(n), open(n) + +.SH KEYWORDS +file, pipeline, process identifier diff --git a/doc/proc.n b/doc/proc.n index f492224..1d5da1c 100644 --- a/doc/proc.n +++ b/doc/proc.n @@ -1,97 +1,97 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: proc.n,v 1.6 2007/10/29 01:42:19 dkf Exp $ -'\" -.so man.macros -.TH proc n "" Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -proc \- Create a Tcl procedure -.SH SYNOPSIS -\fBproc \fIname args body\fR -.BE - -.SH DESCRIPTION -.PP -The \fBproc\fR command creates a new Tcl procedure named -\fIname\fR, replacing -any existing command or procedure there may have been by that name. -Whenever the new command is invoked, the contents of \fIbody\fR will -be executed by the Tcl interpreter. -Normally, \fIname\fR is unqualified -(does not include the names of any containing namespaces), -and the new procedure is created in the current namespace. -If \fIname\fR includes any namespace qualifiers, -the procedure is created in the specified namespace. -\fIArgs\fR specifies the formal arguments to the -procedure. It consists of a list, possibly empty, each of whose -elements specifies -one argument. Each argument specifier is also a list with either -one or two fields. If there is only a single field in the specifier -then it is the name of the argument; if there are two fields, then -the first is the argument name and the second is its default value. -.PP -When \fIname\fR is invoked a local variable -will be created for each of the formal arguments to the procedure; its -value will be the value of corresponding argument in the invoking command -or the argument's default value. -Arguments with default values need not be -specified in a procedure invocation. However, there must be enough -actual arguments for all the -formal arguments that do not have defaults, and there must not be any extra -actual arguments. There is one special case to permit procedures with -variable numbers of arguments. If the last formal argument has the name -\fBargs\fR, then a call to the procedure may contain more actual arguments -than the procedure has formals. In this case, all of the actual arguments -starting at the one that would be assigned to \fBargs\fR are combined into -a list (as if the \fBlist\fR command had been used); this combined value -is assigned to the local variable \fBargs\fR. -.PP -When \fIbody\fR is being executed, variable names normally refer to -local variables, which are created automatically when referenced and -deleted when the procedure returns. One local variable is automatically -created for each of the procedure's arguments. -Global variables can only be accessed by invoking -the \fBglobal\fR command or the \fBupvar\fR command. -Namespace variables can only be accessed by invoking -the \fBvariable\fR command or the \fBupvar\fR command. -.PP -The \fBproc\fR command returns an empty string. When a procedure is -invoked, the procedure's return value is the value specified in a -\fBreturn\fR command. If the procedure does not execute an explicit -\fBreturn\fR, then its return value is the value of the last command -executed in the procedure's body. -If an error occurs while executing the procedure -body, then the procedure-as-a-whole will return that same error. -.SH EXAMPLES -This is a procedure that accepts arbitrarily many arguments and prints -them out, one by one. -.CS -\fBproc\fR printArguments args { - foreach arg $args { - puts $arg - } -} -.CE -.PP -This procedure is a bit like the \fBincr\fR command, except it -multiplies the contents of the named variable by the value, which -defaults to \fB2\fR: -.CS -\fBproc\fR mult {varName {multiplier 2}} { - upvar 1 $varName var - set var [expr {$var * $multiplier}] -} -.CE - -.SH "SEE ALSO" -info(n), unknown(n) - -.SH KEYWORDS -argument, procedure +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: proc.n,v 1.7 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH proc n "" Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +proc \- Create a Tcl procedure +.SH SYNOPSIS +\fBproc \fIname args body\fR +.BE + +.SH DESCRIPTION +.PP +The \fBproc\fR command creates a new Tcl procedure named +\fIname\fR, replacing +any existing command or procedure there may have been by that name. +Whenever the new command is invoked, the contents of \fIbody\fR will +be executed by the Tcl interpreter. +Normally, \fIname\fR is unqualified +(does not include the names of any containing namespaces), +and the new procedure is created in the current namespace. +If \fIname\fR includes any namespace qualifiers, +the procedure is created in the specified namespace. +\fIArgs\fR specifies the formal arguments to the +procedure. It consists of a list, possibly empty, each of whose +elements specifies +one argument. Each argument specifier is also a list with either +one or two fields. If there is only a single field in the specifier +then it is the name of the argument; if there are two fields, then +the first is the argument name and the second is its default value. +.PP +When \fIname\fR is invoked a local variable +will be created for each of the formal arguments to the procedure; its +value will be the value of corresponding argument in the invoking command +or the argument's default value. +Arguments with default values need not be +specified in a procedure invocation. However, there must be enough +actual arguments for all the +formal arguments that do not have defaults, and there must not be any extra +actual arguments. There is one special case to permit procedures with +variable numbers of arguments. If the last formal argument has the name +\fBargs\fR, then a call to the procedure may contain more actual arguments +than the procedure has formals. In this case, all of the actual arguments +starting at the one that would be assigned to \fBargs\fR are combined into +a list (as if the \fBlist\fR command had been used); this combined value +is assigned to the local variable \fBargs\fR. +.PP +When \fIbody\fR is being executed, variable names normally refer to +local variables, which are created automatically when referenced and +deleted when the procedure returns. One local variable is automatically +created for each of the procedure's arguments. +Global variables can only be accessed by invoking +the \fBglobal\fR command or the \fBupvar\fR command. +Namespace variables can only be accessed by invoking +the \fBvariable\fR command or the \fBupvar\fR command. +.PP +The \fBproc\fR command returns an empty string. When a procedure is +invoked, the procedure's return value is the value specified in a +\fBreturn\fR command. If the procedure does not execute an explicit +\fBreturn\fR, then its return value is the value of the last command +executed in the procedure's body. +If an error occurs while executing the procedure +body, then the procedure-as-a-whole will return that same error. +.SH EXAMPLES +This is a procedure that accepts arbitrarily many arguments and prints +them out, one by one. +.CS +\fBproc\fR printArguments args { + foreach arg $args { + puts $arg + } +} +.CE +.PP +This procedure is a bit like the \fBincr\fR command, except it +multiplies the contents of the named variable by the value, which +defaults to \fB2\fR: +.CS +\fBproc\fR mult {varName {multiplier 2}} { + upvar 1 $varName var + set var [expr {$var * $multiplier}] +} +.CE + +.SH "SEE ALSO" +info(n), unknown(n) + +.SH KEYWORDS +argument, procedure diff --git a/doc/puts.n b/doc/puts.n index 5459270..8db4b97 100644 --- a/doc/puts.n +++ b/doc/puts.n @@ -1,98 +1,98 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: puts.n,v 1.11 2007/10/29 01:42:19 dkf Exp $ -'\" -.so man.macros -.TH puts n 7.5 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -puts \- Write to a channel -.SH SYNOPSIS -\fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR -.BE - -.SH DESCRIPTION -.PP -Writes the characters given by \fIstring\fR to the channel given -by \fIchannelId\fR. -.PP -\fIChannelId\fR must be an identifier for an open channel such as a -Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return -value from an invocation of \fBopen\fR or \fBsocket\fR, or the result -of a channel creation command provided by a Tcl extension. The channel -must have been opened for output. -.PP -If no \fIchannelId\fR is specified then it defaults to -\fBstdout\fR. \fBPuts\fR normally outputs a newline character after -\fIstring\fR, but this feature may be suppressed by specifying the -\fB\-nonewline\fR switch. -.PP -Newline characters in the output are translated by \fBputs\fR to -platform-specific end-of-line sequences according to the current -value of the \fB\-translation\fR option for the channel (for example, -on PCs newlines are normally replaced with carriage-return-linefeed -sequences. -See the \fBfconfigure\fR manual entry for a discussion on ways in -which \fBfconfigure\fR will alter output. -.PP -Tcl buffers output internally, so characters written with \fBputs\fR -may not appear immediately on the output file or device; Tcl will -normally delay output until the buffer is full or the channel is -closed. -You can force output to appear immediately with the \fBflush\fR -command. -.PP -When the output buffer fills up, the \fBputs\fR command will normally -block until all the buffered data has been accepted for output by the -operating system. -If \fIchannelId\fR is in nonblocking mode then the \fBputs\fR command -will not block even if the operating system cannot accept the data. -Instead, Tcl continues to buffer the data and writes it in the -background as fast as the underlying file or device can accept it. -The application must use the Tcl event loop for nonblocking output -to work; otherwise Tcl never finds out that the file or device is -ready for more output data. -It is possible for an arbitrarily large amount of data to be -buffered for a channel in nonblocking mode, which could consume a -large amount of memory. -To avoid wasting memory, nonblocking I/O should normally -be used in an event-driven fashion with the \fBfileevent\fR command -(do not invoke \fBputs\fR unless you have recently been notified -via a file event that the channel is ready for more output data). -.SH EXAMPLES -Write a short message to the console (or wherever \fBstdout\fR is -directed): -.CS -\fBputs\fR "Hello, World!" -.CE -.PP -Print a message in several parts: -.CS -\fBputs\fR -nonewline "Hello, " -\fBputs\fR "World!" -.CE -.PP -Print a message to the standard error channel: -.CS -\fBputs\fR stderr "Hello, World!" -.CE -.PP -Append a log message to a file: -.CS -set chan [open my.log a] -set timestamp [clock format [clock seconds]] -\fBputs\fR $chan "$timestamp - Hello, World!" -close $chan -.CE - -.SH "SEE ALSO" -file(n), fileevent(n), Tcl_StandardChannels(3) - -.SH KEYWORDS -channel, newline, output, write +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: puts.n,v 1.12 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH puts n 7.5 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +puts \- Write to a channel +.SH SYNOPSIS +\fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR +.BE + +.SH DESCRIPTION +.PP +Writes the characters given by \fIstring\fR to the channel given +by \fIchannelId\fR. +.PP +\fIChannelId\fR must be an identifier for an open channel such as a +Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return +value from an invocation of \fBopen\fR or \fBsocket\fR, or the result +of a channel creation command provided by a Tcl extension. The channel +must have been opened for output. +.PP +If no \fIchannelId\fR is specified then it defaults to +\fBstdout\fR. \fBPuts\fR normally outputs a newline character after +\fIstring\fR, but this feature may be suppressed by specifying the +\fB\-nonewline\fR switch. +.PP +Newline characters in the output are translated by \fBputs\fR to +platform-specific end-of-line sequences according to the current +value of the \fB\-translation\fR option for the channel (for example, +on PCs newlines are normally replaced with carriage-return-linefeed +sequences. +See the \fBfconfigure\fR manual entry for a discussion on ways in +which \fBfconfigure\fR will alter output. +.PP +Tcl buffers output internally, so characters written with \fBputs\fR +may not appear immediately on the output file or device; Tcl will +normally delay output until the buffer is full or the channel is +closed. +You can force output to appear immediately with the \fBflush\fR +command. +.PP +When the output buffer fills up, the \fBputs\fR command will normally +block until all the buffered data has been accepted for output by the +operating system. +If \fIchannelId\fR is in nonblocking mode then the \fBputs\fR command +will not block even if the operating system cannot accept the data. +Instead, Tcl continues to buffer the data and writes it in the +background as fast as the underlying file or device can accept it. +The application must use the Tcl event loop for nonblocking output +to work; otherwise Tcl never finds out that the file or device is +ready for more output data. +It is possible for an arbitrarily large amount of data to be +buffered for a channel in nonblocking mode, which could consume a +large amount of memory. +To avoid wasting memory, nonblocking I/O should normally +be used in an event-driven fashion with the \fBfileevent\fR command +(do not invoke \fBputs\fR unless you have recently been notified +via a file event that the channel is ready for more output data). +.SH EXAMPLES +Write a short message to the console (or wherever \fBstdout\fR is +directed): +.CS +\fBputs\fR "Hello, World!" +.CE +.PP +Print a message in several parts: +.CS +\fBputs\fR -nonewline "Hello, " +\fBputs\fR "World!" +.CE +.PP +Print a message to the standard error channel: +.CS +\fBputs\fR stderr "Hello, World!" +.CE +.PP +Append a log message to a file: +.CS +set chan [open my.log a] +set timestamp [clock format [clock seconds]] +\fBputs\fR $chan "$timestamp - Hello, World!" +close $chan +.CE + +.SH "SEE ALSO" +file(n), fileevent(n), Tcl_StandardChannels(3) + +.SH KEYWORDS +channel, newline, output, write diff --git a/doc/unset.n b/doc/unset.n index 655ec0f..c21155c 100644 --- a/doc/unset.n +++ b/doc/unset.n @@ -1,63 +1,63 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: unset.n,v 1.11 2007/10/29 01:42:19 dkf Exp $ -'\" -.so man.macros -.TH unset n 8.4 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -unset \- Delete variables -.SH SYNOPSIS -\fBunset \fR?\fI\-nocomplain\fR? ?\fI\-\-\fR? ?\fIname name name ...\fR? -.BE -.SH DESCRIPTION -.PP -This command removes one or more variables. -Each \fIname\fR is a variable name, specified in any of the -ways acceptable to the \fBset\fR command. -If a \fIname\fR refers to an element of an array then that -element is removed without affecting the rest of the array. -If a \fIname\fR consists of an array name with no parenthesized -index, then the entire array is deleted. -The \fBunset\fR command returns an empty string as result. -If \fI\-nocomplain\fR is specified as the first argument, any possible -errors are suppressed. The option may not be abbreviated, in order to -disambiguate it from possible variable names. The option \fI\-\-\fR -indicates the end of the options, and should be used if you wish to -remove a variable with the same name as any of the options. -If an error occurs, any variables after the named one causing the error not -deleted. An error can occur when the named variable does not exist, or the -name refers to an array element but the variable is a scalar, or the name -refers to a variable in a non-existent namespace. -.SH EXAMPLE -Create an array containing a mapping from some numbers to their -squares and remove the array elements for non-prime numbers: -.CS -array set squares { - 1 1 6 36 - 2 4 7 49 - 3 9 8 64 - 4 16 9 81 - 5 25 10 100 -} - -puts "The squares are:" -parray squares - -\fBunset\fR squares(1) squares(4) squares(6) -\fBunset\fR squares(8) squares(9) squares(10) - -puts "The prime squares are:" -parray squares -.CE -.SH "SEE ALSO" -set(n), trace(n), upvar(n) -.SH KEYWORDS -remove, variable +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 2000 Ajuba Solutions. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: unset.n,v 1.12 2007/10/29 17:17:54 dgp Exp $ +'\" +.so man.macros +.TH unset n 8.4 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +unset \- Delete variables +.SH SYNOPSIS +\fBunset \fR?\fI\-nocomplain\fR? ?\fI\-\-\fR? ?\fIname name name ...\fR? +.BE +.SH DESCRIPTION +.PP +This command removes one or more variables. +Each \fIname\fR is a variable name, specified in any of the +ways acceptable to the \fBset\fR command. +If a \fIname\fR refers to an element of an array then that +element is removed without affecting the rest of the array. +If a \fIname\fR consists of an array name with no parenthesized +index, then the entire array is deleted. +The \fBunset\fR command returns an empty string as result. +If \fI\-nocomplain\fR is specified as the first argument, any possible +errors are suppressed. The option may not be abbreviated, in order to +disambiguate it from possible variable names. The option \fI\-\-\fR +indicates the end of the options, and should be used if you wish to +remove a variable with the same name as any of the options. +If an error occurs, any variables after the named one causing the error not +deleted. An error can occur when the named variable does not exist, or the +name refers to an array element but the variable is a scalar, or the name +refers to a variable in a non-existent namespace. +.SH EXAMPLE +Create an array containing a mapping from some numbers to their +squares and remove the array elements for non-prime numbers: +.CS +array set squares { + 1 1 6 36 + 2 4 7 49 + 3 9 8 64 + 4 16 9 81 + 5 25 10 100 +} + +puts "The squares are:" +parray squares + +\fBunset\fR squares(1) squares(4) squares(6) +\fBunset\fR squares(8) squares(9) squares(10) + +puts "The prime squares are:" +parray squares +.CE +.SH "SEE ALSO" +set(n), trace(n), upvar(n) +.SH KEYWORDS +remove, variable -- cgit v0.12