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. If no name or value arguments are
supplied, the command returns a list containing alternat
ing 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 chan
nels. 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 opera
tions 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; 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 com
mand).
-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.
except for channels that connect to terminal-like
devices; for these channels the initial setting is
line. Additionally, stdin and stdout are intially
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 out
put. 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 chan |
nel, the bytes in the Japanese file would be con |
verted 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 sim |
ply read or write raw bytes. The Tcl binary com |
mand 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 Con
trol-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 char
acter marker. For read-write channels, a two-ele
ment list specifies the end of file marker for
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 writ
ing.
-translation mode
-translation {inMode outMode}
In Tcl scripts the end of a line is always repre
sented using a single newline character (\n). How
ever, in actual files and devices the end of a line
may be represented differently on different plat
forms, 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 con
trol 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 chan
nels; the read translation mode is the first ele
ment 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
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 -encod |
ing 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 transla
tion mode, cr mode translates newline char
acters 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 trans
lation mode, crlf mode translates newline
characters to carriage-return-linefeed
sequences. This mode is typically used on
Windows platforms and for network connec
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
output. This mode is typically used on UNIX
platforms.
SEE ALSO
close(n), flush(n), gets(n), puts(n), read(n), socket(n)
KEYWORDS
blocking, buffering, carriage return, end of line,
lation, encoding, filter, byte array, binary
Man(1) output converted with
man2html