fconfigure(n)						       Tcl Built-In Commands						     fconfigure(n)

__________________________________________________________________________________________________________________________________________________

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 con-
	      verted 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-ele-
	      ment list specifies the end of file marker for input and output, respectively.  As a convenience, when setting the end-of-file char-
	      acter 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 (
).  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 ele-
	      ment.  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  new-
		     line  (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 encod-
		     ing 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 trans-
		     lation 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 char-
		     acter.  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 typi-
		     cally 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(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n), Tcl_StandardChannels(3)

KEYWORDS

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

Tcl									8.3							     fconfigure(n)