On Apache
Under GNU General Public License
2024-04-25 03:55 @18.116.90.141 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
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 alter-
nating 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 non-
blocking 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 appli-
cation 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 buf-
fer 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 char-
acter 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 set-
ting 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 interpreta-
tion 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 out-
put when the channel is closed. If char is the empty string, then there is no spe-
cial 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 conve-
nience, 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 char-
acter (\n). However, in actual files and devices the end of a line may be repre-
sented differently on different platforms, or even for different devices on the
same platform. For example, under UNIX newlines are used in files, whereas car-
riage-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 sup-
ported:
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 sock-
ets 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 charac-
ter 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 sin-
gle carriage return character. 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.
crlf The end of a line in the underlying file or device is represented by a car-
riage 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 typ-
ically used on Windows platforms and for network connections.
lf The end of a line in the underlying file or device is represented by a sin-
gle 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 com-
mand 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 sys-
tem 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 termi-
nal:
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, nonblock-
ing, platform, translation, encoding, filter, byte array, binary
Tcl 8.3 fconfigure(n)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-04-25 03:55 @18.116.90.141 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)