Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tcl_StackChannel(3)	    Tcl	Library	Procedures	   Tcl_StackChannel(3)

______________________________________________________________________________

NAME
       Tcl_StackChannel,  Tcl_UnstackChannel,  Tcl_GetStackedChannel, Tcl_Get-
       TopChannel - manipulate stacked I/O channels

SYNOPSIS
       #include	<tcl.h>

       Tcl_Channel
       Tcl_StackChannel(interp,	typePtr, clientData, mask, channel)

       int
       Tcl_UnstackChannel(interp, channel)

       Tcl_Channel
       Tcl_GetStackedChannel(channel)

       Tcl_Channel
       Tcl_GetTopChannel(channel)

ARGUMENTS
       Tcl_Interp *interp (in)			Interpreter for	error  report-
						ing.

       const Tcl_ChannelType *typePtr (in)	The new	channel	I/O procedures
						to use for channel.

       void *clientData	(in)			Arbitrary  one-word  value  to
						pass  to  channel  I/O	proce-
						dures.

       int mask	(in)				Conditions under which channel
						will  be  used:	OR-ed combina-
						tion	 of	 TCL_READABLE,
						TCL_WRITABLE   and  TCL_EXCEP-
						TION.  This can	be a subset of
						the operations	currently  al-
						lowed on channel.

       Tcl_Channel channel (in)			An  existing  Tcl channel such
						as returned by Tcl_CreateChan-
						nel.
______________________________________________________________________________

DESCRIPTION
       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.

       The Tcl_ChannelType version  currently  supported  is  TCL_CHANNEL_VER-
       SION_5.	See Tcl_CreateChannel for details.

       Tcl_StackChannel	 stacks	 a new channel on an existing channel with the
       same name that was registered for channel by Tcl_RegisterChannel.

       Tcl_StackChannel	works by creating a new	channel	structure and  placing
       itself  on  top	of  the	 channel stack.	 EOL translation, encoding and
       buffering options are shared between all	channels in  the  stack.   The
       hidden  channel	does  no buffering, newline translations, or character
       set encoding.  Instead, the buffering, newline translations, and	encod-
       ing functions all remain	at the top of the channel stack.  A pointer to
       the new top channel structure is	returned.  If  an  error  occurs  when
       stacking	the channel, NULL is returned instead.

       The mask	parameter specifies the	operations that	are allowed on the new
       channel.	 These can be a	subset of the operations allowed on the	origi-
       nal  channel.   For  example, a read-write channel may become read-only
       after the Tcl_StackChannel call.

       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.

       Tcl_UnstackChannel reverses the process.	 The old channel is associated
       with  the  channel  name,  and	the   processing   module   added   by
       Tcl_StackChannel	 is  destroyed.	  If  there  is	 no  old channel, then
       Tcl_UnstackChannel is equivalent	to Tcl_Close.  If an error occurs  un-
       stacking	 the  channel,	TCL_ERROR is returned, otherwise TCL_OK	is re-
       turned.

       Tcl_GetTopChannel returns the top channel in the	stack of channels  the
       supplied	channel	is part	of.

       Tcl_GetStackedChannel  returns  the  channel  in	 the stack of channels
       which is	just below the supplied	channel.

SEE ALSO
       Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n)

KEYWORDS
       channel,	compression

Tcl				      8.3		   Tcl_StackChannel(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_UnstackChannel.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help