Tcl Built-In Commands - fconfigure manual page

  NAME
    fconfigure - Set and get options on a channel
  SYNOPSIS
    fconfigure channelId
    fconfigure channelId name
    fconfigure channelId name value ?name value ...?
  DESCRIPTION
    -blocking boolean
    -buffering newValue
    -buffersize newSize
    -encoding name
    -eofchar char
    -eofchar {inChar outChar}
    -translation mode
    -translation {inMode outMode}
      auto
      binary
      cr
      crlf
      lf
  STANDARD CHANNELS
  SERIAL PORT CONFIGURATION OPTIONS
    -mode baud,parity,data,stop
    -handshake type
    -queue
    -timeout msec
    -ttycontrol {signal boolean signal boolean ...}
    -ttystatus
    -xchar {xonChar xoffChar}
    -pollinterval msec
    -sysbuffer inSize
    -sysbuffer {inSize outSize}
    -lasterror
  SERIAL PORT SIGNALS
    TXD(output)
    RXD(input)
    RTS(output)
    CTS(input)
    DTR(output)
    DSR(input)
    DCD(input)
    RI(input)
    BREAK
  ERROR CODES (Windows only)
    RXOVER:
    TXFULL
    OVERRUN
    RXPARITY
    FRAME
    BREAK
  SEE ALSO
  KEYWORDS

### NAME

fconfigure - 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 and must refer to an open channel such as a Tcl standard channel (stdin, stdout, or stderr), the return value from an invocation of open or socket, or the result of a channel creation command provided by a Tcl extension.

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. See the manual entry for the command that creates each type of channels for the options that that specific type of channel supports. For example, see the manual entry for the socket command for its additional options.

-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. 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. Additionally, stdin and stdout are initially set to line, and stderr is set to none.

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

-encoding name
  This option is used to specify the encoding of the channel, so that the data can be converted to and from Unicode for use in Tcl. For instance, in order for Tcl to read characters from a Japanese file in shiftjis and properly process and display the contents, the encoding would be set to shiftjis. Thereafter, when reading from the channel, the bytes in the Japanese file would be converted to Unicode as they are read. Writing is also supported - as Tcl strings are written to the channel they will automatically be converted to the specified encoding on output.

  If a file contains pure binary data (for instance, a JPEG image), the encoding for the channel should be configured to be binary. Tcl will then assign no interpretation to the data in the file and simply read or write raw bytes. The Tcl binary command can be used to manipulate this byte-oriented data.

  The default encoding for newly opened channels is the same platform- and locale-dependent system encoding used for interfacing with the operating system.

-eofchar char

-eofchar {inChar outChar}
  This option supports DOS file systems that use Control-z (\x1a) as an end of file marker. If char is not an empty string, then this character signals end-of-file when it is encountered during input. For output, the end-of-file character is output when the channel is closed. If char is the empty string, then there is no special end of file character marker. For read-write channels, a two-element list specifies the end of file marker for input and output, respectively. As a convenience, when setting the end-of-file character for a read-write channel you can specify a single value that will apply to both reading and writing. When querying the end-of-file character of a read-write channel, a two-element list will always be returned. The default value for -eofchar is the empty string in all cases except for files under Windows. In that case the -eofchar is Control-z (\x1a) for reading and the empty string for writing.

-translation mode

