Provided by: tcl8.5-doc_8.5.15-2ubuntu1_all bug

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  by  allowing them to operate asynchronously; 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.  It is usually
              better to set the -translation option to binary when you want  to  transfer  binary
              data,  as  this  turns  off the other automatic interpretations of the bytes in the
              stream as well.

              The default encoding for newly opened channels is the same  platform-  and  locale-
              dependent  system  encoding  used  for  interfacing  with  the operating system, as
              returned by encoding 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.  The acceptable range for
              -eofchar values is \x01 - \x7f; attempting to set -eofchar to a  value  outside  of
              this range will generate an error.

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

                     Internally,  i.e.  when  it  comes to the actual behaviour of the translator
                     this value is identical to  lf  and  is  therefore  reported  as  such  when
                     queried. Even if binary was used to set the translation.

              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.

              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.

EXAMPLES

       Instruct Tcl to always send output to stdout immediately,  whether  or  not  it  is  to  a
       terminal:
              fconfigure stdout -buffering none

       Open a socket and read lines from it without ever blocking the processing of other events:
              set s [socket some.where.com 12345]
              fconfigure $s -blocking 0
              fileevent $s readable "readMe $s"
              proc readMe chan {
                 if {[gets $chan line] < 0} {
                    if {[eof $chan]} {
                       close $chan
                       return
                    }
                    # Could not read a complete line this time; Tcl's
                    # internal buffering will hold the partial line for us
                    # until some more data is available over the socket.
                 } else {
                    puts stdout $line
                 }
              }

       Read a PPM-format image from a file:
              # Open the file and put it into Unix ASCII mode
              set f [open teapot.ppm]
              fconfigure $f -encoding ascii -translation lf

              # Get the header
              if {[gets $f] ne "P6"} {
                 error "not a raw-bits PPM"
              }

              # Read lines until we have got non-comment lines
              # that supply us with three decimal values.
              set words {}
              while {[llength $words] < 3} {
                 gets $f line
                 if {[string match "#*" $line]} continue
                 lappend words {*}[join [scan $line %d%d%d]]
              }

              # Those words supply the size of the image and its
              # overall depth per channel. Assign to variables.
              lassign $words xSize ySize depth

              # Now switch to binary mode to pull in the data,
              # one byte per channel (red,green,blue) per pixel.
              fconfigure $f -translation binary
              set numDataBytes [expr {3 * $xSize * $ySize}]
              set data [read $f $numDataBytes]

              close $f

SEE ALSO

       close(3tcl),  flush(3tcl),  gets(3tcl),  open(3tcl), puts(3tcl), read(3tcl), socket(3tcl),
       Tcl_StandardChannels(3tcl)

KEYWORDS

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