'\"
'\" 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 <tcl.h>\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