From 66a17ecd6338f4871396c407f750c65400c8ad72 Mon Sep 17 00:00:00 2001 From: welch Date: Fri, 2 Jul 1999 19:51:14 +0000 Subject: Name change from Tcl_ReplaceChannel to Tcl_StackChannel --- doc/ChnlReplace.3 | 95 -------------------------------------------------- doc/ChnlStack.3 | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 95 deletions(-) delete mode 100644 doc/ChnlReplace.3 create mode 100644 doc/ChnlStack.3 diff --git a/doc/ChnlReplace.3 b/doc/ChnlReplace.3 deleted file mode 100644 index 3c56cb3..0000000 --- a/doc/ChnlReplace.3 +++ /dev/null @@ -1,95 +0,0 @@ -'\" -'\" Copyright (c) 1999 Scriptics Corporation -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: ChnlReplace.3,v 1.3 1999/06/30 17:46:51 welch Exp $ -.so man.macros -.TH Tcl_ReplaceChannel 3 8.2 Tcl "Tcl Library Procedures" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -Tcl_ReplaceChannel, Tcl_UndoReplaceChannel \- stack an I/O channel on top of another, and undo it -.SH SYNOPSIS -.nf -.nf -\fB#include \fR -.sp -Tcl_Channel -\fBTcl_ReplaceChannel\fR(\fIinterp, typePtr, clientData, mask, channel\fR) -.sp -void -\fBTcl_UndoReplaceChannel\fR(\fIinterp, channel\fR) -.sp -.SH ARGUMENTS -.AS Tcl_ChannelType -.AP Tcl_Interp *interp in -The Tcl interpreter in which \fIchannel\fP is registered. -.AP Tcl_ChannelType *typePtr in -The new channel I/O procedures to use for \fIchannel\fP. -.AP ClientData clientData in -Arbitrary one-word value to pass to channel I/O procedures. -.AP int mask in -Conditions under which \fIchannel\fR will be used: OR-ed combination of -\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. -This can be a subset of the operations currently allowed on \fIchannel\fP. -.AP Tcl_Channel channel in -An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR. -.BE - -.SH DESCRIPTION -.PP -These functions are for use by extensions that add processing -layers on top of Tcl I/O channels. Examples include compression -and encryption modules. These functions transparently stack and unstack -a new channel on top of an existing one. -Any number of channels can be stacked together. -.PP -\fBTcl_ReplaceChannel\fR -replaces an existing \fIchannel\fP with a new channel by -the same name that was registered for \fIchannel\fP -with \fBTcl_RegisterChannel\fP. -Because the channel name is the same, all Tcl-level I/O -operations will automatically use the new channel instead -of the old one. -The new channel uses the I/O channel functions -defined in \fItypePtr\fP, and the channel functions are passed -the new \fIclientData\fP. -A pointer to the new channel structure is returned. -If an error occurs when creating the new channel, -NULL is returned instead. -.PP -The \fImask\fP parameter specifies the operations that -are allowed on the new channel. -These can be a subset of the operations allowed on the original channel. -For example, a read-write channel may become -read-only after the \fBTcl_ReplaceChannel\fR call. -.PP -The old Tcl_Channel data structure -is linked to the new channel -using the \fBsupercedes\fP structure member of the -Tcl_Channel that is returned by -\fBTcl_ReplaceChannel\fR. -The new channel functions -should use the standard channel APIs like -\fBTcl_Read\fP, \fBTcl_ReadChars\fP and \fBTcl_Write\fP -to get at the underlying channel instead of -accessing the other channel data structure directly. -.PP -Closing the new channel closes the channels stacked below it. -The close of stacked channels is executed in a way that -allows buffered data to be properly flushed. -.PP -\fBTcl_UndoReplaceChannel\fP reverses the process. -The old channel is associated with the channel name, -and the new channel created by -\fBTcl_ReplaceChannel\fR is destroyed. -If there is no old channel, then \fBTcl_UndoReplaceChannel\fP -is equivalent to \fBTcl_Close\fP . - -.SH "SEE ALSO" -Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). - -.SH KEYWORDS -channel, compression diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3 new file mode 100644 index 0000000..2d9c2ec --- /dev/null +++ b/doc/ChnlStack.3 @@ -0,0 +1,102 @@ +'\" +'\" Copyright (c) 1999 Scriptics Corporation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: ChnlStack.3,v 1.1 1999/07/02 19:51:14 welch Exp $ +.so man.macros +.TH Tcl_StackChannel 3 8.2 Tcl "Tcl Library Procedures" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcl_StackChannel, Tcl_UnstackChannel \- stack an I/O channel on top of another, and undo it +.SH SYNOPSIS +.nf +.nf +\fB#include \fR +.sp +Tcl_Channel +\fBTcl_StackChannel\fR(\fIinterp, typePtr, clientData, mask, channel\fR) +.sp +void +\fBTcl_UnstackChannel\fR(\fIinterp, channel\fR) +.sp +Tcl_Channel +\fBTcl_GetStackedChannel\fR(\fIchannel\fR) +.sp +.SH ARGUMENTS +.AS Tcl_ChannelType +.AP Tcl_Interp *interp in +Interpreter for error reporting - can be NULL. +.AP Tcl_ChannelType *typePtr in +The new channel I/O procedures to use for \fIchannel\fP. +.AP ClientData clientData in +Arbitrary one-word value to pass to channel I/O procedures. +.AP int mask in +Conditions under which \fIchannel\fR will be used: OR-ed combination of +\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. +This can be a subset of the operations currently allowed on \fIchannel\fP. +.AP Tcl_Channel channel in +An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR. +.BE + +.SH DESCRIPTION +.PP +These functions are for use by extensions that add processing +layers to Tcl I/O channels. Examples include compression +and encryption modules. These functions transparently stack and unstack +a new channel on top of an existing one. +Any number of channels can be stacked together. +.PP +\fBTcl_StackChannel\fR +replaces an existing \fIchannel\fP with a new channel by +the same name that was registered for \fIchannel\fP +with \fBTcl_RegisterChannel\fP. +.PP +\fBTcl_StackChannel\fR +works by creating a new channel structure under the existing +\fIchannel\fP and pushing the existing channel functions +down to the newly created channel. +The hidden channel does no buffering, newline translations, +or character set encoding. +Instead, +the buffering, newline translations, and +encoding functions all remain at the top of the channel stack. +The top-most channel gets changed to use the +I/O channel functions +defined in \fItypePtr\fP, and the channel functions are passed +the new \fIclientData\fP. +The existing \fIchannel\fP structure is modified in place, +so C applications that continue to use \fIchannel\fP will +also see the effects of the new processing module. +A pointer to a new channel structure is returned, +although this new data structure is the one that has been +pushed down below the top of the channel module stack. +(This pointer can also be obtained with the +\fBTcl_GetStackedChannel\fP call.) +If an error occurs when stacking the channel, +NULL is returned instead. +.PP +The \fImask\fP parameter specifies the operations that +are allowed on the new channel. +These can be a subset of the operations allowed on the original channel. +For example, a read-write channel may become +read-only after the \fBTcl_StackChannel\fR call. +.PP +Closing a channel closes the channels stacked below it. +The close of stacked channels is executed in a way that +allows buffered data to be properly flushed. +.PP +\fBTcl_UnstackChannel\fP reverses the process. +The old channel is associated with the channel name, +and the processing module added by +\fBTcl_StackChannel\fR is destroyed. +If there is no old channel, then \fBTcl_UnstackChannel\fP +is equivalent to \fBTcl_Close\fP . + +.SH "SEE ALSO" +Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). + +.SH KEYWORDS +channel, compression -- cgit v0.12