-translation {inMode outMode}
  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. On input (i.e., with gets and read) the Tcl I/O system automatically translates the external end-of-line representation into newline characters. Upon output (i.e., with puts), the I/O system translates newlines to the external end-of-line representation. The default translation mode, auto, handles all the common cases automatically, but the -translation option provides explicit control over the end of line translations.

  The value associated with -translation is a single item for read-only and write-only channels. The value is a two-element list for read-write channels; the read translation mode is the first element of the list, and the write translation mode is the second element. As a convenience, when setting the translation mode for a read-write channel you can specify a single value that will apply to both reading and writing. When querying the translation mode of a read-write channel, a two-element list will always be returned. The following values are currently supported:

  auto
    As the input translation mode, auto treats any of newline (lf), carriage return (cr), or carriage return followed by a newline (crlf) as the end of line representation. The end of line representation can even change from line-to-line, and all cases are translated to a newline. As the output translation mode, auto chooses a platform specific representation; 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. The default setting for -translation is auto for both input and output.

  binary
    No end-of-line translations are performed. This is nearly identical to lf mode, except that in addition binary mode also sets the end-of-file character to the empty string (which disables it) and sets the encoding to binary (which disables encoding filtering). See the description of -eofchar and -encoding for more information.

  cr
    The end of a line in the underlying file or device is represented by a single carriage return character. As the input translation mode, cr mode converts carriage returns to newline characters. As the output translation mode, cr mode translates newline characters to carriage returns. This mode is typically used on Macintosh platforms.

  crlf
    The end of a line in the underlying file or device is represented by a carriage return character followed by a linefeed character. As the input translation mode, crlf mode converts carriage-return-linefeed sequences to newline characters. As the output translation mode, crlf mode 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 input or output. This mode is typically used on UNIX platforms.

### STANDARD CHANNELS

The Tcl standard channels (stdin, stdout, and stderr) can be configured through this command like every other channel opened by the Tcl library. Beyond the standard options described above they will also support any special option according to their current type. If, for example, a Tcl application is started by the inet super-server common on Unix system its Tcl standard channels will be sockets and thus support the socket options.

### SERIAL PORT CONFIGURATION OPTIONS

If channelId refers to a serial port, then the following additional configuration options are available on Windows and Unix systems with a POSIX serial interface:

-mode baud,parity,data,stop
  This option is a set of 4 comma-separated values: the baud rate, parity, number of data bits, and number of stop bits for this serial port. The baud rate is a simple integer that specifies the connection speed. Parity is one of the following letters: n, o, e, m, s; respectively signifying the parity options of ``none'', ``odd'', ``even'', ``mark'', or ``space''. Data is the number of data bits and should be an integer from 5 to 8, while stop is the number of stop bits and should be the integer 1 or 2.

-handshake type
  (Windows and Unix). This option is used to setup automatic handshake control. Note that not all handshake types maybe supported by your operating system. The type parameter is case-independent. If type is none then any handshake is switched off. rtscts activates hardware handshake. Hardware handshake signals are described below. For software handshake xonxoff the handshake characters can be redefined with -xchar. An additional hardware handshake dtrdsr is available only under Windows. There is no default handshake configuration, the initial value depends on your operating system settings. The -handshake option cannot be queried.

-queue
  (Windows and Unix). The -queue option can only be queried. It returns a list of two integers representing the current number of bytes in the input and output queue respectively.

-timeout msec
  (Windows and Unix). This option is used to set the timeout for blocking read operations. It specifies the maximum interval between the reception of two bytes in milliseconds. For Unix systems the granularity is 100 milliseconds. The -timeout option does not affect write operations or nonblocking reads. This option cannot be queried.

-ttycontrol {signal boolean signal boolean ...}
  (Windows and Unix). This option is used to setup the handshake output lines (see below) permanently or to send a BREAK over the serial line. The signal names are case-independent. {RTS 1 DTR 0} sets the RTS output to high and the DTR output to low. The BREAK condition (see below) is enabled and disabled with {BREAK 1} and {BREAK 0} respectively. It's not a good idea to change the RTS (or DTR) signal with active hardware handshake rtscts (or dtrdsr). The result is unpredictable. The -ttycontrol option cannot be queried.

-ttystatus
  (Windows and Unix). The -ttystatus option can only be queried. It returns the current modem status and handshake input signals (see below). The result is a list of signal,value pairs with a fixed order, e.g. {CTS 1 DSR 0 RING 1 DCD 0}. The signal names are returned upper case.

-xchar {xonChar xoffChar}
  (Windows and Unix). This option is used to query or change the software handshake characters. Normally the operating system default should be DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters.

