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 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
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
