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 sup-
       plied, 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  chan-
       nels.  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  opera-
              tions 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  non-
              blocking  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  appli-
              cation  must  be  using the Tcl event loop (e.g. by
              calling Tcl_DoOneEvent or invoking the  vwait  com-
              mand).

       -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  out-
              put.  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 chan-
              nel, the bytes in the Japanese file would  be  con-
              verted  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 sim-
              ply read or write raw bytes.  The Tcl  binary  com-
              mand  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 Con-
              trol-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 char-
              acter marker.  For read-write channels, a  two-ele-
              ment  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 writ-
              ing.

       -translation mode

       -translation {inMode outMode}
              In Tcl scripts the end of a line is  always  repre-
              sented using a single newline character (\n).  How-
              ever, in actual files and devices the end of a line
              may  be  represented differently on different plat-
              forms, 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 con-
              trol 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  chan-
              nels;  the  read translation mode is the first ele-
              ment 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 -encod-
                     ing 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  transla-
                     tion  mode, cr mode translates newline char-
                     acters 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 trans-
                     lation  mode,  crlf  mode translates newline
                     characters    to    carriage-return-linefeed
                     sequences.   This  mode is typically used on
                     Windows platforms and  for  network  connec-
                     tions.

              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 chan-
       nel 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 connec-
              tion  speed.   Parity  is one of the following let-
              ters: 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 hand-
              shake 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 set-
              tings.  The -handshake option cannot be queried.


       -queue (Windows and Unix). The -queue option can  only  be
              queried.   It returns a list of two integers repre-
              senting 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 granu-
              larity  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 sig-
              nal 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 dis-
              abled  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  -tty-
              control 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 max-
              imum  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 chan-
              nel. 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 vari-
              ous 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 volt-
       age (+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 indi-
                     cate that the input buffer is full.

              CTS(input)
                     Clear To Send: The complement to RTS.  Indi-
                     cates  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 auto-
                     matically  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" sig-
                     nal.

              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 set-
       tings 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 -sys-
                     buffer  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(n), flush(n), gets(n), puts(n), read(n),  socket(n),
       Tcl_StandardChannels(3)


KEYWORDS
       blocking,  buffering, carriage return, end of line, flush-
       ing, linemode, newline,  nonblocking,  platform,  transla-
