'''[http://www.tcl.tk/man/tcl/TclCmd/chan.htm%|%chan]''', a [Tcl Commands%|%built-in] Tcl command, manipulates [channel%|%channels].



** See Also **

   [Additional file commands]:   Tips and tricks for processing the content in a channel.

   [chan mode]:   an example of extening the `chan` ensemble

   [stacked channel]:   

   [transform]:   

   `[ycl%|%ycl chan connect]`:   Connect the output of one channel to the input of another.  Uses a separate thread to avoid deadlocks.

   `[ycl%|%ycl chan osin/osout/osboth]`:   Creates a `[chan pipe]` facade around another channel, making it possible, for example to use a [reflected channel] with `<@`.  Can also be used to work around the fact that `[exec]` (and therefore `[open]`) ignore encoding and translation in the case of `<@`.



** Synopsis **

    :   '''chan''' ''action'' ?''arg arg ...''?



** Documentation **

    [http://www.tcl.tk/man/tcl/TclCmd/chan.htm%|%official reference]:   

    [TIP] [http://www.tcl.tk/cgi-bin/tct/tip/208%|%208]:   add `chan`



** Description **

Introduced in [Tcl] [Changes in Tcl/Tk 8.5%|%8.5].

`chan` provides various operations on a channel, including many that have been
available using a mix of other commands.  ''action'' indicates what to do with
the channel. Any unique abbreviation for an ''action'' is acceptable. The valid
''actions''s are:


*** New actions (no analog in rest of Tcl) ***

   '''`[chan create]`''' ''mode cmdPrefix'':   creates a channel using a ''cmdPrefix'' (e.g., an [namespace ensemble%|%ensemble] or [TclOO%|%object])

   '''[chan pending]''' ''mode'' ''channelId'':   returns the number of bytes (of input or output, depending on ''mode'') buffered internally

   '''[chan pop]''' ''channelId'':   pop one [transform] off a [stacked channel]

   '''[chan postevent]''' ''channelId eventSpec'':   generate event on channel (which it must be listening for)

   '''[chan push]''' ''channelId'' ''cmdPrefix'':   stack a [transform] on top of the ''channel''

   '''[chan pipe]''':   create a standalone pipe and return a pair of file descriptors for its read and write ends, in this order ([TIP] [http://tip.tcl.tk/304.html#304], available in Tcl >= 8.6).

   '''[chan truncate]''' ''channelId'' ?''length''?:   truncate the file behind the channel

----

[AMG]: `chan` aggregates all the commands you'll need for working with
channels, ''except'' creating traditional channels (it can only create pipes
and [reflected channel%|%reflected channels]).  Use `[open]` or `[socket]` or an extension
command, same as always.  If you find a core channel command not incorporated
as a `chan` subcommand, please report it.


*** Renamed actions (available as another command as well) ***

   '''[chan blocked]''' ''channelId'':   supercedes [fblocked]

   '''[chan close]''' ''channelId'':   supercedes [close]

   '''[chan configure]''' ''channelId'' ?''optionName''? ?''value''? ?''optionName value''?...:   supercedes [fconfigure]

   '''[chan copy]''' ''inputChan outputChan'' ?''options...''?:   same as [fcopy]
   '''[chan eof]''' ''channelId'':   supercedes [eof]

   '''[chan event]''' ''channelId event'' ?''script''?:   supercedes [fileevent]

   '''[chan flush]''' ''channelId'':   supercedes [flush]

   '''[chan gets]''' ''channelId'' ?''varName''?:   supercedes [gets]

   '''[chan names]''' ?''globPattern''?:   supercedes [file channels]

   '''[chan puts]''' ?'''-nonewline'''? ?''channelId''? ''string'':   supercedes [puts]

   '''[chan read]''' ''channelId'' ?''numChars''?:    
  
   '''[chan read]''' ?'''-nonewline'''? ''channelId'':   supercedes [read]

   '''[chan seek]''' ''channelId offset'' ?''origin''?:   supercedes [seek]

   '''[chan tell]''' ''channelId'':   supercedes [tell]



** History **

[RS]: History sometimes runs in circles... [Tcl 2.1] didn't have commands
dealing with channels. [Peter da Silva] added the "stream" extension, where one
could write

======
stream fp open $filename r
set x [stream fp gets]
stream fp close
======

Later, the parts of "stream" went into the core as separate commands. Still
later, in 8.5, they get reunited again in [chan], which arguably makes the
command set leaner, but scripts wordier...

<<categories>> Changes in Tcl/Tk 8.5 | Channel | Command