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. 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.
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.
-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.
-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
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 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
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. See the description of
-eofchar 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, flush-
ing, linemode, newline, nonblocking, platform, translation