chan configure

chan configure, a built-in Tcl command, sets and retrieves configuration values for channels. It replaces the older fconfigure.


chan configure channelId
chan configure channelId name
chan configure channelId name value ?name value ...?


official reference

See Also



Configure a channel so that no buffering is done, meaning that all input and output are immediately flushed through the channel:

chan configure stdout -buffering none

Configure a channel to be byte-oriented, meaning that no newline conversions are performed, that on input each byte is interpreted as a separate Unicocde character, and that on output the bottom 8 bits of the number that is the code point for each character are written to the channel:

chan configure $binaryDataFile -translation binary


The binary encoding is an alias for iso8859-1 which is a subset of Unicode comprised of the code points \u0000-\u00ff and contains the characters in the Basic Latin and the Latin-1 Supplement Unicode code charts. -encoding binary was introduced as a migration aid to help with either the transition from Tcl 7.6 to 8.0 or the transition from 8.0 to 8.1.

Warning: -encoding binary turns off -translation, but -encoding iso8859-1 does not.

ref dgp and kbk in Tcl Chatroom ,2013-12-02

When data is read from a binary channel, each byte constitutes the Unicode character indicated by that byte.

When a string is put into a binary channel, the lower 8 bits of the number representing the code point of each character are written to the channel. If every character in the string has a code point of 255 or less no data is lost.

stdout encoding bug

RS 2015-04-13: On Windows 7, stdout (if not redirected) breaks in a funny way when the encoding is changed - notice the "%" prompt:

 % fconfigure stdout -encoding utf-8
 % fconfigure stdout -encoding utf-8

With longer output, the whole console (Cygwin bash in cmd.exe) freezes and can only be closed, but no longer be used. In cmd.exe without Cygwin, Ctrl-C makes the console responsive again.

A workaround in both cases is to pipe stdout through cat. When stdout is redirected to a file, the problem is likewise not seen.

This behavior was not the case in Tcl 8.4:

 % fconfigure stdout -encoding utf-8

DKF: This is a consequence of the special channel type used to handle the console on Windows (which uses direct writing to the console API using unicode characters). Its encoding should not be changed, but we can't prevent that from happening without extra magic to let channel types veto changes to generic properties (something that currently isn't supported).

Tcl 8.4 “worked” because it was doing the wrong thing entirely that just happened to be more resistant to this problem.


LV 2008 02 28:

Some of the wiki pages talk about the construct,

chan configure $serial_port -mode $baudRate,$plex,$bits,$polarity

or some such thing. The -mode flag, used for specifying baud rate, etc, has moved to open now. I don't know how one would change those values on an open descriptor...