fconfigure - Set and get options on a channel
fconfigure channelId fconfigure channelId name fconfigure channelId name value ?name value ...?
fconfigure(1t) Tcl Built-In Commands fconfigure(1t)
______________________________________________________________________________
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 correspond-
ing value; in this case the return value is an empty string.
The options described below are supported for all channels. In addi-
tion, 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 nor-
mally 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 asyn-
chronously; see the documentation for those commands for
details. For nonblocking mode to work correctly, the applica-
tion 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 automati-
cally flush output for the channel whenever a newline character
is output. If newValue is none, the I/O system will flush auto-
matically 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 mil-
lion, 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 plat-
form- 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 chan-
nels, 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 spec-
ify 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 dif-
ferent 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 transla-
tions.
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 spe-
cific 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 informa-
tion.
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 new-
line characters. As the output translation mode, crlf
mode translates newline characters to carriage-return-
linefeed sequences. This mode is typically used on Win-
dows 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 sup-
port 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 process-
ing 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
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | runtime/tcl-8 |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
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
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://prdownloads.sourceforge.net/tcl/tcl-
core8.6.7-src.tar.gz.
Further information about this software can be found on the open source
community website at https://www.tcl.tk/.
Tcl 8.3 fconfigure(1t)