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


** See Also **

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

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



    :   '''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
and reflected channels).  Use `[open]` or `[socket]` or an extension
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 **
** Determine EOL Sequence Length **

[MG]: has just needed to find out how long the EOL sequence in a particular file
was. Checking `fconfigure $fid -translation` didn't help (as it was just 'auto'
on the read, and always crlf (Win XP) on the write, even if the file used Unix
line-endings). Came up with this (which is possibly obvious, but I'm rather
pleased with myself anyway;)

======
proc lineEndingSize file {
    set fid [open $file r]
    chan gets $fid line
    set size [expr {[chan tell $fid] - [string bytelength $line]}]
    close $fid
    return $size;
}
======

[DKF]: That can go wrong. The problem is that you need to use the encoded
length of the string read, and some encodings have multiple ways of encoding a
particular character. This is all rather nasty; even guessing based on the
value of `[fconfigure] -encoding` can go wrong! So instead try this:

======
proc lineEndingSize file {
   set f [open $file]
   gets $f line
   set after [tell $f]
   seek $f 0
   read $f [string length $line]
   set before [tell $f]
   close $f
   return [expr {$after - $before}]
}
======

[MG]: I'll try that instead, thanks :)




[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