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



SEE ALSO
       close(n), flush(n), gets(n), puts(n), read(n), socket(n)


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