fconfigure(n) Tcl (7.5) 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 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; 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
Page 1 (printed 2/19/99)
fconfigure(n) Tcl (7.5) fconfigure(n)
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 output. 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
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.
-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.
Page 2 (printed 2/19/99)
fconfigure(n) Tcl (7.5) fconfigure(n)
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, 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 translation mode, cr mode translates
newline characters 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 connections.
Page 3 (printed 2/19/99)
fconfigure(n) Tcl (7.5) fconfigure(n)
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, flushing,
linemode, newline, nonblocking, platform, translation
Page 4 (printed 2/19/99)