- NAME
- fconfigure - Set and get options on a channel
- SYNOPSIS
- fconfigure channelId
- fconfigure channelId name
- fconfigure channelId name value ?name value ...?
- DESCRIPTION
- -blocking boolean
- -buffering newValue
- -buffersize newSize
- -eofchar char
- -eofchar {inChar outChar}
- -translation mode
- -translation {inMode outMode}
- auto
- binary
- cr
- crlf
- lf
- SEE ALSO
- KEYWORDS
fconfigure - Set and get options on a channel
fconfigure channelId
fconfigure channelId name
fconfigure channelId name value ?name value ...?
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 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.
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.
- 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.
close, flush, gets, puts, read, socket
blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation
Copyright © 1995-1996 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.