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 chan-
nels.
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 sup-
plied, 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 indefin-
itely. 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; 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 TclDoOneEvent or invoking the
vwait command).
-buffering newValue
If newValue is full then the I/O system will buffer
Tcl Last change: 8.3 1
Tcl Built-In Commands fconfigure(1T)
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 automati-
cally 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.
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
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 out-
put, the end-of-file character is output when the chan-
nel is closed. If char is the empty string, then there
Tcl Last change: 8.3 2
Tcl Built-In Commands fconfigure(1T)
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.
-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 exam-
ple, 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 char-
acters. 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 representa-
tion 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
Tcl Last change: 8.3 3
Tcl Built-In Commands fconfigure(1T)
representation; for sockets on all 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 -encoding for more information.
Internally, i.e. when it comes to the actual
behaviour of the translator this value is identi-
cal to lf and is therefore reported as such when
queried. Even if binary was used to set the trans-
lation.
cr The end of a line in the underlying file or device
is represented by a single carriage return charac-
ter. As the input translation mode, cr mode con-
verts carriage returns to newline characters. As
the output translation mode, cr mode translates
newline characters 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 fol-
lowed 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 typi-
cally used on UNIX platforms.
STANDARD CHANELS
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
Tcl Last change: 8.3 4
Tcl Built-In Commands fconfigure(1T)
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 PM-format image from a file:
# Open the file and put it into Unix ASCI 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 PM"
}
# 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 [eval concat [scan $line %d%d%d]
}
# Those words supply the size of the image and its
# overall depth per channel. Assign to variables.
foreach {xSize ySize depth} $words {break}
# Now switch to binary mode to pull in the data,
Tcl Last change: 8.3 5
Tcl Built-In Commands fconfigure(1T)
# 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(1T), flush(1T), gets(1T), open(1T), puts(1T),
read(1T), socket(1T), TclStandardChannels(3TCL)
KEYWORDS
blocking, buffering, carriage return, end of line, flushing,
linemode, newline, nonblocking, platform, translation,
encoding, filter, byte array, binary
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWTcl
Interface Stability Uncommitted
NOTES
Source for Tcl is available on http:/opensolaris.org.
Tcl Last change: 8.3 6
|
