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 chan-nel channel
nel 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 cur-rent current
rent 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 chan-nels channels
nels 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; 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 automati-cally automatically
cally 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, subse-quently subsequently
quently 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 sys-tem system
tem 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 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 readwrite
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 chan-nel channel
nel 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 Win-dows. Windows.
dows. 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 dif-ferent different
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 representa-tion. representation.
tion. 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 conve-nience, convenience,
nience, 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 cur-rently currently
rently 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 trans-lated translated
lated 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, 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 filter-ing). filtering).
ing). See the description of -eofchar and -encoding for more information.
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 charac-ters characters
ters 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 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 connec-tions. connections.
tions.
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 out-put. output.
put. 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.
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, plat-form, platform,
form, translation, encoding, filter, byte array, binary
Tcl 8.3 fconfigure(n)
|