Manual Pages for UNIX Darwin command on man fconfigure

fconfigure(n) Tcl Built-In Commands fconfigure(n)

NAME

fconfigure - Set and get options on a channel

SYNOPSIS

ffccoonnffiigguurree channelId ffccoonnffiigguurree channelId name ffccoonnffiigguurree channelId name value ?name value ...?

DESCRIPTION

The ffccoonnffiigguurree 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 channel such as a Tcl standard channel (ssttddiinn, ssttddoouutt, or ssttddeerrrr), the return value from an invocation of ooppeenn or ssoocckkeett, 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 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 correspond-

ing value; in this case the return value is an empty string.

The options described below are supported for all channels. In addi-

tion, 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 ssoocckkeett command for its additional options.

-bblloocckkiinngg boolean

The -bblloocckkiinngg 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 nor-

mally in blocking mode; if a channel is placed into nonblocking mode it will affect the operation of the ggeettss, rreeaadd, ppuuttss,

fflluusshh, and cclloossee commands; see the documentation for those com-

mands for details. For nonblocking mode to work correctly, the application must be using the Tcl event loop (e.g. by calling TTccllDDooOOnneeEEvveenntt or invoking the vvwwaaiitt command).

-bbuuffffeerriinngg newValue

If newValue is ffuullll then the I/O system will buffer output until its internal buffer is full or until the fflluusshh command is

invoked. If newValue is lliinnee, then the I/O system will automati-

cally flush output for the channel whenever a newline character

is output. If newValue is nnoonnee, the I/O system will flush auto-

matically after every output operation. The default is for

-bbuuffffeerriinngg to be set to ffuullll except for channels that connect to

terminal-like devices; for these channels the initial setting is

lliinnee. Additionally, ssttddiinn and ssttddoouutt are initially set to lliinnee, and ssttddeerrrr is set to nnoonnee.

-bbuuffffeerrssiizzee 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 mil-

lion, allowing buffers of ten to one million bytes in size.

-eennccooddiinngg 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 sshhiiffttjjiiss and properly process and display the contents, the encoding would be set to sshhiiffttjjiiss. 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 bbiinnaarryy. Tcl will then assign no interpretation to the data in the file and simply read or write raw bytes. The Tcl bbiinnaarryy

command can be used to manipulate this byte-oriented data.

The default encoding for newly opened channels is the same plat-

form- and locale-dependent system encoding used for interfacing

with the operating system.

-eeooffcchhaarr char

-eeooffcchhaarr {{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 chan-

nels, 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 spec-

ify 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 -eeooffcchhaarr is the empty string in all cases except for files

under Windows. In that case the -eeooffcchhaarr is Control-z (\x1a)

for reading and the empty string for writing.

-ttrraannssllaattiioonn mode

-ttrraannssllaattiioonn {{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 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 ggeettss and rreeaadd) the

Tcl I/O system automatically translates the external end-of-line

representation into newline characters. Upon output (i.e., with

ppuuttss), the I/O system translates newlines to the external end-

of-line representation. The default translation mode, aauuttoo,

handles all the common cases automatically, but the -ttrraannssllaattiioonn

option provides explicit control over the end of line transla-

tions.

The value associated with -ttrraannssllaattiioonn 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: aauuttoo As the input translation mode, aauuttoo treats any of newline (llff), carriage return (ccrr), or carriage return followed by a newline (ccrrllff) 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, aauuttoo chooses a platform spe-

cific representation; for sockets on all platforms Tcl chooses ccrrllff, for all Unix flavors, it chooses llff, for the Macintosh platform it chooses ccrr and for the various flavors of Windows it chooses ccrrllff. The default setting

for -ttrraannssllaattiioonn is aauuttoo for both input and output.

bbiinnaarryy No end-of-line translations are performed. This is

nearly identical to llff mode, except that in addition

bbiinnaarryy mode also sets the end-of-file character to the

empty string (which disables it) and sets the encoding to bbiinnaarryy (which disables encoding filtering). See the

description of -eeooffcchhaarr and -eennccooddiinngg for more informa-

tion. ccrr The end of a line in the underlying file or device is represented by a single carriage return character. As the input translation mode, ccrr mode converts carriage returns to newline characters. As the output translation mode, ccrr mode translates newline characters to carriage

returns. This mode is typically used on Macintosh plat-

forms. ccrrllff 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, ccrrllff

mode converts carriage-return-linefeed sequences to new-

line characters. As the output translation mode, ccrrllff

mode translates newline characters to carriage-return-

linefeed sequences. This mode is typically used on Win-

dows platforms and for network connections. llff 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. SSTTAANNDDAARRDD CCHHAANNNNEELLSS The Tcl standard channels (ssttddiinn, ssttddoouutt, and ssttddeerrrr) 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 iinneett super-server common

on Unix system its Tcl standard channels will be sockets and thus sup-

port the socket options.