-pollinterval msec
  (Windows only). This option is used to set the maximum time between polling for fileevents. This affects the time interval between checking for events throughout the Tcl interpreter (the smallest value always wins). Use this option only if you want to poll the serial port more or less often than 10 msec (the default).

-sysbuffer inSize

-sysbuffer {inSize outSize}
  (Windows only). This option is used to change the size of Windows system buffers for a serial channel. Especially at higher communication rates the default input buffer size of 4096 bytes can overrun for latent systems. The first form specifies the input buffer size, in the second form both input and output buffers are defined.

-lasterror
  (Windows only). This option is query only. In case of a serial communication error, read or puts returns a general Tcl file I/O error. fconfigure -lasterror can be called to get a list of error details. See below for an explanation of the various error codes.

### SERIAL PORT SIGNALS

RS-232 is the most commonly used standard electrical interface for serial communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and a positive voltage (+3..+12V) define a space (off=0) bit (RS-232C). The following signals are specified for incoming and outgoing data, status lines and handshaking. Here we are using the terms workstation for your computer and modem for the external device, because some signal names (DCD, RI) come from modems. Of course your external device may use these signal lines for other purposes.

TXD(output)
  Transmitted Data: Outgoing serial data.

RXD(input)
  Received Data:Incoming serial data.

RTS(output)
  Request To Send: This hardware handshake line informs the modem that your workstation is ready to receive data. Your workstation may automatically reset this signal to indicate that the input buffer is full.

CTS(input)
  Clear To Send: The complement to RTS. Indicates that the modem is ready to receive data.

DTR(output)
  Data Terminal Ready: This signal tells the modem that the workstation is ready to establish a link. DTR is often enabled automatically whenever a serial port is opened.

DSR(input)
  Data Set Ready: The complement to DTR. Tells the workstation that the modem is ready to establish a link.

DCD(input)
  Data Carrier Detect: This line becomes active when a modem detects a "Carrier" signal.

RI(input)
  Ring Indicator: Goes active when the modem detects an incoming call.

BREAK
  A BREAK condition is not a hardware signal line, but a logical zero on the TXD or RXD lines for a long period of time, usually 250 to 500 milliseconds. Normally a receive or transmit data signal stays at the mark (on=1) voltage until the next character is transferred. A BREAK is sometimes used to reset the communications line or change the operating mode of communications hardware.

### ERROR CODES (Windows only)

A lot of different errors may occur during serial read operations or during event polling in background. The external device may have been switched off, the data lines may be noisy, system buffers may overrun or your mode settings may be wrong. That's why a reliable software should always catch serial read operations. In cases of an error Tcl returns a general file I/O error. Then fconfigure -lasterror may help to locate the problem. The following error codes may be returned.

RXOVER:
  Windows input buffer overrun. The data comes faster than your scripts reads it or your system is overloaded. Use fconfigure -sysbuffer to avoid a temporary bottleneck and/or make your script faster.

TXFULL
  Windows output buffer overrun. Complement to RXOVER. This error should practically not happen, because Tcl cares about the output buffer status.

OVERRUN
  UART buffer overrun (hardware) with data lost. The data comes faster than the system driver receives it. Check your advanced serial port settings to enable the FIFO (16550) buffer and/or setup a lower(1) interrupt threshold value.

RXPARITY
  A parity error has been detected by your UART. Wrong parity settings with fconfigure -mode or a noisy data line (RXD) may cause this error.

FRAME
  A stop-bit error has been detected by your UART. Wrong mode settings with fconfigure -mode or a noisy data line (RXD) may cause this error.

BREAK
  A BREAK condition has been detected by your UART (see above).

### SEE ALSO

close, flush, gets, puts, read, socket, Tcl_StandardChannels

### KEYWORDS

blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation, encoding, filter, byte array, binary

    Copyright © 1995-1996 Sun Microsystems, Inc.
    Copyright © 1995-1997 Roger E. Critchlow Jr.