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  alternat­
       ing  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  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.

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

              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

                     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.


SEE ALSO

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


KEYWORDS

       blocking,   buffering,   carriage  return,  end  of  line,

       lation, encoding, filter, byte array, binary


Man(1) output converted with man2html