fconfigure

fconfigure(3tcl)              Tcl Built-In Commands             fconfigure(3tcl)



________________________________________________________________________________

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 additional options for sockets, and the
       open command for additional options for serial devices.

       -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 one and one
              million, allowing buffers of one 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



Tcl                                    8.3                      fconfigure(3tcl)