Set and get options on a channel

Synopsis

• fconfigure channelId
  
• fconfigure channelId name
  
• fconfigure channelId name value ?name value ...?

Description

The fconfigure command sets and retrieves options for channels. ChannelId identifies the channel for which to set or query an option. If no name or value arguments are supplied, the command returns a list containing alternating option names and values for the channel. If name is supplied but no value then the command returns the current value of the given option. If one or more pairs of name and value are supplied, the command sets each of the named options to the corresponding value; in this case the return value is an empty string.

The options described below are supported for all channels. In addition, each channel type may add options that only it supports.

-blocking boolean

The -blocking option determines whether I/O operations on the channel can cause the process to block indefinitely. The value of the option must be a proper boolean value. Channels are normally in blocking mode; if a channel is placed into nonblocking mode it will affect the operation of the gets, read, puts, flush, and close commands; see the documentation for those commands for details. Setting stdin, stdout, or stderr into nonblocking mode is disallowed because it could interfere with the operation of the parent process. For nonblocking mode to work correctly, the application must be using the Tcl event loop (e.g. by calling Tcl_DoOneEvent or invoking the vwait command).

-buffering newValue

If newValue is full then the I/O system will buffer output until its internal buffer is full or until the flush command is invoked. If newValue is line, then the I/O system will automatically flush output for the channel whenever a newline character is output. If newValue is none, the I/O system will flush automatically after every output operation. The default is for -buffering to be set to full except for channels that connect to terminal-like devices; for these channels the initial setting is line.

-buffersize newSize

Newvalue must be an integer; its value is used to set the size of buffers, in bytes, subsequently allocated for this channel to store input or output. Newvalue must be between ten and one million, allowing buffers of ten to one million bytes in size.

-translation mode

In Tcl scripts the end of a line is always represented using a single newline character (\n). However, in actual files and devices the end of a line may be represented differently on different platforms, or even for different devices on the same platform. For example, under UNIX newlines are used in files, whereas carriage-return-linefeed sequences are normally used in network connections. The Tcl I/O system automatically translates between the newlines used internally and whatever end-ofline characters are appropriate for the underlying files and devices. The -translation option selects the end-of-line character(s) to use on the file or device for a particular channel. Note that if you want no translations at all applied to input and output on a specific channel, you should set it to lf mode - see below. The following values are currently supported:

cr

The end of a line in the underlying file or device is represented by a single carriage return character. During input commands such as read Tcl translates carriage returns to newline characters, and during output commands such as puts Tcl translates newline characters to carriage returns. This mode is typically used on Macintosh platforms.

translates

carriage-return-linefeed sequences to newlines, and during output commands such as puts Tcl translates newline characters to carriage-return-linefeed sequences. This mode is typically used on Windows platforms and for network connections.

lf

The end of a line in the underlying file or device is represented by a single newline (linefeed) character. In this mode no translations occur during either intput or output. This mode is typically used on UNIX platforms.

platform

nel according to the platform on which the application is executing; for sockets on all platforms Tcl chooses crlf, for all Unix flavors, it chooses lf, for the Macintosh platform it chooses cr and for the various flavors of Windows it chooses crlf.

auto In this mode Tcl sets the translation mode based on the first valid end-of-line sequence it sees during input on the channel. If output is generated for the channel before an end-of-line sequence has appeared on input, then Tcl uses platform mode for the channel. The default setting for -translation is auto.

See Also

close, flush, gets, puts, read

Keywords

blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation