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.


SEE ALSO
       close(n),  flush(n),  gets(n),  open(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-
